# Headscale 自托管網路控制平面 - 專案概述

## 專案介紹

這是一個自托管的 Headscale 伺服器設置，提供 Tailscale 相容的 WireGuard 網路控制平面。讓您可以完全掌控自己的設備連網需求，建立安全可靠的私人網路。

## 功能特色

### 🔒 完全掌控
- 自訂 IP 範圍分配
- 完整的 ACL 政策控制
- 可自訂的 DNS 設置
- 支援 Exit Node 和路由宣告

### 🌐 高可用性
- Docker 容器化部署
- 自動重啟機制
- 監控指標收集（Prometheus）
- 完整的備份還原系統

### 🛡️ 安全保障
- 預授權金鑰系統
- API 金鑰管理
- TLS 加密通訊
- 節點標籤分類
- HuJSON ACL 政策（`policy.hujson`）

### 📂 檔案分享
- Taildrive 節點間目錄分享（需 v0.29.0+）
- 由 ACL `nodeAttrs` / `grants` 控管分享與讀寫權限

### 📱 便管理
- 中文介面和註解
- 自動化管理腳本
- 健康檢查機制
- 詳細的日誌記錄

## 架構概覽

```
┌─────────────────┐     ┌─────────────────┐
│   設備 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 授權。