dozycatAPI 与 CLI
dozycat 控制平面 HTTP API 的端点参考，以及与之同源、经过对等测试的 dozycat CLI 子命令。
概览
dozycat 是 dozycat 的集中式控制平面：API、Web UI 和 CLI 共用同一套服务方法。CLI 是 HTTP API 之上的薄壳——配置 --api URL（或环境变量 DOZYFS_API）即驱动远端 API；否则直接对本地 SQLite 注册表（--db）操作。无论哪种后端，调用的都是同一组方法，因此 API、UI、CLI 在能力上永不漂移。仓库里有对等测试（parity test）断言每个服务操作都至少有一条 HTTP 路由可达。
提示：API 返回 JSON（
Content-Type: application/json; charset=utf-8），并带 Access-Control-Allow-Origin: *。健康检查在 GET /api/health，返回 {"status":"ok"} 与可用操作列表。关于 cat / volume / route / node 等概念，参见 核心概念；关于稳定路由与冷热轮换，参见 生命周期。
端点参考
所有路径都以 /api 为前缀。下面按资源分组。
status（状态）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/status | status | 控制平面汇总快照（节点、cat、卷计数等） |
| GET | /api/health | health | 存活探针，返回 ok 与操作列表 |
volumes（卷）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/volumes | list_volumes | 列出所有卷 |
| POST | /api/volumes | create_volume | 创建一个卷（需 volume_id、tenant_id、gcs_prefix） |
| GET | /api/volumes/{volume_id} | get_volume | 查看单个卷 |
| POST | /api/volumes/{volume_id}/activate | activate | 把卷激活到指定 cat_id + node_id |
| POST | /api/volumes/{volume_id}/schedule | schedule | 容量感知调度：自动挑选空闲 ready 节点（或校验给定节点）后激活 |
routes（稳定路由）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/routes | list_routes | 列出所有稳定路由（含 public_url） |
| GET | /api/routes/{stable_name} | resolve_route | 把 xxxxx.dozyfs 解析到当前绑定（节点 + epoch） |
| POST | /api/routes/{stable_name}/public | set_public_url | 设置路由对外的 https 公共地址 |
nodes（节点）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/nodes | list_nodes | 列出所有裸机节点 |
| POST | /api/nodes | register_node | 注册/更新节点及其 cat-agent 端点（需 node_id、address、agent_url） |
| GET | /api/nodes/{node_id} | get_node | 查看单个节点 |
cats（微虚拟机）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/cats | list_cats | 列出所有 cat 及其 state / desired_state |
| GET | /api/cats/{cat_id} | get_cat | 查看单个 cat |
| POST | /api/cats/{cat_id}/idle | idle | 将 cat 降到某档闲置层（tier：hot/warm/cold/deep-cold） |
| POST | /api/cats/{cat_id}/desired | set_desired | 声明期望状态（running/cold/off） |
| POST | /api/cats/{cat_id}/reconcile | reconcile | 朝期望状态推进一步 |
| POST | /api/cats/{cat_id}/lifecycle | lifecycle | 规划/执行某个生命周期动作（pause、snapshot、drain 等） |
reconcile（协调）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| POST | /api/reconcile | reconcile_all | 对整个机群各 cat 协调一次 |
events（事件）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| GET | /api/events?limit=N | list_events | 列出最近的控制平面事件 |
| POST | /api/events | record_event | 记录一条事件（需 event_type） |
heatmap / warmup（热度图 / 预热）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| POST | /api/heatmap | heatmap | 从访问日志计算热门目录（带衰减 decay） |
| POST | /api/warmup | warmup | 按热度规划或执行（execute）JuiceFS 预热 |
tokens（作用域访问令牌）
| 方法 | 路径 | 操作 | 说明 |
|---|---|---|---|
| POST | /api/tokens | issue_token | 签发令牌（明文密钥仅在此返回一次） |
| GET | /api/tokens | list_tokens | 列出令牌元数据（绝不泄露密钥） |
| POST | /api/tokens/verify | verify_token | 针对某 op/cat/volume 校验令牌 |
| POST | /api/tokens/{token_id}/revoke | revoke_token | 按 id 吊销令牌 |
等价的 CLI 子命令
CLI 程序名为 dozycat。每个 HTTP 资源都有对应子命令组：
| 资源 | CLI |
|---|---|
| volumes | dozycat registry create-volume | activate | schedule | idle | status | list-volumes | get-volume |
| routes | dozycat route get | ls | set-url |
| mounts | dozycat mount add | ls | get | rm（自带 S3/GCS 桶，FUSE） |
| nodes | dozycat node register | ls | get |
| cats | dozycat cat set-desired | reconcile | reconcile-all | ls | get |
| events | dozycat registry record-event | list-events |
| heatmap / warmup | dozycat heatmap <log>、dozycat warmup <log> --mountpoint … |
| lifecycle | dozycat lifecycle <action> --cat-id … --state … |
| tokens | dozycat token issue | ls | verify | revoke |
注意：除非配置了
--api/DOZYFS_API，多数子命令都需要一个后端——传 --db 指向本地 SQLite 注册表。lifecycle 在无后端时只能打印计划；--execute 会把计划下发给该 cat 所在节点的 cat-agent（有 --db 时本地执行）。作用域访问令牌
令牌密钥形如 dzt_…，每个令牌带 TTL（过期时间）和作用域。作用域是三条独立的轴：
ops—— 允许的操作（如lifecycle、idle）cats—— 允许的 cat idvolumes—— 允许的卷 id
任一轴省略即默认为 ["*"]（不限制）。校验返回 valid 与具体 reason：ok、unknown、op_not_in_scope、cat_not_in_scope、volume_not_in_scope、expired、revoked。
仅一次：明文密钥只在
issue 时返回一次。list 与 verify 都不会再吐出密钥，服务端只存 sha256 哈希。务必在签发时妥善保存。示例
创建卷
curl -sS -X POST http://127.0.0.1:8080/api/volumes \
-H 'Content-Type: application/json' \
-d '{"volume_id":"vol-acme","tenant_id":"acme","gcs_prefix":"gs://acme-fs/","quota_gb":50}'
# CLI 等价（远端 API）：
export DOZYFS_API=http://127.0.0.1:8080
dozycat registry create-volume --volume-id vol-acme \
--tenant-id acme --gcs-prefix gs://acme-fs/ --quota-gb 50列出 cat
curl -sS http://127.0.0.1:8080/api/cats
# CLI 等价：
dozycat cat ls --api http://127.0.0.1:8080签发作用域令牌
curl -sS -X POST http://127.0.0.1:8080/api/tokens \
-H 'Content-Type: application/json' \
-d '{"scope":{"ops":["lifecycle"],"cats":["cat-A"]},"ttl_seconds":3600,"label":"ci"}'
# -> {"token":"dzt_…","token_id":"…","expires_at":…}
# CLI 等价：
dozycat token issue --scope-ops lifecycle --scope-cats cat-A --ttl 3600 --label ci生命周期动作
# 仅打印某个动作的计划命令（不执行）：
dozycat lifecycle pause --cat-id cat-A --state running
# 下发到该 cat 所在节点的 cat-agent 执行：
dozycat lifecycle pause --cat-id cat-A --state running \
--api http://127.0.0.1:8080 --execute
# HTTP 等价：
curl -sS -X POST http://127.0.0.1:8080/api/cats/cat-A/lifecycle \
-H 'Content-Type: application/json' \
-d '{"state":"running","action":"pause","execute":true}'错误与状态码
- 400 —— 缺少必填字段、JSON 非法或参数值有误。响应体形如
{"error":"missing required field(s): …"}。 - 404 —— 路径无匹配路由，或资源（如卷/节点）不存在。
- 405 —— 路径存在但方法不被允许。
- 200 —— 成功，响应体为操作结果对象。
CLI 把 API 错误统一转成 error: api <code>: <message> 并以退出码 2 返回。
运行控制平面
# 启动 API + Web UI（也直接挂载静态 UI）：
python -m dozycat.api --db /var/lib/dozyfs/registry.db --host 0.0.0.0 --port 8080完整源码见 github.com/dozycat/dozyfs 的 dozycat/api.py 与 dozycat/cli.py。