OpenProject 开发环境搭建指南：一份 Docker 配置跑通 Windows / Mac / Linux

OpenProject 开发环境搭建指南：一份 Docker 配置跑通 Windows / Mac / Linux

【免费下载链接】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 开发环境：后端跑在3000端口，前端热重载服务跑在4200端口，数据库、缓存全部容器化。之所以选 Docker 方案，是因为 OpenProject 的后端依赖（Ruby、PostgreSQL、Memcached、Angular 构建链）横跨多种语言与运行时，用仓库自带的 docker-compose.yml 一键拉起，可以彻底避开手动装组件时的版本漂移问题，三台不同系统的电脑跑出的环境完全一致。

搭建前快速自检

开始之前，对照下面的清单确认一遍，缺哪项补哪项：

• 内存 ≥ 4 GB（Docker 虚拟化宿主需分配至少 4 GB，不足时前端容器会以 "Exit status 137" 报错退出）
• 磁盘空闲 ≥ 20 GB（镜像、代码与依赖占用）
• 网络可用（首次拉取镜像和依赖较慢）
• 已安装 Git、Docker（Windows 上需为 Docker Desktop 并启用 WSL2 后端）
• 已安装 Node.js v18 或更高版本（前端构建依赖），版本管理推荐用 nvm：执行nvm install 18后nvm use 18

自检通过只需一条命令：终端里依次运行git --version、docker --version、node -v，三个版本号都能正常打印即可。

克隆代码并进入项目目录

把源码克隆到本地，然后切换到项目根目录，后面所有命令都在这个目录执行。

git clone https://gitcode.com/GitHub_Trending/op/openproject.git cd openproject

看到终端提示符出现在openproject目录下、且能ls出docker-compose.yml文件，即代表克隆成功。

配置 DEV_UID 开发变量并创建 gateway 网络

容器内的构建过程需要一个非 root 用户来写文件，否则项目目录下的文件都会变成 root 属主，后续操作会处处撞权限问题。OpenProject 用DEV_UID/DEV_GID两个变量告诉镜像"你是谁"，docker compose会从项目根目录的.env文件读取它们。仓库提供了现成的模板，复制一份并改成你自己的 ID 即可：

cp .env.example .env

然后编辑.env，把DEV_UID、DEV_GID改成当前系统用户的实际数字 ID（模板默认是1000/1001）。Mac / Linux 用户可以用id -u和id -g直接查到自己该填的值。

docker-compose.yml中的 hocuspocus 服务依赖一个外部网络gateway，它不在 compose 文件里自动创建，需要手动建一次（重复执行无副作用）：

docker network create gateway

三大平台差异一览

除DEV_UID/DEV_GID的写法外，三个平台后续流程完全一致，无需分别记忆：

💡 建议三个平台都优先走.env文件而不是临时 export，变量一次配置长期生效，换终端也不会丢。

启动容器并初始化数据库

下面三条命令依次完成：后端依赖与数据库初始化、前端依赖安装、拉起应用。setup是仓库内置的初始化目标，会在容器内完成 Ruby 依赖安装（bundle install）、创建并迁移数据库（db:create / db:migrate / db:seed），不需要手动进容器敲这些命令。

docker compose run --rm backend setup docker compose run --rm frontend npm install docker compose up -d backend

判定标准逐条给到：

• setup结束时无报错退出，容器内数据库迁移日志滚动完毕，即初始化成功；
• npm install末尾出现 "added xxx packages" 字样即依赖就绪；
• docker compose ps里backend、db、cache、frontend几个服务状态为 running，且 backend 处于 healthy 状态，即整套环境启动成功。

如果后端日志长时间停在启动阶段，用docker compose logs -f backend跟踪输出，确认没有报 "Could not resolve host" 之类的网络错误再往下走。👀

验收：访问地址、默认账号与界面确认

打开浏览器访问http://localhost:3000，应看到 OpenProject 首页：

使用默认账号登录：用户名admin，密码admin。登录后新建一个项目、打开任意工作包的详情页，能看到字段、评论与附件面板渲染正常，说明前后端、数据库、静态资源链路全部打通：

不想开浏览器也可以用命令行验收：curl -I http://localhost:3000返回HTTP/1.1 200 OK即后端就绪；curl -I http://localhost:4200有响应即前端服务正常。

常见问题排查

容器启动失败

多半是端口被占或镜像拉不下来。先看docker compose ps找出卡在 restarting / exited 的服务，再用docker compose logs <服务名>定位首行报错；3000 / 4200 被占用时，在docker-compose.override.yml（由docker-compose.override.example.yml复制而来）中用PORT/FE_PORT变量改端口即可，无需动主文件。

数据库连接错误

先确认db服务是否在运行：docker compose ps db。若在跑但后端报连接失败，检查docker compose logs db里是否有 "ready to accept connections" 字样——没有说明初始化未完成，等它就绪后重启后端服务即可。

前端编译报错

常见诱因是node_modules状态损坏（切分支、中断安装后尤甚）。在容器内删掉重装，比在宿主机折腾 Node 版本更可靠：

docker compose exec frontend bash -c "rm -rf node_modules && npm install"

重装后重新docker compose up -d frontend，编译日志恢复滚动且无红色 error 堆栈即恢复。

延伸阅读与命令速查

环境跑通后，建议按顺序阅读：

• 安装与运维文档：docs/installation-and-operations/installation/
• 开发文档总入口（含 Docker 开发详解）：docs/development/development-environment/docker/README.md
• 开发 FAQ：docs/development/faq/
• 贡献指南：CONTRIBUTING.md
• 前端源码在 frontend/src/（依赖定义见 frontend/package.json），后端 API 在 lib/api/

【免费下载链接】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