Create comprehensive README.md documentation
- Organize scattered README content into structured markdown - Add project overview and server information - Include quick start guide with Docker setup - Document device connection workflow - Provide node management operations - Add user and key management sections - Include network testing and daily commands - Add troubleshooting guide and port information - Organize content with proper headings and sections Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
252
README.md
Normal file
252
README.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Headscale 自托管網路控制平面
|
||||
|
||||
## 概述
|
||||
|
||||
這是一個自托管的 Headscale 伺服器設置，提供 Tailscale 相容的 WireGuard 網路控制平面，讓您可以完全掌控自己的設備連網需求。
|
||||
|
||||
## 伺服器資訊
|
||||
|
||||
- **公開端點**: https://headscale.lotimmy.com
|
||||
- **管理介面**:透過 Headscale CLI 或直接使用 Tailscale 客戶端
|
||||
|
||||
## 快速開始
|
||||
|
||||
### 1. 準備 Docker 網路
|
||||
|
||||
```bash
|
||||
docker network create shared-net
|
||||
```
|
||||
|
||||
### 2. 啟動服務
|
||||
|
||||
```bash
|
||||
# 背景執行
|
||||
make up
|
||||
|
||||
# 前景執行（除錯用）
|
||||
make up-fg
|
||||
```
|
||||
|
||||
### 3. 查看服務狀態
|
||||
|
||||
```bash
|
||||
make ps # 查看容器狀態
|
||||
make logs # 查看日誌
|
||||
```
|
||||
|
||||
## 設備連接指南
|
||||
|
||||
### 步驟 1: 產生預授權金鑰
|
||||
|
||||
```bash
|
||||
# 產生 10 年期預授權金鑰（推薦）
|
||||
headscale preauthkeys create \
|
||||
--user 1 \
|
||||
--reusable \
|
||||
--ephemeral=false \
|
||||
--expiration 87600h
|
||||
|
||||
# 短期金鑰（24 小時）
|
||||
headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 24h
|
||||
```
|
||||
|
||||
### 步驟 2: 設備連接
|
||||
|
||||
在您的設備上執行：
|
||||
|
||||
```bash
|
||||
# 基本連接
|
||||
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: 註冊節點
|
||||
|
||||
```bash
|
||||
headscale nodes register --user mainnet --key <設備返回的金鑰>
|
||||
```
|
||||
|
||||
## 節點管理
|
||||
|
||||
### 查看節點
|
||||
|
||||
```bash
|
||||
# 列出所有節點
|
||||
headscale nodes list
|
||||
|
||||
# JSON 格式輸出
|
||||
headscale nodes list --output json | jq '.[] | {id, name, tags: .forced_tags}'
|
||||
|
||||
# 查看路由
|
||||
headscale nodes list-routes
|
||||
```
|
||||
|
||||
### 節點標籤管理
|
||||
|
||||
```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 7 --tags tag:mobile # ipad-mini-6
|
||||
|
||||
# 移除所有標籤
|
||||
headscale nodes tag --identifier 13 --tags ""
|
||||
```
|
||||
|
||||
### 節點操作
|
||||
|
||||
```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
|
||||
|
||||
# 批准路由
|
||||
headscale nodes approve-routes --identifier 4 --routes 0.0.0.0/0,192.168.42.0/24,::/0
|
||||
```
|
||||
|
||||
## 使用者管理
|
||||
|
||||
```bash
|
||||
# 查看所有使用者
|
||||
headscale users list
|
||||
|
||||
# 重新命名使用者（namespace）
|
||||
headscale users rename --identifier 1 --new-name mainnet
|
||||
```
|
||||
|
||||
## 金鑰管理
|
||||
|
||||
### 預授權金鑰
|
||||
|
||||
```bash
|
||||
# 列出預授權金鑰
|
||||
headscale preauthkeys list --user 1
|
||||
```
|
||||
|
||||
### API 金鑰
|
||||
|
||||
```bash
|
||||
# 列出 API 金鑰
|
||||
headscale apikeys list
|
||||
|
||||
# 撤銷 API 金鑰
|
||||
headscale apikeys revoke <KEY_ID>
|
||||
```
|
||||
|
||||
## 網路測試
|
||||
|
||||
```bash
|
||||
# 測試內部連通性
|
||||
tailscale ping 100.64.0.4
|
||||
|
||||
# 查看 tailnet 節點列表
|
||||
tailscale status
|
||||
```
|
||||
|
||||
## 日常管理
|
||||
|
||||
### 服務控制
|
||||
|
||||
```bash
|
||||
make up # 啟動服務
|
||||
make down # 停止服務
|
||||
make restart # 重啟服務
|
||||
make logs # 查看日誌
|
||||
make exec # 進入容器
|
||||
```
|
||||
|
||||
### 備份與還原
|
||||
|
||||
```bash
|
||||
# 執行備份
|
||||
./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
|
||||
```
|
||||
|
||||
### 資料清理
|
||||
|
||||
```bash
|
||||
# 清理容器和資料
|
||||
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 設置
|
||||
|
||||
### 日誌查看
|
||||
|
||||
```bash
|
||||
# 查看 Headscale 日誌
|
||||
make logs
|
||||
|
||||
# 進入容器檢查
|
||||
make exec
|
||||
|
||||
# 查看 Docker 事件
|
||||
docker events --filter name=headscale
|
||||
```
|
||||
|
||||
## 參考資源
|
||||
|
||||
- [Headscale 官方文件](https://headscale.net/)
|
||||
- [Tailscale 文件](https://tailscale.com/kb/)
|
||||
- [WireGuard 文件](https://www.wireguard.com/)
|
||||
Reference in New Issue
Block a user