API 文件

Town OS systemcontroller API 的完整參考——涵蓋帳號、儲存、套件庫、套件、systemd、 設定、稽核、頁面、DNS、監控、系統服務、語言地區、虛擬機器映像檔與狀態，共 77 個端點。

身分驗證

呼叫 POST /account/authenticate 並附上使用者名稱與密碼即可驗證。 回應中會含有一個 Bearer 權杖。請在後續請求中帶上它：

Authorization: Bearer <token>

工作階段閒置 7 天後過期。共有五種驗證層級：

即使分割區內部的端點並不限於管理者，建立物件儲存分割區仍然只保留給管理者： 分割區是一棵權限樹的根，並且會配置一個帶配額的 btrfs 子磁碟區， 因此授權允許你操作分割區內部的使用者，而不是允許你決定這個分割區該不該存在。

狀態

健康檢查與系統概覽。未驗證的呼叫者會取得精簡回應，只含 status 與 needs_setup。已驗證的呼叫者則取得完整的儀表板資料， 包含檔案系統數量、套件計數、unit 狀態摘要、磁碟使用量、外部／內部 IP，以及是否有可用升級。

儲存

列出檔案系統。除分頁參數外，請求主體中還可傳入選用的 name （前綴篩選）與 state（user、installed 或 uninstalled）。

建立一個新的 btrfs 子磁碟區。送出 name 與選用的 quota （位元組）。若配額為 0 或省略，則採用系統預設值（50 GB）。保留名稱 （installed、uninstalled、archives）會被拒絕。

修改既有的檔案系統。送出 name 以指明對象，並附上一個 filesystem 物件，其中含更新後的 name 與／或 quota。

移除一個檔案系統。請求主體：{"name": "mydata"}。

上傳封存檔並解開到目標子磁碟區。接受 multipart/form-data， 含一個 subvolume 欄位與一個 archive 檔案。支援 .tar.gz、.tgz、.tar.bz2、.tbz2、 .tar.xz、.txz、.tar、.zip 與 .7z。

下載子磁碟區內容的封存檔。會以所要求的格式回傳串流封存。

依套件分組列出套件磁碟區，並可選擇是否納入已解除安裝的磁碟區。

依內部名稱刪除某個特定的套件磁碟區。

一次呼叫即刪除屬於某個套件的所有磁碟區，不必逐一依內部名稱移除。

套件

列出所有套件庫中全部可用的套件。每筆項目含套件庫、名稱、版本、描述、supplies 標籤、 安裝狀態，以及是否有可用升級。支援分頁參數。

依套件庫分組列出套件。接受選用的 search 查詢參數。 回傳一個由 {"repo": "...", "packages": [...]} 組成的陣列。

列出已安裝套件的識別碼。支援分頁參數。

取得某個已安裝套件的詳細資訊。送出 repo、name 與 version。回傳問題、使用者回答、註記與註記型別。

取得某個已安裝套件所保存的問題回答。送出 repo、 name 與 version。回傳一份鍵值對應。

列出某個套件的可用版本。請求主體：{"name": "nginx"}。 回傳一個版本識別碼的字串陣列。

列出子套件。送出 repo 與 name。回傳一個字串陣列。

取得某個套件的安裝問題。請求主體：{"name": "nginx"}。 回傳一份從問題鍵到 {"query": "...", "type": "..."} 的對應。

取得特定套件版本的問題。送出 repo、name 與 version。

為某個 oauth 問題啟動 OAuth 裝置流程。送出 repo、 name、version 與 question。系統控制器 會向供應商執行該流程的起始步驟，並回傳 flow_id、approve_url（請在使用者的瀏覽器中開啟）、 選用的 user_code，以及 interval_ms——輪詢的頻率。

供應商的各個網址來自套件而非 Town OS，因此呼叫前會先檢查： 只允許 https，而且絕不能是主機自身網路上的位址。

輪詢上面啟動的流程。送出 flow_id。回傳 status： 使用者尚未核准時為 pending，核准完成時為 approved 並附上 token，而流程逾時或權杖已被取走後則為 expired—— 每個流程只能使用一次。取得的權杖接著會作為該問題的答案送到 /packages/install，與手動輸入的回答完全相同。

在真正安裝之前先預覽這次安裝會做什麼。送出 repo、 name 與 version。回傳磁碟區細節、連接埠對應、 磁碟使用量、配額資訊、升級的來源版本，以及一段易讀的摘要。

安裝一個套件。

解除安裝一個套件。送出 repo、name、version， 以及選用的 purge_volumes（布林值）以刪除相關資料。

停用一個已安裝的套件（停止其服務）。送出 repo 與 name。

重新啟用一個已停用的套件（啟動其服務）。送出 repo 與 name。

刪除某個已安裝套件的所有資料磁碟區。送出 repo 與 name。

檢查某個套件是否有先前安裝留下的磁碟區。送出 repo 與 name。回傳 has_uninstalled_volumes、 uninstalled_versions 與 installed_versions。

刪除先前已解除安裝版本留下的磁碟區。送出 repo 與 name。

列出已安裝套件的可用升級。每筆項目含 installed_version、latest_version，以及套件定義是否 changed。

忽略目前的升級通知。送出一個空的 JSON 物件。

回傳原始的 YAML 套件定義。送出 repo、name 與 version。以 Content-Type: text/x-yaml 回傳檔案內容。 若該套件檔案不存在則回傳 404。

列出所有套件庫中的精選套件。

取回某個套件快取的 last 回答。送出 repo 與 name。回傳上一次解除安裝時保存的回答，供重新安裝時重用。

刪除某個套件快取的 last 回答檔案。送出 repo 與 name。

為某個已安裝套件中由 git 填入的磁碟區拉取最新變更，並重新啟動相依的服務。 送出 repo、name 與 version。 重新建置之前會依已保存的回答重新求值範本變數。

設定

以鍵值物件取得所有設定。

取得單一設定項。請求主體：{"key": "default_quota"}。 回傳 key 與 value。

設定某個項目的值。請求主體：{"key": "default_quota", "value": "107374182400"}。

預設設定

頁面

靜態網站代管，支援三種內容來源型別：上傳封存檔、容器映像檔與 git 儲存庫。 使用者為其指定一個網域，系統則透過 Caddy 容器提供內容。 所有會造成變更的端點都需要管理者驗證；清單端點只需一般驗證。

列出所有頁面，支援排序、搜尋與分頁。可依名稱、儲存庫網址、 分支、網域、來源型別、狀態與時間戳記排序。

建立一個新頁面。接受名稱、來源型別（archive、 container_image 或 git）、儲存庫網址、分支、網域、 容器映像檔與映像檔內目錄。來源型別預設為 archive。 git 與容器映像檔類型的頁面會以非同步方式佈建。

為封存類型的頁面上傳內容的 tar 封存檔。接受含 name 與 archive 檔案的 multipart 表單。僅對來源型別為 archive 的頁面有效；其他來源型別會回傳 400。

對頁面的儲存庫網址、分支、網域、來源型別、容器映像檔或映像檔內目錄做部分更新。 只有提供的欄位會被變更。

從資料庫刪除一個頁面，移除 webroot 符號連結，並刪除對應的 btrfs 子磁碟區。

從來源重新建置頁面內容。git 頁面會拉取最新變更；容器映像檔頁面會從映像檔重新擷取。 封存頁面會回傳 400（請改用 /pages/upload 重新上傳）。

網路

網路是一個具名的 WireGuard 疊加網路，並與一個 DNS TLD 配對。 套件安裝到某個網路中，對等裝置加入這個網路，而 TLD 決定誰能解析什麼。 網路名稱必須是合法的 DNS 標籤，且不超過 32 個字元，因為它們同時會被當作 WireGuard 介面字尾與 systemd unit 名稱使用。

home 網路始終存在——它隨資料庫一併植入，而不是在開機時建立——並且在三個方面很特別： 它無法刪除，也不能被第二次建立；它只提供 DNS （沒有 WireGuard 介面、沒有子網路、沒有對等裝置）；而且在它上面註冊對等裝置會被拒絕， 回傳 400。每個帳號都屬於 home 網路，因此若在此接受註冊，單憑成員身分就等於取得了進入通道的途徑， 而且儲存下來的對等裝置所描述的通道根本不存在。

停用網路只會關掉傳輸層：WireGuard 介面不會被拉起，遠端存取因此中斷， 而本地 DNS 解析與容器本身照常執行。

列出網路。每筆項目含名稱、TLD、子網路、本機在疊加網路中的位址、公鑰、監聽連接埠與啟用旗標。 私鑰永遠不會被序列化。

建立網路。子網路由本機識別種子與網路名稱以確定性方式推導而來，取自 10.64.0.0/10，以避開家用路由器常用的位址範圍。 以本機識別為依據，代表兩台都在提供對等接入的 Town OS 主機會選出不同的子網路， 因此同時加入兩者的裝置永遠不會遇到衝突。建立 home 會因 TLD 衝突檢查而回傳 409。

刪除網路。會拒絕 home 網路。

拉起該網路的 WireGuard 傳輸層。

關掉傳輸層，同時讓 DNS 與容器繼續執行。

對等裝置

列出已在某個網路中註冊的對等裝置。

列出目前確實處於連線狀態的對等裝置，而不只是已註冊的。

註冊一個對等裝置。wireguard 授權是放行非管理者的依據；依網路的範圍與每個對等裝置的歸屬由處理常式檢查。 對 home 網路會回傳 400，因為它只提供 DNS。

在對等裝置的 TTL 到期之前續期其註冊。註冊是有時效的，回收程序會清掉已過期的項目。

把某個對等裝置從網路中移除。

本地 CA

以 PEM 格式下載本機的本地憑證授權單位。Town OS 會為套件名稱簽發自己的憑證， 因此信任這張憑證正是讓那些名稱在瀏覽器中不再出現警告的關鍵。它刻意設為公開： CA 憑證本來就是拿來散布的那一部分，而且用戶端在持有任何可用於驗證的憑據之前就需要它。

監控

整合的 Prometheus、Node Exporter 與 Grafana 堆疊，用於系統監控。 整套元件以受 systemd 監管、帶 Restart=always 的 podman 容器執行。

回傳每個監控服務的容器狀態（名稱、映像檔、執行狀態、連接埠）。 未設定監控時會回傳 {"status": "disabled"}。

如何取得儀表板資料

系統控制器上並不存在任何反向代理。監控資料由專屬的 5308 連接埠提供，瀏覽器直接與該連接埠通訊；控制器自己的連接埠（5309）只承載 /monitoring/status。5308 上由誰監聽，取決於所設定的後端：

• uPlot 模式（預設）——由一個 socat 轉送器把 Prometheus 的 HTTP API 開在 5308 上， 介面直接查詢 /api/v1/query_range，並自行繪製圖表。
• Grafana 模式——Grafana 透過 podman 的連接埠對應直接監聽 5308，介面則以 iframe 內嵌。

TOWN_OS_MONITORING_PORT 可以更動儀表板連接埠； TOWN_OS_PROMETHEUS_PORT 與 TOWN_OS_NODE_EXPORTER_PORT 對兩個 loopback 連接埠有同樣作用。

語言地區

系統的國際化語言地區資訊。

回傳目前的語言地區、已填入的語言地區清單、常見語言（含其母語字體名稱） 以及延伸語言地區。使用 BCP 47 語言代碼。

物件儲存管理 API（gfeh）

以上都是 Town OS 的 API，通常應用程式應該使用它。在它之下， 每個 gfehd 分割區還有自己的管理介面： 以 JSON over HTTP 提供，而且只在它的 Unix socket 上，絕不監聽連接埠。

這個介面上既沒有權杖，也沒有身分驗證。socket 的檔案系統權限本身就是存取控制， 因此能夠連到它，就已經代表是這台機器上的 root。socket 位於 btrfs 磁碟區上， 因為那是 gfehd 容器與系統控制器容器都看得到的唯一一個檔案系統。

gfehd 會把內部錯誤對應成 HTTP 狀態碼——404、409、400—— 而 Go 用戶端再把它們對應回哨兵錯誤，因此 errors.Is 跨過 socket 邊界之後依然可用。

對於名為 <network> 的網路，其分割區的檔案位置如下：

用戶端函式庫

Town OS 內附 Go 與 JavaScript 用戶端函式庫，涵蓋完整的 API。 兩個用戶端遇到非 200 回應時，都會依據 RFC 9457 的問題細節拋出帶型別的錯誤。

Go 用戶端

Go 用戶端位於 src/svc/systemcontroller/client.go，實作了 Client 介面。它同時支援 Unix socket 與 HTTP 連線。

// 透過 Unix 網域 socket 連線（正式環境）
client := systemcontroller.InitClient("/run/town-os/systemcontroller.sock")

// 透過 HTTP 連線（開發 / 測試）
client := systemcontroller.FromClient(http.DefaultClient, "http://localhost:5309")

驗證完成後請設定 client.Token。所有方法的第一個參數都是 context.Context。

儲存

套件庫

套件

Systemd

帳號

稽核、設定與升級

封存檔

健康檢查

開發參考

Town OS 後端執行於 5309 連接埠，Vite 開發伺服器則在 5173 連接埠。 請用 make dev 啟動完整的開發環境。

核心目標

測試目標

建置目標