headscale/SUMMARY.md

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