open-compute 运维手册:备份、升级、故障恢复与 ocd doctor 诊断实战

原创2026-10-10 16:56:161,605 阅读

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 主机。

open-compute 自托管 Workers 平台主视觉

一、先认识你要运维的对象:一个二进制 ocd

open-compute 只有一种生产发行形式:按平台构建的单个 ocd 可执行文件,内嵌 workerd、Caddy、Pyodide 等运行时资产,启动全程离线,不需要外部资源目录或自动下载。这意味着运维心智模型很简单:

  • 一个文件:把匹配平台的 ocd 安装到固定路径(如 /opt/open-compute/ocd),替换二进制即完成部署;
  • 一份清单:用户级配置在 ~/.open-compute/,系统级在 /var/lib/open-compute/(ocd.toml + 各实例 compute.toml);
  • 一套服务:可用 systemd 单元、launchd 任务 或 容器编排 托管。

open-compute 平台架构:单二进制 ocd 内嵌 workerd、Caddy 与资源后端

完整构建与运行契约见 单二进制分发文档,故障排查手册总目录在 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,任一项失败即返回失败退出码。三个关键认知:

  1. doctor 不是自愈工具。损坏的 SQLite、错误的 master key、摘要不匹配都是"停止条件",不要靠反复执行 doctor 碰运气;
  2. 区分健康探针:/health/live 只代表进程存活,/health/ready 代表共享入口就绪,实例级状态要看 <instance_id>.localhost 上的 /health/status 或 ocd instances;
  3. ready 失败时先诊断再重启,按症状对照故障手册处理。

open-compute Dashboard 中的能力与运维视图示意

三、备份实战:创建、校验与保留策略

备份是离线、经过认证的全平台快照,覆盖 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 自动迁移,也不接受部分目录恢复——这正是演练恢复的价值所在。

open-compute Dashboard 实例状态与部署概览

四、升级实战: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 恢复

几个贯穿所有恢复场景的黄金法则:

  1. 恢复前必须先恢复清单与配置:ocd.toml、master key、各实例 compute.toml,保持原路径与私有权限;
  2. 禁止危险动作:不覆盖已有数据目录、不 force、不自愈改写 SQLite、不生成新 master key 覆盖旧平台、不手删快照 envelope;
  3. 恢复是原子操作:快照先全量验证到 staging,通过后一次性安装;失败时目标目录保持为空;
  4. 验证才算数:恢复后跑 doctor --full、KV/D1/DO 读写冒烟、二次重启,没有实际执行的验证不得记为成功。

open-compute 资源绑定与实例管理视图

六、收集 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 单二进制平台的日常运维、升级与灾备恢复就有了清晰、可演练的闭环。

登录后查看全文
open-compute