生命周期层。统一 API。
api.hoody.com 是容器诞生的地方。创建、暂停、快照、跨服务器复制、Realm 隔离、计费——全部通过 HTTP 完成。
100+ 接口。逐服务 OpenAPI 规范。Realm 作用域 Token。暂停、快照、复制、同步——全部在同一界面。
# create a container
$ curl -X POST https://api.hoody.com/api/v1/projects/ID/containers \
-H "Authorization: Bearer hdy_..." \
-H "Content-Type: application/json" \
-d '{"name":"dev-box","container_image":"debian/13","cpu":2,"memory":4}'
<< 201 Created
{ "id": "67e89abc…", "status": "creating", "urls": ["terminal-1…", "files…", "display-1…", …] }
六种状态。明确的转换。
容器在定义的状态机中流转，每次转换都有对应接口，且每次转换都是容器历史中的一条记录事件。
正在配置文件系统和资源
正常运行，所有 URL 均可访问
已关机 · 存储持续计费
RAM 已冻结 · 可即时恢复
操作过程中发生错误
异步复制进行中
POST/containers/ID/start
POST/containers/ID/stop
POST/containers/ID/force-stop
POST/containers/ID/restart
POST/containers/ID/pause
POST/containers/ID/resume
POST/containers/ID/network/start
POST/containers/ID/network/stop
暂停运行中的工作。对整台机器创建快照。
通过 pause/resume 冻结 RAM。通过有状态快照捕获文件系统、进程和内存。将容器恢复到任意历史时刻，无需重新初始化。
容器休眠，而非关机
- —RAM 状态就地冻结；打开的文件和数据库连接池保持不变
- —在 LLM 推理中途暂停——恢复时无需重新预热上下文
- —夜间暂停自动化任务——次日早上恢复
- —POST /containers/ID/pause · POST /containers/ID/resume
计算机的 Git
- —运行时创建 = 有状态（文件系统 + 进程 + 内存）
- —停止后创建 = 无状态（仅文件系统）
- —快照别名最多 100 个字符，可选按天数自动过期
- —POST /containers/ID/snapshots · PATCH /containers/ID/snapshots/NAME 用于恢复
分支容器。保持同步。
将容器的完整状态——包括快照历史——复制到另一台服务器或地区。同步将增量变更从源端传播到副本。
container-67e89abc…
server: node-us-east-1
container-abc1234d…
server: node-eu-west-1
target_project_id 用于跨项目复制
source_snapshot 用于复制特定状态
典型耗时：同一服务器 50GB 约 3–5 分钟，跨服务器 50GB 约 10–15 分钟
同步会覆盖副本上的本地更改。同步是单向的——源端变更流向副本，不可逆向。
隔离与计费是 API 原语
Realm 限定 API 主机本身。钱包拆分防止被攻陷后耗尽基础设施预算。
API 级多租户
- —Realm A 中的 AI 智能体在字面上无法访问 Realm B 的资源
- —Token 通过 realm_ids 限定到特定 Realm
- —Realm 隔离位于项目 RBAC 之上——它会改变 API 主机
通用余额与 AI 余额
- —被攻陷的 AI 工作负载无法耗尽基础设施预算
- —Stripe（PCI 合规）、100+ 种加密货币（NOWPayments）、银行转账
- —自动生成 PDF 发票 · 分页交易历史
完整 API 界面
按资源分组，每个接口均有 OpenAPI 规范。
鉴权与 Token
25+ 接口
OAuth、注册、JWT 登录/刷新/登出、带备份码的 2FA、含 CIDR IP 白名单和 Realm 作用域的长效 hdy_ Token
容器与生命周期
20+ 接口
CRUD、统计、启动/停止/暂停/恢复/重启、防火墙规则、网络启停
快照、复制与同步
10+ 接口
快照 CRUD（含别名和过期）、异步跨服务器复制、增量单向同步
钱包与计费
20+ 接口
余额、交易记录、支付方式（Stripe + 加密货币 + 银行转账）、付款、带 PDF 的发票、通用→AI 转账
Realm 与项目
5+ 接口
Realm 列表（含可选用量统计）、项目 CRUD、项目作用域容器列表
代理别名 · 权限 · 日志
31 个接口
由控制平面提供，文档在 /platform/proxy——别名（6）、权限（17）、日志（8）
每项服务都发布其自己的 OpenAPI 规范（如 Hoody SQLite、Hoody Terminal、Hoody Cron）——在任何语言中生成类型化客户端。
传统编排要求你自行拼凑的东西
Terraform、kubectl、AWS SDK 和 Docker daemon API 各自覆盖控制平面所在单一界面的一部分功能。以下是真实的对比拆解。
| 能力 | 控制平面 | 传统方案 |
|---|---|---|
| 容器 CRUD | POST /projects/ID/containers | Terraform provider + module + apply |
| 暂停 RAM 状态 | POST /containers/ID/pause · /resume | 无直接类比（VMware 挂起） |
| 运行中 + RAM 快照 | POST /containers/ID/snapshots | 自定义脚本 + VM 快照 |
| 跨服务器复制 | POST /containers/ID/copy + /sync | rsync + 手动引导 + 重新注册 |
| 多租户 API 隔离 | realm_ids[] · REALM.api.hoody.com | RBAC 层 + 命名空间规范 |
| 统一计费 + LLM 额度 | general → AI transfer (one-way) | Stripe + 独立 LLM 供应商账单 |
| 签名 API 响应 | X-Hoody-Signature (ED25519) | 仅 TLS（内容未签名） |
| 从规范生成类型化客户端 | GET /api/v1/openapi.json | 自行编写 SDK |
当需要 Terraform 的 plan/apply 模型、kubectl 的调度，或 AWS 的托管服务时，使用对应工具。当容器是首要原语、并希望在一套 API 中完成整个生命周期管理（包括暂停和快照）时，控制平面才真正发挥价值。
第一个容器只需一次 POST。
获取 API Token，选择镜像，HTTP 201 返回前每项套件服务 URL 即已就绪。
另见——/platform/proxy（URL 路由与鉴权机制）。