升级说明

升级已有部署时，运维人员需要了解的近期 schema 迁移信息都在这里。全新安装从空数据库开始，可以跳过这一页。部署的先后顺序和回滚方法，见滚动部署顺序和部署可靠性。

启动本次发布之前

启动本次发布之前，先运行 alembic upgrade head，升级到 0086_conversation_read_receipts。官方支持的部署脚本会在替换 API 之前执行迁移；除非下面特别说明，这里列出的每个迁移都只做增量修改，上一个发布还在运行时执行也是安全的。少数几个需要先停掉所有写入的迁移，列在执行不向后兼容的迁移里。

迁移完成后，用现有的完整环境变量启动主控制平面监听器：它会把新注册的设置项导入一次，具体见 Admin Settings。

近期迁移

新的排在前面。

迁移	改了什么
`0086_conversation_read_receipts`	新增一张空表，记录每个所有者在每个对话里最近读到的那次完成，并带有版本号索引和 job/attempt 索引，分别用于增量轮询和外键清理。它不改动任何现有行，只会在被引用的表上短暂持有外键定义锁。现有的浏览器回执，会在那个浏览器下次打开更新后的界面时导入；降级会丢掉云端的回执，但浏览器缓存不受影响。
`0085_terminal_resume_index`	在 `agent_jobs` 上以并发方式建一个部分索引，只收录终端还在等待恢复的轮次。它会读完整个任务历史，但不会阻塞正在运行的 API；如果中途中断，直接重跑即可。不改动任何行。
`0084_host_removal_move_out`	新增 `agent_runner_hosts.removal_moves_out` 和 `removal_leaves_unmoved`，所有已有主机上都是 false。这样已经在等待中的移除仍保持原来的含义：等正在运行的轮次结束后，再撤销这台主机。
`0083_host_move_out`	给准入限制的检查约束加上 `move_out` 这种用途。不改动任何已有数据。降级时会删除所有迁出用的限制；已经迁走的沙箱组保留各自的检查点。
`0082_team_environments`	给环境和环境绑定加上可为空的团队列，并允许仓库的默认设置指向任意一个环境。不改动任何已有数据。只要还存在团队环境（包括已归档的），降级就会被拒绝。
`0081_snapshot_pushed_commit`	新增 `agent_sandbox_snapshots.pushed_commit_sha`，并把每个从未发布过的快照的 commit 复制进去。`published_commit_sha` 保持原样，所以依赖它的旧 API 照常可用，也不会触发任何通知。
`0080_user_ssh_servers`	新增所有者 SSH 服务器相关的表，见 SSH 服务器。不改动任何已有数据。
`0079_teams`	新增团队相关的表：成员、一次性邀请、加入申请和团队审计日志。目前还没有别的地方引用团队，所以它不改动任何已有数据，也不影响任何人能运行或看到的内容。
`0078_environment_snapshots`	新增环境安装快照，并在环境绑定上加了 setup 指纹，用来决定一个工作区可以从哪个快照启动；见环境安装快照。
`0077_sandbox_usage_days`	新增按天统计的容器用量表，并在 `agent_sandboxes` 上建一个所有者索引，建索引时没有用 `CONCURRENTLY`。这张表每个保留容器只有一行，所以短暂的写锁很快就会释放。
`0076_mcp_residency_fence`	给 MCP 审批记录加上一个可为空的 residency 代次；已有的审批记录这一列为空。
`0075_runtime_upgrades`	新增两个空的 JSON 列，用于从管理员设置页面升级 agent。
`0074_host_removal_pending`	新增 `agent_runner_hosts.removal_requested_at`，所有已有主机这一列都为空。降级会删掉这一列，原本在等待移除的主机会停留在排空状态。
`0073_sandbox_restore`	新增 `cold` 和 `restoring` 两种沙箱状态，以及启动栅栏，把检查点和它所终结的那次运行绑在一起；见恢复被移除主机上的沙箱。已有的检查点不带栅栏，永远不会让沙箱组迁移。只要还有沙箱组处于 cold 或 restoring，降级就会被拒绝。
`0072_drop_old_memory_tables`	删除已经退役的记忆相关的表。如果回滚到 `0070` 之前，会发现这些表是空的，旧版记忆里的头像和偏好都没了。
`0071_temporary_workspaces`	去掉 `agent_threads.repo` 和 `agent_environment_bindings.repo` 上的 `NOT NULL`，让对话可以不关联仓库直接开始。只要存在这样的对话，降级就会被拒绝。
`0070_memory_cutover`	把记忆功能的开关和已保存的偏好，搬到持久记忆表里。
`0069_agent_memories`	新增持久记忆表。
`0067_failed_snapshot_wake`	只替换了一个触发器函数。
`0066_admin_job_listing_index`	在 `agent_jobs` 上以并发方式建索引。任务历史很长时会花一些时间，但不会阻塞正在运行的 API；如果中途中断，直接重跑即可。
`0051_host_drain_fence_epoch`	给每台主机回填一个非空的排空栅栏 epoch。之后只要与排空相关的生命周期、凭据、放置或归属状态发生变化，数据库就会轮换这个 epoch。V2 控制平面激活之后，这个修订和 recipe 标记 `AGENT_DEPLOY_DRAIN_FENCE_V2` 就是应用和 schema 回滚的底线；见回滚兼容性。
`0049_host_drain_fence`	让每台已有主机都从"没有部署排空所有者、也没有释放回执"的状态开始。它引入的 V1 标记只留给旧版编排器做过渡升级用；V2 激活之后，就不能再回滚到它了。
`0048_sandbox_plugins`	新增 `agent_threads.plugins`，已有对话默认不带插件。需要重新构建沙箱镜像，让更新后的 CLI 包装脚本能加载所选的插件。
`0046_job_claim_retry`	新增 `agent_jobs.claim_retry_at`，worker 的认领查询要用到它。已经在排队的任务仍可立即被认领。

更早的、需要停机维护窗口的修订，列在执行不向后兼容的迁移里。如果数据库还标记着 2026-09-10 之前已退役的旧迁移链，就无法直接升级；见保留旧迁移链的数据库。

新增迁移时

在同一个 pull request 里给上表加一行，写清楚升级线上部署的运维人员需要知道什么：会改动哪些已有数据、可能锁表多久、降级会不会被拒绝。然后把 启动本次发布之前 一节和 ENVIRONMENT.md 里写的 head 修订号也更新掉；有测试会检查这两处写的都是当前的 head。