fix: pin headscale image to v0.29.0 and drop removed config keys

新版 headscale 移除了部分設定鍵，搭配 watchtower 自動更新 :latest
導致容器啟動即 FATAL、無限重啟，所有節點離線。

- config.yaml: 註解 randomize_client_port（FATAL）與 ephemeral_node_inactivity_timeout（已改名）
- docker-compose.yml: image 釘到 v0.29.0，停止破壞性自動升級
- OPERATIONS.md / CLAUDE.md: 補上故障排除與升級注意事項

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -91,6 +91,7 @@ The `config.yaml` file contains:
 - External Docker network (`shared-net`) for connectivity
 - Three critical ports: 8080 (HTTP API), 9090 (metrics), 50443 (gRPC)
 - Watchtower integration for automatic image updates
+  > ⚠️ Because the image is pinned to `:latest` **and** auto-updated by Watchtower, a breaking change in a new Headscale release can crash-loop the container (a removed config key triggers a startup FATAL, taking every node offline). Removed keys seen so far: `randomize_client_port` (FATAL), `ephemeral_node_inactivity_timeout` (renamed to `node.ephemeral.inactivity_timeout`). Prefer pinning a specific version tag, or review the CHANGELOG BREAKING section before upgrading. See OPERATIONS.md → 故障排除.
 
 ### Security Model
 - Bearer token authentication for API access (hardcoded in scripts)

OPERATIONS.md

@@ -243,6 +243,30 @@ dig @1.1.1.1 example.com
 
 ### 常見問題
 
+#### 升級後容器無限重啟、所有節點離線（設定鍵被移除）
+
+**症狀**：所有 tailscale/headscale 節點突然全部連不上；`docker ps` 顯示 headscale 一直 `restarting`（`RestartCount` 持續飆高）。
+
+**原因**：本服務使用 `headscale/headscale:latest` 並開啟 watchtower 自動更新，新版可能**移除舊設定鍵**，使容器一啟動就 FATAL 而陷入重啟迴圈。已知案例：
+
+- `randomize_client_port`（頂層）— **FATAL**，已移除，改到 policy 檔設定 `"randomizeClientPort": true`。
+- `ephemeral_node_inactivity_timeout` — WARN，改名為 `node.ephemeral.inactivity_timeout`。
+
+**診斷**：
+```bash
+docker inspect headscale --format 'Status={{.State.Status}} RestartCount={{.RestartCount}}'
+docker logs --tail 20 headscale   # 找 FATAL 那行，會指出是哪個設定鍵
+```
+
+**修復**：依日誌把被移除的鍵在 `config/config.yaml` 註解掉（或依新版語法遷移），再重建容器：
+```bash
+docker-compose up -d --force-recreate
+docker inspect headscale --format '{{.State.Status}} {{.RestartCount}}'   # 應為 running / 0
+curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/health     # 應為 200
+```
+
+**根治建議**：把 image 釘到固定版本（如 `headscale/headscale:v0.26.0`），或移除 watchtower 標籤改為手動升級，避免破壞性更新自動套用（見「日常維護」）。
+
 #### 設備無法連接
 
 1. **檢查服務狀態**
@@ -368,6 +392,7 @@ headscale nodes list
 - [ ] 備份驗證測試
 - [ ] 檢查磁碟空間
 - [ ] 更新 Docker 映像：`docker pull headscale/headscale:latest`
+  > ⚠️ 升級前先看 [CHANGELOG](https://github.com/juanfont/headscale/blob/main/CHANGELOG.md) 的 BREAKING 段落，確認沒有被移除的設定鍵；建議釘版本而非用 `:latest` 自動更新（參見「故障排除 → 升級後容器無限重啟」）。
 - [ ] 檢查系統資源使用
 - [ ] 清理舊的日誌檔案
 

config/config.yaml

@@ -85,7 +85,9 @@ derp:
 disable_check_updates: false
 
 # ephemeral_node_inactivity_timeout: 臨時節點（ephemeral node）多久沒活動就自動刪除
-ephemeral_node_inactivity_timeout: 30m
+# ⚠️ 此鍵已於新版 Headscale 移除，改名為 node.ephemeral.inactivity_timeout（預設仍為 30m）。
+#    保留 30m 預設行為，故直接停用本鍵；如需自訂請改用新的 node.ephemeral.inactivity_timeout 區塊。
+# ephemeral_node_inactivity_timeout: 30m
 
 database:
   # type: 資料庫類型（可選 sqlite 或 postgres，建議用 sqlite）
@@ -225,5 +227,7 @@ logtail:
   enabled: false
 
 # randomize_client_port: 是否隨機使用 WireGuard port（預設 41641，開啟後會隨機挑 port，主要解決防火牆相容問題）
-# randomize_client_port: false
-randomize_client_port: true
+# ⚠️ 此頂層鍵已於新版 Headscale 移除，啟動會直接 FATAL（導致容器無限重啟）。
+#    新版改為在 policy 檔頂層設定 "randomizeClientPort": true（見 policy.path / policy.mode），
+#    或用 nodeAttrs 針對個別節點授權。一般家用情境不需要，維持預設即可。
+# randomize_client_port: true

docker-compose.yml

@@ -1,6 +1,8 @@
 services:
   headscale:
-    image: headscale/headscale:latest
+    # 釘版本避免 watchtower 自動套用破壞性更新（見 OPERATIONS.md → 故障排除）。
+    # 升級時手動改 tag 並先看 CHANGELOG 的 BREAKING 段落。
+    image: headscale/headscale:v0.29.0
     container_name: headscale
     restart: unless-stopped
     networks: