From 0e94b7c1cd14721dfaafc2ba97d10a64931d9c90 Mon Sep 17 00:00:00 2001
From: Timmy <loyangchun@gmail.com>
Date: Thu, 18 Jun 2026 18:36:46 +0800
Subject: [PATCH] docs: document ACL policy and Taildrive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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>
---
 CLAUDE.md     |  8 +++++++-
 OPERATIONS.md | 34 ++++++++++++++++++++++++++++++++++
 README.md     | 37 +++++++++++++++++++++++++++++++++++++
 SUMMARY.md    |  5 +++++
 4 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3045c77..9b89980 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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/
diff --git a/OPERATIONS.md b/OPERATIONS.md
index c14772e..0f411a1 100644
--- a/OPERATIONS.md
+++ b/OPERATIONS.md
@@ -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
+```
+
 ## 設備連接流程
 
 ### 完整流程
diff --git a/README.md b/README.md
index c810d74..f7fb5cd 100644
--- a/README.md
+++ b/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>/<分享名稱>
+```
+
 ## 故障排除
 
 ### 常見問題
diff --git a/SUMMARY.md b/SUMMARY.md
index 700013b..5c44e94 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -23,6 +23,11 @@
 - API 金鑰管理
 - TLS 加密通訊
 - 節點標籤分類
+- HuJSON ACL 政策（`policy.hujson`）
+
+### 📂 檔案分享
+- Taildrive 節點間目錄分享（需 v0.29.0+）
+- 由 ACL `nodeAttrs` / `grants` 控管分享與讀寫權限
 
 ### 📱 便管理
 - 中文介面和註解