5 分钟跑通 OpenProject：目录、启动与配置一次讲清
【免费下载链接】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 是自托管的开源项目管理平台，可替代 Jira 做项目组合管理、甘特图与敏捷跟踪。这篇安装与使用上手指南带你从 clone 到浏览器里看到页面，目录结构、启动命令、配置文件一次讲清。
先确认这三件事，再装依赖
结论先行：会 Docker 就能装 OpenProject，主机上不需要单独装 Ruby 或 Node。
- Docker 是唯一硬依赖。官方开发环境方案把 Postgres 数据库、Ruby、Node 等全部装进 compose 容器里，见 docs/development/。
- 内存至少 4GB。文档明确要求 docker compose 需要 4GB RAM，不足时前端容器会报 Exit status 137。
- 准备好用户 ID。
.env里的DEV_UID、DEV_GID要填本机用户 ID，否则容器生成的文件会归 root 所有。
顺着这条线读目录：入口 → 核心 → 资源 → 依赖
OpenProject 是 Rails 后端 + Angular 前端的双栈应用，目录按这个顺序读最省力。
入口层：config.ru和Rakefile承接外部请求与任务；URL 到控制器的映射集中在 config/routes.rb；Procfile.dev 列出了开发环境并行的 4 个进程——rails server、Angular 前端、good_job 后台任务、hocuspocus 协同编辑服务。
核心代码集中在app/：app/controllers/ 处理请求，app/models/ 承载数据与业务规则，app/services/ 放 489 个服务类，把导入导出、权限等逻辑从控制器里剥出来；UI 组件在app/components/与app/views/。前端在 frontend/，2000 多个 TS 与 SASS 文件，热更新靠npm run serve。
插件化模块在 modules/：gantt、meeting、storages、reporting 等 29 个子模块，每个都是独立 gem，企业级功能多从这里来。
静态资源：浏览器直接访问的文件在public/，经应用处理的图片、字体在app/assets/。
依赖管理：Ruby 侧看Gemfile（模块化版本是Gemfile.modules），版本锁定在.ruby-version（当前 4.0.6）；前端看frontend/package.json，要求 Node 24。其余一句话带过：db/migrate/是 260 多个迁移脚本，lib/是框架扩展，spec/是测试，config/environments/存各环境行为。
一条命令链起服务，这样验证启动成功
完整链路三步，共 6 条命令：
- 克隆代码并复制两个示例配置（override 文件负责端口暴露，不复制端口不生效）：
git clone https://gitcode.com/GitHub_Trending/op/openproject cd openproject cp .env.example .env cp docker-compose.override.example.yml docker-compose.override.yml- 初始化网络与依赖（backend setup 会自动起数据库、跑迁移并写入种子数据）：
docker network create gateway docker compose run --rm backend setup docker compose run --rm frontend npm install- 启动后端并检查状态：
docker compose up -d backend docker compose ps成功标准：docker compose ps中 backend 状态为 Up；浏览器打开http://localhost:3000出现登录页，种子用户可直接登录。要改前端代码时，再补跑docker compose up -d frontend启动 Angular 热更新。
OpenProject 配置速查表：改哪里
高频配置就下面这些，其余文件不用动：
| 文件 | 作用 | 什么时候需要改 |
|---|---|---|
.env | compose 环境变量：DEV_UID/DEV_GID、OPENPROJECT_EDITION | 首次运行必改 |
docker-compose.override.yml | 端口映射 | 3000 端口被占用时 |
| config/database.yml.example | Postgres 连接串，dev/test/prod 三套 | 不用内置数据库时 |
config/configuration.yml.example | 邮件发送、品牌标识等应用级配置 | 自托管改邮件或 Logo 时 |
| config/environments/ | development/test/production 的 Rails 行为 | 定制某环境行为时 |
| config/routes.rb | URL 路由映射 | 新增页面或接口时 |
Gemfile/frontend/package.json | 后端/前端依赖清单 | 加功能、加依赖时 |
⚠️ 一句提醒：config/credentials.yml这类文件专门存放密钥等敏感值，生产环境不要把明文密码直接写进仓库里的database.yml。
跑起来之后做什么
- 生产部署（反向代理、TLS、备份）走 docs/installation-and-operations/，别拿开发环境配置直接上生产。
- 验证改动：
bin/compose rspec spec/features/work_package_show_spec.rb能单跑一个功能测试用例。 - 动代码前先读 AGENTS.md 与 docs/development/ 里的开发环境指南，约定都写在里面。
【免费下载链接】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），仅供参考
