From 8009785e257deffaf66bb95c192a6bf279567182 Mon Sep 17 00:00:00 2001
From: Timmy <loyangchun@gmail.com>
Date: Sun, 21 Jun 2026 13:56:52 +0800
Subject: [PATCH] docs: add node naming convention and HTTP API rename method

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 OPERATIONS.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/OPERATIONS.md b/OPERATIONS.md
index 0f411a1..68c3acc 100644
--- a/OPERATIONS.md
+++ b/OPERATIONS.md
@@ -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