系统更新说明

更新以同一发布版本的 Frontend、Backend、Executor Manager、Executor 和相关计算服务为一组。先备份、停止新增工作并排空任务，再停止所有执行服务、迁移数据库和统一切换镜像。

更新前

1. 确认目标版本的 Compose、环境变量和迁移要求，保存当前镜像标签与配置。
2. 备份 PostgreSQL、Memory Service 历史文件及对象存储；涉及 Mem0 版本变化时执行 部署指南 的只读预检和迁移流程。
3. 所有节点选择同一发布标签，避免 Backend、Manager 与 Executor 契约混用。
4. 进入维护窗口，停止新增任务、续聊、听记处理、授权和配置变更。暂停会产生新工作的定时任务，对全部执行节点设置 draining，等待 active_runs 为零，并等待已领取的听记任务结束。

draining 仍允许领取已绑定会话的任务，Manager 的定时入队也会继续工作。因此排空后必须停止所有 Manager，不能只设置 draining 后就开始升级中心服务。

先停止所有执行服务

在主节点停止 Manager；启用 AI 听记时同时停止 Worker：

docker compose stop executor-manager
docker compose --profile ai-note stop ai-note-worker

在每台边缘节点的部署目录停止对应 Manager：

docker compose -f docker-compose.worker.yml stop executor-manager-worker

确认所有节点都已停止，再在各执行机器查看平台管理的旧 Executor：

docker ps -a --filter label=owner=executor_manager --format 'table {{.ID}}	{{.Image}}	{{.Status}}	{{.Names}}'

核对清单中的会话均无运行任务，逐个停止仍在运行的旧 Executor，将 CONTAINER_ID 替换为清单中的实际 ID：

docker stop CONTAINER_ID

平台创建的动态 Executor 使用自动删除容器机制，停止后不会再被 Manager 附着。保留宿主机 WORKSPACE_ROOT、数据库和对象存储，既有会话续聊时按目标镜像重新创建执行器。不要清理用户基础浏览器或其他服务容器；它们不属于上述 owner 标签。拉取镜像或重启 Manager 不会自动替换仍在运行的 warm/persistent Executor。

更新主节点

在部署目录修改 .env 中实际使用的镜像变量，并在本次 shell 中设置相同值。以下 RELEASE_TAG 为待部署版本，占位值必须替换：

export BACKEND_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-backend:RELEASE_TAG
export EXECUTOR_MANAGER_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-executor-manager:RELEASE_TAG
export EXECUTOR_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-executor:RELEASE_TAG
export FRONTEND_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-frontend:RELEASE_TAG
export MEMORY_SERVICE_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-memory-service:RELEASE_TAG

docker compose pull backend executor-manager frontend memory-service
docker pull "${EXECUTOR_IMAGE}"
docker compose stop backend frontend memory-service
docker compose run --rm --no-deps backend /app/.venv/bin/alembic upgrade heads
docker compose up -d backend executor-manager frontend memory-service

迁移期间保持 PostgreSQL 可用。迁移命令使用目标 Backend 镜像，--no-deps 避免启动已停止的依赖服务；Backend 正常启动默认也执行 upgrade heads。多 head 部署使用 heads，回滚不可直接假设 downgrade -1 可用。镜像标签还应保存到部署配置，单次 shell export 不会持久化。

AI 听记启用时，用同一版本更新已停止的 Worker：

export AI_NOTE_WORKER_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-ai-note-worker:RELEASE_TAG
docker compose --profile ai-note pull ai-note-worker
docker compose --profile ai-note up -d --force-recreate ai-note-worker

更新边缘节点

主节点迁移和健康检查完成后，每台边缘机器在自己的部署目录执行。修改 .env 并在 shell 中显式设置目标镜像，Compose 读取 .env 不会自动导出 shell 变量：

export EXECUTOR_MANAGER_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-executor-manager:RELEASE_TAG
export EXECUTOR_IMAGE=registry.cn-hangzhou.aliyuncs.com/ripper/poco-executor:RELEASE_TAG
docker compose -f docker-compose.worker.yml pull
docker pull "${EXECUTOR_IMAGE}"
docker compose -f docker-compose.worker.yml up -d

Executor 不在 Compose 服务列表，必须在每个执行节点单独拉取实际 EXECUTOR_IMAGE。边缘节点明确使用 worker 编排；省略 -f 会读取默认主编排。保留原 EXECUTOR_WORKER_ID 和本地 WORKSPACE_ROOT，历史会话绑定不会因更新自动迁移到另一节点。

Compose 与配置变化

同步目标版本的两份编排，并逐项比较现有 .env。变量名相同不保证默认值、传入范围或运行契约没有变化。根目录 .env 只用于 Compose 插值，未写入 environment 或挂载的参数不会自动进入容器，见 配置参考。

Manager 启动脚本位于镜像中；修改本地脚本并重启旧镜像不会更新容器脚本。部署节点需保留工作区、对象存储和数据库数据，不执行 down -v 作为常规升级步骤。

仅更改前端资源且服务契约未变化时，可使用 docker compose up -d --force-recreate frontend。整个平台升级仍需完成上述维护流程。

升级后核对

检查服务健康、迁移版本、节点注册和 capacity，恢复节点的 online 状态；再验证登录、新任务、既有会话续聊、消息流、导出与下载。确认续聊容器实际使用目标 Executor 镜像。启用连接器、定时任务、听记或记忆时，验证对应链路后恢复定时任务并退出维护窗口。

从会话运行时之前的版本升级时，Manager 会把工作区 .poco/stream-outbox/ 下的旧格式事件日志（{run_id}.jsonl 和版本 1 的终态清单）移到同目录的 legacy-v1/，每个文件记录一次 legacy_runtime_journal_quarantined 错误日志。新版本无法补投递这些记录，升级前完成排空即可保证其中事件已经送达；确认对应运行均已结束后可删除这些目录。

出现错误先保留日志和运行标识，再按备份与迁移依赖制定恢复目标。数据库迁移回滚 描述适用条件；降级镜像不能自动恢复已经改变的数据库或外部数据。