headscale/README.md

Headscale 自托管網路控制平面

概述

這是一個自托管的 Headscale 伺服器設置，提供 Tailscale 相容的 WireGuard 網路控制平面，讓您可以完全掌控自己的設備連網需求。

伺服器資訊

• 公開端點: https://headscale.lotimmy.com
• 管理介面:透過 Headscale CLI 或直接使用 Tailscale 客戶端

快速開始

1. 準備 Docker 網路

docker network create shared-net

2. 啟動服務

# 背景執行
make up

# 前景執行（除錯用）
make up-fg

3. 查看服務狀態

make ps      # 查看容器狀態
make logs    # 查看日誌

設備連接指南

步驟 1: 產生預授權金鑰

# 產生 10 年期預授權金鑰（推薦）
headscale preauthkeys create \
  --user 1 \
  --reusable \
  --ephemeral=false \
  --expiration 87600h

# 短期金鑰（24 小時）
headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 24h

步驟 2: 設備連接

在您的設備上執行：

# 基本連接
tailscale up --login-server https://headscale.lotimmy.com --auth-key <您的金鑰>

# 連接並接受路由（適用於客戶端）
tailscale up --login-server https://headscale.lotimmy.com --auth-key <您的金鑰> --accept-routes

# 作為 Exit Node 並宣告路由
tailscale up --reset \
  --login-server https://headscale.lotimmy.com \
  --advertise-exit-node \
  --advertise-routes=192.168.42.0/24 \
  --accept-routes=false

步驟 3: 註冊節點

headscale nodes register --user mainnet --key <設備返回的金鑰>

節點管理

查看節點

# 列出所有節點
headscale nodes list

# JSON 格式輸出
headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}'

# 查看路由
headscale nodes list-routes

節點標籤管理

# 給節點加上 server 或 mobile 標籤
headscale nodes tag --identifier 4 --tags tag:server    # ct102
headscale nodes tag --identifier 9 --tags tag:server    # 15-macbook-pro
headscale nodes tag --identifier 12 --tags tag:server   # ip-192-168-88-82

headscale nodes tag --identifier 2 --tags tag:mobile    # iphone-15-pro-max
headscale nodes tag --identifier 5 --tags tag:mobile    # apple-tv-bedroom
headscale nodes tag --identifier 7 --tags tag:mobile    # ipad-mini-6

# 移除所有標籤
headscale nodes tag --identifier 13 --tags ""

節點操作

# 重新命名節點
headscale nodes rename --identifier 2 iphone-15-pro-max
headscale nodes rename --identifier 4 ip-192-168-42-102

# 刪除節點
headscale nodes delete --identifier 6
headscale nodes delete --identifier 6 --force

# 批准路由
headscale nodes approve-routes --identifier 4 --routes 0.0.0.0/0,192.168.42.0/24,::/0

使用者管理

# 查看所有使用者
headscale users list

# 重新命名使用者（namespace）
headscale users rename --identifier 1 --new-name mainnet

金鑰管理

預授權金鑰

# 列出預授權金鑰
headscale preauthkeys list --user 1

API 金鑰

# 列出 API 金鑰
headscale apikeys list

# 撤銷 API 金鑰
headscale apikeys revoke <KEY_ID>

網路測試

# 測試內部連通性
tailscale ping 100.64.0.4

# 查看 tailnet 節點列表
tailscale status

日常管理

服務控制

make up      # 啟動服務
make down    # 停止服務
make restart # 重啟服務
make logs    # 查看日誌
make exec    # 進入容器

備份與還原

# 執行備份
./headscale_backup_and_restore.sh

# 手動備份
docker compose down
tar czvf headscale_backup_$(date +%Y%m%d_%H%M%S).tar.gz .
docker compose up -d

資料清理

# 清理容器和資料
make clean

# 清理未使用的 Docker 資源
make prune

網路配置

IP 範圍

• IPv4: 100.64.0.0/10 (Tailscale 相容)
• IPv6: fd7a:115c:a1e0::/48 (Tailscale 相容)

埠號

• 8080: Headscale HTTP API
• 9090: Prometheus 指標
• 50443: gRPC API

DNS 配置

• MagicDNS: 已啟用 (internal.lotimmy.com)
• 全域 DNS: NextDNS、Cloudflare、Google、Quad9
• 本地 DNS 覆蓋: 已啟用

ACL 政策與 Taildrive

ACL 政策以 HuJSON 檔管理，啟用方式為 config.yaml 的 policy.mode: file 與 policy.path: /etc/headscale/policy.hujson（對應 repo 的 config/policy.hujson）。

⚠️ 沒有 policy 檔時 headscale 預設「全部互通」；一旦啟用 policy，acls 變成唯一授權來源。policy.hujson 內務必保留 allow-all 規則，否則所有節點會立即斷線。

目前規則：

• acls：accept src=* dst=*:* —— 維持全互通。
• nodeAttrs：所有節點皆取得 drive:share / drive:access。
• grants：tailscale.com/cap/drive，所有 share 開放讀寫（rw）。

修改後驗證與套用：

# 驗證語法
docker exec headscale headscale policy check --file /etc/headscale/policy.hujson
# 查看目前生效的政策
docker exec headscale headscale policy get
# 套用（file 模式需重啟容器讀取）
make restart

Taildrive（節點間檔案分享）

需 headscale v0.29.0+（已支援 nodeAttrs / Taildrive policy）。分享端僅 Linux/macOS/Windows，iOS/Android 可存取。

# 分享端：把目錄分享出去
tailscale drive share <分享名稱> /要分享的/目錄
tailscale drive list

# 存取端
#   macOS/Windows：用 Finder/檔案總管連 WebDAV
#   Linux：掛載 http://100.100.100.100:8080/<tailnet>/<peer-name>/<分享名稱>

故障排除

常見問題

1. 設備無法連接

   • 檢查預授權金鑰是否有效
   • 確認服務正在運行 (make ps)
   • 檢查日誌 (make logs)

2. 路由無法使用

   • 確認節點標籤設置正確
   • 檢查路由是否已批准
   • 驗證子網路由格式

3. DNS 解析問題

   • 確認 MagicDNS 已啟用
   • 檢查 DNS 伺服器連通性
   • 驗證 base_domain 設置

日誌查看

# 查看 Headscale 日誌
make logs

# 進入容器檢查
make exec

# 查看 Docker 事件
docker events --filter name=headscale

參考資源

• Headscale 官方文件
• Tailscale 文件
• WireGuard 文件