OpenProject Docker 数据库迁移指南：将 all-in-one 容器从 MySQL 平滑迁移到 PostgreSQL

OpenProject Docker 数据库迁移指南将 all-in-one 容器从 MySQL 平滑迁移到 PostgreSQL【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject本指南针对使用 OpenProject 官方 all-in-one Docker 镜像部署、当前以 MySQL 为底层数据库的安装实例详细讲解如何借助镜像内置的 pgloader 迁移脚本将全部数据平滑迁移到 PostgreSQL并在迁移后恢复正常容器启动流程。读完本文你将掌握从备份、搭建目标 PostgreSQL、配置MYSQL_DATABASE_URL与DATABASE_URL环境变量、执行迁移到迁移后清理的完整操作链路并理解迁移脚本在镜像中的底层实现原理。迁移方案概述与原理OpenProject 官方 Docker 镜像all-in-one 容器内置了一套基于 pgloader 的 MySQL → PostgreSQL 迁移方案。其核心思路是容器内同时预置 MySQL 与 PostgreSQL 客户端通过两个环境变量分别指定「迁移源」MySQL与「迁移目标」PostgreSQL的连接信息启动容器时由迁移入口脚本自动执行数据搬运并将过程反馈给你。从仓库的镜像构建配置可以印证这一设计。在 docker/prod/mysql-to-postgres/Dockerfile 中可以看到镜像安装mysql-client与postgresql-client保证迁移期间两种数据库客户端均可用通过COPY docker/mysql-to-postgres/bin/build /tmp/build-pgloader在镜像构建阶段编译 pgloaderbin/build脚本位于 docker/prod/mysql-to-postgres/bin/build通过COPY docker/mysql-to-postgres/bin/migrate-mysql-to-postgres /usr/local/bin/将迁移脚本安装为可执行命令该层镜像的默认入口CMD [migrate-mysql-to-postgres]就是迁移脚本本身。因此当你带着迁移环境变量启动官方镜像时容器会自动执行内置的migrate-mysql-to-postgres脚本全程无需手工安装 pgloader。OpenProject 还提供了一套自定义构建的 pgloaderpgloader-ccl其中嵌入了针对大型 MySQL 数据库迁移的内存优化可参考同仓库的打包版迁移指南 docs/installation-and-operations/misc/packaged-postgresql-migration/README.md 了解其背景。第一步迁移前备份当前安装任何数据库迁移都存在风险开始前请务必为现有安装创建一份完整备份。针对 Docker 部署备份要点如下详细步骤见 docs/installation-and-operations/operation/backing-up/README.md使用 docker-compose 的场景数据卷由 Docker 管理需按 Docker 卷备份的常规方式处理例如从数据库容器导出逻辑备份docker exec -it db_1 pg_dump -U postgres -d openproject -x -O openproject.sql以上命令假设数据库容器名为db_1实际名称可通过docker ps | grep postgres确认。使用 all-in-one 容器的场景备份你在启动容器时通过-v绑定的本地数据卷如pgdata、assets目录并可将数据库单独导出为逻辑备份docker exec -it $OP_CONTAINER_NAME su - postgres -c pg_dump -d openproject -x -O openproject.sql其中$OP_CONTAINER_NAME为你的 OpenProject 容器名可用docker ps | grep openproject查找。备份完成后建议将归档文件复制到安全的异地位置如对象存储或备份服务器以防迁移中途出现不稳定状态时能够回滚。第二步准备目标 PostgreSQL 数据库迁移的目标是一个 PostgreSQL 数据库。根据你的使用场景有两种选择使用容器内置 PostgreSQL 实例all-in-one 镜像内部自带配置好的 PostgreSQL可直接使用连接串postgres://openproject:openproject127.0.0.1/openproject无需任何额外搭建使用外部 PostgreSQL 数据库在容器之外搭建独立 PostgreSQL并像当初提供 MySQL 连接信息一样把连接信息交给容器。如果选择在宿主机容器外搭建 PostgreSQL以下是通用的基于 apt 的安装步骤请按你的发行版适当调整1. 安装 PostgreSQLOpenProject 要求至少 PostgreSQL 9.5[roothost] apt-get install postgresql postgresql-contrib libpq-dev如果发行版自带包过旧需要从上游获取更新版本的安装包。2. 切换到 PostgreSQL 系统用户[roothost] su - postgres3. 以 PostgreSQL 用户创建 OpenProject 的系统用户[postgreshost] createuser -W openproject命令会提示你设置密码。下文示例统一假设密码为openproject实际使用请务必选择强密码并将指南中的占位值全部替换为你的真实密码。4. 创建由该用户拥有的数据库[postgreshost] createdb -O openproject openproject5. 退出 PostgreSQL 系统用户[postgreshost] exit # 你现在又回到 root 了。第三步配置迁移所需的环境变量运行镜像内置迁移部分时需要为容器提供两个环境文件/变量分别指向迁移源与迁移目标。3.1 迁移源MYSQL_DATABASE_URL记下或复制当前 MySQL 的DATABASE_URL形如# 大致如下 # mysql2://user:passwordlocalhost:3306/dbname # 传入容器时将 mysql2 替换为 mysql MYSQL_DATABASE_URLmysql://user:passwordlocalhost:3306/dbname重要提醒该 URL 必须以mysql://开头而不是mysql2://这是因为迁移脚本pgloader需要的是标准的 MySQL 协议连接串而mysql2://是 Ruby 生态中 mysql2 适配器的专有前缀二者不可混用。3.2 迁移目标DATABASE_URL传入指向新 PostgreSQL 数据库的DATABASE_URL。它可以是容器内置库的默认值postgres://openproject:openproject127.0.0.1/openproject也可以是你按上文搭建的外部 PostgreSQL 的连接信息POSTGRES_DATABASE_URLpostgresql://USER:PASSWORDHOST/Database name如果密码中包含特殊字符需要注意在数据库 URL 中进行百分号编码percent-encoding。例如打包版指南中提供了一行 Ruby 命令用于转义密码openproject run ruby -r cgi -e puts CGI.escape(your-password-here);Docker 场景下可借助任意支持 URL 编码的方式先处理密码再拼接进DATABASE_URL。3.3 适配主机名localhost与host.docker.internal注意取决于你的 Docker 安装方式与网络配置数据库 URL 中的主机名localhost可能需要替换为host.docker.internal才能访问 Docker 宿主机。例如在 macOS 上localhost指向的是 Docker 客户端即容器自身而非宿主机。请根据你的 Docker 网络环境选择正确的地址。第四步运行迁移准备好上述两个环境变量后直接运行以下命令将环境变量内容替换为你的实际值docker run -it \ -e MYSQL_DATABASE_URLmysql://user:passwordlocalhost:3306/dbname \ -e DATABASE_URLpostgresql://openproject:PASSWORDlocalhost:5432/openproject \ openproject/openproject:latest镜像启动后会自动完成迁移所需的全部步骤包括检测到MYSQL_DATABASE_URL的存在触发内置的migrate-mysql-to-postgres迁移入口即 docker/prod/mysql-to-postgres/Dockerfile 中CMD指定的脚本使用 pgloader 将 MySQL 中的数据、表结构与索引搬运至目标 PostgreSQL在交互终端中向你输出迁移进度与后续操作提示。迁移耗时取决于当前安装的数据量大型数据库可能花费较长时间请耐心等待其完成。迁移脚本会通过容器日志明确告知你迁移状态与下一步应执行的操作。第五步迁移后的收尾工作迁移成功完成后需要移除迁移专用的MYSQL_DATABASE_URL环境变量并按正常方式启动容器docker run -d -p 8080:80 --name openproject \ -e SECRET_KEY_BASEyour-secret-key-base \ -e DATABASE_URLpostgresql://openproject:PASSWORDlocalhost:5432/openproject \ -v /var/lib/openproject/pgdata:/var/openproject/pgdata \ -v /var/lib/openproject/assets:/var/openproject/assets \ openproject/openproject:latest要点启动时不再传入MYSQL_DATABASE_URL否则容器会再次进入迁移流程保留指向 PostgreSQL 的DATABASE_URL若使用内置库则保留默认值即可若此前使用了绑定数据卷务必保持原有-v参数不变确保附件等文件数据不丢失。自此你的 OpenProject 容器便运行在 PostgreSQL 之上。若将来需要再次迁移或回滚请先恢复第一步中的备份归档再重复上述流程。常见问题与注意事项汇总问题/场景处理方式MYSQL_DATABASE_URL必须以什么协议前缀开头必须以mysql://开头不能是mysql2://数据库 URL 中密码含特殊字符先对密码做百分号编码再拼入 URL容器访问宿主机数据库失败将 URL 中localhost替换为host.docker.internal如 macOS 环境迁移后容器又执行迁移检查是否仍残留MYSQL_DATABASE_URL环境变量务必移除迁移耗时长属正常现象OpenProject 对 pgloader 做了内存优化pgloader-ccl请耐心等待完成PostgreSQL 版本要求OpenProject 要求至少 PostgreSQL 9.5此外若你使用的是 DEB/RPM 打包安装而非 Docker的 OpenProject可参考同仓库的 docs/installation-and-operations/misc/packaged-postgresql-migration/README.md其中覆盖了openproject config:set MYSQL_DATABASE_URL、sudo openproject run ./docker/mysql-to-postgres/bin/migrate-mysql-to-postgres、openproject reconfigure及可选卸载 MySQL 等打包版专属步骤其备份归档说明数据库 dump、附件、配置文件、仓库的打包对理解迁移前应保留哪些数据也很有参考价值。小结本指南完整覆盖了 Docker all-in-one OpenProject 从 MySQL 迁移到 PostgreSQL 的五个核心环节备份、搭建目标库、配置双环境变量、执行迁移与迁移后收尾。整个过程由镜像内置的 pgloader 迁移脚本自动驱动见 docker/prod/mysql-to-postgres/Dockerfile 及 docker/prod/mysql-to-postgres/bin/build你只需正确提供MYSQL_DATABASE_URL与DATABASE_URL两个连接串即可在最小人工干预下完成数据库底座的切换。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考