使用 Docker Compose 安装 OpenProject

该仓库包含了使用 Docker Compose 安装 OpenProject 的方法。

注意
需要 Kubernetes 安装方法？
请使用 OpenProject helm chart 在 Kubernetes 上安装 OpenProject。

快速入门

首先，您需要克隆 openproject-deploy 仓库：

git clone https://github.com/opf/openproject-deploy --depth=1 --branch=stable/15 openproject

复制示例 .env 文件并修改您需要调整的配置项：

cp .env.example .env
vim .env

如果您使用 .env.example 中默认的 OPDATA 值，需确保对应文件夹存在且拥有正确权限：

sudo mkdir -p /var/openproject/assets
sudo chown 1000:1000 -R /var/openproject/assets

接下来启动容器并在后台运行，同时拉取所有镜像的最新版本：

OPENPROJECT_HTTPS=false docker compose up -d --build --pull always

稍等片刻，OpenProject 将在 http://localhost:8080 启动运行。默认用户名为 admin，密码为 admin。
OPENPROJECT_HTTPS=false 环境变量显式禁用首次启动时的 HTTPS 模式。生产环境强烈建议在 TLS 终止代理后运行 OpenProject，正式使用前请移除该标志。

自定义配置

仓库中的 docker-compose.yml 文件可按需修改。但请注意，每次拉取更新时该文件会被覆盖。
最佳实践是使用 docker-compose.override.yml 文件进行自定义配置，例如挂载特定配置文件、覆盖环境变量或禁用不需要的服务。

详情请参考官方 Docker Compose 文档。

故障排除

pull access denied for openproject/proxy, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

在 docker compose up 过程中出现此提示可忽略。

若在 docker compose pull 时出现，添加 --ignore-buildable 选项可避免命令失败退出：

docker compose pull --ignore-buildable

HTTPS/SSL

默认情况下 OpenProject 启用 HTTPS 选项，但不会自行处理 SSL 终止。通常通过反向代理设置实现。未配置时访问会触发 ERR_SSL_PROTOCOL_ERROR 错误。

如需禁用 HTTPS 请参考下文。

若使用集成的 Caddy 代理处理出站连接，需重写 Caddyfile。默认配置会转发前端反向代理的 X-Forwarded-* 头信息而未自行设置，存在安全隐患。应在 Caddyfile 中配置 trusted_proxies 解决，详见 Caddy 文档。

端口

默认端口绑定到 0.0.0.0 表示公开访问。修改方法见下文。

镜像配置

OpenProject 提供适用于本 compose 设置的 slim 容器。
可用容器及版本信息请参阅 官方文档。

配置

通过修改 docker-compose.yml 中 x-op-app -> environment 下的环境变量可调整 OpenProject 配置。部分变量已预定义，可通过环境修改。

启动时直接传递变量：

VARIABLE=value docker-compose up -d

或在当前目录的 .env 文件中定义变量（参考 .env.example）。

禁用 HTTPS

OPENPROJECT_HTTPS=false

修改端口

PORT=4000

绑定到本地回环地址：

PORT=127.0.0.1:8080

指定镜像标签

TAG=my-docker-tag

BIM 版本

安装或切换至 BIM 版本请参考 Docker 安装 BIM 指南。

升级

从仓库拉取更新：

git pull origin stable/15

构建控制平面：

docker-compose -f docker-compose.yml -f docker-compose.control.yml build

备份现有数据：

docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup

执行升级：

docker-compose -f docker-compose.yml -f docker-compose.control.yml run upgrade

重启容器并拉取最新镜像：

docker compose up -d --build --pull always

备份

停止当前实例：

docker-compose down

构建控制脚本：

docker-compose -f docker-compose.yml -f docker-compose.control.yml build

执行备份：

docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup

重启服务：

docker-compose up -d

卸载

停止容器但不删除：

docker-compose stop

删除容器栈：

docker-compose down

[!注意]
此操作不会删除持久化数据卷（通常为 compose_opdata 附件卷和 compose_pgdata 数据库卷）。
数据卷名称取决于 docker-compose.yml 所在目录名（本例为 compose）。

彻底清除数据需手动删除卷：

docker volume rm compose_opdata compose_pgdata

故障排查

查看日志：

docker-compose logs -n 1000

完整文档请访问 官方文档。

网络问题

若遇到类似 OP#42802 的网络超时问题，尝试移除前端和后端独立网络配置（可能与使用 podman 有关）。

SMTP 设置失败：网络不可达

确保容器能解析外部 SMTP 服务器 DNS（参考 OP#44515）：

worker:
  dns:
    - "您的 DNS IP" # 或添加公共 DNS 如 8.8.8.8