之前另一篇文章寫了簡單版 Tailscale 官方雲端加上 NAS 容器，照著做大致就能動。本文是完整自駕版，主要的差異是，控制伺服器是 CyberQ 自架的 Headscale，而 Collie 這個名稱從 Collie 犬種來的 Herdr 外掛程式，改跑在另一個 AI 算力節點上，不是 NAS。
之所以要分成兩篇，是因為換掉這種私有網路控制伺服器為自架之後，Tailscale 官方文件的預設路徑會直接失敗，而且失敗的方式相當隱晦，設定看起來套用成功，服務也起來了，只是每一個請求都拿到 404。本文把這些地方逐一標出來，並給出實際跑得起來的替代路徑。
全文的數字與訊息都是在自己的環境實測的，一台 QNAP TS-855X（QuTS hero h6.0.2.3591）跑 Headscale 0.29.3，一台 aarch64 的算力節點跑 Herdr 0.8.2 與 Collie 1.1.0，客戶端是 iPhone 與一台 Windows 筆電。
跑起來用手機或筆電瀏覽器都能夠與家裡或公司內的 AI 代理人互動 (地端 OpenCode、agy、Claude等等都行)，且走自己的私有網路環境，不假手其他雲端中繼。
為什麼不能照抄簡單版 ?
一、`tailscale serve` 的 HTTPS 在 Headscale 上不能用
Collie 的預設路徑是 tailscale serve --bg 8787，由 serve 終止 TLS 並注入身分標頭。這條路相依 tailscale cert，也就是控制伺服器要能替節點的 MagicDNS 名稱申請憑證。Headscale 沒有實作這個功能，看 GitHub 上，它相關 issue 排在未來版本。
實測時容器的啟動程式自己講得很清楚：
serve proxy: this node is configured as a proxy that exposes an HTTPS endpoint to tailnet,
but it is not able to issue TLS certs, so this will likely not work.
tailscale serve status → No serve config連帶後果是整條 PWA 路徑斷掉 (PWA是可以在 iPhone 手機上把網站變成桌面 APP 圖示方便點選使用的功能)，沒有 HTTPS 就沒有 secure context，瀏覽器會關閉 service worker，加入主畫面與 Web Push 都不能用。Collie 有一個 COLLIE_SERVE_MODE=http 的旗標對應這個情境，原始碼裡的提示甚至直接點名 Headscale，但那只是讓服務可連，PWA 仍然沒有。
要在 Headscale 上同時拿到 HTTPS 與 PWA，唯一的路是自己準備一個有真憑證的反向代理，CyberQ 這次採用的就是這個方式。
二、`${TS_CERT_DOMAIN}` 會展開成 `no-https`
照 Tailscale 的 Docker 文件寫 TS_SERVE_CONFIG，裡面的 ${TS_CERT_DOMAIN} 在 Headscale 上會展開成字面的字串 no-https。這造成一個很難查的狀況：
tailscale serve status
http://no-https:8787 (tailnet only)
|-- / proxy http://127.0.0.1:8787設定套用成功了，服務也在跑，但那個 Web handler 的鍵對不上任何真實名稱，於是不管你用什麼 Host 連進去都是 404 錯誤。解法是把 MagicDNS 名稱寫死，不要用變數。
順帶一提，Host 不對時回 404 的是 tailscale serve 自己，Collie 的 Host 閘門回的是 403。看錯誤訊息時，這個差別可以幫你判斷卡在哪一層。
三、身分標頭的值不能採用 email，而且 tagged 節點要設定沒有身分才行
tailscale serve 在 Headscale 上確實會注入身分標頭。實測從一個屬於使用者的節點打進來：
{
"Tailscale-User-Login": "cyberq",
"Tailscale-User-Name": "cyberq",
"Tailscale-User-Profile-Pic": "",
"X-Forwarded-For": "100.64.0.4"
}JSON
注意兩件事。第一，值是 Headscale 的使用者名稱，不是 email。官方文件範例寫的是 [email protected]，照抄到自架環境會把自己鎖在門外，COLLIE_TRUSTED_USER 要填純使用者名。第二，Tailscale-User-Profile-Pic 是空的，Headscale 目前沒有顯示名稱與頭像的欄位。
更關鍵的是，從帶標籤（tagged）的節點打進來，完全沒有身分標頭，只剩 X-Forwarded-For 與 X-Forwarded-Host。標籤節點在 Tailscale 的模型裡是機器不是人，本來就沒有人的身分。這件事會影響我們用的架構，如果讓 NAS 當入口代理，而 NAS 是 tag:nas 的節點，那麼人員身分閘門在這條路上一定失效，寫入授權必須改用別的機制。
怎樣驗證呢? 在同一台機器上多起一個 userspace 的 tailscaled 當探針節點，帶 --socks5-server，用 curl --socks5-hostname 打進去，後端放一支會印出所有標頭的小程式。這樣不必動手機，就能分辨「Headscale 不支援」與「來源節點是 tagged 所以沒身分」這兩個長得很像的狀況。
建議部署架構
手機（Tailscale App 加 Collie PWA）
│ HTTPS，網址是 collie.example.com
│ 公開 DNS 只給憑證申請用；tailnet 內由 headscale 的 extra_records
│ 蓋成 NAS 的 tailnet 位址，流量不繞出公網
▼
NAS 上既有的 Caddy
│ Let's Encrypt 憑證，來源限制只允許 tailnet
│ 改寫 Host 成算力節點的 MagicDNS 名稱
▼
算力節點的 tailscale serve --http
│ http://agent-host.ts.example.com:8787，tailnet 內
▼
127.0.0.1:8787 Collie 橋接程式（Bun）
▼
Herdr 伺服器，各家 CLI 代理人活在它的 pane 內CyberQ 實作成這個架構，有兩個刻意的選擇。
Collie 跑在 AI 代理人在的 AI 算力機器上
Herdr 的側欄只看得見 Herdr 自己啟動的 pane，所以 Collie 鏡射到的內容取決於裝在哪一台。把它裝在 NAS 上而代理人在別台，手機看到的會是空的。
NAS 只當入口
它全年開機、已經有 Caddy 與公開網域，拿來終止 TLS 最省事。代價是它是 tagged 節點，身分標頭到不了後端，所以寫入授權走裝置配對。
實作的前置條件
一個自架的 Headscale（本文為 0.29.3）與一個可以申請憑證的公開網域
NAS 上一個已經在跑的 Caddy，或其他能改寫 Host 的反向代理
算力節點上的 Herdr 0.7.0 以上與 Bun
手機安裝 Tailscale App
實作步驟
步驟一：控制端的 DNS 覆寫
在 headscale 的 config.yaml 加一筆 extra_records，讓公開名稱在 tailnet 內指向 NAS 的 tailnet 位址：
dns:
extra_records:
- name: "collie.example.com"
type: "A"
value: "100.64.0.1"公開 DNS 那邊照樣建一筆 A 記錄指向公網 IP，那只是給 Let’s Encrypt 的挑戰用。改完 config.yaml 要重啟 headscale 容器，SIGHUP 只會重載 ACL 政策，不會重載 DNS 設定。
ACL 政策可以維持既有寫法。實測確認 Headscale 0.29.3 同時接受新的 grants 與 legacy acls，兩者可以並存在同一份檔案，docker kill -s HUP headscale 熱重載成功並回報 Policy reload completed with changes。
步驟二：算力節點加入 tailnet，不需要 root
如果算力節點上跑著別的服務，你多半不會想讓 tailscaled 去改寫 resolv.conf，也不見得想裝系統級服務。userspace 模式可以完全避開：
# 靜態執行檔，不經套件管理員
curl -fsSL -o ts.tgz https://pkgs.tailscale.com/stable/tailscale_1.102.3_arm64.tgz
tar xzf ts.tgz --strip-components=1
tailscaled --tun=userspace-networking \
--socket=$HOME/.local/state/tailscale/tailscaled.sock \
--statedir=$HOME/.local/state/tailscale --port=41641登入時指向自架控制端，並關掉 DNS 接管：
tailscale --socket=$HOME/.local/state/tailscale/tailscaled.sock up \
--login-server=https://headscale.example.com \
--authkey="$KEY" --hostname=agent-host --accept-dns=false金鑰用 headscale preauthkeys create --user <數字ID> --expiration 2h 產生。金鑰帶了 --tags 時客戶端就不可以再給 --advertise-tags，否則會被回 requested tags are invalid or not permitted，而那個訊息會讓人以為是 tagOwners 寫錯。
以 systemd --user 常駐時要注意沒有開 lingering 的話登出會停。userspace 模式的代價是沒有子網路路由與出口節點功能，本用途用不到。
接著開 serve，用 HTTP 模式，因為 TLS 由 NAS 的 Caddy 負責：
tailscale --socket=... serve --bg --http=8787 --set-path=/ 8787
# http://agent-host.ts.example.com:8787 (tailnet only)
# |-- / proxy http://127.0.0.1:8787步驟三：安裝 Collie
herdr plugin install AltanS/collie
herdr plugin action invoke start --plugin herdr.collie實測在 aarch64 上安裝耗時 176 秒，安裝階段會 clone、跑 bun install、typecheck、編譯出單一執行檔並建置 PWA。裝好之後：
plugin id 是 herdr.collie
設定檔在 herdr plugin config-dir herdr.collie 回報的目錄底下的 .env
橋接程式只綁 127.0.0.1:8787，ss -ltnp 可以確認
有 systemd 時跑在 systemd --user 的 collie.service 底下
.env 的內容：
COLLIE_MUX=herdr
COLLIE_PORT=8787
# 入口是自己的反向代理，Collie 不要去管 tailscale serve
COLLIE_SKIP_SERVE=1
# Host 閘門。用非預設 socket 時 Collie 的自動探索拿不到 tailnet 名稱，這一項必填
COLLIE_PUBLIC_HOSTS=agent-host:8787,agent-host.ts.example.com:8787,collie.example.com
COLLIE_ALLOWED_ORIGINS=https://collie.example.com
COLLIE_PUBLIC_URL=https://collie.example.com設定 COLLIE_SKIP_SERVE=1 之後，橋接程式會主動警告 COLLIE_TRUSTED_USER 在這條路上無效。那是正確的行為，不是錯誤。
步驟四：NAS 的 Caddy 當入口
collie.example.com {
# 只允許 tailnet 進來。理由見下方說明，這裡不能用 tailnet 的 100.64.0.0/10
@tailnet remote_ip 172.31.250.0/24
handle @tailnet {
reverse_proxy http://100.64.0.3:8787 {
# tailscale serve 依 Host 比對，不改寫會直接 404
header_up Host agent-host:8787
}
}
handle {
respond "not available" 403
}
log {
output file /var/log/caddy/collie.log
format json
}
}為什麼來源限制寫的是橋接網路的網段，不是 tailnet 網段呢 ? NAS 上的 tailscaled 是子網路路由器，它會對轉發進 Docker 容器的封包做 SNAT，因此所有 tailnet 客戶端到達 Caddy 時，來源都變成橋接網路的閘道位址。實測手機連進來就是這個位址。這代表來源 IP 不能用來分辨是哪一台裝置，但仍然分得出「從 tailnet 進來的」與「從公網或區網進來的」，因為後兩者是真實 IP。
這個限制確實有用，vhost 上線幾分鐘內，日誌裡就出現公網掃描器在打 /api/.env、/backend/.env 這類路徑，全部拿到 403。
憑證只用到 443。 實測 Caddy 走 TLS-ALPN-01 挑戰就拿到憑證，不需要開 80 埠，容器重建的時機不同時也可能走 HTTP-01。
Caddyfile 是以檔案 bind mount 進容器的，要修改的畫，用 sed -i 改不會生效，會換掉 inode，容器裡看到的還是舊檔，caddy reload 只回 config is unchanged，看起來像設定沒問題但就是沒套用。要嘛用 cat > file 覆寫保留 inode，要嘛重建容器。headscale 的 config.yaml 也是同樣的道理。
步驟五：手機端
iOS 的 Tailscale App 沒有明顯的入口可以改控制伺服器，路徑藏在登入流程裡，開 App，點右上角帳號圖示，選 Log in，再點右上角的選單，選 Use custom coordination server，填入你的 headscale 網址。你的 headscale 也提供了一頁 /apple 說明同樣的步驟。
這條路不吃 preauthkey。 按下登入後會跳出瀏覽器顯示一段註冊指令，拿到 headscale 上執行即可：
headscale auth register --auth-id hskey-authreq-XXXX --user <使用者名>Windows 那側則要注意兩件事，沒有 sudo，要以系統管理員身分開 PowerShell 去執行，而且指令不能斷行，否則後半段的旗標會被當成另一條命令：
& "C:\Program Files\Tailscale\tailscale.exe" up --login-server=https://headscale.example.com --authkey=<KEY> --accept-routes --accept-dns=true --reset--accept-dns=true 一定要留著，否則 collie.example.com 在那台上會解析到公網 IP 而不是 tailnet 位址，Caddy 會回 403。
步驟六：配對，這是關掉遠端 shell 的那個開關
Collie 在設計上就是對主機的遠端 shell 存取，一個 API 呼叫可以把任意按鍵送進活著的終端機。實測在還沒配對任何裝置的狀態下：
curl -X POST http://127.0.0.1:8787/api/pane/w4:p1/reply \
-H 'Content-Type: application/json' \
-d '{"text":"id -un > /tmp/proof.txt","submit":true}'
# {"ok":true}，檔案裡就是這台機器的使用者名配對一台裝置之後，連 loopback 直連的寫入都會被拒。
collie pair # 主機上執行，印出 8 碼、10 分鐘有效在手機的 Settings 找到 Paired devices，輸入這組碼與一個裝置標籤。之後：
未配對的客戶端讀取 200
未配對的客戶端寫入 403
loopback 直連寫入 403 ← 配對之前這一行是 200在這個架構下，配對是唯一的寫入授權機制。人員身分標頭到不了（入口是 tagged 節點），來源 IP 分不出裝置（SNAT），所以只剩 Collie 自己發的權杖。
實務上有個很容易誤判的地方，本文測試時就碰到了，手機能打字進 pane，不代表配對成功。沒有配對任何裝置時寫入閘門是關的，所以打字本來就會成功。要確認配對真的成立，看 collie devices list 有沒有列出裝置，而不是看手機能不能操作。
配對權杖綁瀏覽器與來源網址，所以同一支手機的不同瀏覽器算兩台裝置，而 iOS 上主畫面的 PWA 是獨立的儲存區，裝完 PWA 之後還要再配對一次。實測時同一支手機最後有三筆：
phone-chrome Chrome 分頁
phone-safari Safari 分頁
phone-pwa 主畫面的 PWA要用推播的話，要配對的是最後那一個，因為 iOS 的 Web Push 只在加到主畫面的 PWA 裡有效。
步驟七：PWA 與推播
有了真憑證，這兩項就能夠使用。iOS Safari 的加入主畫面可以正常安裝。
collie push-keys mailto:[email protected] # 寫入 VAPID 金鑰到 .env，權限 600
collie restart
# 然後在手機的 PWA 裡：Settings 允許通知
collie push-test "標題" "內容"
# [push] enabled (1 saved subscription(s))
# ✓ sent "標題" to 1 device(s).實測一到兩秒內手機收到。發送端函式庫 web-push 會發一則 url.parse() 的 DeprecationWarning，那是上游相依不是設定錯誤，主機回報送出成功只代表推播服務收下了，實際有沒有落到裝置上仍要看手機。
訂閱綁在推播端點上，重裝 PWA 或換網址都會產生新端點，舊的不會自動消失。用 collie push list 看、collie push forget <端點尾段> 清掉。
如果你了換網址等於全部重來。 配對權杖、推播訂閱與已安裝的 PWA 都綁來源網址，換名字之後三樣全部失效，手機要重裝 PWA、重新配對、重新開通知。
步驟八：驗證清單
# 1. 橋接程式只綁 loopback
ss -ltnp | grep 8787 # LISTEN 127.0.0.1:8787
# 2. 服務狀態與版本
collie status # ✓ Collie is running · v1.1.0
# 3. tailnet 那一側
tailscale serve status # http://agent-host.ts.example.com:8787 (tailnet only)
# 4. 配對確實生效（從另一台沒配對的機器）
curl -s -o /dev/null -w '%{http_code}\n' https://collie.example.com/api/snapshot # 200
curl -s -o /dev/null -w '%{http_code}\n' -X POST ... /api/pane/<id>/reply # 403
# 5. 稽核軌跡與推播
cat ~/.local/state/collie/audit.log
collie push-test順手把 headscale 的公網曝露面縮小
既然控制伺服器是自架的，它的 443 就得對全世界開著。有人會想把它放到 Cloudflare 橘雲後面吃 WAF，把 DERP 留在灰雲。這個方案不可行，三個理由：
一、橘雲會讓控制協定直接壞掉。 Tailscale 控制協定是 POST 加 Upgrade: tailscale-control-protocol，DERP 是 Upgrade: derp，都不是標準的 Upgrade: websocket。Cloudflare 的 proxy 與 Tunnel 只處理 websocket 值。
二、DERP 不是只有 UDP 3478。 stun_listen_addr 只是 STUN，DERP 中繼本身內嵌在 headscale 的 HTTP 服務裡，走 443/TCP。那個子網域一樣得開 443。
三、同 IP 同埠，WAF 一行 curl 就繞過。 兩個子網域指向同一個公網 IP 的同一個 443，對 IP 送 SNI 等於控制面網域即可。要讓 WAF 有意義得讓源站拒絕非 Cloudflare 來源，但灰雲的 DERP 又需要 443 全開，L3/L4 分不出來。
而且 WAF 對這個服務本來就沒什麼可做的，headscale 的認證在 Noise 協定與節點金鑰，不在 HTTP 層，沒有 preauthkey 或手動註冊誰都進不來。
實際有效的做法是路徑白名單。 在 Caddy 上只放行 headscale 真正用到的端點：
headscale.example.com {
# 平台設定說明頁設定過一次就用不到，只讓 tailnet 來源看得到
@platform_public {
path /apple /apple/* /windows /windows/*
not remote_ip 172.31.250.0/24
}
handle @platform_public {
respond 404
}
@headscale path /ts2021 /register /register/* /key /bootstrap-dns /health /derp /derp/* /verify /apple /apple/* /windows /windows/*
handle @headscale {
# 不要對 headscale 加壓縮，會干擾 upgrade 之後的原始串流
reverse_proxy headscale:8080 {
header_up True-Client-IP {remote_host}
header_up X-Real-IP {remote_host}
}
}
handle {
respond 404
}
}實測效果，公網那側：
/ts2021 500 /key 400 /health 200 /bootstrap-dns 200 /derp/probe 200 /verify 405
/apple 404 /windows 404 /swagger 404 /api/v1/node 404 /metrics 404 / 404（/ts2021 的 500 與 /key 的 400 是因為用 GET 打需要特定方法的端點，端點本身正常。）tailnet 那側 /apple 與 /windows 仍是 200。
擋掉 /api/v1/* 不影響管理介面，如果你跟本文一樣用 headplane，它是走內部網路直連 http://headscale:8080，不經過 Caddy。
在這種情況下，新的 Apple 裝置在加入 tailnet 之前拿不到 /apple/ios 的設定描述檔，等於雞生蛋。加新裝置時要臨時放行，或從已在 tailnet 的裝置把描述檔取下來再傳過去。
改完務必照這個順序驗證，公網端點矩陣、tailnet 端仍可存取、既有節點沒斷線、管理介面仍可用，最後起一個臨時的 userspace 探針節點確認 /ts2021 與 /register/* 沒被誤擋，驗完把節點刪掉。CyberQ 實作這一步，也確認新節點仍註冊得進來。
Collie 日常維運指令
| 動作 | Herdr action |
|---|---|
| 啟動 / 停止 / 重啟 | invoke start / stop / restart |
| 狀態 / 版本 | invoke status / version |
| 更新 | invoke update |
| 跨大版更新 | invoke update-major |
| 推播金鑰 / 測試 | invoke push-keys / push-test |
實測 invoke update 從 1.0.1 升到 1.0.2 花 20 秒，再升到 1.1.0 花 5 秒，兩次配對紀錄、推播訂閱與 .env 都存活，註冊表回報的版本也跟得上，不需要手動重新 link。
1.1.0 版之後，Collie 顯示語系多了中文，不過是簡體中文喔。
優缺點與適用性
優點
控制平面與資料平面都在自己手上，沒有第三方帳號、沒有 Tailscale 每月席次訂閱費。Collie 鏡射的是 AI 代理人真正所在的機器。算力節點用 userspace tailscaled 加入，全程免 root、不動系統 DNS、不裝系統服務，要移除只要停掉一個使用者層的服務。
缺點與風險
它本質上是遠端 shell，配對之後仍然是遠端 shell，只是多了一道憑證。手機的裝置安全變成最後一道防線。單人設計，沒有多租戶隔離。而自架 Headscale 讓你必須自己準備有憑證的反向代理，否則就得接受沒有 PWA 與推播。控制伺服器的網域也必然進入憑證透明度日誌，取難猜的名字藏不住，這是自架要接受的代價。
適用情境
一個人、一個自架 tailnet、代理人跑在自己的工作站或算力節點上，而且已經在用 Herdr。如果你只想要最短路徑而且不介意用 Tailscale 官方的控制伺服器，另一篇的 NAS 容器版比較省事。
疑難排解
手機開 URL 得到 403 或 not available。
先看反向代理的日誌，確認它看到的來源位址是什麼。如果代理跑在容器裡而 tailscaled 是子網路路由器，來源會被 SNAT 成橋接網路的閘道位址，任何以 tailnet 網段寫的來源限制都會全部落空。
頁面出來但所有請求 404。
這是 tailscale serve 在回應。檢查代理有沒有把 Host 改寫成節點的 MagicDNS 名稱，以及 serve 設定裡的名稱是不是被 ${TS_CERT_DOMAIN} 展開成了 no-https。
頁面出來但所有請求 403，訊息是 host not allowed。
這是 Collie 在回應，COLLIE_PUBLIC_HOSTS 沒有包含代理送過來的 Host。
寫入回 403，訊息是 origin required。
設了 COLLIE_ALLOWED_ORIGINS 之後，寫入請求必須帶相符的 Origin 標頭，這是 CSRF 防護。用 curl 測試時要自己補上。
改了設定檔卻沒有生效。
檢查該檔案是不是 bind mount，sed -i 會換掉 inode 導致容器讀舊檔。
start 印出一串 tailscale 相關的 error。
在自備代理的架構下這是預期行為，訊息實際上是三行：'tailscale status' named no host for this node、tailscale not found; cannot publish the tailnet front door、the tailnet front door did not come up。橋接程式仍在 loopback 上正常運作。
節點離線很久之後還連得回來嗎?
這取決於 headscale 的 node.expiry。設成 0 時節點金鑰不會自動到期，離線多久回來都不必重新登入，也不會被自動刪除（ephemeral.inactivity_timeout 只對 ephemeral 節點生效）。
