docs: add node naming convention and HTTP API rename method

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-21 13:56:52 +08:00
parent 566675c693
commit 0e35a3d164

View File

@@ -27,6 +27,26 @@ headscale nodes delete --identifier 6
headscale nodes delete --identifier 6 --force
```
**命名規約**:Linux 節點統一用 `ip-<內網IP>`(點改連字號),例如內網 `192.168.42.105``ip-192-168-42-105`。改名只動 headscale 的 `givenName`(`tailscale status` 顯示的名字);節點自報的 `name`(hostname)不受影響。
#### 用 HTTP API 改名(容器不在本機時)
當 headscale 容器不在當前機器、無法 `docker exec` 時,改用公開端點的 API。需要一把有效 API key(過期會回 `401`):
```bash
# 在 headscale 主機產生臨時 key
docker exec headscale headscale apikeys create --expiration 1h
# 查節點 ID(givenName 即顯示名)
curl -s -H "Authorization: Bearer <API_KEY>" \
https://headscale.lotimmy.com/api/v1/node \
| jq '.nodes[] | {id, givenName, name}'
# 改名:POST /api/v1/node/{id}/rename/{newName},成功回 HTTP 200
curl -s -X POST -H "Authorization: Bearer <API_KEY>" \
https://headscale.lotimmy.com/api/v1/node/45/rename/ip-192-168-42-105
```
### 節點標籤管理
```bash