Timmy
c3f7ef2c75
- Remove old README file - Add QUICKSTART.md for quick setup (3-step process) - Add SUMMARY.md for project overview and architecture - Add OPERATIONS.md for detailed management procedures - Keep README.md as comprehensive main documentation - Organize content by purpose: quick start, overview, operations Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
6.3 KiB
6.3 KiB
Headscale 操作手冊
節點管理
查看節點狀態
# 列出所有節點
headscale nodes list
# JSON 格式輸出（含標籤）
headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}'
# 查看節點路由
headscale nodes list-routes
節點操作
# 重新命名節點
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
節點標籤管理
# 給節點加上 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 13 --tags ""
路由管理
# 批准路由（讓節點提供路由給其他節點）
headscale nodes approve-routes --identifier 4 --routes 0.0.0.0/0,192.168.42.0/24,::/0
headscale nodes approve-routes --identifier 5 --routes 192.168.42.0/24
金鑰管理
預授權金鑰（Pre-auth Keys）
# 產生 10 年期預授權金鑰
headscale preauthkeys create \
--user 1 \
--reusable \
--ephemeral=false \
--expiration 87600h
# 短期金鑰（24 小時）
headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 24h
# 列出預授權金鑰
headscale preauthkeys list --user 1
API 金鑰管理
# 列出 API 金鑰
headscale apikeys list
# 撤銷 API 金鑰
headscale apikeys revoke <KEY_ID>
# 使用腳本創建 API 金鑰
./create_headscale_api_key.sh
使用者管理
# 查看所有使用者
headscale users list
# 重新命名使用者（namespace）
headscale users rename --identifier 1 --new-name mainnet
設備連接流程
完整流程
- 產生預授權金鑰
headscale preauthkeys create \
--user 1 \
--reusable \
--ephemeral=false \
--expiration 87600h
- 設備連接
tailscale up --login-server https://headscale.lotimmy.com --auth-key <金鑰>
- 註冊節點
headscale nodes register --user mainnet --key <設備返回的金鑰>
- 配置標籤和路由
# 添加標籤
headscale nodes tag --identifier <id> --tags tag:server
# 批准路由（如果需要）
headscale nodes approve-routes --identifier <id> --routes 0.0.0.0/0,::/0
Exit Node 配置
作為 Exit Node
tailscale up --reset \
--login-server https://headscale.lotimmy.com \
--advertise-exit-node \
--advertise-routes=192.168.42.0/24 \
--accept-routes=false
使用 Exit Node
# 指定 Exit Node
tailscale up --exit-node=<節點名稱或 IP>
# 使用特定節點的路由
tailscale up --exit-node=<節點名稱> --accept-routes
備份與還原
自動備份
# 執行自動備份
./headscale_backup_and_restore.sh
手動備份
# 停止服務
make down
# 建立備份
tar czvf headscale_backup_$(date +%Y%m%d_%H%M%S).tar.gz .
# 重新啟動服務
make up
備份驗證
備份腳本會自動：
- 停止服務
- 建立壓縮檔
- 計算資料庫 MD5 檢查碼
- 重啟服務
- 複製到遠端備份伺服器
- 驗證遠端備份完整性
日誌監控
服務日誌
# 查看 Tail 日誌
make logs
# 進入容器檢查
make exec
# 實時監控
make logs -f
API 健康檢查
# API 檢查腳本
./api_user_request.sh
# 手動檢查 API
curl -s https://headscale.lotimmy.com:8080/v1/metrics | head -n 10
系統監控
# 查看 Docker 事件
docker events --filter name=headscale
# 檢查容器資源使用
docker stats headscale
網路測試
內部連通性測試
# 測試內部節點連通性
tailscale ping 100.64.0.4
tailscale ping <節點名稱>
# 查看 tailnet 網路狀態
tailscale status
# 測試路由
tailscale ping <內網 IP>
DNS 測試
# 測試 MagicDNS
nslookup <節點名稱>.internal.lotimmy.com
# 測試自訂 DNS
dig @1.1.1.1 example.com
故障排除
常見問題
設備無法連接
- 檢查服務狀態
make ps
make logs
- 檢查預授權金鑰
headscale preauthkeys list --user 1
- 檢查防火牆
# 檢查端口
netstat -tlnp | grep 8080
netstat -tlnp | grep 9090
netstat -tlnp | grep 50443
節點顯示離線
- 檢查 WireGuard 連接
wg show
- 重啟節點
tailscale down
tailscale up
- 檢查系統日誌
journalctl -u tailscale -f
路由無法使用
- 確認節點標籤
headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}'
- 確認路由批准
headscale nodes list-routes
- 檢查 ACL 政策
headscale policy check
DNS 問題
- 檢查 MagicDNS
nslookup <節點名稱>.internal.lotimmy.com
- 檢查 DNS 伺服器
curl -s https://dns.nextdns.io/health
- 重啟 DNS 服務
systemctl restart systemd-resolved
緊急處理
服務無法啟動
# 檢查配置檔案
headscale config check
# 檢查 Docker 日誌
make logs
# 清理 Docker 資源
make clean
make up
資料庫損壞
- 停止服務
make down
- 從備份還原
# 恢復備份檔案
tar xzvf headscale_backup_xxxx.tar.gz
# 重新啟動
make up
- 驗證資料
headscale nodes list
日常維護
每日檢查清單
- 檢查服務狀態：
make ps - 查看日誌錯誤：
make logs - 檢查連接節點數：
headscale nodes list | wc -l - 執行 API 檢查：
./api_user_request.sh - 檢查備份狀態（如果設定自動）
每週維護
- 備份驗證測試
- 檢查磁碟空間
- 更新 Docker 映像：
docker pull headscale/headscale:latest - 檢查系統資源使用
- 清理舊的日誌檔案
每月維護
- 更新系統軟體
- 重新審核 API 金鑰
- 測試災難還原流程
- 更新 ACL 政策
- 檢查安全性設定