API 文档

Town OS systemcontroller API 的完整参考——涵盖账户、存储、仓库、软件包、systemd、 设置、审计、页面、DNS、监控、系统服务、语言区域、虚拟机镜像和状态，共 77 个端点。

身份验证

调用 POST /account/authenticate 并提供用户名和密码即可完成验证。 响应中包含一个 Bearer 令牌。在后续请求中带上它：

Authorization: Bearer <token>

会话在闲置 7 天后过期。共有五种权限级别：

即便分区内部的端点并不限于管理员，创建对象存储分区仍然只保留给管理员： 分区是一棵权限树的根，并且会分配一个带配额的 btrfs 子卷， 因此授权准许你操作分区内部的用户，而不是准许你决定这个分区是否应当存在。

状态

健康检查与系统总览。未认证的调用方会得到一个精简响应，只含 status 和 needs_setup。已认证的调用方会得到完整的仪表盘数据， 包括文件系统数量、软件包计数、单元状态摘要、磁盘用量、外部/内部 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——轮询间隔。

服务商的各个 URL 来自软件包而非 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 容器提供内容服务。 所有会产生改动的端点都需要管理员身份；列表端点只需普通认证。

列出所有页面，支持排序、搜索和分页。可按名称、仓库 URL、 分支、域名、来源类型、状态和时间戳排序。

创建一个新页面。接受名称、来源类型（archive、 container_image 或 git）、仓库 URL、分支、域名、 容器镜像和镜像内目录。来源类型默认为 archive。 git 和容器镜像类型的页面会异步准备。

为归档类型的页面上传内容的 tar 包。接受包含 name 和 archive 文件的 multipart 表单。仅对来源类型为 archive 的页面有效；其他来源类型返回 400。

对页面的仓库 URL、分支、域名、来源类型、容器镜像或镜像内目录做局部更新。 只有提供的字段会被修改。

从数据库中删除一个页面，移除 webroot 符号链接，并删除对应的 btrfs 子卷。

从来源重新构建页面内容。git 页面会拉取最新改动；容器镜像页面会从镜像中重新提取。 归档页面返回 400（请改用 /pages/upload 重新上传）。

网络

网络是一个具名的 WireGuard 覆盖网，并与一个 DNS TLD 配对。 软件包安装到某个网络中，对等设备加入这个网络，而 TLD 决定谁能解析什么。 网络名称必须是合法的 DNS 标签，且不超过 32 个字符，因为它们同时会被用作 WireGuard 接口后缀和 systemd 单元名称。

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 对两个环回端口起同样作用。

语言区域

系统的国际化语言区域信息。

返回当前语言区域、已填充的语言区域列表、常见语言（含其母语字形名称） 以及扩展语言区域。使用 BCP 47 语言代码。

对象存储管理 API（gfeh）

以上都是 Town OS 的 API，通常应用程序应当使用它。在它之下， 每个 gfehd 分区还有自己的管理接口： 以 JSON over HTTP 提供，并且只在它的 Unix 套接字上，绝不监听端口。

这个接口上既没有令牌，也没有身份验证。套接字的文件系统权限本身就是访问控制， 因此能够访问到它，就已经意味着是这台机器上的 root。套接字位于 btrfs 卷上， 因为那是 gfehd 容器与系统控制器容器都能看到的唯一一个文件系统。

gfehd 会把内部错误映射为 HTTP 状态码——404、409、400—— 而 Go 客户端再把它们映射回哨兵错误，因此 errors.Is 在跨越套接字边界之后依然可用。

对于名为 <network> 的网络，其分区的文件位置如下：

客户端库

Town OS 自带 Go 和 JavaScript 客户端库，覆盖完整的 API。 两个客户端在遇到非 200 响应时，都会依据 RFC 9457 的问题详情抛出带类型的错误。

Go 客户端

Go 客户端位于 src/svc/systemcontroller/client.go，实现了 Client 接口。它同时支持 Unix 套接字和 HTTP 连接。

// 通过 Unix 域套接字连接（生产环境）
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 启动完整的开发环境。

核心目标

测试目标

构建目标