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 <noreply@anthropic.com>
This commit is contained in:
2026-03-24 10:26:22 +08:00
parent c3f7daa99e
commit c3f7ef2c75
4 changed files with 557 additions and 107 deletions

380
OPERATIONS.md Normal file
View File

@@ -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 <KEY_ID>
# 使用腳本創建 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 <id> --tags tag:server
# 批准路由(如果需要)
headscale nodes approve-routes --identifier <id> --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 政策
- [ ] 檢查安全性設定

70
QUICKSTART.md Normal file
View File

@@ -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 章節

107
README
View File

@@ -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 <KEY_ID>
# 為指定節點加上 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

107
SUMMARY.md Normal file
View File

@@ -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 授權。