尧图网页设计 
forkd REST API完全参考Controller守护进程全端点、认证、TLS与Prometheus监控详解【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkdforkd 是一个高性能 Agent 沙箱系统通过快照写时复制Copy-on-Write技术让预热虚拟机在约 100 毫秒内派生 100 个独立实例。forkd Controller 守护进程对外暴露一套 REST API默认127.0.0.1:8889本文带你从启动、认证、TLS 加密到每一个 v1 端点与 Prometheus 监控指标完整读懂这套 API。一、认识 Controllerforkd 的控制平面 ️你可以把 forkd 想象成一套虚拟机流水线快照Snapshot把一台预热好的虚拟机冻结成vmstate memory.bin文件作为母版沙箱Sandbox从母版快速恢复出的独立子虚拟机彼此完全隔离KVM 级别分支Branch运行中的沙箱暂停约 150 毫秒复制出新母版再恢复运行。所有这些操作都通过forkd Controller 守护进程的 REST API 驱动CLI、Python SDK 都是它的客户端。官方端点文档见 docs/API.md路由实现在 crates/forkd-controller/src/http.rs。二、一键启动默认配置与安全底线默认启动方式参考 crates/forkd-controller/src/main.rsforkd-controller serve \ --bind 127.0.0.1:8889 \ --state /var/lib/forkd/state.json \ --audit-log /var/log/forkd/audit.log \ --token-file /etc/forkd/token几个关键默认值配置项默认值说明--bind127.0.0.1:8889仅回环地址本地单租户可用--state/var/lib/forkd/state.json快照/沙箱注册表自动创建--audit-log/var/log/forkd/audit.log每请求一行 JSON 的审计日志--token-file未设置不设则免认证仅限回环BRANCH 并发上限4可用--branch-concurrency调整安全底线fail closed如果绑定到非回环地址如0.0.0.0:8889却没给--token-file守护进程会直接拒绝启动避免裸奔。这个校验逻辑就在 crates/forkd-controller/src/lib.rs。三、认证详解Bearer Token 三步走 启用认证只需两个动作守护进程侧把令牌写入文件并传给--token-file。令牌要求非空、至少 16 字节高熵随机值占位符REPLACE_ME/CHANGE_ME开头会被直接拒绝客户端侧每个请求带上请求头curl -H Authorization: Bearer token文件内容 \ http://127.0.0.1:8889/v1/sandboxes例外/healthz永远免认证/healthz/带尾斜杠也可以这样负载均衡器和 K8s 探活不需要持有凭证。认证中间件实现在 crates/forkd-controller/src/auth.rs有两个值得新手留意的细节令牌比较采用constant-time 比较subtle::ConstantTimeEq杜绝响应时间暴露令牌长度的时序侧信道令牌在启动时读取一次轮换令牌需要重启守护进程。所有 401 响应都返回统一格式{ error: missing bearer token }四、TLS 加密两条 PEM 文件开启 HTTPS 想让 API 走 HTTPS多租户或跨主机部署的推荐姿势只需成对提供forkd-controller serve \ --bind 127.0.0.1:8889 \ --tls-cert /etc/forkd/cert.pem \ --tls-key /etc/forkd/key.pem两个参数必须成对出现只给其一会报错退出底层使用 rustlsaws-lc-rs 加密提供器配置加载见 crates/forkd-controller/src/lib.rs建议配合 Bearer Token 双保险使用K8s 部署示例见 packaging/k8s/forkd-controller.yaml。部署前建议先跑一次forkd doctor它会检查内核版本、UFFD_WP、memfd、HugePages 等 14 项前置条件一眼确认你的主机是否满足live_fork等高级 API 的能力要求五、v1 全端点速查表 API 采用/vN前缀做版本管理破坏性变更会进入新前缀旧主版本并行支持一个小版本。当前 v1 共 20 个端点5.1 状态与发现端点方法路径说明认证GET/healthz存活探针恒返回{ok:true}免认证GET/version返回构建版本与 API 版本需要GET/metricsPrometheus 文本格式指标需要5.2 快照端点Snapshot方法路径说明POST/v1/snapshots用 kernel rootfs 启动母版机、等待用户态预热后做快照GET/v1/snapshots列出全部已注册快照DELETE/v1/snapshots/:tag删除快照链式快照支持?cascadetrue递归删整棵子树或?forcetrue孤立化子节点二者互斥GET/v1/snapshots/:tag/infov0.5 链信息链深度、父哈希、磁盘占用、依赖者列表POST/v1/snapshots/:tag/compact把多层 diff 链压平为无父的独立快照原子落盘中断不残留半成品POST /v1/snapshots的核心参数tag1–64 位字母/数字/-/_、kernel、rootfs、tap、boot_wait_secs≤60默认 10 秒预热窗口。5.3 沙箱端点Sandbox——一次 fork 100 台 方法路径说明POST/v1/sandboxes从快照 tag fork N 个子沙箱1 ≤ n ≤ 1000GET/v1/sandboxes列出活跃沙箱GET/v1/sandboxes/:id单个沙箱元数据DELETE/v1/sandboxes/:id终止沙箱并清理 cgroup返回 204POST/v1/sandboxes/:id/ping与 Guest 内 agent 往返验证存活POST/v1/sandboxes/:id/exec在沙箱内起子进程可设timeout_secsPOST/v1/sandboxes/:id/eval在已预热的 Python 解释器PID 1里求值表达式创建请求中最常用的开关per_child_netns: true—— 每个子 VM 独占网络命名空间需先运行 scripts/netns-setup.sh 预配池memory_limit_mib—— 通过 cgroup v2memory.max限制内存live_fork: true—— 以 memfd 支撑内存启动为后续mode: live分支铺路要求 Linux ≥ 5.7prewarm: true—— 恢复后立即做一次丢弃型快照把首次 BRANCH 的冷缓存惩罚2–9 倍摊平到创建阶段。一次 API 调用批量派生 100 个沙箱的实测曲线每沙箱内存占用与累计耗时5.4 BRANCH 分支端点150 毫秒分身 ⚡POST /v1/sandboxes/:id/branch是 forkd 的灵魂端点暂停运行中的沙箱 → 快照其内存与 vmstate 为新 tag → 恢复运行。三种模式mode暂停窗口原理full0.5–8 s暂停期内写完整 guest RAMdiff~200 ms空闲源只写脏页完整镜像异步重建live子 50 msUFFD_WP 异步捕获脏页需live_fork: true启动两个高频选项tag可省略守护进程自动生成branch-源id-时间戳-hexwait: false仅 live 模式——源恢复约 10 ms立即返回快照状态为writing后台拷贝完成后翻转为ready轮询GET /v1/snapshots即可感知。同一 tag 的并发 BRANCH 会收到409 Conflict超过并发上限默认 4返回503 Service Unavailable。不同模式的暂停窗口对比实测5.5 Workspace 端点可挂起的有状态工作区 Workspace 是快照 tag 名字的封装支持跨守护进程重启的 suspend/resume方法路径说明GET / POST/v1/workspaces列出 / 创建创建即拉起一个运行中沙箱GET / DELETE/v1/workspaces/:name查询 / 删除连带清理其状态快照POST/v1/workspaces/:name/suspend挂起到ws-name-state状态 tag可选diff: true加速写入POST/v1/workspaces/:name/resume从最近状态快照恢复运行状态机为running → suspended → running守护进程崩溃后状态变为stale需重新 resume。六、Prometheus 监控/metrics 指标清单 GET /metrics输出 Prometheus 文本格式text/plain; version0.0.4指标名保持稳定可直接被 exporter 依赖指标类型用途forkd_snapshots_totalgauge已注册快照数forkd_sandboxes_activegauge活跃子 VM 数forkd_branches_in_flightgauge正在写 memory.bin 的 BRANCH 数forkd_branch_concurrency_capgauge配置的 BRANCH 并发上限forkd_orphan_firecrackers_detected_totalcounter检测到孤儿 Firecracker 进程累计次数可配告警forkd_build_info{versionX.Y.Z}gauge恒为 1label 携带构建版本最小 Grafana 告警建议forkd_orphan_firecrackers_detected_total增长、forkd_branches_in_flight长期贴近 cap 值。七、审计日志与错误码 每个请求都会向审计日志追加一行 JSON时间戳、方法、路径、状态码、延迟、来源 IP、UA实现在 crates/forkd-controller/src/audit.rs。运维要点日志轮转rename 文件后向守护进程发送SIGHUP它会原子重开路径不丢记录优雅停机SIGTERM/SIGINT 触发最多 30 秒的在途请求排空统一错误体所有 4xx/5xx 都带{ error: human-readable message }。状态码典型场景400 Bad Requesttag 非法、mode与diff同时设置、cascade与force冲突401 Unauthorized缺 Bearer Token 或令牌不匹配404 Not Found快照 tag / 沙箱 id / workspace 名不存在409 Conflicttag 已存在、快照正在写、删除会破坏 diff 链未带 cascade/force500 Internal ErrorFirecracker 启动/恢复/快照失败503 Service UnavailableBRANCH 达到并发上限、共享 tap 被占用、netns 池耗尽八、延伸阅读 端点契约细节含请求/响应 JSON 示例docs/API.md安全设计与威胁模型docs/SECURITY.md运维手册systemd 单元packaging/systemd/forkd-controller.servicedocs/RUNBOOK.mdBRANCH 模式设计推导docs/design/branching.md暂停窗口实测数据bench/pause-window/RESULTS-v0.3.md 小贴士本地单租户开发可直接用默认回环免认证模式只要计划把 API 暴露到局域网或 K8s 集群请始终成对启用--token-file与 TLS。【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 forkd REST API完全参考：Controller守护进程全端点、认证、TLS与Prometheus监控详解
forkd REST API完全参考Controller守护进程全端点、认证、TLS与Prometheus监控详解【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkdforkd 是一个高性能 Agent 沙箱系统通过快照写时复制Copy-on-Write技术让预热虚拟机在约 100 毫秒内派生 100 个独立实例。forkd Controller 守护进程对外暴露一套 REST API默认127.0.0.1:8889本文带你从启动、认证、TLS 加密到每一个 v1 端点与 Prometheus 监控指标完整读懂这套 API。一、认识 Controllerforkd 的控制平面 ️你可以把 forkd 想象成一套虚拟机流水线快照Snapshot把一台预热好的虚拟机冻结成vmstate memory.bin文件作为母版沙箱Sandbox从母版快速恢复出的独立子虚拟机彼此完全隔离KVM 级别分支Branch运行中的沙箱暂停约 150 毫秒复制出新母版再恢复运行。所有这些操作都通过forkd Controller 守护进程的 REST API 驱动CLI、Python SDK 都是它的客户端。官方端点文档见 docs/API.md路由实现在 crates/forkd-controller/src/http.rs。二、一键启动默认配置与安全底线默认启动方式参考 crates/forkd-controller/src/main.rsforkd-controller serve \ --bind 127.0.0.1:8889 \ --state /var/lib/forkd/state.json \ --audit-log /var/log/forkd/audit.log \ --token-file /etc/forkd/token几个关键默认值配置项默认值说明--bind127.0.0.1:8889仅回环地址本地单租户可用--state/var/lib/forkd/state.json快照/沙箱注册表自动创建--audit-log/var/log/forkd/audit.log每请求一行 JSON 的审计日志--token-file未设置不设则免认证仅限回环BRANCH 并发上限4可用--branch-concurrency调整安全底线fail closed如果绑定到非回环地址如0.0.0.0:8889却没给--token-file守护进程会直接拒绝启动避免裸奔。这个校验逻辑就在 crates/forkd-controller/src/lib.rs。三、认证详解Bearer Token 三步走 启用认证只需两个动作守护进程侧把令牌写入文件并传给--token-file。令牌要求非空、至少 16 字节高熵随机值占位符REPLACE_ME/CHANGE_ME开头会被直接拒绝客户端侧每个请求带上请求头curl -H Authorization: Bearer token文件内容 \ http://127.0.0.1:8889/v1/sandboxes例外/healthz永远免认证/healthz/带尾斜杠也可以这样负载均衡器和 K8s 探活不需要持有凭证。认证中间件实现在 crates/forkd-controller/src/auth.rs有两个值得新手留意的细节令牌比较采用constant-time 比较subtle::ConstantTimeEq杜绝响应时间暴露令牌长度的时序侧信道令牌在启动时读取一次轮换令牌需要重启守护进程。所有 401 响应都返回统一格式{ error: missing bearer token }四、TLS 加密两条 PEM 文件开启 HTTPS 想让 API 走 HTTPS多租户或跨主机部署的推荐姿势只需成对提供forkd-controller serve \ --bind 127.0.0.1:8889 \ --tls-cert /etc/forkd/cert.pem \ --tls-key /etc/forkd/key.pem两个参数必须成对出现只给其一会报错退出底层使用 rustlsaws-lc-rs 加密提供器配置加载见 crates/forkd-controller/src/lib.rs建议配合 Bearer Token 双保险使用K8s 部署示例见 packaging/k8s/forkd-controller.yaml。部署前建议先跑一次forkd doctor它会检查内核版本、UFFD_WP、memfd、HugePages 等 14 项前置条件一眼确认你的主机是否满足live_fork等高级 API 的能力要求五、v1 全端点速查表 API 采用/vN前缀做版本管理破坏性变更会进入新前缀旧主版本并行支持一个小版本。当前 v1 共 20 个端点5.1 状态与发现端点方法路径说明认证GET/healthz存活探针恒返回{ok:true}免认证GET/version返回构建版本与 API 版本需要GET/metricsPrometheus 文本格式指标需要5.2 快照端点Snapshot方法路径说明POST/v1/snapshots用 kernel rootfs 启动母版机、等待用户态预热后做快照GET/v1/snapshots列出全部已注册快照DELETE/v1/snapshots/:tag删除快照链式快照支持?cascadetrue递归删整棵子树或?forcetrue孤立化子节点二者互斥GET/v1/snapshots/:tag/infov0.5 链信息链深度、父哈希、磁盘占用、依赖者列表POST/v1/snapshots/:tag/compact把多层 diff 链压平为无父的独立快照原子落盘中断不残留半成品POST /v1/snapshots的核心参数tag1–64 位字母/数字/-/_、kernel、rootfs、tap、boot_wait_secs≤60默认 10 秒预热窗口。5.3 沙箱端点Sandbox——一次 fork 100 台 方法路径说明POST/v1/sandboxes从快照 tag fork N 个子沙箱1 ≤ n ≤ 1000GET/v1/sandboxes列出活跃沙箱GET/v1/sandboxes/:id单个沙箱元数据DELETE/v1/sandboxes/:id终止沙箱并清理 cgroup返回 204POST/v1/sandboxes/:id/ping与 Guest 内 agent 往返验证存活POST/v1/sandboxes/:id/exec在沙箱内起子进程可设timeout_secsPOST/v1/sandboxes/:id/eval在已预热的 Python 解释器PID 1里求值表达式创建请求中最常用的开关per_child_netns: true—— 每个子 VM 独占网络命名空间需先运行 scripts/netns-setup.sh 预配池memory_limit_mib—— 通过 cgroup v2memory.max限制内存live_fork: true—— 以 memfd 支撑内存启动为后续mode: live分支铺路要求 Linux ≥ 5.7prewarm: true—— 恢复后立即做一次丢弃型快照把首次 BRANCH 的冷缓存惩罚2–9 倍摊平到创建阶段。一次 API 调用批量派生 100 个沙箱的实测曲线每沙箱内存占用与累计耗时5.4 BRANCH 分支端点150 毫秒分身 ⚡POST /v1/sandboxes/:id/branch是 forkd 的灵魂端点暂停运行中的沙箱 → 快照其内存与 vmstate 为新 tag → 恢复运行。三种模式mode暂停窗口原理full0.5–8 s暂停期内写完整 guest RAMdiff~200 ms空闲源只写脏页完整镜像异步重建live子 50 msUFFD_WP 异步捕获脏页需live_fork: true启动两个高频选项tag可省略守护进程自动生成branch-源id-时间戳-hexwait: false仅 live 模式——源恢复约 10 ms立即返回快照状态为writing后台拷贝完成后翻转为ready轮询GET /v1/snapshots即可感知。同一 tag 的并发 BRANCH 会收到409 Conflict超过并发上限默认 4返回503 Service Unavailable。不同模式的暂停窗口对比实测5.5 Workspace 端点可挂起的有状态工作区 Workspace 是快照 tag 名字的封装支持跨守护进程重启的 suspend/resume方法路径说明GET / POST/v1/workspaces列出 / 创建创建即拉起一个运行中沙箱GET / DELETE/v1/workspaces/:name查询 / 删除连带清理其状态快照POST/v1/workspaces/:name/suspend挂起到ws-name-state状态 tag可选diff: true加速写入POST/v1/workspaces/:name/resume从最近状态快照恢复运行状态机为running → suspended → running守护进程崩溃后状态变为stale需重新 resume。六、Prometheus 监控/metrics 指标清单 GET /metrics输出 Prometheus 文本格式text/plain; version0.0.4指标名保持稳定可直接被 exporter 依赖指标类型用途forkd_snapshots_totalgauge已注册快照数forkd_sandboxes_activegauge活跃子 VM 数forkd_branches_in_flightgauge正在写 memory.bin 的 BRANCH 数forkd_branch_concurrency_capgauge配置的 BRANCH 并发上限forkd_orphan_firecrackers_detected_totalcounter检测到孤儿 Firecracker 进程累计次数可配告警forkd_build_info{versionX.Y.Z}gauge恒为 1label 携带构建版本最小 Grafana 告警建议forkd_orphan_firecrackers_detected_total增长、forkd_branches_in_flight长期贴近 cap 值。七、审计日志与错误码 每个请求都会向审计日志追加一行 JSON时间戳、方法、路径、状态码、延迟、来源 IP、UA实现在 crates/forkd-controller/src/audit.rs。运维要点日志轮转rename 文件后向守护进程发送SIGHUP它会原子重开路径不丢记录优雅停机SIGTERM/SIGINT 触发最多 30 秒的在途请求排空统一错误体所有 4xx/5xx 都带{ error: human-readable message }。状态码典型场景400 Bad Requesttag 非法、mode与diff同时设置、cascade与force冲突401 Unauthorized缺 Bearer Token 或令牌不匹配404 Not Found快照 tag / 沙箱 id / workspace 名不存在409 Conflicttag 已存在、快照正在写、删除会破坏 diff 链未带 cascade/force500 Internal ErrorFirecracker 启动/恢复/快照失败503 Service UnavailableBRANCH 达到并发上限、共享 tap 被占用、netns 池耗尽八、延伸阅读 端点契约细节含请求/响应 JSON 示例docs/API.md安全设计与威胁模型docs/SECURITY.md运维手册systemd 单元packaging/systemd/forkd-controller.servicedocs/RUNBOOK.mdBRANCH 模式设计推导docs/design/branching.md暂停窗口实测数据bench/pause-window/RESULTS-v0.3.md 小贴士本地单租户开发可直接用默认回环免认证模式只要计划把 API 暴露到局域网或 K8s 集群请始终成对启用--token-file与 TLS。【免费下载链接】forkd高性能Agent沙箱预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离并利用快照写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考