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 GBDocker 虚拟化宿主需分配至少 4 GB不足时前端容器会以 Exit status 137 报错退出磁盘空闲 ≥ 20 GB镜像、代码与依赖占用网络可用首次拉取镜像和依赖较慢已安装 Git、DockerWindows 上需为 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的写法外三个平台后续流程完全一致无需分别记忆平台终端环境变量写法启动命令WindowsDocker Desktop WSL2PowerShell$env:DEV_UID 1000、$env:DEV_GID 1000或统一写入.env文件docker compose up -d backendMacTerminalexport DEV_UID$(id -u)、export DEV_GID$(id -g)或写入.envdocker compose up -d backendLinuxTerminal同 Mac若以非 root 运行 Docker 需先确认当前用户在 docker 组内docker compose up -d backend 建议三个平台都优先走.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开发 FAQdocs/development/faq/贡献指南CONTRIBUTING.md前端源码在 frontend/src/依赖定义见 frontend/package.json后端 API 在 lib/api/使用场景命令说明启动全部开发服务docker compose up -d backend拉起后端及依赖的数据库、缓存、前端查看后端实时日志docker compose logs -f backend排查启动失败时第一优先看它重跑依赖与数据库初始化docker compose run --rm backend setup换机器或清库后重新初始化运行后端测试docker compose exec backend bundle exec rspec在容器内跑 RSpec 用例前端测试docker compose exec frontend npm test在容器内跑前端测试停止整套环境docker compose down保留数据卷下次 up 直接恢复【免费下载链接】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），仅供参考