跳到主要内容

实例升级

1. 升级说明​

Docker Compose 部署方式因架构简单，部署方式简洁，因此升级操作较其他方式也容易很多。

大多为镜像和少量配置的更新。

⚠️ 升级前必读：破坏性变更​

每次升级前请务必查阅 csghub-omnibus Release Notes，确认当前目标版本是否引入了破坏性变更（Breaking Changes）。

当前已知破坏性变更示例：

版本范围破坏性变更处理方式
v2.3.0 及以上内置 PostgreSQL 由 15.x 升级到 16.x升级前必须执行 pg_dumpall 数据导出，升级后导入；否则容器启动后会因数据目录不兼容而失败
v2.0.0-ce/eeDataflow 日志存储由 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 的写入。

  1. 停止除 PostgreSQL 外的所有服务：

    # 停止所有服务
    docker exec -it csghub-omnibus csghub-ctl stop
    # 仅启动 PostgreSQL
    docker exec -it csghub-omnibus csghub-ctl start postgresql

  2. 导出全量数据库：

    docker exec -it csghub-omnibus su - postgres -c "pg_dumpall --clean --if-exists -U csghub -f /tmp/all_dbs.sql"

  3. 将备份文件拷贝到宿主机：

    docker cp csghub-omnibus:/tmp/all_dbs.sql ./all_dbs.sql

  4. 停止并移除旧容器：

    docker compose down

  5. 备份旧版 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. 恢复数据库​

等待容器就绪后，将备份数据恢复到新数据库中：

  1. 将备份文件拷贝到新容器中：

    docker cp ./all_dbs.sql csghub-omnibus:/tmp/all_dbs.sql

  2. 再次停止除 PostgreSQL 外的所有服务，确保没有其他连接正在读写数据库：

    docker exec -it csghub-omnibus csghub-ctl stop
    docker exec -it csghub-omnibus csghub-ctl start postgresql

  3. 终止所有非模板连接，然后恢复数据：

    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 参数会在恢复时自动清理旧角色和数据库，避免与初始化创建的默认资源冲突。

  4. 重新配置并启动所有服务：

    docker exec -it csghub-omnibus csghub-ctl reconfigure
    docker exec -it csghub-omnibus csghub-ctl start

  5. 验证服务状态：

    docker exec -it csghub-omnibus csghub-ctl status

如果没有现网数据可迁移（例如全新安装或纯测试环境），可以跳过上述步骤直接执行 docker compose pull && docker compose up -d。

3. 升级操作​

  1. 拉取镜像并重建容器（非 v2.3.0 跳过数据库备份，直接执行此步骤）：

    docker compose pull && docker compose up -d

  2. 检查服务状态

    docker exec -it csghub-omnibus csghub-ctl status

4. 升级后服务异常​

如果升级后服务异常，先通过如下方式进行排查：

  1. 通过docker compose logs -f查看详细报错

    通过日志通常可以判断出是初始化报错还是其他错误。如果是初始化报错需要检查docker-compose.yaml中的配置格式是否正确。

  2. 如果日志没有异常就进入到容器中通过csghub-ctl tail <service>查看具体启动失败的容器报错

  3. 如果不能判断错误原因，请提交协助。