内部 PostgreSQL 升级

Coolify 自托管实例使用一个名为 coolify-db 的内部 PostgreSQL 数据库容器。普通的 Coolify 更新不会自动将 PostgreSQL 升级到新的主版本。

PostgreSQL 主版本升级（例如从 15 到 18）需要数据迁移。仅更改 Docker 镜像是不够的，因为 PostgreSQL 会拒绝由不同主版本创建的数据目录。

请先备份

在升级内部 PostgreSQL 数据库之前，请创建或验证最近的 Coolify 备份。升级脚本会保留之前的 Docker 卷以便回滚，但在更改数据库版本之前，您仍应拥有外部备份。

何时使用此功能

仅在需要将 内部 Coolify 数据库 升级到更新的 PostgreSQL 主版本时使用此功能。

不要将其用于您在 Coolify 中作为项目资源创建的 PostgreSQL 数据库。这些数据库拥有自己的生命周期和备份/恢复流程。

升级 PostgreSQL

在您的 Coolify 服务器上运行脚本：

/data/coolify/source/upgrade-postgres.sh 18

将 18 替换为目标 PostgreSQL 主版本。

脚本将执行以下操作：

检测当前的 coolify-db PostgreSQL 版本。
停止 coolify 应用程序容器以防止写入。
在 /data/coolify/backups/internal-postgres/ 中创建压缩的 pg_dumpall 备份。
创建一个新的 Docker 卷，例如 coolify-db-pg18。
使用目标版本将转储恢复到临时 PostgreSQL 容器中。
对恢复的数据库进行冒烟测试。
写入 /data/coolify/source/docker-compose.postgres-upgrade.yml。
使用新的 PostgreSQL 镜像和卷重启 Coolify 堆栈。
在 /data/coolify/source/postgres-upgrade-rollback.env 中保存回滚元数据。

PostgreSQL 18 卷路径

PostgreSQL 18 及更高版本使用 /var/lib/postgresql 作为容器挂载路径。较旧版本使用 /var/lib/postgresql/data。脚本会自动选择正确的路径。

Docker Compose 中的变更

脚本不会修改 docker-compose.yml 或 docker-compose.prod.yml。相反，它会创建此覆盖文件：

/data/coolify/source/docker-compose.postgres-upgrade.yml

对于 PostgreSQL 18，其内容类似于：

services:
  postgres:
    image: "postgres:18-alpine"
    volumes:
      - coolify-db:/var/lib/postgresql
volumes:
  coolify-db:
    name: "coolify-db-pg18"
    external: true

未来的 Coolify 更新会自动包含此覆盖文件，因此在正常升级后，升级后的镜像和卷将保持活动状态。

如果您还有 /data/coolify/source/docker-compose.custom.yml，PostgreSQL 升级覆盖文件将在自定义 compose 文件之后加载。对于冲突的 postgres 服务设置，PostgreSQL 升级覆盖文件优先。

回滚

如果升级后的数据库无法正常工作，请运行：

/data/coolify/source/upgrade-postgres.sh rollback

回滚使用上次成功升级期间保存的元数据。它会恢复之前活跃的 PostgreSQL 镜像、Docker 卷和挂载路径。

例如：

15 → 18 → rollback = 15
15 → 18 → 19 → rollback = 18

回滚仅支持单步操作。每次成功升级都会用之前活跃的版本替换回滚元数据。

回滚期间不会删除升级后的 Docker 卷。在确认回滚有效后，您可以手动检查或删除它。

脚本创建的文件

文件	用途
`/data/coolify/source/docker-compose.postgres-upgrade.yml`	指向升级后的 PostgreSQL 镜像和 Docker 卷的 Compose 覆盖文件。
`/data/coolify/source/postgres-upgrade-rollback.env`	`upgrade-postgres.sh rollback` 使用的元数据。
`/data/coolify/source/postgres-upgrade-*.log`	升级或回滚日志。
`/data/coolify/backups/internal-postgres/postgres-upgrade-*.sql.gz`	迁移前创建的压缩数据库转储。

验证活动的 Compose 配置

要检查 Coolify 将使用的最终 Compose 配置，请运行：

docker compose \
  --env-file /data/coolify/source/.env \
  -f /data/coolify/source/docker-compose.yml \
  -f /data/coolify/source/docker-compose.prod.yml \
  -f /data/coolify/source/docker-compose.custom.yml \
  -f /data/coolify/source/docker-compose.postgres-upgrade.yml \
  config

如果您没有 docker-compose.custom.yml，请从命令中删除该行。