open-compute 运维手册:备份、升级、故障恢复与 ocd doctor 诊断实战
open-compute 运维手册:备份、升级、故障恢复与 ocd doctor 诊断实战
open-compute 是一个自托管的、与 Cloudflare Workers 兼容的开源平台,把 Workers、KV、D1、R2、Durable Objects、Queues、Workflows、Cron、Cache、Images、Vectorize、AI Search 等能力打包进一个 Rust 二进制 ocd 中。本运维手册面向新手,带你掌握四件核心事:备份、升级、故障恢复,以及用 ocd doctor 做日常诊断——即使没有深度 Rust 背景,也能按手册安全维护你的 open-compute 主机。
一、先认识你要运维的对象:一个二进制 ocd
open-compute 只有一种生产发行形式:按平台构建的单个 ocd 可执行文件,内嵌 workerd、Caddy、Pyodide 等运行时资产,启动全程离线,不需要外部资源目录或自动下载。这意味着运维心智模型很简单:
- 一个文件:把匹配平台的
ocd安装到固定路径(如/opt/open-compute/ocd),替换二进制即完成部署; - 一份清单:用户级配置在
~/.open-compute/,系统级在/var/lib/open-compute/(ocd.toml+ 各实例compute.toml); - 一套服务:可用 systemd 单元、launchd 任务 或 容器编排 托管。
完整构建与运行契约见 单二进制分发文档,故障排查手册总目录在 docs/references/runbooks/。
二、日常诊断:ocd doctor 健康检查怎么用?
doctor 是运维的第一道防线,源码位于 crates/service/src/doctor/。它有两种模式(详细说明见 健康检查文档):
| 模式 | 用途 | 是否可在线执行 |
|---|---|---|
ocd doctor |
只读检查 schema、配置、缓存身份等 | ✅ 随时可跑 |
ocd doctor --full |
额外执行对象存储 canary 和一次临时 workerd 启动 | ⛔ 需停机并持有数据目录排他锁 |
ocd --instance dev doctor --json
输出是结构化 JSON:每项检查含 name、status(ok / warning / failed / skipped)和可读 message,任一项失败即返回失败退出码。三个关键认知:
- doctor 不是自愈工具。损坏的 SQLite、错误的 master key、摘要不匹配都是"停止条件",不要靠反复执行 doctor 碰运气;
- 区分健康探针:
/health/live只代表进程存活,/health/ready代表共享入口就绪,实例级状态要看<instance_id>.localhost上的/health/status或ocd instances; - ready 失败时先诊断再重启,按症状对照故障手册处理。
三、备份实战:创建、校验与保留策略
备份是离线、经过认证的全平台快照,覆盖 control / KV / D1 / DO / scheduler 数据与 Artifacts Git 仓库。手册见 整机备份与保留。
标准流程四步走:
# 1. 停止实例或整个 daemon
# 2. 创建命名快照
ocd --instance dev backup create --name nightly-20260826 --json
# 3. 逐对象流式校验(MAC/hash)
ocd --instance dev backup inspect --snapshot <uuid> --verify --json
# 4. 用保留计划管理旧快照,不手工删除
ocd --instance dev backup retention-plan --keep-last 7 --json
新手最需警惕的一个坑:Local 对象后端下的快照只是"一致性快照",不是异地备份。Local 模式的对象根目录固定在 <data.path>/objects,要覆盖磁盘或主机丢失,必须在停机后把完整实例数据目录(含 master key 与 objects/format.json)连同实际的 compute.toml 复制到独立存储。平台不支持 Local↔S3 自动迁移,也不接受部分目录恢复——这正是演练恢复的价值所在。
四、升级实战:ocd upgrade 的安全网
升级能力实现于 crates/service/src/release_upgrade/,操作说明见 运行与运维。ocd upgrade 自带完整安全网,建议按顺序使用:
ocd upgrade --dry-run # 先演练:下载、验证、试跑 migration
ocd upgrade # 正式替换已安装二进制
ocd upgrade --restore # 中断后恢复旧 release
升级的内部保护机制值得了解,它们让升级"失败也不会毁数据":
- 先验证后替换:下载目标后先校验所有已登记配置,并在只读 SQLite 快照上试跑 migration,通过后才替换二进制;
- digest 绑定的备份:二进制与升级回执(receipt)的备份保留到重启和就绪成功为止;
- 失败自动回滚:正常重启失败时自动恢复旧 release;若升级中断留下备份,后续升级会 fail closed(拒绝继续),直到你执行
ocd upgrade --restore; - 数据删除必须显式:
purge需 daemon 离线、--dry-run预览与--yes确认,双重防误删。
另注意:跨大版本可能改变 system runtime identity(如 0.3.0),此时旧实例不能原地升级,需在独立新实例上迁移数据,不要 reset 或清空旧数据来绕过拒绝。
五、故障恢复:按症状选择恢复路线
open-compute 的故障手册按"症状 → 停止条件 → 允许的变更 → 回滚 → 验证"组织,全部内嵌在二进制中可用 ocd docs 查看。对照表如下:
| 症状 | 首选路线 | 手册 |
|---|---|---|
| 二进制损坏 / 主机恢复 | 同 release 恢复快照 | 当前 release 恢复 |
| 数据目录丢失 / 灾备演练 | 全新主机恢复 | fresh-host 恢复 |
| 写入返回 507、空间告警 | 只读诊断 + 扩容 / 产品内 GC | 磁盘压力 |
| SQLite quick_check 失败 | 整机快照恢复,勿手改数据库 | SQLite 损坏 |
| workerd 反复重启 | 校验 runtime 资产后重启 | workerd 崩溃循环 |
| R2/快照超时 | 恢复同一 S3 权限,勿换 provider | S3 故障 |
| key 文件丢失 / 解密失败 | 用同一 operator 备份 key 核验 | Master key 恢复 |
几个贯穿所有恢复场景的黄金法则:
- 恢复前必须先恢复清单与配置:
ocd.toml、master key、各实例compute.toml,保持原路径与私有权限; - 禁止危险动作:不覆盖已有数据目录、不 force、不自愈改写 SQLite、不生成新 master key 覆盖旧平台、不手删快照 envelope;
- 恢复是原子操作:快照先全量验证到 staging,通过后一次性安装;失败时目标目录保持为空;
- 验证才算数:恢复后跑
doctor --full、KV/D1/DO 读写冒烟、二次重启,没有实际执行的验证不得记为成功。
六、收集 support bundle:报障前的标准动作
需要离线诊断时,用一条命令生成自动脱敏的诊断包,实现见 collect-support-bundle 手册:
ocd --config /var/lib/open-compute/instances/default/compute.toml \
support-bundle --output /var/tmp/open-compute-support.tar --json
bundle 仅包含白名单内容(release 身份、doctor 结果、metrics、schema、文件摘要),并内置 secret 扫描器:master key、S3/admin 凭据、日志正文、向量值、文档内容一律不进入包体。生成后自行校验 SHA-256 再离线分享即可。
七、新手运维清单(Takeaways)
- ✅ 每次维护窗口先跑
ocd doctor --json留档基线; - ✅ 备份四步:停机 →
backup create→inspect --verify→retention-plan管理保留; - ✅ Local 后端必须额外整目录备份到独立存储,快照不等于异地备份;
- ✅ 升级永远先
--dry-run,失败中断后用--restore收尾; - ✅ 恢复按症状对表走手册,恢复后以
doctor --full+ 冒烟写读为准; - ⛔ 红线:不手删 envelope、不覆盖数据目录、不 force、不绕过 secret 扫描器。
掌握以上流程,open-compute 单二进制平台的日常运维、升级与灾备恢复就有了清晰、可演练的闭环。




