> ## 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.

# 區域網路自動探索

> Foundation 裝置如何於區域網路上找到 Buttress 伺服器

Foundation launcher 不需要寫死的伺服器網址。每台 Buttress 伺服器會於區域網路上自我通告，已繫結的 launcher 會為各 generator 類型挑選最強的相符伺服器。

## 運作方式

每台 Buttress 伺服器於連接埠 `8089` 執行 UDP 傳輸：

* **ANNOUNCE** — 每 5 秒廣播一次，內含伺服器的 `serverInfo`（能力、generator 清單、認證狀態）。
* **QUERY** — launcher 可廣播查詢，伺服器以單播 **RESPONSE** 回應。回應延遲會隨機化，避免多台伺服器同時回覆造成風暴。

傳輸層會於 `0.0.0.0:8089` 綁定接收 socket 以接收進入的查詢，並為每個本機廣播介面綁定一個發送 socket，確保各子網路的廣播從正確的 NIC 送出。

## 通告內容

`serverInfo` 包含 `generators[]` 陣列，列出啟動時計算的各後端硬體能力：

```json theme={null}
{
  "id": "buttress-mac-studio",
  "name": "Studio LLM",
  "version": "2.25.0-beta.9",
  "authentication": {
    "required": true,
    "type": "workspace-jwt",
    "kid": "<key id>",
    "bound": true
  },
  "generators": [
    { "type": "ggml-llm", "score": 57, "hasGpu": true, "usableBytes": 21474836480 },
    { "type": "ggml-stt", "score": 57, "hasGpu": true, "usableBytes": 21474836480 }
  ]
}
```

Foundation launcher 會依 generator 類型（LLM、STT、MLX）篩選通告，並偏好評分最高且支援該後端的伺服器。

### 能力評分

評分為 0-100 數值，由以下項目組成：

| 項目      | 最高分 | 來源                                       |
| ------- | --- | ---------------------------------------- |
| GPU 可用性 | 40  | `hasGpu`                                 |
| 後端變體    | 20  | CUDA = 20，Metal = 15，Vulkan = 10，CPU = 5 |
| GPU 記憶體 | 20  | 以 12 GB 為基準的相對值                          |
| CPU 記憶體 | 10  | 以 32 GB 為基準的相對值                          |
| 伺服器可用性  | 10  | `ok` 健康旗標                                |

無 GPU 的筆記型電腦約 15-25 分；搭載 RTX 4090 的工作站可達 80-90 分。

## 信任模型

不論已繫結或未繫結，所有伺服器皆會通告，但 launcher 對待方式不同：

* **未繫結伺服器**（`authentication.required = false`）會以未受信任端點呈現。手動或公開客戶端仍可使用，但已繫結的 launcher 會忽略它們。
* **已繫結伺服器**（`authentication.required = true`）僅在其 `serverId` 出現於工作區繫結伺服器清單**且**通告由工作區於繫結時登錄的對應伺服器專屬通告金鑰簽署時才被信任。

### 簽署過的通告

每台 Buttress 伺服器都有自己的 Ed25519 通告金鑰對，由 `bricks buttress bind` 產生。公鑰會登錄至 BRICKS 雲端，並透過 `myWorkspaceButtress.buttressServers[].serverPublicKey` 提供給 launcher；私鑰則保留於伺服器主機的 `~/.bricks-cli/buttress/state.json`。

已繫結伺服器送出的每個 UDP `ANNOUNCE` 與 `RESPONSE` 都會夾帶針對 `{ t, d, ts }` 的簽章。launcher 會以登錄的公鑰驗證簽章，並套用 30 秒重放視窗 — 缺乏有效簽章的封包永遠不會進入端點池。此舉封閉了「區域網路上的對等節點重新通告已繫結 `serverId`、藉此取得工作區 bearer token」的偽冒攻擊面。

通訊協定版本已升級為 **2.0**。執行協定 1.0 與 2.0 的 launcher 與伺服器會無聲地丟棄對方的封包，因此新舊組合會互相隱形而非以未簽署的形式互信。若要升級既有的已繫結伺服器，請重新執行 `bricks buttress bind`（會產生新的通告金鑰對）並重新啟動 `bricks-buttress`。

## 手動覆寫

當自動探索不可行時（裝置位於不同子網，或 Buttress 伺服器位於雲端），BRICKS Controller 的 Config Editor 提供將每個 LLM/STT brick 從 **Auto** 切換為 **Manual** 並直接輸入 WebSocket URL 的選項。請參閱[從 Foundation 使用 Buttress](/zh-Hant/foundation/buttress)。

## HTTP 回退

launcher 也可以直接以已知 IP 透過 HTTP 查詢：

```bash theme={null}
curl http://<伺服器主機>:2080/buttress/info
```

該端點回傳的 `serverInfo` 結構與 UDP `ANNOUNCE` 相同。Foundation launcher 在 UDP 廣播被封鎖時（部分企業 Wi-Fi 網路）會於內部使用此路徑。

## 疑難排解

| 症狀                            | 可能原因                                | 解決方式                                |
| ----------------------------- | ----------------------------------- | ----------------------------------- |
| 裝置始終找不到伺服器                    | UDP 廣播被交換器或 AP 封鎖                   | 改用有線網路、允許 `udp/8089` 廣播，或改用手動 URL   |
| iOS 裝置只在行動數據下能找到伺服器，Wi-Fi 找不到 | 廣播 socket 上的 iOS `IP_BOUND_IF` 行為差異 | launcher 已自動處理，會將主動查詢改綁至 Wi-Fi IP   |
| 伺服器有通告但裝置忽略它                  | 伺服器未繫結，或繫結至不同工作區                    | 執行 `bricks buttress status`，必要時重新繫結 |
| `serverInfo.generators[]` 為空  | TOML 設定檔中未列 generator，或全部載入失敗       | 檢視伺服器記錄中下載或硬體偵測錯誤                   |

## 下一步

<CardGroup cols={2}>
  <Card title="工作區繫結" icon="key" href="/zh-Hant/buttress/workspace-binding">
    伺服器的 `kid` 與繫結伺服器清單如何核發。
  </Card>

  <Card title="從 Foundation 使用" icon="mobile" href="/zh-Hant/foundation/buttress">
    各 brick 的連線設定：Auto vs Manual、策略、回退。
  </Card>
</CardGroup>