headscale/README.md

# 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/)