API 與 MCP

API 金鑰

給程式與 AI 代理用的長效權杖，跟使用者帳號分開——機器沒辦法做一次性密碼，也不該借用某個人的密碼。

格式是 walis_<前綴>_<124 位元祕密>；資料庫只存 domain-separated SHA-256 lookup hash，明文只在建立時回傳一次。這裡用固定成本的雜湊才對——祕密是機器產生的高熵值，不像密碼。

金鑰帶有角色（admin、operator、viewer）與用途：

用途	到得了
`mcp`	只有 `/mcp`。新金鑰的安全預設。
`api`	REST 與 MCP，仍受金鑰的角色限制。
`runner`	註冊、心跳、認領與回報——而且只限單一執行器名稱。金鑰指定執行器時會自動變成這個用途。

任何用途的金鑰都不能碰登入、帳號與金鑰本身，所以一把外洩的金鑰不會自我繁殖。

bash

curl -H "Authorization: Bearer walis_..." http://127.0.0.1:11120/api/jobs

MCP

API 本身在 /mcp 提供 MCP，代理只要一個網址加一把金鑰，本機什麼都不用裝：

bash

# Claude Code
claude mcp add --transport http walis http://127.0.0.1:11120/mcp \
  --header "Authorization: Bearer walis_..."

# Codex CLI——權杖讀環境變數，不落在設定檔裡
codex mcp add walis --url http://127.0.0.1:11120/mcp --bearer-token-env-var WALIS_API_KEY

工具有：list_jobs、get_job、trigger_build、wait_for_build、get_build、 get_build_log、list_builds。任務可以直接用名稱指定，不必先查識別碼。

設定、帳號與金鑰管理刻意不開放。那些操作不可逆或牽涉憑證，應該由人在管理介面上做；金鑰即使外流，能造成的損害也侷限在「觸發建置與讀取紀錄」。

/mcp 跟 /api 走同一套認證——它能觸發建置，不會因為不在 /api 底下就被放行。

健康檢查

GET /health 不需要金鑰，會回報這個節點用的是哪一種資料庫、自己叫什麼名字，以及是不是多節點部署：

json

{ "status": "ok", "database": "PostgreSQL", "node": "walis-a", "clustered": true }

SQLite 的 clustered 一律是 false，因為它本來就只有一個節點。放在負載平衡器後面時，這是確認「剛剛是哪一台回應」最快的方法。見高可用。

指標

GET /metrics 輸出 Prometheus 格式：任務數、佇列深度、各狀態的建置數、平均耗時與排隊時間、各狀態的執行器數。

它放在 /api 之外，讓本機的抓取端有個不隨 API 介面變動的固定路徑，但不是不需驗證：驗證中介層把 /metrics 跟管理員限定的路徑列在一起。抓取端要帶一把 admin 用途的金鑰。

設定可攜

GET /api/portability/export 匯出所有任務與自訂動作，不帶識別碼、統計與時間戳—— 那些描述的是這台機器，不是定義本身。匯入以名稱比對：同名的預設略過，選擇覆寫時是就地更新，所以建置紀錄不會斷。

API 與 MCP ​

API 金鑰 ​

MCP ​

健康檢查 ​

指標 ​

設定可攜 ​

API 與 MCP

API 金鑰

MCP

健康檢查

指標

設定可攜