OpenProject 配置参数详解

目标：讲清 OpenProject 17.9.0 的配置体系——configuration.yml、OPENPROJECT_* 环境变量、数据库系统设置（管理后台）三层模型各自的职责、命名规则与优先级，并对数据库连接、邮件（SMTP）、附件存储（本地/S3）、认证与密码策略、会话 Cookie、缓存、代理与 HTTPS 等核心参数逐项展开，最后给出可直接套用的生产配置模板。基于 17.9.0 一体化镜像实测 + 官方文档溯源（溯源查询日期 2026-10-27）。

一、环境信息

• OpenProject：17.9.0（Community 标准版，官方一体化镜像，部署方法见 《OpenProject Docker Compose 部署实战》）
• 实测宿主机：Ubuntu 22.04（x86_64），Docker Engine 29.9.2
• 应用内部组件：Rails 8.1（应用框架）、PostgreSQL 17（内置）、memcached（内置缓存）、Caddy（入口）
• 演示管理账号：admin / q1w2e3r4
• 实测时间：2026-10-27

二、前置条件

• 已按部署篇完成一套可访问的 OpenProject 实例；
• 演示口令修改涉及管理后台「系统设置 → 认证」操作权限（admin 具备）；
• 在容器内执行 Rails 命令查看配置实况（本文多处使用）：

docker exec -it openproject-17.9.0-main bash -c "cd /app && bundle exec rails runner '<表达式>'"

三、参数查看与修改的三种途径

OpenProject 的参数分布在三层，先给结论表，再看各途径的查看/修改方法实测。

3.1 配置层实况查看（实测）

用 rails runner 打印配置对象，以下为本实例的实测回显：

docker exec openproject-17.9.0-main bash -c "cd /app && bundle exec rails runner 'cfg = OpenProject::Configuration; puts({host_name: cfg.host_name, https: cfg.https, default_language: cfg.default_language, password_min_length: cfg.password_min_length, attachments_storage: cfg.attachments_storage, attachments_storage_path: cfg.attachments_storage_path, rails_cache_store: cfg.rails_cache_store, edition: cfg.edition}.inspect)'"
# （输出节选）
# {host_name: "localhost:8142", https: false, default_language: "zh-CN",
#  password_min_length: 10, attachments_storage: :file,
#  attachments_storage_path: #<Pathname:/var/openproject/assets/files>,
#  rails_cache_store: :memcache, edition: "standard"}

对照本文 5.4 节的系统设置层实测（Setting.password_min_length 返回 8），同一「密码最小长度」在两层各有取值——优先级辨析见第四章。

3.2 环境变量全集查看（官方命令，实测）

官方提供 rake 任务列出全部可用环境变量及默认值，本实例实测输出 324 个变量（不含日志行）：

docker exec -it -e RAILS_ENV=production openproject-17.9.0-main \
  bash -c "cd /app && bundle exec rake setting:available_envs"
# （输出节选）
# OPENPROJECT_APP__TITLE (default="OpenProject") Application title
# OPENPROJECT_ATTACHMENT__MAX__SIZE (default=5120) Attachment max. size
# OPENPROJECT_ATTACHMENTS__STORAGE (default=:file) File storage configuration
# OPENPROJECT_BRUTE__FORCE__BLOCK__AFTER__FAILED__LOGINS (default=20) Number of login attempts per user before assuming brute force attack
# OPENPROJECT_EMAIL__DELIVERY__METHOD (default=nil) Email delivery method
# OPENPROJECT_FOG (default={}) Configure fog, e.g. when using an S3 uploader

3.3 系统设置层实况查看（实测）

密码策略等运营项存在数据库，实测读取（与 3.1 的配置层对照）：

docker exec openproject-17.9.0-main bash -c "cd /app && bundle exec rails runner 'puts({min_length: Setting.password_min_length, active_rules: Setting.password_active_rules, brute_force_block_after: Setting.brute_force_block_after_failed_logins, brute_force_block_minutes: Setting.brute_force_block_minutes, host_name: Setting.host_name}.inspect)'"
# {min_length: 8, active_rules: ["lowercase", "numeric"],
#  brute_force_block_after: 20, brute_force_block_minutes: 30,
#  host_name: "localhost:8142"}

min_length: 8 与 ["lowercase", "numeric"] 正是部署篇 4.4 节在管理后台放宽后的结果——系统设置层改动即时入库、即时生效，无需重启。

3.4 修改途径小结

• 环境变量：一体化镜像在 docker-compose.yml 的 environment: 段追加，docker compose up -d 重建生效；分离式官方 Compose 建议用 docker-compose.override.yml 或 .env 文件（官方明确 docker-compose.yml 本体不要编辑）；
• configuration.yml：挂载只读文件到容器 /app/config/configuration.yml（见部署篇第八章）；
• 管理后台：运营参数首选，实时生效，不用重启。

四、三层模型的优先级辨析

官方文档要求「只修改有文档说明的变量」，并给出命名与优先级规则，结合实测梳理如下：

1) 环境变量与 configuration.yml 的映射规则（官方原文规则，实测验证）：YAML 键转大写并加 OPENPROJECT_ 前缀；键内的下划线用双下划线 __ 转义，路径层级用单下划线连接。官方示例：scm.subversion.access_token 对应 OPENPROJECT_SCM_SUBVERSION_ACCESS__TOKEN。实测对照：本文环境变量 OPENPROJECT_HOST__NAME（host_name 键内含下划线）、OPENPROJECT_PASSWORD__MIN__LENGTH（password_min_length）、OPENPROJECT_DEFAULT__LANGUAGE（default_language）均遵循该规则。

2) 配置层是启动时快照：环境变量在应用启动时读取一次，改动需要重建容器。

3) 系统设置层运行时读取：密码策略这类参数的实际生效值来自数据库 Setting。实测证据链：环境变量 OPENPROJECT_PASSWORD__MIN__LENGTH=8 设置后，配置层 OpenProject::Configuration.password_min_length 仍为 10（该键不是密码校验器的取值源），真正生效的是 Setting.password_min_length = 8（管理后台修改后）。结论：密码策略请通过管理后台调整，不要指望环境变量；环境变量适合「连接哪里」类参数（数据库/缓存/SMTP/对象存储/主机名）。

4) 种子变量只管首次初始化：OPENPROJECT_SEED_* 前缀变量只在首启种子（或显式执行 db:seeds）时生效，官方明确「在运行中的系统修改这些变量不会有任何效果」（个别标注者除外）。详见 5.9。

五、核心参数分类详解

5.1 基础标识与访问

5.2 数据库连接

• 一体化镜像：内置 PostgreSQL 17 自动配置，无需（也不应）设置 DATABASE_URL，数据库仅在容器内 5432 监听；
• slim/分离式部署：用 DATABASE_URL 指向外部 PostgreSQL，官方 docker-compose.yml 的原文示例：

DATABASE_URL: "${DATABASE_URL:-postgres://postgres:p4ssw0rd@db/openproject?pool=20&encoding=unicode&reconnect=true}"

常用 URL 参数：pool（连接池，官方按 RAILS_MAX_THREADS 自动扩池——实测日志出现 Increasing database pool size to 17 to match max threads）、encoding=unicode、reconnect=true。生产建议单独建库建账号并限制 pool 与实例内存匹配。

• 数据加密密钥：OPENPROJECT_DATABASE__CIPHER__KEY（configuration.yml 中 database_cipher_key）用于加密库内敏感数据（SCM/LDAP 密码）。官方样例文件的警告原文要点：留空则不加密；一旦使用，丢失或更换该密钥将使已加密数据不可读；换钥需先 rake db:decrypt 改钥后 rake db:encrypt。

5.3 邮件（SMTP）

配置层默认（configuration.yml.example 实测原文）：

email_delivery_method: :smtp
smtp_address: smtp.example.net
smtp_port: 25
smtp_domain: example.net
smtp_authentication: :login
smtp_user_name: "openproject@example.net"
smtp_password: "my_openproject_password"

环境变量写法（官方文档原例，键名同样遵循 __ 规则）：

OPENPROJECT_EMAIL__DELIVERY__METHOD="smtp" \
OPENPROJECT_SMTP__ADDRESS="smtp.example.net" \
OPENPROJECT_SMTP__PORT="587" \
OPENPROJECT_SMTP__DOMAIN="example.net" \
OPENPROJECT_SMTP__AUTHENTICATION="plain" \
OPENPROJECT_SMTP__USER__NAME="user" \
OPENPROJECT_SMTP__PASSWORD="password" \
OPENPROJECT_SMTP__ENABLE__STARTTLS__AUTO="true"

要点：email_delivery_method 支持 smtp / sendmail，不设或设 test 则不实发邮件（开发/演示模式）；OPENPROJECT_BCC__RECIPIENTS（默认 true）密抄发送；OPENPROJECT_EMAIL__LIMIT__PER__DAY（默认 0 不限）可限制日均发信量防滥用。测试投递可在管理后台「系统设置 → 邮件通知」发送测试邮件，或观察 Rails 日志中的 Mailer#notification 行。

5.4 附件存储（本地 / S3）

本地存储（默认）：OPENPROJECT_ATTACHMENTS__STORAGE=:file，落盘目录由 OPENPROJECT_ATTACHMENTS__STORAGE__PATH 控制；一体化镜像实测解析为 /var/openproject/assets/files（对应挂载卷 /var/openproject/assets）。未归属任何对象（工作包/维基）的临时附件按 OPENPROJECT_ATTACHMENTS__GRACE__PERIOD（默认 180 分钟）由定时任务清理。上传限制：OPENPROJECT_ATTACHMENT__MAX__SIZE（默认 5120 KB）与 OPENPROJECT_ATTACHMENT__WHITELIST（默认空数组不限制）。

S3/对象存储（fog 体系）：17.x 的切换由两个条件共同决定（应用源码实测：上传器注册表仅在 fog 凭据非空时注册 :fog 项，实际选中由 attachments_storage 键决定）：① fog 凭据非空；② OPENPROJECT_ATTACHMENTS__STORAGE=:fog。相关变量（本实例 rake setting:available_envs 实测回显）：

OPENPROJECT_ATTACHMENTS__STORAGE (default=:file) File storage configuration
OPENPROJECT_FOG (default={}) Configure fog, e.g. when using an S3 uploader
OPENPROJECT_FOG__DIRECT__UPLOAD__EXPIRES__IN (default=14400) 直接上传签名表单有效期（秒）
OPENPROJECT_FOG__DOWNLOAD__URL__EXPIRES__IN (default=21600) 预签名下载 URL 有效期（秒）
OPENPROJECT_DIRECT__UPLOADS (default=true) 启用向 S3 的直接上传

配置途径二选一：

• 整包哈希：OPENPROJECT_FOG='{ provider: AWS, aws_access_key_id: "xxx", aws_secret_access_key: "xxx", region: "eu-central-1" }'（值必须是可被 YAML 解析的内联哈希，官方提示必要时用 !!str 包裹含特殊字符的字符串）；
• 逐键传递：OPENPROJECT_FOG_CREDENTIALS_PROVIDER=AWS、OPENPROJECT_FOG_CREDENTIALS_AWS__ACCESS__KEY__ID=...、OPENPROJECT_FOG_CREDENTIALS_AWS__SECRET__ACCESS__KEY=...、OPENPROJECT_FOG_DIRECTORY=<桶名>（对应配置键 fog_directory，上传器实测用它定位桶）、自建 S3 兼容存储（MinIO 等）再加 OPENPROJECT_FOG_CREDENTIALS_ENDPOINT=<地址> 与 OPENPROJECT_FOG_CREDENTIALS_PATH__STYLE=true。

要点：凭据结构实测为 fog.credentials 嵌套哈希 + fog.directory（桶名）两键——环境变量 OPENPROJECT_FOG_CREDENTIALS_* 与 OPENPROJECT_FOG_DIRECTORY 正是按命名规则映射到该嵌套结构；凭据里的 provider 应用初始化器会规范化为 AWS（兼容 aws/aws 两写法）；大文件走 100MB 分片上传（初始化器实测 max_put_chunk_size）；预签名/直连上传的主机名解析实测优先取 credentials.endpoint，未设置则拼 目录名.s3-区域.amazonaws.com——自建 S3（MinIO 等）必须设置 endpoint。直接上传（direct_uploads）把上传流量从应用侧转移到浏览器直连 S3，一体化镜像实测为 false。生产建议：S3 方案需保证桶与应用网络可达且时钟同步（预签名 URL 依赖签名时间），跨实例共享附件时必须用 S3 或 RWX 卷（见部署篇第十章）。

5.5 认证与密码策略

部署篇实测结论复述：首登强制改密走的是「数据库设置」层策略，环境变量 OPENPROJECT_PASSWORD__MIN__LENGTH 对已初始化实例无效；新装实例想一步到位可用 5.9 的 SEED_ADMIN_USER_* 变量。

API 认证相关（configuration.yml.example 实测键名）：apiv3_enable_basic_auth（默认 true，API v3 允许 apikey:<API密钥> Basic 认证，见部署篇 4.5 的 opapi- 前缀要点）、authentication.global_basic_auth（全局 Basic 凭据，官方警告该凭据等同管理员权限，慎用）。

5.6 会话与 Cookie

# configuration.yml.example 实测键名与默认值
session_cookie_name: "_open_project_session"   # 会话 Cookie 名
autologin_cookie_name: "autologin"             # 自动登录 Cookie 名
autologin_cookie_path: "/"
drop_old_sessions_on_login: false              # 登录时清除该用户旧会话（默认允许多端并发）
drop_old_sessions_on_logout: true              # 登出时清除该用户全部会话（默认开启）
disable_browser_cache: true                    # 禁止浏览器缓存登录态响应（安全默认开启）

环境变量对应 OPENPROJECT_SESSION__COOKIE__NAME、OPENPROJECT_DROP__OLD__SESSIONS__ON__LOGIN 等。会话签名密钥即 SECRET_KEY_BASE（部署篇已实测：换值重启即全体掉线）。

5.7 缓存

OPENPROJECT_RAILS__CACHE__STORE (=:memcache / :file / :memory)   # 缓存后端
OPENPROJECT_CACHE__MEMCACHE__SERVER (default=nil)                # memcached 地址 host:port
OPENPROJECT_CACHE__REDIS__URL (default=nil)                      # 或用 Redis
OPENPROJECT_CACHE__NAMESPACE (default=nil)                       # 多应用共享 memcached 时的键前缀
OPENPROJECT_CACHE__EXPIRES__IN__SECONDS (default=nil)            # 条目过期时间，空为不过期

一体化镜像实测：未显式设置 memcache server 地址，rails_cache_store 仍为 :memcache（镜像自动对接内置 memcached）。分离式部署必须显式配置（官方 compose 原例：OPENPROJECT_CACHE__MEMCACHE__SERVER: "cache:11211" + OPENPROJECT_RAILS__CACHE__STORE: "memcache"）。多实例部署建议 memcache/Redis 二选一，避免 file store 在多副本下的缓存不一致。

5.8 反向代理与 HTTPS

前端有 Nginx/Traefik/Caddy 终结 TLS 时的推荐组合：

OPENPROJECT_HTTPS=true                 # 应用按 HTTPS 生成链接与安全 Cookie

配套两点：① 代理必须向应用转发 X-Forwarded-Proto: https 与原始 Host 头（一体化镜像内置 Caddy 自动处理；slim 形态自行保证）；② 用 OPENPROJECT_ADDITIONAL__HOST__NAMES 登记外部域名（HOST 校验白名单）。本地 HTTP 直连场景一律 OPENPROJECT_HTTPS=false + OPENPROJECT_HSTS=false（部署篇实测组合）。

5.9 种子变量（仅首启生效）

初始管理员（官方文档原表，实测要点：种子口令默认 admin/admin 并强制首登改密；自动化场景可预设口令并关闭强制改密）：

OPENPROJECT_SEED_ADMIN_USER_PASSWORD="admin"        # 种子管理员口令
OPENPROJECT_SEED_ADMIN_USER_PASSWORD_RESET="true"   # 是否强制首登改密（true/false）
OPENPROJECT_SEED_ADMIN_USER_NAME="OpenProject Admin" # 显示姓名（空格拆分姓/名）
OPENPROJECT_SEED_ADMIN_USER_MAIL="admin@example.net" # 邮箱
OPENPROJECT_SEED_ADMIN_USER_LOCKED="true"           # 直接锁定 admin（纯 LDAP/SSO 场景）

⚠️ 注意：官方明确——若用 SEED_ADMIN_USER_LOCKED 或其他方式禁掉本地管理员，必须同时配置 LDAP/SSO 登录，否则系统无人可登录。

LDAP 连接种子：OPENPROJECT_SEED_LDAP_<名称>_* 系列变量（HOST/PORT/SECURITY/BASEDN/BINDUSER/BINDPASSWORD/LOGIN__MAPPING 等）。17.5 起种子器会校验键名并对未知键报错；键内下划线用 __ 转义（如 LOGIN__MAPPING），连接名里的下划线同样用 __（如 my__ldap）。这些变量在每次 db:seed（含包安装的每次 configure、k8s seeder Job）都会重放。

主题/设计种子（企业版）：OPENPROJECT_SEED_DESIGN_* 系列变量；默认每次种子重放并覆盖后台的定制，加 OPENPROJECT_SEED_DESIGN_ONLY__WHEN__EMPTY="true" 可改为仅在无定制时应用。

5.10 一体化镜像专属：协同编辑（hocuspocus）

官方文档原文要点：AIO 容器自带 hocuspocus 协同服务，由两个变量控制——OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__URL=auto（auto 表示自动生成密钥并拉起内置服务）、OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__SECRET=。改用外部协同服务时显式给 URL+SECRET，或在运行命令中把 URL 置空（-e OPENPROJECT_COLLABORATIVE__EDITING__HOCUSPOCUS__URL=）让配置入口回到管理后台。

六、生产配置模板（slim 分离式 .env）

以下模板整合本文各节推荐值，适配「slim 镜像 + 外部 PostgreSQL + memcached + Nginx TLS 终结 + MinIO」的生产形态（变量均经命名规则推导，替换尖括号内容后可用）：

# ---- 基础标识 ----
OPENPROJECT_HOST__NAME=pm.example.com
OPENPROJECT_HTTPS=true
OPENPROJECT_HSTS=true
OPENPROJECT_APP__TITLE=项目管理系统
OPENPROJECT_DEFAULT__LANGUAGE=zh-CN

# ---- 安全密钥 ----
OPENPROJECT_SECRET__KEY__BASE=<openssl rand -hex 128 生成，固定复用>
OPENPROJECT_DATABASE__CIPHER__KEY=<openssl rand -hex 32，启用后不可更换，务必备份>

# ---- 数据库（slim 必填）----
DATABASE_URL=postgres://openproject:<强口令>@db.internal:5432/openproject?pool=20&encoding=unicode&reconnect=true

# ---- 缓存（多实例必配）----
OPENPROJECT_RAILS__CACHE__STORE=memcache
OPENPROJECT_CACHE__MEMCACHE__SERVER=memcached.internal:11211

# ---- 邮件 ----
OPENPROJECT_EMAIL__DELIVERY__METHOD=smtp
OPENPROJECT_SMTP__ADDRESS=smtp.example.net
OPENPROJECT_SMTP__PORT=587
OPENPROJECT_SMTP__DOMAIN=example.net
OPENPROJECT_SMTP__AUTHENTICATION=plain
OPENPROJECT_SMTP__USER__NAME=openproject@example.net
OPENPROJECT_SMTP__PASSWORD=<SMTP口令>
OPENPROJECT_SMTP__ENABLE__STARTTLS__AUTO=true

# ---- 附件走 S3 兼容存储（MinIO）----
OPENPROJECT_ATTACHMENTS__STORAGE=:fog
OPENPROJECT_FOG_CREDENTIALS_PROVIDER=AWS
OPENPROJECT_FOG_CREDENTIALS_AWS__ACCESS__KEY__ID=<AK>
OPENPROJECT_FOG_CREDENTIALS_AWS__SECRET__ACCESS__KEY=<SK>
OPENPROJECT_FOG_CREDENTIALS_ENDPOINT=http://minio.internal:9000
OPENPROJECT_FOG_CREDENTIALS_PATH__STYLE=true
OPENPROJECT_FOG_CREDENTIALS_REGION=us-east-1
OPENPROJECT_FOG_DIRECTORY=openproject-assets

# ---- 登录保护 ----
OPENPROJECT_BRUTE__FORCE__BLOCK__AFTER__FAILED__LOGINS=20
OPENPROJECT_BRUTE__FORCE__BLOCK__MINUTES=30
OPENPROJECT_AUTOLOGIN=7

一体化镜像最小化演示配置（本文实测所用）见部署篇 4.2，两者差异本质是「连接哪里」由谁提供。

七、常见问题（FAQ）

Q1：设置了 OPENPROJECT_PASSWORD__MIN__LENGTH 但新口令仍按 10 位校验？ 密码策略实际取自数据库 Setting 层（3.1/3.3 实测对照：配置层 10、数据库层 8 并以后者生效）。请走管理后台「管理 → 系统设置 → 认证 → 密码」。

Q2：改了环境变量没生效？ 环境变量是启动时快照：一体化镜像要 docker compose up -d（重建容器而非 restart 能保证注入新值）；分离式官方 Compose 要求改 docker-compose.override.yml 后 docker compose down && up -d（官方文档原话）。另外变量名拼写错误不会报错，只会以默认值运行——用 rake setting:available_envs 清单核对（3.2）。

Q3：环境变量键里的下划线到底写几个？ 键内字面下划线用双下划线 __，层级分隔用单下划线 _。OPENPROJECT_HOST__NAME = host_name、OPENPROJECT_SMTP__USER__NAME = smtp_user_name、OPENPROJECT_SEED_LDAP_X_LOGIN__MAPPING = 登录属性映射键。17.5 起 LDAP 种子对未知键直接报错，其他场景仍是静默默认。

Q4：S3 上传报签名错误或 403？ 排查顺序：① OPENPROJECT_FOG_DIRECTORY 桶名与凭据是否匹配；② 自建 S3 是否漏了 ENDPOINT 与 PATH__STYLE=true；③ 应用与对象存储时钟偏差（预签名 URL 有效期 14400/21600 秒依赖时间同步）；④ 直连上传（direct_uploads）要求浏览器能直达 S3 端点，内网隔离时设 OPENPROJECT_DIRECT__UPLOADS=false 走应用中转。

Q5：SMTP 邮件发不出？ 先确认 EMAIL__DELIVERY__METHOD=smtp（不设则不实发）；再在容器内验证出口连通 nc -vz smtp.example.net 587；STARTTLS 与 SSL 二选一（587 用 SMTP__ENABLE__STARTTLS__AUTO=true，465 用 SMTP__SSL=true + 端口 465）；最后看 Rails 日志中 Net::SMTP 错误行定位认证/证书问题。

Q6：密钥（SECRET_KEY_BASE）丢了会怎样？ 全部会话立即失效（全员重新登录）；若启用了 DATABASE__CIPHER__KEY 加密且两者一起丢失，库内加密数据（如已保存的仓库凭据）不可恢复。两把密钥务必离线备份。

Q7：多实例部署附件怎么共享？ 两条路：S3/fog（5.4，推荐）或 RWX 共享卷（k8s chart 要求）。本地 file 存储在多副本下会「A 实例上传 B 实例 404」。

八、参考链接

• 官方环境变量指南（命名规则/优先级/变量表）：https://www.openproject.org/docs/installation-and-operations/configuration/environment/
• 官方高级配置总览（Docker/种子/示例）：https://www.openproject.org/docs/installation-and-operations/configuration/
• 部署与运维实测：《OpenProject Docker Compose 部署实战》
• 命令行操作（runner/备份/设置任务等）：《OpenProject 常用 CLI 命令详解》
• 产品定位与选型：《OpenProject 介绍与选型指南》