High Altitude Oolong: 手動修改 partition content, enable ssh , wifi for headless raspberry pi OS.

在沒有顯示器與鍵盤的情況下（Headless 模式），可以透過在 SD 卡的 boot 分割區中建立或編輯特定檔案，來完成系統初始化設定。

適用版本：Raspberry Pi OS Trixie (2025-12-04 以後的映像檔)。此版本改用 cloud-init 取代舊版的 userconf.txt 方式。

1. 啟用 SSH 服務

在 boot 分割區的根目錄下，建立一個檔名為 ssh 的空白檔案（不含任何副檔名）。系統在開機過程中由 sshswitch.service 偵測到此檔案後，會自動啟動 OpenSSH 服務並移除該檔案。

touch /media/你的使用者/bootfs/ssh

注意：僅在 cloud-init 的 user-data 中設定 ssh_pwauth: true 是不夠的，該設定只控制 SSH 是否允許密碼登入，並不會啟動 SSH 服務本身。必須建立 ssh 檔案才能啟動服務。

2. 設定使用者帳號與密碼（cloud-init）

自 Trixie 版本起，Raspberry Pi OS 改用 cloud-init 進行首次開機設定。舊版的 userconf.txt 方式已不再支援。使用者帳號需透過 boot 分割區中的 user-data 檔案來設定。

首先產生加密密碼字串：

openssl passwd -6 "你的密碼"

編輯 boot 分割區中的 user-data 檔案，內容如下：

#cloud-config

hostname: raspberrypi

users:
- name: charles-chang
  gecos: Charles Chang
  groups: users,adm,dialout,audio,netdev,video,plugdev,cdrom,games,input,gpio,spi,i2c,render,sudo
  shell: /bin/bash
  lock_passwd: false
  passwd: 此處填入上面指令產生的加密密碼字串
  sudo: ALL=(ALL) NOPASSWD:ALL

ssh_pwauth: true

runcmd:
- nmcli radio wifi on

說明：最後的 runcmd 區段是用來在首次開機時啟用 WiFi radio，原因見下節說明。

3. 設定 WiFi 無線連線

編輯 boot 分割區中的 network-config 檔案。此檔案使用 netplan 格式（YAML），cloud-init 會在首次開機時讀取並套用。

network:
  version: 2

  ethernets:
    eth0:
      dhcp4: true
      optional: true

  wifis:
    wlan0:
      dhcp4: true
      optional: false
      access-points:
        你的WiFi名稱:
          password: "你的WiFi密碼"

注意 YAML 縮排：此檔案對空白字元敏感，請使用空格而非 Tab。

WiFi radio 預設為停用：Raspberry Pi OS Trixie 的 NetworkManager 預設將 WiFi radio 設為軟體停用狀態（WIFI: disabled）。即使 network-config 中已正確設定 WiFi 連線資訊，WiFi 仍無法連線。解決方法是在 user-data 的 runcmd 中加入 nmcli radio wifi on，讓系統在首次開機時自動啟用 WiFi radio。

4. 開機與連線

將設定完成的 SD 卡插入樹莓派後送電開機。Cloud-init 首次開機約需 2-3 分鐘完成設定。完成後即可透過 SSH 連線：

ssh charles-chang@樹莓派的IP位址

可透過路由器的 DHCP 用戶端清單查詢樹莓派的 IP 位址。若已在 user-data 中安裝 avahi-daemon，亦可使用：

ssh charles-chang@raspberrypi.local

5. 安全建議

首次登入後，建議立即執行 passwd 指令更換初始密碼，以確保系統安全性。

設定檔案總覽

檔案	位置	用途
`ssh`	boot 分割區根目錄	啟用 SSH 服務（空白檔案）
`user-data`	boot 分割區根目錄	設定使用者帳號、密碼、runcmd
`network-config`	boot 分割區根目錄	設定 WiFi 和乙太網路連線
`meta-data`	boot 分割區根目錄	cloud-init 中繼資料（通常不需修改）

很麻煩的是 /etc/hosts 也被networkmanager, cloud-init 管理了。
/etc/hosts 有一段話：

# Your system has configured 'manage_etc_hosts' as True.
# As a result, if you wish for changes to this file to persist
# then you will need to either
# a.) make changes to the master file in /etc/cloud/templates/hosts.debian.tmpl
# b.) change or remove the value of 'manage_etc_hosts' in
#     /etc/cloud/cloud.cfg or cloud-config from user-data
#

結果去看 /etc/cloud/cloud.cfg 只有 update_etc_hosts
這個 /etc/cloud/templates/hosts.debian.tmpl 看起來就是原始的，被copy到 /etc/hosts 的檔案，修改這個也可以。

High Altitude Oolong

2026/2/16

手動修改 partition content, enable ssh , wifi for headless raspberry pi OS.