> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作區繫結

> 將 Buttress 伺服器與 BRICKS 工作區配對並啟用 JWT 認證

預設情況下，Buttress 伺服器以**公開模式**執行 — 區域網路上任何客戶端皆可連線、無需認證。**繫結**伺服器會將其與單一 BRICKS 工作區配對，並切換至「所有 WebSocket 與檔案傳輸請求皆須攜帶有效工作區 JWT」的模式。

| 狀態  | 探索通告                                      | WebSocket 認證  | HTTP 檔案傳輸     |
| --- | ----------------------------------------- | ------------- | ------------- |
| 未繫結 | `authentication.required = false`         | 開放            | 開放            |
| 已繫結 | `authentication.required = true`（含 `kid`） | 驗證 JWT，工作區須相符 | 驗證 JWT，工作區須相符 |

繫結為單向配對：一台 Buttress 伺服器一次只能屬於一個工作區。已繫結的伺服器會以 WebSocket close code `1008` 拒絕未認證的連線。

## 前置需求

* 已於本機安裝 Buttress 伺服器（請參閱[安裝](/zh-Hant/buttress/installation)）
* 已安裝 [BRICKS CLI](/zh-Hant/cli)
* 已登入工作區：`bricks auth login <passcode>`

## 繫結伺服器

於執行 Buttress 伺服器的同一台機器執行繫結指令。CLI 會自動偵測本機的 server id，並寫入伺服器啟動時讀取的小型 `state.json`。

```bash theme={null}
bricks buttress bind
```

如要覆寫自動偵測的 id、為伺服器指定友善名稱，或將 state 檔寫到非預設位置：

```bash theme={null}
bricks buttress bind \
  --server-id buttress-mac-studio \
  --name "Studio LLM" \
  --state-dir /etc/buttress
```

非互動式或遠端設定可將 state JSON 輸出至 stdout 後自行寫入：

```bash theme={null}
bricks buttress bind --print > /etc/buttress/state.json
```

<Warning>
  繫結後請重新啟動 Buttress 伺服器。state 檔案僅在啟動時讀取一次 — 若未重新啟動，伺服器會持續以公開模式執行。
</Warning>

### 寫入內容

預設情況下 state 檔案位於 `~/.bricks-cli/buttress/state.json`。可透過 `--state-dir <path>` 覆寫目錄。

```json theme={null}
{
  "workspace": {
    "id": "<工作區 id>",
    "name": "<工作區名稱>",
    "serverId": "<伺服器 id>",
    "issuerPublicKey": "-----BEGIN PUBLIC KEY-----\n…",
    "kid": "<key id>",
    "boundAt": "2026-05-08T12:00:00.000Z"
  },
  "serverKeyPair": {
    "publicKeySpki": "<base64 SPKI>",
    "privateKeyPkcs8": "<base64 PKCS8>",
    "kid": "<announce kid>"
  }
}
```

* `workspace.issuerPublicKey` 為您工作區的 Ed25519 公鑰，伺服器會以此驗證每個進入的 access token。
* `serverKeyPair` 是每次 `bind` 時於本機產生的伺服器專屬 Ed25519 通告金鑰對。公鑰會登錄至雲端（讓 launcher 能驗證簽署過的 UDP 探索封包），私鑰則保留在本機；簽署過的通告詳見[區域網路自動探索](/zh-Hant/buttress/autodiscovery#簽署過的通告)。

<Warning>
  請將 `state.json` 視為機密。`serverKeyPair.privateKeyPkcs8` 欄位讓任何讀取者都能以此伺服器身分簽署 UDP 通告。`bricks buttress bind --print` 將 JSON 輸出至 stdout 時也會在 stderr 提出相同警告。
</Warning>

重新執行 `bricks buttress bind` 會產生新的通告金鑰對並輪替已登錄的公鑰。任何指向舊金鑰的 launcher 快取會停止信任該伺服器，直到從雲端取得新金鑰為止。

## 檢視繫結

`bricks buttress status` 會列印本機 state 檔案以及工作區端的繫結伺服器清單。

```bash theme={null}
bricks buttress status
```

加上 `--json` 取得機器可讀格式：

```bash theme={null}
bricks buttress status --json
```

JSON 結構為 `{ "local": <state.json 或 null>, "remote": <[{ serverId, name, boundAt, lastSeenAt }, …]> }`。

## 解除繫結

移除繫結會清除工作區對該伺服器的紀錄**並**刪除本機 state 檔案。

```bash theme={null}
bricks buttress unbind
```

僅撤銷伺服器端、保留本機 state 檔案：

```bash theme={null}
bricks buttress unbind --keep-local
```

解除繫結後請重新啟動 Buttress 伺服器以回到公開模式。

## 核發長期 access token

Foundation launcher 會自動透過 BRICKS 雲端取得短期 token。對於非互動式呼叫端 — CI 指令碼、CTOR 代理、ACP bridge — 可一次核發長期 access token 以供重複使用。

```bash theme={null}
# 預設 30 天 TTL
bricks buttress issue-token

# 自訂 TTL（秒），輸出 JSON 以便指令碼處理
bricks buttress issue-token --ttl 3600 --json
```

CLI 會輸出 JWT 與其到期時間。可將其作為 `Authorization: Bearer <token>` 標頭傳送，或附加於 WebSocket URL 的 `?access_token=<token>`。

<Tip>
  核發的 token 與您的 CLI session token 綁定。撤銷 CLI 工作區 token 將使該 session 核發的所有 Buttress access token 一併失效。
</Tip>

## 疑難排解

| 症狀                                                        | 可能原因                          | 解決方式                                 |
| --------------------------------------------------------- | ----------------------------- | ------------------------------------ |
| `Could not detect a local server id.`                     | machine ID 偵測失敗（沙箱或缺少識別資訊的容器） | 明確傳入 `--server-id <id>`              |
| `Not logged in. Use bricks auth login first.`             | 沒有有效的 CLI profile             | 執行 `bricks auth login <passcode>`    |
| `bind` 後伺服器仍接受未認證連線                                       | 伺服器未重新啟動                      | 重新啟動 `bricks-buttress`               |
| `unbind` 顯示 `<serverId> was not bound to this workspace.` | 伺服器原本就未繫結，或繫結至其他工作區           | 執行 `bricks buttress status` 確認實際繫結狀態 |
| Foundation 裝置出現「no LAN provider is registered」            | 伺服器繫結的工作區與裝置不同                | 將伺服器重新繫結至裝置所在工作區，或調整裝置歸屬             |

## 下一步

<CardGroup cols={2}>
  <Card title="區域網路自動探索" icon="broadcast-tower" href="/zh-Hant/buttress/autodiscovery">
    Foundation 裝置如何於區域網路找到已繫結的伺服器。
  </Card>

  <Card title="從 Foundation 使用" icon="mobile" href="/zh-Hant/foundation/buttress">
    於各 LLM/STT brick 設定卸載行為。
  </Card>
</CardGroup>