Files

timmy fc9d72e12d docs: add Setup Keys / PAT guide with API rename workaround

Document Setup Keys concept vs SSO, PAT creation and usage, and the
workaround for renaming a setup key — the API silently ignores the
name field on PUT, so the fix is to UPDATE store.db directly and
restart netbird-server.

2026-04-18 09:44:48 +08:00

5.2 KiB

Raw Blame History

Setup Keys 與 Personal Access Token (PAT)

本文整理 NetBird Setup Keys 的概念、PAT 的使用、以及一個 API 實作限制的繞道方法。

Setup Keys：用途

Setup Key 是 NetBird 的 預先認證 token，讓裝置可以免互動登入直接加入網路。

兩種註冊方式

方式	指令/流程	適用
SSO 登入（互動式）	App 開瀏覽器 → OAuth2 → 授權	手機、筆電等個人裝置
Setup Key（非互動）	`netbird up --setup-key <UUID>`	伺服器、容器、CI、IoT

Key 的屬性

Reusable / One-off：一次性或可重複使用
Expires：有效期限（可設定永不過期）
Peer Expiration：加入的 peer 幾天後要重新認證
Auto-assigned Groups：自動加入指定群組
Ephemeral：peer 離線後自動清除（適合 CI / 短命容器）
Usage Limit：被使用次數上限

為什麼不建議給手機用

NetBird UI 會顯示警告：

Using setup keys for user devices is not recommended. SSO with MFA provides stronger security, proper user-device association, and periodic re-authentication.

沒有使用者歸屬，Activity Log 難追溯
缺少 MFA
沒有週期性重新認證
token 形式是一串 UUID，外洩後任何人都能加入

推薦做法：個人裝置（手機、筆電）走 SSO；機器/自動化用 Setup Key。

Personal Access Token (PAT)：API 存取

要用 NetBird API 操作資源（list、revoke、建立 setup key 等），需要一把 PAT。

如何建立 PAT

Dashboard → Team → Users → 你自己 → Personal Access Tokens → Create Token
填：
- Name：易辨識的名稱（例：Claude-API、admin-cli、ansible）
- Expires in：1 – 365 天（強制有期限，無法永不過期）
按 Create Token → Token 只會顯示一次，務必立刻複製保存

PAT 為什麼強制有效期限

這是安全設計：就算 token 外洩，風險也有上限。建議做法：

用密碼管理器（1Password、Bitwarden 等）存放
命名包含用途（方便日後識別哪把是哪把）
到期前 Dashboard 會有提醒
長期用途（例如 IaC 腳本），排進年度維運任務重建

PAT API 用法

TOKEN=nbp_xxxxxxxx

# 列出所有 setup keys
curl -sf -H "Authorization: Token $TOKEN" \
  https://netbird.timmy.us.kg/api/setup-keys | jq

# 查看單一 setup key
curl -sf -H "Authorization: Token $TOKEN" \
  https://netbird.timmy.us.kg/api/setup-keys/<ID> | jq

# Revoke 一把 setup key
curl -X PUT -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"...", "auto_groups":[], "revoked":true}' \
  https://netbird.timmy.us.kg/api/setup-keys/<ID>

陷阱：API 無法更新 Setup Key 的名稱

症狀

對 PUT /api/setup-keys/<id> 送出含 "name":"新名字" 的 payload，API 回 HTTP 200 且 updated_at 有更新，但 name 實際沒變。

原因

NetBird 的 setup-key update handler 只處理 auto_groups 和 revoked — name、type、expires 這些欄位在 API 層被視為建立時固定，payload 裡的值會被忽略。

繞道做法：直接改 SQLite

NetBird 伺服器用 SQLite (/var/lib/netbird/store.db) 存狀態。繞過 API 直接 UPDATE 資料表，再重啟 netbird-server 讓快取重載。

# 步驟 1：把 DB 從容器拷貝出來（容器內沒裝 sqlite3 CLI）
docker cp netbird-server:/var/lib/netbird/store.db /tmp/store.db

# 步驟 2：改名
sqlite3 /tmp/store.db \
  "UPDATE setup_keys SET name='iPhone-15-Pro' WHERE id='d7h3p5mfs58s73f6qdr0'"

# 確認
sqlite3 /tmp/store.db 'SELECT id, name FROM setup_keys'

# 步驟 3：覆蓋回容器 + 重啟 server（讓記憶體快取失效）
docker cp /tmp/store.db netbird-server:/var/lib/netbird/store.db
cd /opt/netbird
docker compose restart netbird-server

# 步驟 4：用 API 驗證
curl -sf -H "Authorization: Token $TOKEN" \
  https://netbird.timmy.us.kg/api/setup-keys | jq '.[] | {id, name}'

重啟 netbird-server 會短暫中斷 gRPC 連線，執行中的 peer 會自動重連，約 5-10 秒內恢復。

替代做法

如果不想動 DB：Revoke 舊 key，建立新 key 並命名正確。缺點是已用那把 key 註冊的 peer 不受影響（peer 註冊成功後 key 已解耦），但任何依賴那把 key 的自動化腳本要更新。

其他可直接改 SQLite 的場景

NetBird 的 API 對某些欄位是 read-only，但 DB 是可以改的（風險自負）：

欄位	API 可改？	DB 可改
setup_keys.name	否	是
setup_keys.type	否	是（但多半不該改）
setup_keys.expires	否（建立時才能設）	是
peers.name	是（`PUT /api/peers/{id}`）	是
users.role	是	是

建議順序：先試 API → 不行再看 DB schema → 確認欄位意義後再改 → 改完必須重啟 netbird-server。

安全提醒

Setup Key 跟 PAT 都等同於長效憑證，存放要當密碼看待
PAT 失竊 → 立刻從 Dashboard revoke
Setup Key 失竊 → 立刻 revoke，已註冊的 peer 不受影響但無法再用這把 key 註冊新 peer
不要把任何一種 token commit 進 git repo

5.2 KiB Raw Blame History Unescape Escape