Tags 與 auth key：給伺服器用的非互動登入

在筆電上裝 Tailscale，跳出瀏覽器登入就好；但伺服器、NAS、容器、雲端 VM 通常沒有瀏覽器可開，而且不該掛在某個人的帳號下。這篇介紹兩個解法：tag 讓裝置以「服務」的身分加入 tailnet，auth key 讓裝置不必互動登入。

本文依 2026 年 10 月的 Tailscale 官方文件整理，CLI 範例以 Tailscale v1.102 為準。Tags、auth key 與 OAuth client 所有方案都能使用。

為什麼伺服器不該用個人帳號登入

用自己的帳號登入伺服器，那台伺服器的身分就是「你」：

• 人離開，伺服器跟著不見：把某個使用者從 tailnet 移除時，他名下的裝置會一起被移除。
• 金鑰到期就斷線：使用者裝置的 node key 預設 180 天到期，到期後要重新登入；伺服器在機房裡沒人按，就這樣斷了。
• 權限跟著人走：伺服器拿到的是那個人的存取權限，往往比它實際需要的大得多。
• 只能一個人管：使用者裝置只能屬於一個人，共用的伺服器不適合綁在某個人身上。

Tags：讓裝置以服務的身分出現

tag 就像服務帳號。裝置打上 tag 之後：

• 身分從使用者換成 tag：同一台裝置不能同時有使用者身分和 tag，加上 tag 會移除原本的使用者身分；反過來用使用者帳號重新登入，也會清掉所有 tag。
• 移除使用者不影響它：裝置不屬於任何人，人員異動不會連帶移除伺服器。
• 金鑰到期預設關閉：第一次以 tag 身分登入的裝置，key expiry 預設是停用的。之後如果只是改 tag，key expiry 設定不變，要等重新登入後才會改成停用。也可以在 Machines 頁面手動開關。
• 一台可以有多個 tag：例如 tag:server 加 tag:prod，任何一個 tag 的規則都會套用到它。

tag 是設計給伺服器這類「非人」裝置的。筆電、手機不要打 tag：tag 身分的裝置不能用 SSH 連到使用者身分的裝置，Taildrop 也不能收送檔案到 tag 過的裝置。

在 tagOwners 定義 tag

tag 要先在 tailnet policy file 的 tagOwners 定義，並指定誰能把它套到裝置上：

"tagOwners": {
  "tag:server": ["group:admins"],
  "tag:nas": ["me@example.com"],
  "tag:ci": [], // 不指定擁有者，只有 Owner、Admin、Network admin 能用
},

tag 名稱必須以 tag: 開頭。擁有者可以是使用者、群組、autogroup，也可以是另一個 tag。Owner、Admin、Network admin 不在清單上也能套用任何 tag。

在規則裡使用 tag

定義好之後，就能在 grants 裡用 tag 指定對象，例如只讓管理者連到伺服器，伺服器之間只開 PostgreSQL：

"grants": [
  {
    "src": ["group:admins"],
    "dst": ["tag:server"],
    "ip": ["*"],
  },
  {
    "src": ["tag:server"],
    "dst": ["tag:db"],
    "ip": ["tcp:5432"],
  },
],

規則的寫法見 ACL / Grants 入門。注意 tag 之間不能做「交集」：沒辦法寫「同時有 tag:prod 和 tag:db 的裝置」，需要的話就用組合式的名稱，例如 tag:prod-db。

套用 tag

• Admin console：在 Machines 頁面點裝置右邊的選單，選 Edit tags（要 Owner、Admin 或 Network admin）。

• CLI：在裝置上以 tag 重新登入，多個 tag 用逗號分隔：

  sudo tailscale login --advertise-tags=tag:server,tag:prod

• auth key：產生 key 時預先套用 tag，裝置一加入就是 tag 身分（下一節）。

以 tag 重新登入會產生新的 node key，但裝置的 Tailscale IP 不變。

Tag 對其他功能的影響

除了上面提到的 SSH、Taildrop 限制，Tailscale Serve 收到來自 tag 裝置的請求時，不會帶 Tailscale-User-Login 這類身份標頭，因為 tag 裝置沒有使用者身分。後端如果靠這些標頭做授權，要記得處理這個情況。

另外，Subnet Router、Exit Node 這類常駐的服務裝置，也很適合用 tag 身分，再搭配 autoApprovers 自動核准它們宣告的路由。

Auth key：免開瀏覽器登入

auth key 讓裝置不用開瀏覽器登入就能加入 tailnet。沒有套用 tag 的 auth key，加入的裝置會以產生 key 的那個人的身分出現；套用了 tag，裝置就改以 tag 身分加入。所以給伺服器用的 key，幾乎都應該帶 tag。

產生 auth key

到 Admin console 的 Keys 頁面選 Generate auth key（要 Owner、Admin、IT admin 或 Network admin）：

auth key 有分大小寫，複製時要完整。

Key 的效期與裝置的效期是兩回事

這是最容易搞混的地方：

• auth key 的效期（1–90 天）只決定這把 key 還能不能拿來加入新裝置。key 到期後，已經用它加入的裝置不會被登出。
• 裝置的 node key 效期才決定裝置何時要重新登入。使用者裝置預設 180 天；tag 身分的裝置預設停用。

所以用帶 tag 的 auth key 加入的伺服器，即使 key 過期了，伺服器也會一直連著。沒辦法產生「永久有效」的 auth key：一般 key 最長 90 天，一次性 key 用過就失效。需要長期自動加入新裝置，改用下面的 OAuth client。

用 auth key 登入

sudo tailscale up --auth-key=tskey-auth-xxxxx

key 已經預先套用 tag 時，不必再加 --advertise-tags。要搭配其他設定時一起帶上，例如同時當 Subnet Router：

sudo tailscale up --auth-key=tskey-auth-xxxxx --advertise-routes=192.168.1.0/24

tailscale up 的旗標行為（每次要帶齊非預設值）見 CLI 指令速查。也可以把 key 存在檔案裡，用 --auth-key=file:/path/to/key 讀取，避免 key 出現在 shell 歷史紀錄。

在 Docker 中使用

官方映像檔 tailscale/tailscale 用環境變數設定，TS_AUTHKEY 放 auth key，TS_STATE_DIR 一定要掛載到會保留的目錄，否則容器每次重啟都會變成一台新裝置：

services:
  tailscale:
    image: tailscale/tailscale:latest
    hostname: my-service
    environment:
      - TS_AUTHKEY=tskey-auth-xxxxx
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_AUTH_ONCE=true
    volumes:
      - ./tailscale-state:/var/lib/tailscale
    cap_add:
      - net_admin
      - net_raw
    restart: unless-stopped

TS_AUTH_ONCE=true 讓容器在已經登入過時不再重新登入，搭配保留的 state 使用。其他 tailscale up 的旗標放在 TS_EXTRA_ARGS，例如 TS_EXTRA_ARGS=--advertise-exit-node。完整的參數見官方的 Docker 參數說明。

在 cloud-init 中使用

建立雲端 VM 時，用 cloud-init 安裝 Tailscale 並以 auth key 加入，開機後就在 tailnet 裡了：

#cloud-config
runcmd:
  - ["sh", "-c", "curl -fsSL https://tailscale.com/install.sh | sh"]
  - ["tailscale", "up", "--auth-key=tskey-auth-xxxxx"]

cloud-init 的內容通常會存在雲端平台的 VM 中繼資料裡，建議用一次性、帶 tag、效期短的 key。

OAuth client：長期自動化的替代方案

Terraform、CI/CD 這類需要長期、反覆建立裝置的情境，90 天就要手動換一次 auth key 很麻煩。這時改用 OAuth client：

1. 在 Admin console 的 Trust credentials 頁面選 Credential → OAuth 建立 OAuth client，scope 給 auth_keys 的 Write 權限，並指定這個 client 能套用的 tag（要 Owner、Admin、Network admin 或 IT admin）。
2. 建立後會拿到 client ID 與 client secret。secret 只會顯示一次，要當下存好。

client secret 可以直接當 auth key 用，但一定要加上 --advertise-tags，而且 tag 要是建立 client 時指定的：

sudo tailscale up --auth-key="${OAUTH_CLIENT_SECRET}?ephemeral=false&preauthorized=true" \
  --advertise-tags=tag:ci

• 用 OAuth client 加入的裝置一定是 tag 身分。
• secret 後面可以加參數：ephemeral 預設是 true（裝置離線後自動移除），伺服器要長期保留就設成 false；preauthorized 預設是 false，有開 device approval 時設成 true 可以免核准。
• Docker 映像檔一樣可以把 secret 放進 TS_AUTHKEY，tag 用 TS_EXTRA_ARGS=--advertise-tags=tag:ci 指定。

也可以用 OAuth client 呼叫 Tailscale API，需要時再產生新的 auth key。

安全提醒：key 外洩怎麼辦

auth key 和 OAuth client secret 都等於「加入你 tailnet 的通行證」：

• 可重複使用的 key 最危險：被偷走的話，任何人都能用它把裝置加進你的 tailnet，拿到這把 key 所帶 tag 的權限（沒帶 tag 就是產生 key 那個人的權限）。官方建議存在專門的密鑰管理工具，不要放進 repository、聊天訊息或文件。
• 能用一次性就用一次性，效期設短一點，並盡量帶 tag，讓 tag 的規則限制它能連到哪裡。
• 撤銷 key：到 Keys 頁面，在 key 的那一列選 Revoke。每個人只能撤銷自己產生的 key。
• 撤銷 key 不會踢掉已加入的裝置：已經用這把 key 加入的裝置要到 Machines 頁面逐一刪除。
• OAuth client secret 外洩：到 Trust credentials 頁面撤銷或刪除那個 client，再檢查有沒有多出來的裝置。
• 搭配 device approval，沒開 Pre-approved 的 key 加入的裝置都要經過核准，可以多擋一層。

參考資料

• Tags（官方）
• Auth keys（官方）
• OAuth clients（官方）
• Docker 參數（官方）
• 用 cloud-init 安裝 Tailscale（官方）
• Key expiry（官方）