forkd生产部署指南：systemd、审计日志、故障恢复与Kubernetes部署完整运维手册

【免费下载链接】forkd高性能Agent沙箱，预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例；运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离，并利用快照+写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd

forkd 是一款高性能 Agent 沙箱系统：预热虚拟机可在约 100 毫秒内派生 100 个独立实例，运行中约 150 毫秒"分叉"出新的运行环境。本文是一份 forkd 生产部署指南，覆盖 systemd 服务部署、审计日志与 logrotate 轮转、常见故障恢复方法，以及 Kubernetes 部署的完整运维流程，帮助新手把 Agent 沙箱稳定跑上生产环境。

💡 所有配置与路径均出自仓库自带资料，建议对照阅读：docs/RUNBOOK.md、packaging/systemd/forkd-controller.service、packaging/k8s/forkd-controller.yaml。

部署前准备：一键完成主机自检

生产部署前的第一步，是让主机具备 KVM、cgroup v2 与 Firecracker 运行条件。forkd 提供了两条自动化路径：

1. 运行sudo bash scripts/setup-host.sh完成 KVM、Firecracker 与 KSM 内存去重调优；
2. 运行sudo bash scripts/netns-setup.sh 100预置 100 个子 VM 所需的独立网络命名空间（scripts/netns-setup.sh）。

主机要求很克制：x86_64 Linux（内核 5.10+）、/dev/kvm可用、Firecracker v1.7+、cgroup v2 统一层级。装好二进制后，用forkd doctor一条命令完成 14 项体检——从平台、KVM、网络命名空间到快照目录空间，全部通过即可放心上线：

doctor的每个检查项都附带修复提示，能显著压缩"报错后盲目排查"的调试循环，实现位于 crates/forkd-cli/src/doctor.rs。

systemd 部署步骤：一条命令拉起守护进程

forkd-controller 以标准 systemd 服务形态运行，仓库直接提供生产级单元文件 packaging/systemd/forkd-controller.service：

sudo bash scripts/setup-host.sh sudo bash scripts/netns-setup.sh 100 cargo build --release sudo install -m 0755 target/release/forkd-controller /usr/local/bin/ sudo install -m 0644 packaging/systemd/forkd-controller.service /etc/systemd/system/ sudo mkdir -p /etc/forkd /var/lib/forkd /var/log/forkd sudo bash -c 'head -c 32 /dev/urandom | base64 > /etc/forkd/token' sudo chmod 600 /etc/forkd/token sudo systemctl daemon-reload sudo systemctl enable --now forkd-controller

启动后两个健康检查即可确认服务就绪：

curl http://127.0.0.1:8889/healthz # {"ok":true} curl http://127.0.0.1:8889/metrics # forkd_sandboxes_active 0

这个服务文件值得新手学习，它的要点包括：

• 自动重启：Restart=on-failure+RestartSec=2s，进程崩溃 2 秒后自愈；
• 最小权限：仅授予CAP_NET_ADMIN / CAP_SYS_ADMIN / CAP_KILL等必要能力，配合ProtectSystem=strict、NoNewPrivileges等加固项；
• 命名空间白名单：RestrictNamespaces=net mnt user pid cgroup，逐项注释了"为什么需要"，防止日后被误删；
• 热重载支持：ExecReload映射到 SIGHUP，用于审计日志轮转（下一节详述）。

🔐 安全提醒：令牌文件/etc/forkd/token等同于该主机的 root 凭证（见 docs/SECURITY.md）；若非回环地址绑定（--bind），务必追加--tls-cert / --tls-key启用 TLS。

审计日志：JSON 行格式 + 无重启热轮转

forkd 守护进程把每个 API 请求写为/var/log/forkd/audit.log中的一行 JSON（实现见 crates/forkd-controller/src/audit.rs）：

{"ts":"2026-05-12T07:12:34Z","method":"POST","path":"/v1/sandboxes","status":201,"latency_us":98342,"ua":"forkd-cli/0.1"}

字段包含时间戳、方法、路径、状态码、微秒级延迟与客户端标识，可直接被 vector / fluent-bit 采集进日志平台。

轮转策略由 packaging/arch/forkd.logrotate 提供：每周轮转、保留 8 份、压缩归档，postrotate中执行systemctl try-reload-or-restart。关键设计是：

• 守护进程收到 SIGHUP 后原子重开日志文件，不重启、不丢在途请求；
• 重开成功后向新文件写入一条log_reopened事件，方便审计断点核验；
• 手动轮转时只需移走文件后systemctl reload forkd-controller。

配合 Prometheus 抓取:8889/metrics，建议配置两条核心告警：

• forkd_sandboxes_active持续 5 分钟超过主机 vCPU 数的 80%；
• forkd_build_info指标缺失 1 分钟 → 守护进程宕机。

故障恢复：四类常见问题的快速处置

生产环境排障大多围绕以下四种症状展开（详见 docs/RUNBOOK.md 第 3 节）：

⚠️ 升级注意：升级时先systemctl stop forkd-controller（活动沙箱会被终止，持久化注册表保留），替换二进制后再启动——启动阶段的reconcile()会自动剪掉 PID 已不存在的沙箱条目，无需手动清理状态文件。

Kubernetes 部署：单 Pod 承载 N 个沙箱

forkd 的 K8s 模型与传统方案截然不同：一个 forkd-controller Pod 承载 N 个沙箱子 VM，K8s 调度器只在 Pod 创建时运行一次，扇出规模不影响调度开销（对比 Kata / Firecracker-on-K8s 的"一沙箱一 Pod"设计）。

入门清单已放在 packaging/k8s/forkd-controller.yaml，快速上手四步：

# 1. 生成令牌并替换 Secret 中的占位符 TOKEN=$(head -c 32 /dev/urandom | base64) sed -i "s|REPLACE_ME_WITH_32_BYTES_BASE64|$TOKEN|" forkd-controller.yaml # 2. 部署并观察 Pod kubectl apply -f forkd-controller.yaml kubectl -n forkd get pods -w # 3. 冒烟测试 kubectl -n forkd port-forward svc/forkd-controller 8889:8889 curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8889/v1/snapshots

清单内置了/healthz就绪探针与存活探针、Recreate升级策略（forkd 持有 VM 状态，不能滚动）、/dev/kvm与 cgroup v2 的 hostPath 挂载。

生产环境加固清单

按 packaging/k8s/README.md 与 docs/SECURITY.md 的建议，上线前完成四项加固：

1. KVM 访问：把privileged: true换成 KVM device plugin，Pod 以资源方式获得/dev/kvm，去掉特权模式；
2. 状态持久化：emptyDir只能撑过容器重启，必须换成 PersistentVolumeClaim，否则 Pod 重建后快照丢失；
3. 令牌管理：占位令牌（REPLACE_ME_*）会导致守护进程拒绝启动——忘记替换是"响亮失败"而非"静默失守"；令牌应按节点 root 权限级别轮换；
4. 专属节点池：把 Pod 固定到带/dev/kvm的节点（nodeSelector），不与不可信租户混部，并用 NetworkPolicy 锁死 8889 端口。

📌 托管 K8s（GKE/EKS/AKS）通常需要金属机型或显式开启嵌套虚拟化才能满足/dev/kvm要求。

容量规划：单机能跑多少个沙箱？

forkd 官方开发基准为 20 vCPU / 30 GiB 主机，实测 N=200 子 VM 共享同一快照约 750 ms 完成扇出。以 512 MiB 的 Python+numpy 预热父 VM 估算：

• 活跃沙箱：约 1 个/ vCPU（算力瓶颈）；
• 闲置池化沙箱：约 50 个/ 8 GiB Pod 内存（瓶颈是进程状态而非内存）；
• N=100 时写时复制开销仅0.12 MiB/子 VM，内存极少成为扇出上限。

下图是 100 个导入 numpy 的沙箱从派生到就绪的横评，forkd 以 101 ms 领先 Docker 约 3000 倍（bench/ 可复现）：

在自己的主机上跑bench/bench-spawn-100.sh，把数字写进容量规划表即可。

小结

• systemd：单元文件自带重启策略与最小权限加固，enable --now一步上线；
• 审计日志：JSON 行 + SIGHUP 原子重开，配合 logrotate 零丢失轮转；
• 故障恢复：四类高频故障都有标准处置路径，升级依赖启动期 reconcile 自愈；
• Kubernetes：一 Pod 多沙箱模型，生产化重点是 PV、KVM 插件与专属节点池。

按本文顺序走完，你就拥有一个可观测、可恢复、可扩容的 forkd 生产沙箱平台。

【免费下载链接】forkd高性能Agent沙箱，预热虚拟机可以在约 100 毫秒内派生出 100 个独立实例；运行过程中约 150 毫秒“分叉”出一个新的运行环境。底层使用 KVM 隔离，并利用快照+写时复制降低资源开销。项目地址: https://gitcode.com/deeplethe/forkd