实例升级
1. 升级说明
Docker Compose 部署方式因架构简单,部署方式简洁,因此升级操作较其他方式也容易很多。
大多为镜像和少量配置的更新。
⚠️ 升级前必读:破坏性变更
每次升级前请务必查阅 csghub-omnibus Release Notes,确认当前目标版本是否引入了破坏性变更(Breaking Changes)。
当前已知破坏性变更示例:
| 版本范围 | 破坏性变更 | 处理方式 |
|---|---|---|
v2.3.0 及以上 | 内置 PostgreSQL 由 15.x 升级到 16.x | 升级前必 须执行 pg_dumpall 数据导出,升级后导入;否则容器启动后会因数据目录不兼容而失败 |
v2.0.0-ce/ee | Dataflow 日志存储由 MongoDB 切换到 PostgreSQL | 升级后需手动执行 Dataflow 数据库迁移 |
2. 前置操作
v2.3.0
PostgreSQL 数据库升级(15.x → 16.x)
v2.3.0 将内置 PostgreSQL 数据库从 15.17 升级至 16.14。PostgreSQL 大版本升级不兼容旧版本的数据文件,需通过逻辑备份与恢复(pg_dumpall / psql)完成升级。
1. 升级前准备(备份 v2.2.0 数据库)
在拉取新镜像前,进入容器停止所有应用服务,仅保留 PostgreSQL,然后导出全量数据。核心原则:备份与导入前后都需停止所有外部服务对 PostgreSQL 的写入。
-
停止除 PostgreSQL 外的所有服务:
# 停止所有服务docker exec -it csghub-omnibus csghub-ctl stop# 仅启动 PostgreSQLdocker exec -it csghub-omnibus csghub-ctl start postgresql -
导出全量数据库:
docker exec -it csghub-omnibus su - postgres -c "pg_dumpall --clean --if-exists -U csghub -f /tmp/all_dbs.sql" -
将备份文件拷贝到宿主机:
docker cp csghub-omnibus:/tmp/all_dbs.sql ./all_dbs.sql -
停止并移除旧容器:
docker compose down -
备份旧版 PostgreSQL 数据目录(防止回滚时需要):
默认数据目录路径为
./csghub/data/postgresql/data,以实际 docker-compose.yaml 中配置的./csghub/data:/var/opt/csghub映射为准。mv ./csghub/data ./csghub/data.backup
2. 启动新版本容器
拉取新镜像并启动容器。新容器的 PostgreSQL 16.14 将自动初始化一个空的数据库目录:
docker compose pull && docker compose up -d
3. 恢复数据库
等待容器就绪后,将备份数据恢复到新数据库中:
-
将备份文件拷贝到新容器中:
docker cp ./all_dbs.sql csghub-omnibus:/tmp/all_dbs.sql -
再次停止除 PostgreSQL 外的所有服务,确保没有其他连接正在读写数据库:
docker exec -it csghub-omnibus csghub-ctl stopdocker exec -it csghub-omnibus csghub-ctl start postgresql -
终止所有非模板连接,然后恢复数据:
docker exec -it csghub-omnibus su - postgres -c "psql -U csghub -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname NOT IN ('template0', 'template1') AND pid <> pg_backend_pid();\""docker exec -it csghub-omnibus su - postgres -c "psql -U csghub -f /tmp/all_dbs.sql"提示:
--clean --if-exists参数会在恢复时自动清理旧角色和数据库,避免与初始化创建的默认资源冲突。 -
重新配置并启动所有服务:
docker exec -it csghub-omnibus csghub-ctl reconfiguredocker exec -it csghub-omnibus csghub-ctl start -
验证服务状态:
docker exec -it csghub-omnibus csghub-ctl status
如果没有现网数据可迁移(例如全新安装或纯测试环境),可以跳过上述步骤直接执行
docker compose pull && docker compose up -d。
3. 升级操作
-
拉取镜像并重建容器(非 v2.3.0 跳过数据库备份,直接执行此步骤):
docker compose pull && docker compose up -d -
检查服务状态
docker exec -it csghub-omnibus csghub-ctl status
4. 升级后服务异常
如果升级后服务异常,先通过如下方式进行排查:
-
通过
docker compose logs -f查看详细报错通过日志通常可以判断出是初始化报错还是其他错误。如果是初始化报错需要检查
docker-compose.yaml中的配置 格式是否正确。 -
如果日志没有异常就进入到容器中通过
csghub-ctl tail <service>查看具体启动失败的容器报错 -
如果不能判断错误原因,请提交协助。