docs: document ACL policy and Taildrive
- README: 新增「ACL 政策與 Taildrive」章節（啟用方式、現行規則、使用指令） - OPERATIONS: 新增 ACL 政策管理 + Taildrive 操作章節 - CLAUDE.md: Core Components 加入 policy.hujson、image 改為 v0.29.0；補 policy 結構說明 - SUMMARY: 功能特色加入 ACL policy 與 Taildrive 檔案分享 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -50,8 +50,9 @@ Production deployment of **Headscale** - a self-hosted WireGuard control plane p
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
- **Headscale Service**: Docker container (`headscale/headscale:latest`)
|
||||
- **Headscale Service**: Docker container, pinned to `headscale/headscale:v0.29.0` (do not use `:latest` — breaking config changes crash-loop the container)
|
||||
- **Configuration**: `/config/config.yaml` with extensive Chinese comments
|
||||
- **ACL Policy**: `/config/policy.hujson` (HuJSON), enabled via `policy.mode: file` + `policy.path`. Holds the allow-all ACL plus Taildrive `nodeAttrs`/`grants`
|
||||
- **Data Storage**: `/data` directory containing SQLite database, keys, and certificates
|
||||
- **Networking**: Three ports exposed (8080 HTTP API, 9090 metrics, 50443 gRPC)
|
||||
- **External Network**: Requires `shared-net` Docker network
|
||||
@@ -64,6 +65,11 @@ The `config.yaml` file contains:
|
||||
- **Authentication**: API key and pre-authentication key system
|
||||
- **Database**: SQLite with WAL mode for performance
|
||||
|
||||
The `policy.hujson` file contains:
|
||||
- **acls**: allow-all (`accept * -> *:*`) to preserve full-mesh — REQUIRED, removing it locks out every node
|
||||
- **nodeAttrs**: grants `drive:share` / `drive:access` to all nodes (Taildrive)
|
||||
- **grants**: `tailscale.com/cap/drive` with all shares set to `rw` (Taildrive read/write)
|
||||
|
||||
### Data Persistence Structure
|
||||
```
|
||||
/data/
|
||||
|
||||
@@ -92,6 +92,40 @@ headscale users list
|
||||
headscale users rename --identifier 1 --new-name mainnet
|
||||
```
|
||||
|
||||
## ACL 政策管理
|
||||
|
||||
政策檔：`config/policy.hujson`（容器內 `/etc/headscale/policy.hujson`），由 `config.yaml` 的 `policy.mode: file` + `policy.path` 啟用。
|
||||
|
||||
```bash
|
||||
# 驗證語法（套用前務必先跑）
|
||||
docker exec headscale headscale policy check --file /etc/headscale/policy.hujson
|
||||
|
||||
# 查看目前生效的政策
|
||||
docker exec headscale headscale policy get
|
||||
|
||||
# 修改後套用（file 模式於啟動時讀取，需重啟）
|
||||
make restart
|
||||
```
|
||||
|
||||
> ⚠️ 啟用 policy 後，`acls` 是唯一授權來源。`policy.hujson` 須保留 allow-all（`accept * -> *:*`）才能維持全互通，否則節點立即斷線。修改後務必確認 `headscale nodes list` 仍 online 且能 `tailscale ping`。
|
||||
|
||||
### Taildrive（節點間檔案分享）
|
||||
|
||||
權限由 policy 控制：`nodeAttrs` 授予 `drive:share` / `drive:access`，`grants` 用 `tailscale.com/cap/drive` 指定 share 範圍與讀寫權限（`rw` / `ro`）。需 headscale v0.29.0+。
|
||||
|
||||
```bash
|
||||
# 分享端（Linux/macOS/Windows）
|
||||
tailscale drive share <分享名稱> /要分享的/目錄
|
||||
tailscale drive list
|
||||
tailscale drive unshare <分享名稱>
|
||||
|
||||
# 存取端（Linux 掛 WebDAV）
|
||||
# http://100.100.100.100:8080/<tailnet>/<peer-name>/<分享名稱>
|
||||
|
||||
# 確認能力已下發到節點
|
||||
docker exec tailscale tailscale debug netmap | grep -i drive
|
||||
```
|
||||
|
||||
## 設備連接流程
|
||||
|
||||
### 完整流程
|
||||
|
||||
37
README.md
37
README.md
@@ -213,6 +213,43 @@ make prune
|
||||
- **全域 DNS**: NextDNS、Cloudflare、Google、Quad9
|
||||
- **本地 DNS 覆蓋**: 已啟用
|
||||
|
||||
## ACL 政策與 Taildrive
|
||||
|
||||
ACL 政策以 HuJSON 檔管理，啟用方式為 `config.yaml` 的 `policy.mode: file` 與 `policy.path: /etc/headscale/policy.hujson`（對應 repo 的 `config/policy.hujson`）。
|
||||
|
||||
> ⚠️ 沒有 policy 檔時 headscale 預設「全部互通」；一旦啟用 policy，`acls` 變成唯一授權來源。`policy.hujson` 內務必保留 allow-all 規則，否則所有節點會立即斷線。
|
||||
|
||||
目前規則：
|
||||
|
||||
- **acls**：`accept src=* dst=*:*` —— 維持全互通。
|
||||
- **nodeAttrs**：所有節點皆取得 `drive:share` / `drive:access`。
|
||||
- **grants**：`tailscale.com/cap/drive`，所有 share 開放讀寫（`rw`）。
|
||||
|
||||
修改後驗證與套用：
|
||||
|
||||
```bash
|
||||
# 驗證語法
|
||||
docker exec headscale headscale policy check --file /etc/headscale/policy.hujson
|
||||
# 查看目前生效的政策
|
||||
docker exec headscale headscale policy get
|
||||
# 套用（file 模式需重啟容器讀取）
|
||||
make restart
|
||||
```
|
||||
|
||||
### Taildrive（節點間檔案分享）
|
||||
|
||||
需 headscale v0.29.0+（已支援 `nodeAttrs` / Taildrive policy）。分享端僅 Linux/macOS/Windows，iOS/Android 可存取。
|
||||
|
||||
```bash
|
||||
# 分享端：把目錄分享出去
|
||||
tailscale drive share <分享名稱> /要分享的/目錄
|
||||
tailscale drive list
|
||||
|
||||
# 存取端
|
||||
# macOS/Windows：用 Finder/檔案總管連 WebDAV
|
||||
# Linux：掛載 http://100.100.100.100:8080/<tailnet>/<peer-name>/<分享名稱>
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常見問題
|
||||
|
||||
@@ -23,6 +23,11 @@
|
||||
- API 金鑰管理
|
||||
- TLS 加密通訊
|
||||
- 節點標籤分類
|
||||
- HuJSON ACL 政策（`policy.hujson`）
|
||||
|
||||
### 📂 檔案分享
|
||||
- Taildrive 節點間目錄分享（需 v0.29.0+）
|
||||
- 由 ACL `nodeAttrs` / `grants` 控管分享與讀寫權限
|
||||
|
||||
### 📱 便管理
|
||||
- 中文介面和註解
|
||||
|
||||
Reference in New Issue
Block a user