升级#

openprogram upgrade 更新代码并重启服务，但只在验证过新代码确实能启动之后才重启。它是"git pull 然后 openprogram restart"的安全替代。

它解决的问题是：OpenProgram 以可编辑安装（editable install）的方式装在仓库里，所以它运行的仓库就是它开发的仓库。一个坏提交在下次重启前都看不出来，而等到那时，本来能用来修复它的工具正好就是坏掉的那个。upgrade 把这个失败提前，挪到一个没人依赖的临时进程里。

快速参考#

openprogram upgrade status          # 会变什么？只读
openprogram upgrade --dry-run       # 打印计划，什么都不改
openprogram upgrade                 # 执行

执行过程#

七个步骤，按顺序执行。第一个失败会中断整条链并打印原因。

步骤	作用
preflight	拒绝脏工作区，解析目标提交，降级前先询问
checkout	将检出快进到目标提交
deps	`pyproject.toml` 变了就跑 `pip install -e .`，`web/package-lock.json` 变了就跑 `npm ci`
build	`npx next build`，仅当 `web/` 下有改动时
probe	用隔离 profile 在临时端口冷启动新代码，等待 `/healthz`，跑 doctor 检查，然后杀掉
restart	重启真正的服务
verify	轮询 `/healthz` 直到它报告新的提交 sha

restart 之前的一切都不会碰到正在运行的实例。语法错误、配置 schema 损坏、前端构建失败，都由 probe 步骤拦下，你的服务继续用旧代码提供服务。

决定升级前先确认#

status 告诉你有没有可更新的内容：

$ openprogram upgrade status
  channel        stable (origin/main)
  head           f5671fd25e4c6ae89e6d77f3fcffc4d4a2c0570a
  target         a2d7f95633527e182ac850e40aca727aa0f6a3e6
  update         available

加 --json 得到机器可读输出（head_sha、target_sha、update_available）。

--dry-run 解析目标并打印将要执行的步骤，不改动任何东西：

$ openprogram upgrade --dry-run
  [OK  ] preflight  stable → origin/main: 80d77d1ed44c → 1a4101433b13
  [OK  ] checkout   planned (dry run)
  [OK  ] deps       planned (dry run)
  [OK  ] build      planned (dry run)
  [OK  ] probe      planned (dry run)
  [OK  ] restart    planned (dry run)
  [OK  ] verify     planned (dry run)

参数#

参数	效果
`--dry-run`	打印计划步骤，不做改动
`--no-restart`	在 probe 之后停止。检出会移动、代码会被验证，但运行中的服务在你手动重启前仍用旧代码
`--yes`、`-y`	跳过降级所需的确认
`--channel NAME`	跟随另一条发布线，并记住它
`--json`	输出包含每个步骤的机器可读结果

通道（Channel）#

通道是要跟踪的 ref 的名字。stable 跟随 origin/main，也是唯一内置的通道。 --channel 会把你的选择持久化为 update.channel 设置，之后运行就不用再加参数。

某个步骤失败时#

失败会打印原因码（dirty-worktree、probe-failed、build-failed、 verify-failed 等）并以非零状态退出。

dirty-worktree — 提交或 stash 你的改动。upgrade 不会移动一个还有未完成工作的检出。
downgrade-needs-confirmation — 目标比你正在运行的版本旧。旧代码可能读不懂新代码写出的配置；确实要这么做就加 --yes。
probe-failed — 新代码启动不了。什么都没有重启，你的服务完好无损；问题要在上游修。
verify-failed — 重启发生了，但服务没有报告新的 sha。自动回滚尚未实现，所以命令会打印手动的逃生出口：
```
git -C <repo> checkout <previous-sha> && openprogram restart
```

每一步之后进度都会写入 ~/.openprogram/upgrade-state.json，升级中途挂掉时就去那里查。

升级#

快速参考#

执行过程#

决定升级前先确认#

参数#

通道（Channel）#

某个步骤失败时#

相关#