fix(compose): exec-form healthcheck; enable embedded DERP (tw)

- healthcheck 改 exec 形式（distroless 映像無 /bin/sh，CMD-SHELL 永遠 unhealthy）
- 補 command: serve、對外開 3478/udp（DERP STUN）
- config.yaml 內建 DERP 設為 enabled（region tw），與線上實跑一致

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

config/config.yaml

@@ -1,233 +1,249 @@
 ---
-# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order:
+# ============================================================================
-#
+# Headscale 設定檔
-# - `/etc/headscale`
+# 檔案搜尋順序：/etc/headscale → ~/.headscale → 當前工作目錄
-# - `~/.headscale`
+# ============================================================================
-# - current working directory
+
+
+# ----------------------------------------------------------------------------
+# 伺服器與監聽位址
+# ----------------------------------------------------------------------------
 
 # server_url: 給客戶端連線用的網址
-# server_url: http://127.0.0.1:8080
 server_url: https://headscale.lotimmy.com
 
-# listen_addr: Headscale 綁定在哪個 IP:Port 等待連線
+# listen_addr: Headscale HTTP API 綁定的 IP:Port
-# listen_addr: 127.0.0.1:8080
 listen_addr: 0.0.0.0:8080
 
-# metrics_listen_addr: 提供 Prometheus 或其他監控系統抓取 metrics 的位址
+# metrics_listen_addr: Prometheus/監控系統抓取 metrics 的位址
-# metrics_listen_addr: 127.0.0.1:9090
 metrics_listen_addr: 0.0.0.0:9090
 
-# grpc_listen_addr: Headscale 提供 gRPC API 的服務位址，通常給內部或管理工具使用
+# grpc_listen_addr: gRPC API 服務位址（給內部或管理工具使用）
 grpc_listen_addr: 0.0.0.0:50443
-# grpc_listen_addr: 127.0.0.1:50443
 
-# grpc_allow_insecure: 是否允許 gRPC 使用未加密連線（建議保持 false 確保安全）
+# grpc_allow_insecure: 是否允許 gRPC 未加密連線（建議保持 false）
 grpc_allow_insecure: false
 
-# noise: Headscale 使用 Noise 協議加密與客戶端的流量
+# unix_socket: 本地 UNIX Socket 路徑
+unix_socket: /var/run/headscale/headscale.sock
+# unix_socket_permission: UNIX Socket 權限設定
+unix_socket_permission: "0770"
+
+
+# ----------------------------------------------------------------------------
+# Noise 加密協議
+# ----------------------------------------------------------------------------
+
 noise:
   # private_key_path: Noise 私鑰路徑，缺少時會自動生成
   private_key_path: /var/lib/headscale/noise_private.key
 
-# prefixes: 設定分配給節點的 IP 範圍（必須在 Tailscale 支援的範圍內）
+
+# ----------------------------------------------------------------------------
+# IP 位址分配（必須位於 Tailscale 支援的範圍內）
+# ----------------------------------------------------------------------------
+
 prefixes:
   # v4: IPv4 分配範圍（預設 100.64.0.0/10）
   v4: 100.64.0.0/10
   # v6: IPv6 分配範圍（預設 fd7a:115c:a1e0::/48）
   v6: fd7a:115c:a1e0::/48
-
+  # allocation: 分配策略（sequential 依序 / random 隨機）
-  # allocation: IP 分配策略（sequential 依序分配，random 隨機分配）
   allocation: sequential
 
-# derp: DERP 是 Tailscale 用來在無法直連時的中繼伺服器設定
+
+# ----------------------------------------------------------------------------
+# DERP 中繼伺服器（直連失敗時的備援通道）
+# ----------------------------------------------------------------------------
+
 derp:
-  # server: 內建的 DERP 伺服器設定
   server:
     # enabled: 是否啟用內建 DERP（需要 https/TLS）
-    enabled: false
+    enabled: true
 
-    # region_id: 內建 DERP 的區域 ID（避免與其他 DERP 衝突）
+    # region_id: 內建 DERP 區域 ID（避免與其他 DERP 衝突）
     region_id: 999
+    # region_code: 區域代碼（顯示於 Tailscale UI）
+    region_code: "tw"
+    # region_name: 區域名稱（顯示於 Tailscale UI）
+    region_name: "Headscale TW"
 
-    # region_code: 區域代碼（會顯示在 Tailscale UI）
+    # stun_listen_addr: STUN 服務監聽位址（協助 NAT 穿透）
-    region_code: "headscale"
-    # region_name: 區域名稱（會顯示在 Tailscale UI）
-    region_name: "Headscale Embedded DERP"
-
-    # stun_listen_addr: STUN 服務的監聽位址（協助 NAT 穿透）
     stun_listen_addr: "0.0.0.0:3478"
 
-    # private_key_path: 內建 DERP 使用的私鑰路徑，沒有會自動生成
+    # private_key_path: 內建 DERP 私鑰路徑，缺少時自動生成
     private_key_path: /var/lib/headscale/derp_server_private.key
 
-    # automatically_add_embedded_derp_region: 是否自動把內建 DERP 加進 DERP map
+    # automatically_add_embedded_derp_region: 自動把內建 DERP 加進 DERP map
     automatically_add_embedded_derp_region: true
 
-    # ipv4: 可選，將公開 IPv4 加入 DERP map（改善 Exit-Node 或 DNS 問題時的連線穩定性）
+    # ipv4 / ipv6: 公開 IP（改善 Exit-Node 或 DNS 問題時的連線穩定性）
-    ipv4: 1.2.3.4
+    ipv4: 125.229.110.50
-    # ipv6: 可選，將公開 IPv6 加入 DERP map
+    ipv6: 2001:b011:3012:373a:be24:11ff:fe40:a31a
-    ipv6: 2001:db8::1
 
   # urls: 外部可用的 DERP map JSON 清單
   urls:
     - https://controlplane.tailscale.com/derpmap/default
 
-  # paths: 本地的 DERP map YAML 檔路徑（通常用在自建 DERP 伺服器）
+  # paths: 本地 DERP map YAML 檔路徑（自建 DERP 伺服器使用）
   paths: []
 
-  # auto_update_enabled: 是否自動定期更新 DERP map
+  # auto_update_enabled: 自動定期更新 DERP map
   auto_update_enabled: true
-
   # update_frequency: DERP map 更新檢查頻率
   update_frequency: 24h
 
-# disable_check_updates: 是否停用 Headscale 啟動時自動檢查更新
-disable_check_updates: false
 
-# ephemeral_node_inactivity_timeout: 臨時節點（ephemeral node）多久沒活動就自動刪除
+# ----------------------------------------------------------------------------
-# ⚠️ 此鍵已於新版 Headscale 移除，改名為 node.ephemeral.inactivity_timeout（預設仍為 30m）。
+# 資料庫
-#    保留 30m 預設行為，故直接停用本鍵；如需自訂請改用新的 node.ephemeral.inactivity_timeout 區塊。
+# ----------------------------------------------------------------------------
-# ephemeral_node_inactivity_timeout: 30m
 
 database:
-  # type: 資料庫類型（可選 sqlite 或 postgres，建議用 sqlite）
+  # type: 資料庫類型（sqlite / postgres，建議 sqlite）
   type: sqlite
 
-  # debug: 是否啟用資料庫偵錯（需搭配 log.level=debug/trace）
+  # debug: 啟用資料庫偵錯（需搭配 log.level=debug/trace）
   debug: false
 
   gorm:
-    # prepare_stmt: 是否啟用 prepared statements
+    # prepare_stmt: 啟用 prepared statements
     prepare_stmt: true
-
+    # parameterized_queries: 啟用參數化查詢（安全性與效能）
-    # parameterized_queries: 是否啟用參數化查詢（提升安全性與效能）
     parameterized_queries: true
-
+    # skip_err_record_not_found: 略過「record not found」錯誤訊息
-    # skip_err_record_not_found: 是否略過「record not found」錯誤訊息
     skip_err_record_not_found: true
-
     # slow_threshold: 慢查詢閾值（毫秒）
     slow_threshold: 1000
 
   sqlite:
-    # path: SQLite 資料庫檔案的存放路徑
+    # path: SQLite 資料庫檔案路徑
     path: /var/lib/headscale/db.sqlite
-
+    # write_ahead_log: 啟用 WAL 模式（正式環境建議開啟）
-    # write_ahead_log: 是否啟用 WAL 模式（建議正式環境開啟，效能與穩定性更好）
     write_ahead_log: true
-
+    # wal_autocheckpoint: WAL 自動 checkpoint 閾值（frame，0 代表停用）
-    # wal_autocheckpoint: WAL 自動 checkpoint 閾值（單位 frame，0 代表停用自動 checkpoint）
     wal_autocheckpoint: 1000
 
-# acme_url: ACME 伺服器 URL（預設使用 Let's Encrypt）
-acme_url: https://acme-v02.api.letsencrypt.org/directory
 
-# acme_email: 註冊 ACME 憑證時的聯絡 email
+# ----------------------------------------------------------------------------
+# TLS / ACME 憑證
+# ----------------------------------------------------------------------------
+
+# acme_url: ACME 伺服器 URL（預設 Let's Encrypt）
+acme_url: https://acme-v02.api.letsencrypt.org/directory
+# acme_email: 註冊 ACME 憑證的聯絡 email
 acme_email: ""
 
 # tls_letsencrypt_hostname: 要申請憑證的網域名稱
 tls_letsencrypt_hostname: ""
-
+# tls_letsencrypt_cache_dir: 憑證與 metadata 存放路徑
-# tls_letsencrypt_cache_dir: 存放憑證與 metadata 的路徑
 tls_letsencrypt_cache_dir: /var/lib/headscale/cache
-
+# tls_letsencrypt_challenge_type: ACME 驗證方式（HTTP-01 或 TLS-ALPN-01）
-# tls_letsencrypt_challenge_type: ACME 驗證方式（支援 HTTP-01 或 TLS-ALPN-01）
 tls_letsencrypt_challenge_type: HTTP-01
-# tls_letsencrypt_listen: HTTP-01 驗證時使用的監聽位址（預設 80 port）
+# tls_letsencrypt_listen: HTTP-01 驗證監聽位址
 tls_letsencrypt_listen: ":http"
 
-# tls_cert_path: 已有憑證的檔案路徑（選填，不用 Let's Encrypt 時使用）
+# tls_cert_path / tls_key_path: 既有憑證路徑（不使用 Let's Encrypt 時填寫）
 tls_cert_path: ""
-# tls_key_path: 已有私鑰的檔案路徑（選填，不用 Let's Encrypt 時使用）
 tls_key_path: ""
 
+
+# ----------------------------------------------------------------------------
+# 日誌
+# ----------------------------------------------------------------------------
+
 log:
-  # format: 日誌輸出格式（text 或 json）
+  # format: 輸出格式（text / json）
   format: text
-  # level: 日誌等級（常見有 debug、info、warn、error）
+  # level: 日誌等級（debug / info / warn / error）
   level: info
 
+# logtail: 是否把 client 日誌送到 Tailscale 官方伺服器（預設關閉）
+logtail:
+  enabled: false
+
+
+# ----------------------------------------------------------------------------
+# ACL 政策
+# ----------------------------------------------------------------------------
+
 policy:
-  # mode: ACL 政策儲存方式（可選 file 或 database）
+  # mode: ACL 儲存方式（file / database）
   mode: file
-  # path: 當 mode=file 時，ACL HuJSON 檔案的路徑
+  # path: mode=file 時的 HuJSON 檔案路徑
   path: /etc/headscale/policy.hujson
 
 
+# ----------------------------------------------------------------------------
+# DNS 與 MagicDNS
+# ----------------------------------------------------------------------------
+
 dns:
-  # 啟用 MagicDNS，讓節點自動有 hostname
+  # magic_dns: 啟用 MagicDNS，讓節點自動取得 hostname
   magic_dns: true
 
-  # 要確定和 headscale server_url 不同網域，例如：
+  # base_domain: MagicDNS 基底網域（須與 server_url 網域不同）
-  # base_domain: example.com
   base_domain: internal.lotimmy.com
 
-  # override_local_dns: 是否強制使用 Headscale 的 DNS，覆蓋本地設定
+  # override_local_dns: 是否強制 tailnet 節點使用以下 DNS，覆蓋本地設定
-  # 如果希望 tailnet 裡所有節點都「強制」走這組 DNS，建議改成 true
+  #   true  → 所有節點強制走這組 DNS
-  # 若你還想保留各節點自己的 DNS（例如公司 VPN、家裡路由器內網），就維持 false
+  #   false → 保留各節點自己的 DNS（例如公司 VPN、家用路由器內網）
   override_local_dns: true
 
   # nameservers.global: 全域 DNS 伺服器清單
   nameservers:
     global:
+      # NextDNS（個人 DoH Profile，含封鎖清單與過濾規則）
+      - https://dns.nextdns.io/9c7b19
 
-      # NextDNS（你的專屬 DoH Profile）
+      # NextDNS 傳統 IPv4（fallback）
-      - https://dns.nextdns.io/9c7b19   # NextDNS DoH：完整支援你的個人設定、封鎖清單、過濾規則
+      - 45.90.28.37
+      - 45.90.30.37
 
-      # NextDNS IPv4 傳統 DNS（可作 fallback）
+      # Cloudflare DNS（快速、穩定）
-      - 45.90.28.37                     # NextDNS IPv4 主 DNS
+      - 1.1.1.1
-      - 45.90.30.37                     # NextDNS IPv4 副 DNS
+      - 1.0.0.1
+      - 2606:4700:4700::1111
+      - 2606:4700:4700::1001
+      - https://cloudflare-dns.com/dns-query
 
+      # Google DNS（高穩定度 fallback）
+      - https://dns.google/dns-query
 
-      # Cloudflare DNS（快速＋穩定）
+      # Quad9 DNS（側重惡意網站過濾）
-      - 1.1.1.1                         # Cloudflare IPv4 主 DNS（fallback）
+      - https://dns.quad9.net/dns-query
-      - 1.0.0.1                         # Cloudflare IPv4 副 DNS
-      - 2606:4700:4700::1111            # Cloudflare IPv6 主 DNS
-      - 2606:4700:4700::1001            # Cloudflare IPv6 副 DNS
-      - https://cloudflare-dns.com/dns-query   # Cloudflare DoH：快速＋加密
 
-      # Google DNS（可靠但不做安全過濾）
+    # nameservers.split: Split DNS，針對特定網域指定 DNS
-      - https://dns.google/dns-query    # Google DoH：高穩定度 fallback
+    split: {}
+    # 範例：
+    #   foo.bar.com:
+    #     - 1.1.1.1
+    #   darp.headscale.net:
+    #     - 1.1.1.1
+    #     - 8.8.8.8
 
-      # Quad9 DNS（帶惡意網站安全過濾）
+  # search_domains: 自訂搜尋網域（啟用 MagicDNS 時會自動加入 base_domain）
-      - https://dns.quad9.net/dns-query # Quad9 DoH：側重惡意網站與安全防護
-
-    # nameservers.split: Split DNS，每個網域指定不同 DNS 伺服器
-    split:
-      {}
-      # foo.bar.com:
-      #   - 1.1.1.1
-      # darp.headscale.net:
-      #   - 1.1.1.1
-      #   - 8.8.8.8
-
-  # search_domains: 自訂搜尋網域（啟用 MagicDNS 時，base_domain 會自動加在最前面）
   search_domains: []
 
-  # Extra DNS records
+  # extra_records: 額外 DNS 紀錄（目前僅支援 A 與 AAAA）
-  # so far only A and AAAA records are supported (on the tailscale side)
+  # 詳見 docs/ref/dns.md
-  # See: docs/ref/dns.md
-  # extra_records: 額外的 DNS 紀錄（支援 A 與 AAAA，可用檔案或直接寫在這裡）
   extra_records: []
   #   - name: "grafana.myvpn.example.com"
   #     type: "A"
   #     value: "100.64.0.3"
-  #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }
 
-  # extra_records_path: 額外 DNS 紀錄的 JSON 檔路徑（檔案變更時會自動載入） 
+  # extra_records_path: 額外 DNS 紀錄 JSON 檔案路徑（檔案變更時自動載入）
   # extra_records_path: /var/lib/headscale/extra-records.json
 
-# unix_socket: Headscale 提供本地 UNIX Socket 的路徑
-unix_socket: /var/run/headscale/headscale.sock
-# unix_socket_permission: UNIX Socket 的權限設定（例如 0770）
-unix_socket_permission: "0770"
 
-logtail:
+# ----------------------------------------------------------------------------
-  # enabled: 是否啟用 Logtail，把 client 日誌送到 Tailscale 官方伺服器（預設關閉）
+# 其他雜項
-  enabled: false
+# ----------------------------------------------------------------------------
 
-# randomize_client_port: 是否隨機使用 WireGuard port（預設 41641，開啟後會隨機挑 port，主要解決防火牆相容問題）
+# disable_check_updates: 停用 Headscale 啟動時自動檢查更新
-# ⚠️ 此頂層鍵已於新版 Headscale 移除，啟動會直接 FATAL（導致容器無限重啟）。
+disable_check_updates: false
-#    新版改為在 policy 檔頂層設定 "randomizeClientPort": true（見 policy.path / policy.mode），
+
-#    或用 nodeAttrs 針對個別節點授權。一般家用情境不需要，維持預設即可。
+# ephemeral_node_inactivity_timeout: 臨時節點閒置多久後自動刪除
-# randomize_client_port: true
+ephemeral_node_inactivity_timeout: 30m
+
+# randomize_client_port: 隨機選擇 WireGuard port（預設 41641），有助穿越嚴格防火牆
+# randomize_client_port:  # removed in new headscale; moved to policy file true

data/noise_private.key

@@ -1 +0,0 @@
-privkey:08a7dc8305baa74525b91b7d31a48dd8e91a13f812b732a7de4b4da8fef09d68

docker-compose.yml

@@ -1,9 +1,8 @@
 services:
   headscale:
-    # 釘版本避免 watchtower 自動套用破壞性更新（見 OPERATIONS.md → 故障排除）。
-    # 升級時手動改 tag 並先看 CHANGELOG 的 BREAKING 段落。
     image: headscale/headscale:v0.29.0
     container_name: headscale
+    command: serve
     restart: unless-stopped
     networks:
       - shared-net
@@ -14,7 +13,7 @@ services:
 
     # 健康檢查
     healthcheck:
-      test: ["CMD-SHELL", "headscale version >/dev/null 2>&1 || exit 1"]
+      test: ["CMD", "headscale", "version"]
       interval: 30s
       timeout: 10s
       retries: 3
@@ -38,6 +37,7 @@ services:
       - "8080:8080"    # HTTP API
       - "9090:9090"    # Metrics
       - "50443:50443"  # gRPC
+      - "3478:3478/udp" # DERP STUN
 
     # 標籤配置
     labels: