OpenProject 如何在离线（气隙）环境中安装？-开发者社区

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

如果目标服务器无法访问互联网（例如生产内网、气隙隔离环境），直接docker pull或在线安装 OpenProject 都不可行。官方给出的方案是：在一台有网络的机器上拉取并导出 Docker 镜像，把单个归档文件搬到离线主机，再用docker load加载后按常规 Docker 方式启动。Docker 镜像内置了全部依赖，因此离线主机上只需要已经装好 Docker Engine。

本文基于 Docker all-in-one 安装文档的 "Offline/air-gapped installation" 章节和安装 FAQ 整理，覆盖准备、镜像导出、传输、加载与启动验证。

为什么选择 Docker 而不是离线安装包

安装 FAQ 明确回答了"能否离线安装"：基于 Linux 包（deb/rpm）的安装方式在安装过程中需要加载相当数量的依赖（如 SQLite3、unzip、poppler-utils、unrtf 等），因此官方推荐离线安装使用 Docker 方案。Docker 镜像包含所有依赖，可以通过docker save作为单个文件传输，没有其他额外依赖。

FAQ 还给出了另一条可选路径：在可以联网的虚拟机上装好 OpenProject，再把整台虚拟机镜像复用到离线主机。本文主线采用官方推荐的 Docker 方案。

前提条件

离线主机已安装 Docker Engine：all-in-one 容器要求主机上有 Docker，"通常需要一个较新的操作系统"（见 Docker 文档开头）。
另有一台可访问互联网、同样装有 Docker 的机器，用于拉取和导出镜像。
硬件要求（系统要求文档，适用于单台服务器、最多 200 个总用户）：
- CPU：四核（≥ 2 GHz）
- 内存：4096 MB
- 空闲磁盘：20 GB
架构支持：从 OpenProject 12.5.6 起，容器同时发布AMD64（x86）和ARM64两个架构；注意BIM Edition 仅支持 AMD64。
镜像体积：文档说明导出文件约为700 MB，传输介质需要能容纳它。

另外，all-in-one 容器有一个与离线无关但需要提前知道的限制：该容器方案不支持在 OpenProject 内部集成本地代码仓库（可以引用外部仓库，但不能通过 OpenProject 本身来配置仓库）；需要此功能只能用包安装方式，而包安装恰恰不适合离线场景。

第一步：在有网机器上导出镜像

在可以访问互联网的系统上执行：

docker pull openproject/openproject:17 && docker save openproject/openproject:17 | gzip > openproject-stable.tar.gz

这会生成一个包含 OpenProject Docker 镜像的压缩归档openproject-stable.tar.gz（文档说明体积约 700 MB）。这里的17是文档当前使用的非浮动版本标签；如需其他版本，替换为对应的X.Y.Z标签即可。

可选：传输前验证镜像签名与来源

文档说明每个发布到 Docker Hub 的 OpenProject 镜像都用 Sigstore cosign 做了 keyless（OIDC）签名，附带 Release、SBOM、VEX 等认证信息。原文指出这是可选的，但对生产环境和气隙安装推荐执行。在在线机器上安装 cosign 后，可以验证例如 SBOM 这一项认证：

cosign verify-attestation \ --type https://cyclonedx.org/bom/v1.6 \ --certificate-identity-regexp 'https://github.com/.*/.github/workflows/.*' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ openproject/openproject:16

其他认证类型（Release、VEX）可用同样的命令更换--type验证。文档还建议：生产环境应把校验固定到不可变摘要（openproject/openproject@sha256:...）而不是标签；用cosign tree openproject/openproject:16可以列出镜像上挂载的全部信息。

第二步：把归档文件传到离线主机

把openproject-stable.tar.gz复制到目标系统，"用任何可行的方式"：文档列举了 sftp、scp，以及在真正气隙（air-gapped）场景下使用U 盘。

第三步：在离线主机上加载镜像

文件到位后执行：

gunzip openproject-12.tar.gz && docker load -i openproject-12.tar

这会解压归档并把其中的镜像层加载进 Docker。加载完成后.tar文件即可删除。

文档原样说明：原文第一步生成的文件名是openproject-stable.tar.gz，而第三步的示例命令里写的是openproject-12.tar.gz/openproject-12.tar。执行时请把这两个文件名替换为你实际传输的文件名（本文示例统一用openproject-stable.tar.gz，对应解压出的openproject-stable.tar）。

第四步：按常规方式启动容器

加载完成后，"安装和后续升级都与平时一样"——你只是把平时的docker pull（或隐式拉取）换成了上面的导出/加载步骤。

快速验证可用文档 Quick Start 中的命令（容器内已内置 PostgreSQL、memcached，属于测试/起步用的 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

各变量的用途（均来自文档说明）：

-p 8080:80：把容器 80 端口映射到宿主机 8080。
SECRET_KEY_BASE：Rails 的密钥基，替换为强随机值（文档建议用openssl rand -hex 64生成）。它必须像密码一样妥善保管，每次启动容器都必须复用同一个值，否则已有会话和加密后的数据库内容将无法读取；OpenProject 会拒绝以默认值或弱值启动。
OPENPROJECT_HOST__NAME：应用主机名，用于生成表单和邮件中的链接，需要与外部请求的主机名一致。
OPENPROJECT_HTTPS=false：关闭默认开启的 HTTPS 模式，让实例可以走纯 HTTP。文档强烈建议生产系统不要设为 false，而是在外层 Web 服务器做 TLS 终结；离线内网中若没有外部代理，请自行评估。
OPENPROJECT_DEFAULT__LANGUAGE：控制首次安装时基础数据和演示数据使用的语言，同时作为新用户的默认回退语言。

首次启动会花一些时间初始化；成功标志是文档描述的：几分钟后终端出现成功信息并给出默认管理员口令（登录名admin，密码admin），随后可用浏览器访问http://localhost:8080。该命令不做守护化、日志直接打在终端上，便于排查；确认无误后如需后台运行，改用-d：

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

如果重启容器不丢数据，文档建议在宿主机上创建/var/lib/openproject/{pgdata,assets}两个目录并挂载进容器（生产用法，需设置正确的对外主机名）：

sudo mkdir -p /var/lib/openproject/{pgdata,assets} docker run -d -p 8080:80 --name openproject \ -e OPENPROJECT_HOST__NAME=openproject.example.com \ -e SECRET_KEY_BASE=<your-secret-key-base> \ -v /var/lib/openproject/pgdata:/var/openproject/pgdata \ -v /var/lib/openproject/assets:/var/openproject/assets \ openproject/openproject:17

命名后可用docker stop openproject/docker start openproject停启。

排查与限制

伪 TTY 启动失败：文档记录了有用户因 pseudo-TTY 分配和写入/dev/stdout的权限问题无法以此方式启动 OpenProject，给出的变通做法是即使使用-d也加上-t参数。
all-in-one 容器不适合直接当生产形态：文档明确不推荐把单容器方案直接用于生产（它关闭 HTTPS、且数据库与组件耦合，影响后续升级）；更完整的生产路径是 Docker Compose 安装（每组件一个容器）。离线环境下同样适用：只是把 compose 流程里的docker pull换成本文的docker save/docker load，文档原话是"你只是把docker-compose pull或镜像的常规隐式下载替换成了这里描述的步骤"。
升级：离线升级流程与在线一致，同样是先在联网侧导出新版本镜像再传输加载，然后按对应安装方式正常升级。
版本标签：文档推荐使用非浮动标签（X.Y.Z）用于生产；浮动标签X.Y在补丁版本发布时会更新，且紧急修复的补丁版本仍可能触发数据库迁移，需要能运行 seeder/migrations 任务。