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 覆蓋: 已啟用

故障排除

常見問題

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 文件