服务端升级

5 步走：备份 → docker pull → up -d → 健康检查 → 业务回归。顺利 30 分钟收工，出错按 9.5 回滚。

9.1 备份

升级前在 compose 目录（通常 /opt/jecloud-ai/）做两件事，文件下载到本机或对象存储。

1. 导出库：docker compose exec postgres pg_dump -U postgres jecloud_ai > backup/db-$(date +%Y%m%d-%H%M).sql
2. 归档文件：tar -czf backup/files-$(date +%Y%m%d-%H%M).tgz uploads data
3. 记下旧 tag：docker compose config | grep image: 贴到工单

注意： 没备份 = 不要升级。迁移失败或新版不兼容旧数据，没备份只能现场重建。

提示： 顺手查磁盘：df -h /var/lib/docker 剩余 ≥ 镜像大小 × 2，紧了先 docker system prune -f。

9.2 docker pull + up -d

核心动作：拉新镜像 → 改 compose tag → 重启。

1. 拉镜像（不影响线上）：docker pull registry.your-company.com/jecloud-ai/agent:v1.4.2
2. 备 compose 后改 tag：cp compose.yml compose.yml.bak.$(date +%Y%m%d-%H%M)，编辑 services.agent.image 那一行（只改 tag，别动其它字段）
3. 重启：docker compose pull && docker compose up -d

services:
  agent:
    image: registry.your-company.com/jecloud-ai/agent:v1.4.1   # 旧
    # ↓ 改成
    image: registry.your-company.com/jecloud-ai/agent:v1.4.2   # 新

注意： 不要用 docker compose restart。restart 只是把旧容器重启一下，不会按新 tag 重建，必须 up -d。postgres 的 tag 也别动。

9.3 健康检查

容器跑起来不等于服务可用。compose 按依赖顺序起：postgres 先 healthy → agent 再接请求。

1. docker compose ps 等到所有容器都是 Up (healthy)，刚启动只 Up 再等 30~60 秒
2. 本机探活：curl -i http://localhost:3001/health，期望 200 + JSON 含 "status":"ok"、llm_configured:true、mcp_configured:true
3. 跟 5 分钟日志：docker compose logs -f --tail=50 agent | grep -iE "error|exception" 不刷新红字即过

提示： 可忽略告警：刚启动的 postgres connection refused 1 次、websocket reconnecting < 3 次——重试就稳。持续刷的 ERROR 才是真问题。

9.4 业务回归

用普通业务账号（不是 admin）从浏览器跑一遍，5 项全过算业务面没回归。

1. 登录 + 进主界面，会话列表加载出来不卡白屏
2. 欢迎页点一条推荐问题，流式回答完整结束
3. 工作台 5 工具（审批 / 通知 / 备忘录 / 日历 / 通讯录）依次点开，列表能拉出
4. 底部工具标签（推荐问题 / 菜单地图 / 数据分析）依次点开，菜单地图能加载平台菜单树
5. admin → 系统设置 → 系统信息，「服务端版本」必须 = 本次目标 tag

注意： 版本号没变？docker pull 拿了缓存或 compose 还是旧 tag。重新跑 docker compose pull + docker compose up -d --force-recreate。

9.5 回滚

新版有 bug、迁移失败、配置死循环——按下面 4 步在 15 分钟内回到旧版。

1. 发公告 + 停服 + 留底当前库（用于事后捞脏数据）
2. 只起 postgres，把 9.1 那份 pg_dump DROP + CREATE + 重灌
3. 编辑 compose.yml 把 agent 的 tag 改回旧版，postgres 不动
4. docker compose up -d，跑 9.4 的 5 项业务回归

# 1) 停 agent + 留底当前库
docker compose stop agent
docker compose exec postgres \
  pg_dump -U postgres jecloud_ai -Fc -f /tmp/before_rollback.dump
docker compose cp postgres:/tmp/before_rollback.dump ./backup/
docker compose stop postgres

# 2) 只起 postgres，恢复升级前的备份
docker compose up -d postgres
docker compose cp ./backup/db-20260615-2200.sql postgres:/tmp/
docker compose exec -T postgres psql -U postgres \
  -c "DROP DATABASE jecloud_ai;" \
  -c "CREATE DATABASE jecloud_ai;"
docker compose exec -T postgres \
  psql -U postgres -d jecloud_ai -f /tmp/db-20260615-2200.sql

# 3) compose 改回旧 tag 后启全栈
docker compose up -d

注意： 数据丢失风险：恢复备份 = 抹掉升级后产生的新数据。必要时用留底的 before_rollback.dump 起临时库 jecloud_ai_dirty，按 created_at 导出 csv 让业务方补录。千万别 docker compose down -v：会把数据卷一起删，备份和当前库全没。

小贴士： 升级 / 回滚卡住？排查走日志查看与故障排查；自动重启策略 + healthcheck 配置见docker-compose 配置详解。

相关

• 日志查看与故障排查
• 数据备份与恢复
• 桌面端升级