From c3f7ef2c7552c3a78aaab1b17dae786de48cd737 Mon Sep 17 00:00:00 2001 From: Timmy Date: Tue, 24 Mar 2026 10:26:22 +0800 Subject: [PATCH] Restructure documentation files for better organization - 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 --- OPERATIONS.md | 380 ++++++++++++++++++++++++++++++++++++++++++++++++++ QUICKSTART.md | 70 ++++++++++ README | 107 -------------- SUMMARY.md | 107 ++++++++++++++ 4 files changed, 557 insertions(+), 107 deletions(-) create mode 100644 OPERATIONS.md create mode 100644 QUICKSTART.md delete mode 100644 README create mode 100644 SUMMARY.md diff --git a/OPERATIONS.md b/OPERATIONS.md new file mode 100644 index 0000000..48c2c64 --- /dev/null +++ b/OPERATIONS.md @@ -0,0 +1,380 @@ +# Headscale 操作手冊 + +## 節點管理 + +### 查看節點狀態 + +```bash +# 列出所有節點 +headscale nodes list + +# JSON 格式輸出（含標籤） +headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}' + +# 查看節點路由 +headscale nodes list-routes +``` + +### 節點操作 + +```bash +# 重新命名節點 +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 +``` + +### 節點標籤管理 + +```bash +# 給節點加上 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 "" +``` + +### 路由管理 + +```bash +# 批准路由（讓節點提供路由給其他節點） +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） + +```bash +# 產生 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 金鑰管理 + +```bash +# 列出 API 金鑰 +headscale apikeys list + +# 撤銷 API 金鑰 +headscale apikeys revoke + +# 使用腳本創建 API 金鑰 +./create_headscale_api_key.sh +``` + +## 使用者管理 + +```bash +# 查看所有使用者 +headscale users list + +# 重新命名使用者（namespace） +headscale users rename --identifier 1 --new-name mainnet +``` + +## 設備連接流程 + +### 完整流程 + +1. **產生預授權金鑰** +```bash +headscale preauthkeys create \ + --user 1 \ + --reusable \ + --ephemeral=false \ + --expiration 87600h +``` + +2. **設備連接** +```bash +tailscale up --login-server https://headscale.lotimmy.com --auth-key <金鑰> +``` + +3. **註冊節點** +```bash +headscale nodes register --user mainnet --key <設備返回的金鑰> +``` + +3. **配置標籤和路由** +```bash +# 添加標籤 +headscale nodes tag --identifier --tags tag:server + +# 批准路由（如果需要） +headscale nodes approve-routes --identifier --routes 0.0.0.0/0,::/0 +``` + +## Exit Node 配置 + +### 作為 Exit Node + +```bash +tailscale up --reset \ + --login-server https://headscale.lotimmy.com \ + --advertise-exit-node \ + --advertise-routes=192.168.42.0/24 \ + --accept-routes=false +``` + +### 使用 Exit Node + +```bash +# 指定 Exit Node +tailscale up --exit-node=<節點名稱或 IP> + +# 使用特定節點的路由 +tailscale up --exit-node=<節點名稱> --accept-routes +``` + +## 備份與還原 + +### 自動備份 + +```bash +# 執行自動備份 +./headscale_backup_and_restore.sh +``` + +### 手動備份 + +```bash +# 停止服務 +make down + +# 建立備份 +tar czvf headscale_backup_$(date +%Y%m%d_%H%M%S).tar.gz . + +# 重新啟動服務 +make up +``` + +### 備份驗證 + +備份腳本會自動： +1. 停止服務 +2. 建立壓縮檔 +3. 計算資料庫 MD5 檢查碼 +4. 重啟服務 +5. 複製到遠端備份伺服器 +6. 驗證遠端備份完整性 + +## 日誌監控 + +### 服務日誌 + +```bash +# 查看 Tail 日誌 +make logs + +# 進入容器檢查 +make exec + +# 實時監控 +make logs -f +``` + +### API 健康檢查 + +```bash +# API 檢查腳本 +./api_user_request.sh + +# 手動檢查 API +curl -s https://headscale.lotimmy.com:8080/v1/metrics | head -n 10 +``` + +### 系統監控 + +```bash +# 查看 Docker 事件 +docker events --filter name=headscale + +# 檢查容器資源使用 +docker stats headscale +``` + +## 網路測試 + +### 內部連通性測試 + +```bash +# 測試內部節點連通性 +tailscale ping 100.64.0.4 +tailscale ping <節點名稱> + +# 查看 tailnet 網路狀態 +tailscale status + +# 測試路由 +tailscale ping <內網 IP> +``` + +### DNS 測試 + +```bash +# 測試 MagicDNS +nslookup <節點名稱>.internal.lotimmy.com + +# 測試自訂 DNS +dig @1.1.1.1 example.com +``` + +## 故障排除 + +### 常見問題 + +#### 設備無法連接 + +1. **檢查服務狀態** +```bash +make ps +make logs +``` + +2. **檢查預授權金鑰** +```bash +headscale preauthkeys list --user 1 +``` + +3. **檢查防火牆** +```bash +# 檢查端口 +netstat -tlnp | grep 8080 +netstat -tlnp | grep 9090 +netstat -tlnp | grep 50443 +``` + +#### 節點顯示離線 + +1. **檢查 WireGuard 連接** +```bash +wg show +``` + +2. **重啟節點** +```bash +tailscale down +tailscale up +``` + +3. **檢查系統日誌** +```bash +journalctl -u tailscale -f +``` + +#### 路由無法使用 + +1. **確認節點標籤** +```bash +headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}' +``` + +2. **確認路由批准** +```bash +headscale nodes list-routes +``` + +3. **檢查 ACL 政策** +```bash +headscale policy check +``` + +#### DNS 問題 + +1. **檢查 MagicDNS** +```bash +nslookup <節點名稱>.internal.lotimmy.com +``` + +2. **檢查 DNS 伺服器** +```bash +curl -s https://dns.nextdns.io/health +``` + +3. **重啟 DNS 服務** +```bash +systemctl restart systemd-resolved +``` + +### 緊急處理 + +#### 服務無法啟動 + +```bash +# 檢查配置檔案 +headscale config check + +# 檢查 Docker 日誌 +make logs + +# 清理 Docker 資源 +make clean +make up +``` + +#### 資料庫損壞 + +1. **停止服務** +```bash +make down +``` + +2. **從備份還原** +```bash +# 恢復備份檔案 +tar xzvf headscale_backup_xxxx.tar.gz + +# 重新啟動 +make up +``` + +3. **驗證資料** +```bash +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 政策 +- [ ] 檢查安全性設定 \ No newline at end of file diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..405fae8 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,70 @@ +# Headscale 快速上手指南 + +## 伺服器資訊 + +- **公開端點**: https://headscale.lotimmy.com +- **管理介面**: 透過 Headscale CLI 或 Tailscale 客戶端 + +## 三步快速啟動 + +### 1. 準備環境 + +```bash +# 建立 Docker 網路 +docker network create shared-net + +# 啟動服務 +make up + +# 查看狀態 +make ps +``` + +### 2. 設備連接 + +```bash +# 產生預授權金鑰 +headscale preauthkeys create \ + --user 1 \ + --reusable \ + --ephemeral=false \ + --expiration 87600h + +# 設備連接指令 +tailscale up --login-server https://headscale.lotimmy.com --auth-key <金鑰> +``` + +### 3. 註冊節點 + +```bash +# 在設備連接後執行 +headscale nodes register --user mainnet --key <設備返回的金鑰> +``` + +## 常用指令 + +### 服務管理 +```bash +make up # 啟動服務 +make down # 停止服務 +make restart # 重啟服務 +make logs # 查看日誌 +``` + +### 節點管理 +```bash +headscale nodes list # 查看節點 +headscale nodes tag --id 4 --tags tag:server # 標記節點 +``` + +### 健康檢查 +```bash +./api_user_request.sh # API 檢查 +make logs # 服務日誌 +``` + +## 下一步 + +- 查看 [README.md](README.md) 獲取完整文件 +- 查看節點狀態：`headscale nodes list` +- 配置 Exit Node：參考 README 中的 Exit Node 章節 \ No newline at end of file diff --git a/README b/README deleted file mode 100644 index 35dfe1d..0000000 --- a/README +++ /dev/null @@ -1,107 +0,0 @@ -https://headscale.lotimmy.com - -docker network create shared-net - -# Create a pre-auth key -headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 24h - -# Create a pre-auth key with long expiration -headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 87600h - -headscale preauthkeys create \ - --user 1 \ # 給 ID 是 1 的人用（記得先用 list 查 ID） - --reusable \ # 拿到這組 key，你想裝幾台機器都可以，不用換 - --ephemeral=false \ # 機器離線後名字還是會留著，不會被系統踢掉 - --expiration 87600h # 有效期開到最滿（10 年），懶人必備，不用每年重弄 - - -HS_十年金鑰 -2026-01-14T03:31:35Z TRC expiration has been set expiration=315360000000 -ef127d5251adc78d0250f869d00e5454e40612ba47f4ce80 - - -tailscale up --login-server <你的網址> --auth-key <指令產生的金鑰> -tailscale up --login-server https://headscale.lotimmy.com --auth-key ef127d5251adc78d0250f869d00e5454e40612ba47f4ce80 -tailscale up --login-server https://headscale.lotimmy.com --auth-key ef127d5251adc78d0250f869d00e5454e40612ba47f4ce80 --accept-routes - -# Register a node -headscale nodes register --user USERNAME --key 2HdYHEaOQ30UUckHXt_dBYZr -headscale nodes register --user mainnet --key tzDlexiDOMMIOlJUlkQUADTy -headscale nodes register --user mainnet --key WxG-YH2yUTAz4Vf5bJaiJxG4 -headscale nodes register --user mainnet --key xi1HU_5AJqJXdKIhLY4E8WiU -headscale nodes register --user mainnet --key t1o75XesCYNkVJxUnm-VNIst -headscale nodes register --user mainnet --key lvfjwzg2KeISpdJtMtqMNeFN -headscale nodes register --user mainnet --key 4L66v9uDIuzJdgeo4dupGLfL -headscale nodes register --key 7oLjwdXp0OyIlrRbEZr35Gwv --user mainnet - -# List routes -headscale nodes list-routes - -# Approve routes -headscale nodes approve-routes --identifier 3 --routes 0.0.0.0/0,::/0 -headscale nodes approve-routes --identifier 4 --routes 0.0.0.0/0,192.168.42.0/24,::/0 -headscale nodes approve-routes --identifier 33 --routes 0.0.0.0/0,192.168.42.0/24,::/0 -headscale nodes approve-routes --identifier 5 --routes 192.168.42.0/24 -headscale nodes approve-routes --identifier 6 --routes 0.0.0.0/0,192.168.88.0/24,::/0 -headscale nodes approve-routes --identifier 19 --routes 0.0.0.0/0,192.168.88.0/24,::/0 - -# List all nodes -headscale nodes list -headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}' - - -# Rename nodes -headscale nodes rename --identifier 2 iphone-15-pro-max -headscale nodes rename --identifier 4 ip-192-168-42-102 -headscale nodes rename --identifier 5 apple-tv-bedroom -headscale nodes rename --identifier 7 ipad-mini-6 -headscale nodes rename --identifier 7 iphone-12 -headscale nodes rename --identifier 38 galaxy-tab-a - -# Delete node 6 -headscale nodes delete --identifier 6 -headscale nodes delete --identifier 6 --force - -# List pre-auth keys -headscale preauthkeys list --user 1 - - -# List API keys -headscale apikeys list - -# Revoke API key -headscale apikeys revoke - -# 為指定節點加上 server 或 mobile 的 tag -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 13 --tags tag:server # ip-141-11-93-252 - -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 8 --tags tag:mobile # oppo-a74-5g -headscale nodes tag --identifier 11 --tags tag:mobile # iphone-xr - -# 移除指定節點（ID 13）的所有 tags -headscale nodes tag --identifier 13 --tags "" - - -# 查看所有使用者 -headscale users list - -# 將 ID 1 的使用者（namespace）改名為 mainnet -headscale users rename --identifier 1 --new-name mainnet - - -# ping 內部 tailnet 節點（例：100.64.0.4） -tailscale ping 100.64.0.4 - - - -tailscale up --reset \ - --login-server https://headscale.lotimmy.com \ - --advertise-exit-node \ - --advertise-routes=192.168.42.0/24 \ - --accept-routes=false diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..700013b --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,107 @@ +# Headscale 自托管網路控制平面 - 專案概述 + +## 專案介紹 + +這是一個自托管的 Headscale 伺服器設置，提供 Tailscale 相容的 WireGuard 網路控制平面。讓您可以完全掌控自己的設備連網需求，建立安全可靠的私人網路。 + +## 功能特色 + +### 🔒 完全掌控 +- 自訂 IP 範圍分配 +- 完整的 ACL 政策控制 +- 可自訂的 DNS 設置 +- 支援 Exit Node 和路由宣告 + +### 🌐 高可用性 +- Docker 容器化部署 +- 自動重啟機制 +- 監控指標收集（Prometheus） +- 完整的備份還原系統 + +### 🛡️ 安全保障 +- 預授權金鑰系統 +- API 金鑰管理 +- TLS 加密通訊 +- 節點標籤分類 + +### 📱 便管理 +- 中文介面和註解 +- 自動化管理腳本 +- 健康檢查機制 +- 詳細的日誌記錄 + +## 架構概覽 + +``` +┌─────────────────┐ ┌─────────────────┐ +│ 設備 A │ │ 設備 B │ +│ (iOS/Android) │ │ (macOS/Linux) │ +└─────────┬───────┘ └─────────┬───────┘ + │ │ + │ WireGuard (端口隨機) │ + │ │ + └──────────┬───────────┘ + │ + ┌──────────▼───────────┐ + │ Headscale 控制平面 │ + │ (Docker 容器) │ + │ - API Server (8080) │ + │ - Metrics (9090) │ + │ - gRPC (50443) │ + └──────────┬───────────┘ + │ + ┌──────────▼───────────┐ + │ 資料持久化層 │ + │ - SQLite 資料庫 │ + │ - 加密金鑰 │ + │ - 配置檔案 │ + └──────────────────────┘ +``` + +## 技術棧 + +### 核心技術 +- **Headscale**: WireGuard 控制平面 +- **Docker**: 容器化部署 +- **Docker Compose**: 服務編排 +- **SQLite**: 資料庫 +- **WireGuard**: 加密隧道協議 + +### 網路技術 +- **IP 範圍**: 100.64.0.0/10 (IPv4), fd7a:115c:a1e0::/48 (IPv6) +- **DNS**: NextDNS + Cloudflare + Google 多重備援 +- **協議**: HTTPS, gRPC, WireGuard + +### 管理工具 +- **Make**: 自動化腳本 +- **Shell Scripts**: 各種管理操作 +- **Tailscale Client**: 設備端連接 + +## 部署環境 + +- **伺服器**: 支援 Docker 的 Linux 系統 +- **記憶體**: 建議 512MB+（視節點數量） +- **儲存**: 建議 1GB+（含備份空間） +- **網路**: 需要公開 HTTPS 端點 + +## 使用場景 + +### 個人使用 +- 家庭設備安全連接 +- 遠端辦公網路 +- 個人雲端服務連接 + +- 企業部署 +- 分支機構連接 +- 遠端員工存取 +- 安全的內網通訊 + +## 版本控制 + +- Git 倉庫: http://192.168.42.124:31337/timmy/headscale.git +- 分支: master +- 最後更新: $(date) + +## 授權資訊 + +基於 Headscale 開源專案部署，遵循 Apache 2.0 授權。 \ No newline at end of file