OpenProject 安装与使用完整指南：3 步启动自托管项目管理平台-平芜编程栈

OpenProject 安装与使用完整指南：3 步启动自托管项目管理平台

【免费下载链接】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 开源替代品之一。这篇文章带你从一台空机器跑起来一个可用的实例。

OpenProject 是什么：适合谁用

OpenProject 是 Web 端的项目管理平台：项目和组合管理、工作包（任务）跟踪、甘特图排期、缺陷跟踪、工时记录、Wiki 和论坛，一个系统全搞定。🚀

和 Jira、Asana 这类 SaaS 不同，OpenProject 的社区版免费且完全自托管——数据留在你自己的服务器上，不用担心数据主权，也不受供应商锁定。所以它特别适合这几类人：

想用一个开源平台替代 Jira / Asana / Monday 的团队
对数据主权有硬性要求的企业（金融、政务、医疗等强监管行业）
希望甘特图排期和敏捷看板共存于一套系统的团队

它的招牌能力是计划：把工作拆成工作包后，可以在甘特图上排起止时间、依赖关系和里程碑。

安装准备：硬件与环境检查

开始之前，先确认三件事。

硬件：官方最低标准是 4 核 CPU（2GHz 以上）、4GB 内存、20GB 空闲磁盘，可支撑 200 人以内使用；规模更大时按并发人数增加 CPU 和内存，细节见系统要求说明。

运行环境：官方推荐 Docker 方式部署，不用手工装 Ruby、PostgreSQL 这些依赖——Docker 镜像里数据库和缓存都打包好了。

客户端：Chrome、Firefox、Edge、Safari 的最新版本都能正常访问。

如果你是开发者、想直接跑源码，可以先拿到仓库：

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

克隆下来就是完整源码，开发用的容器环境在 docker/dev/。但如果你只是想用它管理项目，走下面的镜像路线就够了。

首次运行：一行命令快速启动

看到 OpenProject 跑起来的最快方式是 all-in-one 镜像：一条命令，应用、数据库、缓存全部装进一个容器。

docker run -it -p 8080:80 \ -e SECRET_KEY_BASE=<your-secret-key-base> \ -e OPENPROJECT_HOST__NAME=localhost:8080 \ -e OPENPROJECT_HTTPS=false \ -e OPENPROJECT_DEFAULT__LANGUAGE=en \ openproject/openproject:17

首次启动要执行数据库迁移和初始化数据，需要几分钟，别急着关终端。跑成功后输出里会出现一条成功信息，默认管理员账号是admin/admin。✅

现在打开浏览器访问http://localhost:8080，进来了。

登录后先做两件事：

创建第一个项目。向导问几个问题后生成项目概览页，之后可以在里面加成员、启用模块（Wiki、工时跟踪等）、创建工作包。
改掉 admin 密码。

启动前必改的配置：4 个 OpenProject 环境变量

上面的快速启动参数只适合本地尝鲜。要正式用起来，有 4 个环境变量必须动。

SECRET_KEY_BASE：整个系统的"主密钥"

作用：Rails 用它加密会话和数据库里的敏感内容。一旦更换，已有登录态和加密数据就读不出来了。
在哪里改：启动命令的-e SECRET_KEY_BASE参数。
改成什么样：一个强随机值，可以用openssl rand -hex 64生成。像保管密码一样保管它，每次启动必须用同一个值；OpenProject 遇到默认值或弱值会直接拒绝启动。

OPENPROJECT_HOST__NAME：用户看到的访问地址

作用：决定 OpenProject 生成的所有链接的样式，包括邮件里的链接。它和用户浏览器里的地址不一致，链接就会全乱。
在哪里改：启动命令对应参数；启动后也可以在后台管理 → 系统设置里改。
改成什么样：用户实际访问的域名，例如openproject.example.com。

OPENPROJECT_HTTPS：生产环境别动它

作用：控制是否强制 HTTPS，生产默认开启。
在哪里改：只有本地纯 HTTP 测试时才加-e OPENPROJECT_HTTPS=false。
改成什么样：生产保持开启，前面挂 nginx 或 Apache 反向代理做 TLS 终结，并转发X-Forwarded-Proto头即可。

OPENPROJECT_DEFAULT__LANGUAGE：初始数据的语言

作用：首次安装时决定内置类型、状态等基础数据的语言，也是新用户的回退语言。
在哪里改：启动命令对应参数。
改成什么样：中文团队填zh，英文团队填en，不传默认英文。

还有一步别漏：挂载数据目录。快速启动时数据库（pgdata）和附件（assets）都写在容器里，删容器就全没了。正式使用前在宿主机建一个目录（如/var/lib/openproject），把pgdata和assets两个子目录挂载进容器。官方单容器安装文档里有完整的生产启动示例。

OpenProject 安装常见坑 ⚠️

版本标签：镜像有浮动标签和固定标签两种。浮动标签会悄悄升级到新补丁版本，而补丁版本可能带数据库迁移。生产请用固定标签，升级要有计划。
all-in-one 镜像不支持内置代码仓库：容器形态只能引用外部仓库，不能由 OpenProject 自己管理本地代码库。需要这个功能请走包管理器安装。
Windows 未获官方支持：Docker 镜像也许能跑，但官方只保证 Linux（及 Docker 环境）的表现。
macOS 挂载报 "Operation not permitted"：把数据目录改放到当前用户拥有权限的文件夹下即可。
首启慢是正常的：数据库初始化要几分钟，长时间没输出时看终端日志找真实报错，而不是反复重启。

跑起来之后去哪里

实例跑通之后，可以按这个顺序深入：

部署与运维：安装与运维指南覆盖 Docker Compose（小实例官方推荐）、Helm（大实例推荐）和包安装等全部方式，以及备份、升级、监控的操作步骤。
进阶配置：邮件发送、单点登录、附件存储到 S3 等，在高级配置里逐项讲。
日常使用：项目、工作包、甘特图和报表怎么用好，从用户指南读起。
参与开发：仓库自带完整测试套件（spec/目录），开发文档会带你搭好本地开发环境。

遇到问题时，官方的 OpenProject Community 论坛是最活跃的地方，团队自己也在那儿用这套系统管理开发。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考