Redmine 7.0 配置参数详解

本文为 Redmine 配置体系详解篇：覆盖 configuration.yml 全部参数组逐项说明、database.yml 双数据库模板、邮件投递端到端实测（含收信取证）、OpenLDAP 统一认证接入全链路实测，以及附件存储、主题与插件目录结构在 Redmine 7.0 中的新变化。部署栈的搭建见《Redmine 7.0 Docker Compose 部署实战》，产品背景见《Redmine 7.0 介绍与选型指南》，命令行运维清单见《Redmine 7.0 常用 CLI 命令详解》。全部配置与命令均基于 Redmine 7.0.2 于 2026-10-27 实测。

一、配置体系总览

1.1 四层配置入口

Redmine 7.0 的运行时配置分散在四个入口，优先级从高到低：

层级	位置	职责	修改后生效方式
① 应用内设置	「管理 → 配置」页面，落库 `settings` 表	业务行为类：界面语言、Issue 追踪、邮件通知开关、仓库、附件大小上限等	即时生效
② configuration.yml	`config/configuration.yml`	基础设施类：邮件投递方式、附件路径、会话 Cookie、数据库加密密钥、SCM 命令路径	重启应用进程
③ database.yml	`config/database.yml`	数据库连接参数	重启应用进程
④ additional_environment.rb	`config/additional_environment.rb`	追加 Ruby 环境定制（环境变量、加载路径）	重启应用进程

两层职责的划分原则：「做什么」在管理界面配，「怎么连」在 YAML 配。例如「是否启用邮件通知、通知哪些事件」属于①，「SMTP 服务器地址、认证方式」属于②——邮件配置因此横跨两层，最常见的配置错误就是只在界面开了通知、没在 YAML 里写投递方式（或反之）。

本文聚焦②③两层的全部参数与④⑥章的实测；①层界面设置项以官方用户指南为准，不展开。

💡 技术拓展：为什么 Redmine 用 YAML 而不是环境变量做主配置 Redmine 是 Rails 应用，YAML 配置文件是 Rails 生态的惯例（数据库连接、应用配置都走 config/*.yml），优点是支持按环境（default / production / development）分块继承——production 块的值覆盖 default 块的同名键，同一套配置文件可在多环境复用。对比同批次的 Plane（Django，.env 环境变量驱动）与 OpenProject（Rails 同门，YAML+环境变量混合），Redmine 属于最传统的纯 YAML 风格，也因此对容器化部署不友好——官方镜像才额外设计了 REDMINE_DB_* 系列环境变量，在启动时生成 database.yml 来兼容。理解这条主线，配置排障就有了坐标：环境变量只管「引导」，落地的配置事实永远是 config/ 下这两个 YAML 文件。

1.2 配置文件从哪来

Redmine 发布包里只有 config/configuration.yml.example 模板，configuration.yml 不存在时应用用模板中的默认值运行（全部注释态、email_delivery 为空）。启用自定义配置的标准做法是复制模板后编辑：

cp config/configuration.yml.example config/configuration.yml

格式为标准 YAML：缩进两个空格（禁用 Tab，模板头注释显式警告），顶层分 default / production / development 三个环境块。合法性与生效验证（实测回显）：

$ cd /usr/src/redmine
$ ruby -ryaml -e 'YAML.load_file("config/configuration.yml"); puts "YAML 合法"'
YAML 合法

YAML 语法错误会让应用启动直接失败，改完先做这一步语法检查再重启。

二、configuration.yml 逐项详解

以下按模板中的参数组顺序逐项说明，参数名与注释均来自 7.0.2 的 configuration.yml.example 原文（10,185 字节）。

2.1 邮件投递：email_delivery

模板给出四种内置形态（注释示例），核心结构是 delivery_method + 对应 settings：

default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: smtp.example.com
      port: 587
      domain: example.com            # HELO 域
      authentication: :login         # :plain / :login / :cram_md5，无认证则省略
      user_name: redmine@example.com
      password: "邮箱密码"
      enable_starttls_auto: true     # 587 端口 STARTTLS

delivery_method: :smtp——直连 SMTP 服务器，参数最全，生产主流；
delivery_method: :sendmail——投递给本机 /usr/sbin/sendmail 命令，无 SMTP 参数，适合邮件服务就在本机的架构；
Gmail 型示例：enable_starttls_auto: true + 587 端口（模板注释原文给出完整写法）。

实际生效验证方法与完整端到端实测见第四章。

2.2 附件存储：attachments_storage_path

default:
  attachments_storage_path: /var/redmine/files

附件实体文件的绝对路径，留空则用默认值 files/（应用目录下）。此参数是生产部署最重要的参数之一：Docker 部署时官方镜像把 /usr/src/redmine/files 挂载出来（对应 B2 篇编排文件的 ../files-pg:/usr/src/redmine/files 卷），裸机多实例或希望附件独立分区的场景则显式指向独立路径。实测验证落盘结构（附件按「年份/月」两级目录存储）：

$ ls files/
2026
$ find files/ -type f
files/2026/10/27060117_upload-demo.txt

修改此参数后，历史附件不会自动迁移——新旧路径并存会导致老附件 404，官方为此提供了迁移任务 rake redmine:attachments:move_to_subdirectories（结构化迁移的姊妹任务，见 D1 篇任务清单）。

default:
  autologin_cookie_name: autologin        # Cookie 名（默认 autologin）
  autologin_cookie_path: /                # 生效路径
  autologin_cookie_secure: true           # 仅 HTTPS 传递（生产启用 HTTPS 后建议开启）

三个参数控制「自动登录」持久化 Cookie 的名字、路径与 Secure 标记。注意它只影响 Cookie 属性，自动登录功能的总开关在管理界面「认证」设置里（autologin 选项，默认关闭）。

2.4 版本库集成：scm_*

Redmine 可直接浏览 Subversion/Git/Mercurial 等仓库，这组参数决定调用哪些可执行文件：

default:
  scm_subversion_command: svn
  scm_mercurial_command: /usr/local/bin/hg
  scm_git_command: /usr/local/bin/git
  scm_cvs_command: cvs
  scm_bazaar_command: bzr
  scm_stderr_log_file: /var/log/redmine_scm_stderr.log   # SCM 命令错误日志

配套的路径校验正则（防路径穿越/越权浏览）按 SCM 各一条，支持 %project% 占位符把项目标识注入路径：

default:
  scm_git_path_regexp: /gitpath/%project%(\.[a-z0-9_])?/
  scm_subversion_path_regexp: file:///svnpath/[a-z0-9_]+

正则整体被 \A \z 包裹（全路径匹配）且区分大小写——官方注释原文强调这两点，配置过宽会放大仓库越权暴露面。本环境未启用仓库模块，参数保持注释态。

2.5 敏感数据加密：database_cipher_key

default:
  database_cipher_key: "一串足够长的随机密钥"

用于加密落库的敏感字段：SCM 密码、LDAP 认证源密码、双因素认证（TOTP）密钥。模板注释给出完整的密钥生命周期操作：

启用加密：设好密钥后执行 rake db:encrypt RAILS_ENV=production；
更换密钥：先 rake db:decrypt 解密 → 改密钥 → 再 rake db:encrypt。

模板原文的 WARNING 必须重视：密钥丢失或变更后，已加密数据将不可读。此密钥与 REDMINE_SECRET_KEY_BASE（会话密钥）是两把不同的钥匙——前者保护落库敏感字段，后者保护会话 Cookie 签名，轮换策略应分开管理。对应的加密任务在 7.0.2 的任务清单里实际存在（rake db:encrypt / db:decrypt / db:encryption:init，实测 rake -T 可见）。

2.6 会话令牌：secret_token

default:
  secret_token: '一串至少30字符的随机串'

会话 Cookie 完整性签名密钥，模板注释明确两点：更换后所有旧会话立即失效；负载均衡多实例部署必须各节点一致。在容器部署语境下它被 REDMINE_SECRET_KEY_BASE 环境变量替代（B2 篇 §2.1 已展开，镜像启动时注入），裸机部署才用此参数，二者取其一。

2.7 敏感操作二次确认：sudo_mode

default:
  sudo_mode: true
  sudo_mode_timeout: 15     # 分钟

启用后，改账号资料、项目管理员授权、全局设置、删除项目等敏感操作需要重输一次当前密码，15 分钟内免重复输入。7.0 默认开启（模板注释：Enabled by default）。这也是实测中通过 Web 界面改配置时偶尔弹出「请输入密码确认」的原因——是安全特性而非故障。

2.8 缩略图与甘特图：ImageMagick / Ghostscript / 字体

default:
  imagemagick_convert_command: /usr/bin/convert   # 附件缩略图
  gs_command: /usr/bin/gs                          # PDF 附件缩略图
  thumbnails_generation_timeout: 10                # 生成超时（秒）
  minimagick_font_path: /usr/share/fonts/ipa-mincho/ipam.ttf   # 甘特图 PNG 导出 CJK 字体

minimagick_font_path 对中文环境尤其重要：导出甘特图 PNG 时若不指定 CJK 字体，中文条目标签会显示为方块。模板注释注明该参数在 4.1.0 前叫 rmagick_font_path（改名陷阱，老教程常见错）。服务器需预装 ImageMagick/Ghostscript 与对应字体文件。

2.9 界面与杂项参数

参数	作用	备注
`max_concurrent_ajax_uploads`	同时上传的 AJAX 并发数	默认 2
`avatar_server_url`	头像服务器地址	默认 Gravatar，可换 Libravatar 或自建兼容服务
`common_mark_enable_hardbreaks`	Markdown 换行是否视为硬换行	`true` 时单个回车即换行
`webhook_blocklist`	Webhook 目标黑名单（IP 段/域名数组）	防 SSRF：把内网网段列入黑名单，避免内部 webhook 被外发探测
`pandoc_command`	Pandoc 可执行文件路径	7.0 新增：Office/LibreOffice 附件转 Markdown 预览
`markdownized_preview_generation_timeout`	Pandoc 预览生成超时（秒）	默认 10
`markdownized_preview_max_source_size`	预览转换的源文件大小上限（字节）	默认 10 MB
`markdownized_preview_max_output_size`	转换输出上限（字节）	默认 100 KB，超出截断

Pandoc 四件套是 7.0 的新功能组（A1 篇版本矩阵里提到的「7.0 新增 Pandoc 支持」落到配置层就是这组参数），让 .docx/.xlsx/.pptx/.odt 附件可以直接在浏览器预览。

三、数据库连接：database.yml

3.1 镜像生成版（事实基准）

容器化部署时 database.yml 由官方镜像 entrypoint 依据 REDMINE_DB_* 环境变量自动生成，本环境实际落地的文件内容（实测回显）：

production:
  adapter: postgresql
  host: "db-pg"
  port: "5432"
  username: "redmine"
  password: "q1w2e3r4"
  database: "redmine"
  encoding: "utf8"

七个键恰好是排障时最先核对的清单——连接类故障（端口错、认证错、编码错）都能在此文件与数据库服务两端对表定位。

3.2 手写模板（裸机部署参照）

PostgreSQL 生产模板：

production:
  adapter: postgresql
  host: 127.0.0.1
  port: 5432
  username: redmine
  password: "数据库密码"
  database: redmine
  encoding: utf8

MySQL 系（MySQL 8.0+ / MariaDB）生产模板：

production:
  adapter: mysql2
  host: 127.0.0.1
  port: 3306
  username: redmine
  password: "数据库密码"
  database: redmine
  encoding: utf8mb4
  variables:
    transaction_isolation: "READ-COMMITTED"

MySQL 系模板比 PG 多两处：encoding: utf8mb4（四字节字符）与 variables.transaction_isolation: "READ-COMMITTED"——后者也可不写在 yml 里、改为数据库服务端全局配置（B2 篇编排文件用的就是服务端 --transaction-isolation=READ-COMMITTED 方式），两处改一处即可，官方安装文档对 MySQL 系的这条硬性要求在 5.2 节对照实测中已验证（adapter=Mysql2、迁移与默认数据装载全部正常）。

版本适配提醒（A1 篇版本矩阵）：PostgreSQL 14+、MySQL 8.0–8.4；transaction_isolation 参数名在 MySQL 8.0 前后写法不同（旧版为 tx_isolation），老教程若出现该旧名需按实际版本改写。

四、邮件投递配置与端到端实测

4.1 配置装载验证

第二章 2.1 节写入 SMTP 配置并重启后，用 Rails 内嵌脚本读取 ActionMailer 实际装载值（实测回显）：

$ cd /usr/src/redmine
$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production \
    bundle exec rails runner \
    'm = ActionMailer::Base
     puts "delivery_method: #{m.delivery_method}"
     puts "smtp: #{m.smtp_settings.slice(:address, :port, :domain).inspect}"'
delivery_method: smtp
smtp: {address: "10.89.64.1", port: 8125, domain: "redmine.test"}

configuration.yml → ActionMailer 的装载链路即验证完成。（命令中的 SECRET_KEY_BASE 前置说明见 B2 篇排障 8.2：命令行会话需要显式补上会话密钥环境变量。）

4.2 发送测试邮件与收信取证

管理界面「邮件通知」页的「发送测试邮件」按钮面向管理员账号投递一封标题为 Redmine test 的邮件；等价的命令行触发（实测回显）：

$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production \
    bundle exec rails runner 'Mailer.test_email(User.find_by(login: "admin")).deliver_now
puts "测试邮件已投递"'
测试邮件已投递

在 SMTP 服务器侧抓到的完整报文头（实测取证，节选）：

Date: Tue, 27 Oct 2026 10:27:03 +0000
From: Redmine <redmine@example.net>
To: admin@dummy.invalid
Message-ID: <6ae07c7720743_42b00809dc@bd6eedb23eeb.mail>
Subject: Redmine test
MIME-Version: 1.0
Content-Type: multipart/alternative;
 charset=UTF-8

报文暴露了两个需要进管理界面改的默认值：发件人 redmine@example.net 与 管理员邮箱 admin@dummy.invalid。前者在「管理 → 配置 → 邮件通知」的「发件人」与「抄送」字段修改，后者在「我的账号」页设置——生产环境漏改发件人域名是退信的常见根因。

4.3 邮件排障三步法

实测沉淀的三步定位顺序：

YAML 装载层：§4.1 的 runner 脚本看 delivery_method 与 smtp_settings 是否与预期一致（配置文件语法错或写错环境块会让参数静默不生效）；
网络层：在应用所在主机 nc -zv <smtp地址> <端口> 验证可达（本实测环境的 SMTP 服务从应用侧连接探测通过）；
投递层：日志（log/production.log）搜 Net::SMTP 或 535/550 等 SMTP 错误码——认证失败、收件方拒信都会在此留下完整栈。

五、LDAP 认证接入（OpenLDAP 实测）

5.1 认证源配置参数

LDAP 配置入口在「管理 → LDAP 认证」→「新建认证模式」。Redmine 未提供 auth_sources 的 REST API，创建/编辑走 Web 表单。各字段与 OpenLDAP 目录的对应关系：

界面字段	本实测值	说明
名称	OpenLDAP 测试	显示名
主机	redmine-7.0.2-ldap	LDAP 服务器地址
端口	389	LDAPS 用 636
账号	cn=admin,dc=redmine,dc=test	绑定 DN（用于检索用户，非用户本人）
密码	（绑定账号密码）	开启 `database_cipher_key` 后加密落库
基准 DN	dc=redmine,dc=test	用户检索起点
登录名属性	uid	目录中登录名字段
名字/姓氏属性	cn / sn	on-the-fly 建号时的姓名来源
邮件属性	mail	同上，邮箱来源
即时用户注册	勾选	on-the-fly register：LDAP 验证通过即自动建档

测试环境目录结构（OpenLDAP 2.4.57，dc=redmine,dc=test）：

dn: uid=ldapuser,ou=people,dc=redmine,dc=test
objectClass: inetOrgPerson
uid: ldapuser
sn: Test
cn: LDAP Test User
mail: ldapuser@redmine.test

5.2 认证链路实测

配置提交后（302 回列表页，实测），认证源列表显示 LDAP / redmine-7.0.2-ldap。用 LDAP 目录账号直接登录 Redmine（登录页输入 ldapuser / q1w2e3r4，实测 HTTP 回显）：

ldapuser 登录: 302 -> /my/page

登录即成功——Redmine 以 uid=ldapuser,ou=people,dc=redmine,dc=test 为候选 DN 在基准 DN 下检索、绑定验证口令、通过后自动建档。建档结果核验（管理界面用户列表，实测回显）：

<id>6
<login>ldapuser
<mail>ldapuser@redmine.test

用户 id=6 自动注册，邮箱从 LDAP mail 属性同步。三个行为要点：

口令永远不落 Redmine 库：LDAP 用户的验证每次实时到目录服务完成，Redmine 只存档案；
on-the-fly 注册：不勾选时，LDAP 验证通过但本地无档案的用户会被拒绝，需管理员手工建号并选同一认证源；
绑定账号权限最小化：账号 字段的 DN 只需「检索用户」权限，不要用目录管理员 DN（实测为演示方便用了 admin DN，生产应建专用只读绑定账号）。

5.3 故障排查要点

「管理 → LDAP 认证」列表页每行有「测试」链接，直接验证绑定 DN 与基准 DN 的连通性，比用户登录试错更快。常见故障按序排查：主机/端口连通性 → 绑定 DN 或密码错 → 基准 DN 写错（检索为空）→ 属性名错（登录名属性不是 uid/sAMAccountName）。AD 域环境把登录名属性改为 sAMAccountName、基准 DN 写 dc=公司,dc=com 形态即可，其余流程一致。

六、附件、主题与插件目录结构

6.1 目录总览

Redmine 7.0 应用目录中与运维直接相关的五个目录（实测结构）：

/usr/src/redmine/
├── config/            # configuration.yml / database.yml（§二、§三）
├── files/             # 附件实体（attachments_storage_path 默认值）
├── log/               # production.log 等日志
├── plugins/           # 自定义插件安装点（README: "Put your Redmine plugins here."）
├── themes/            # 自定义主题安装点（README: "Put your Redmine themes here."）
└── public/plugin_assets/   # 插件静态资产输出目录

6.2 Redmine 7.0 的重要变化：主题目录迁移

7.0 起自定义主题目录从传统的 public/themes 迁移到应用根目录 themes/。实测两个事实：

public/themes 在 7.0.2 中不存在（ls 报 No such file or directory）；
内置主题 alternate 与 classic 移入 app/assets/themes/（纳入 Rails 资产管线），自定义主题放根目录 themes/。

老教程「把主题目录拷到 public/themes」的做法在 7.0 会静默失效——主题不报错，但永远不出现在选择列表。主题安装实测：把 PurpleMine2 主题目录放入 themes/ 后无需任何命令，重启即被识别（实测回显）：

$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production \
    bundle exec rails runner 'Redmine::Themes.themes.each { |t| puts "theme: #{t.id} -> #{t.name}" }'
theme: alternate -> Alternate
theme: classic -> Classic
theme: PurpleMine2 -> Purplemine2

启用方式：各用户「我的账号 → 界面主题」自选，或管理界面统一设置默认主题。

6.3 插件安装四步法（实测）

以 RedMica UI extension v0.6.0（官方插件目录收录的 UI 增强插件，requires_redmine version_or_higher: '6.0'，兼容 7.0）为例，标准安装路径：

① 放置：插件目录放入 plugins/（目录名即插件 id，如 plugins/redmica_ui_extension）；

② 依赖安装（仅当插件带 Gemfile）：

$ cd /usr/src/redmine
$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production bundle install
...(依赖解析与安装，生产环境只装非 development/test 组)...

③ 迁移（仅当插件带 db/migrate）：

$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production \
    bundle exec rake redmine:plugins:migrate

实测该插件无迁移脚本，任务静默成功（exit=0、无输出）——有迁移的插件会在此打印逐条迁移回执，与 B2 篇首次启动的迁移日志同构；

④ 重启并核验：

$ SECRET_KEY_BASE=$REDMINE_SECRET_KEY_BASE RAILS_ENV=production \
    bundle exec rails runner 'Redmine::Plugin.all.each { |p| puts "#{p.id} v#{p.version}" }'
redmica_ui_extension v0.6.0

重启应用进程后插件注册生效（实测重启后 HTTP 200），管理页底部「插件」列表同步显示。卸载反向操作：redmine:plugins:migrate 带 VERSION=0 回滚插件表结构 → 删除插件目录 → 重启（迁移回滚命令详见 D1 篇）。

⚠️ 排障沉淀：7.0.2 中不存在 redmine:plugins:assets 任务（实测 rake 报 Don't know how to build task，建议替代为 redmine:plugins:test / redmine:plugins:migrate）。老教程插件安装四步里的「assets 复制」一步在 7.0 已不需要——插件静态资产由 Rails 资产管线在启动时处理。任务清单以 rake -T 实测输出为准的原则，再次得到验证。

七、配置生效规则与排障实录

7.1 生效规则速查

改动	生效方式	实测依据
管理界面设置（settings 表）	保存即生效	无需重启
configuration.yml	重启应用进程	§4.1 邮件参数重启后装载
database.yml	重启应用进程	B2 篇 §3.1 迁移链路
主题目录（themes/）	重启识别	§6.2 主题列表实测
插件目录（plugins/）	bundle install + migrate + 重启	§6.3 四步实测

7.2 排障实录

实录一：改了 configuration.yml 邮件参数，发信行为不变。 现象是配置文件已改但测试邮件仍按旧参数投递。根因：参数写在了 development 块（复制模板时未删除尾部环境块），生产环境读的是 default + production 合并结果。定位方法即 §4.1 的 runner 脚本——它读的是 ActionMailer 运行时真实值，与配置文件文本解耦；修改生效必须重启进程。

实录二：rake redmine:plugins:assets 报 Don't know how to build task。 现象与完整回显见 §6.3 排障沉淀。根因是 7.0 移除了该任务（资产改由 Rails 管线处理），老教程步骤未更新。教训：7.0 时代所有 rake 步骤先过一遍 rake -T 再执行，任务名不存在时注意 rake 给出的 Did you mean? 提示。

实录三：LDAP 配置正确但登录始终失败。 排查顺序按 §5.3：先用认证源列表页「测试」链接排除绑定 DN/基准 DN 问题（本实测通过），再核对登录名属性——目录里用户主键是 uid 而配置写成 cn 时，检索命不中用户，登录永远拒绝。属性名与目录结构（ldapsearch 输出）逐字段对照是唯一可靠定位方式。

小结：Redmine 7.0 的配置面 = 两个 YAML（基础设施）+ 一个管理界面（业务行为）+ 三类目录（files/themes/plugins）。相比 6.x 需要重点记住的变化有三处：主题目录迁到根 themes/、Pandoc 预览参数组新增、redmine:plugins:assets 任务移除。日常运维命令（迁移、加密、清理、邮件收发任务）的完整实测清单请继续阅读《Redmine 7.0 常用 CLI 命令详解》。

Redmine 7.0 配置参数详解

Redmine 7.0 配置参数详解

一、配置体系总览

1.1 四层配置入口

1.2 配置文件从哪来

二、configuration.yml 逐项详解

2.1 邮件投递：email_delivery

2.2 附件存储：attachments_storage_path

2.3 自动登录 Cookie：autologin_cookie_*

2.4 版本库集成：scm_*

2.5 敏感数据加密：database_cipher_key

2.6 会话令牌：secret_token

2.7 敏感操作二次确认：sudo_mode

2.8 缩略图与甘特图：ImageMagick / Ghostscript / 字体

2.9 界面与杂项参数

三、数据库连接：database.yml

3.1 镜像生成版（事实基准）

3.2 手写模板（裸机部署参照）

四、邮件投递配置与端到端实测

4.1 配置装载验证

4.2 发送测试邮件与收信取证

4.3 邮件排障三步法

五、LDAP 认证接入（OpenLDAP 实测）

5.1 认证源配置参数

5.2 认证链路实测

5.3 故障排查要点

六、附件、主题与插件目录结构

6.1 目录总览

6.2 Redmine 7.0 的重要变化：主题目录迁移

6.3 插件安装四步法（实测）

七、配置生效规则与排障实录

7.1 生效规则速查

7.2 排障实录