OpenProject 12.2.1 版本解析：活动记录数据损坏修复、期刊聚合机制与 HTTPS 配置变更

OpenProject 12.2.1 版本解析：活动记录数据损坏修复、期刊聚合机制与 HTTPS 配置变更

【免费下载链接】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 12.2.1 是 2022-08-18 发布的紧急修复版本，核心使命是修复 12.2.0 中可能随机损坏数据库活动记录（activity records）的关键缺陷，同时引入全新的 HTTPS 配置项OPENPROJECT_HTTPS。本文以官方发布说明为主线，结合当前仓库中的服务层实现、设置定义与安装文档，深入拆解缺陷根因、期刊（journal）聚合的底层逻辑、升级与恢复方案，以及不同部署形态下的 HTTPS 配置方法，帮助读者理解该版本的技术全貌并安全完成升级。

版本概览

• 版本号：12.2.1
• 发布日期：2022-08-18
• 发布性质：紧急缺陷修复（critical bug fix）
• 主要变更：
  1. 修复 12.2.0 引入的活动记录数据损坏缺陷，并附带数据恢复迁移；
  2. 引入OPENPROJECT_HTTPS环境变量，规范非 HTTPS 场景下的配置方式；
  3. 附带若干界面与集成层面的缺陷修复。

官方建议：所有用户都应尽快升级到 12.2.1；尚未升级到 12.2.0 的系统可直接升级到 12.2.1，以完全规避该缺陷。

关键缺陷：12.2.0 中活动记录的数据损坏问题

缺陷现象

在 OpenProject 12.2.0 中，一个关键缺陷可能导致数据库中的活动记录被随机损坏，这些记录控制着工作包（work package）、会议（meeting）、Wiki 页面等对象的变更展示与聚合。当系统聚合一条活动（即同一用户在前 5 分钟内多次编辑同一对象）时，可能误删错误的数据库对象，导致后续更新该对象时抛出错误。

典型症状

该缺陷会以下列形式呈现：

• 无法访问通知中心（页面保持空白）；
• 工作包中无法看到活动记录（对应社区工单 #43773）；
• 更新已有工作包时出现内部错误（internal errors）。

修复与恢复方案

升级到 12.2.1 将修复该缺陷，并附带一个迁移（migration），尝试为受影响的记录恢复被中断的活动（intermediate activities）。官方特别澄清：

最新版本本身未受影响，你在系统中已做的所有变更仍然正确。

但需要注意，受影响的活动在恢复后可能缺失部分变更，或包含来自先前/后续活动的变更。任何记录被恢复的活动都会附带一条说明该情况的备注（note）。

对于 OpenProject 云客户：受影响的记录已按相同方式恢复；如果实例受此缺陷影响，官方会单独联系告知。

源码级原理：期刊聚合（Journal Aggregation）机制

要理解该缺陷为何发生，需要先理解 OpenProject 的活动记录底层——期刊（journal）聚合机制。聚合逻辑位于 app/services/journals/create_service.rb，其核心目标是：同一用户在前 5 分钟内连续编辑同一对象时，将多次变更合并进同一条期刊记录，而不是为每次编辑都生成新记录，从而避免活动时间线被琐碎编辑刷屏。

聚合的判定条件

从源码注释（create_service.rb 第 70-84 行）可以看到，可聚合的前驱记录（aggregatable predecessor）必须同时满足以下条件：

• 期刊创建发生在配置的聚合时间窗口内；
• 由同一用户执行；
• cause（变更原因）相同；
• 前驱记录与待创建记录之间只存在一条备注（note）；
• 前驱记录与待创建记录具有相同的权限限制（restriction）。

def aggregatable?(predecessor, notes, internal, cause) predecessor && aggregation_active? && within_aggregation_time?(predecessor) && # ... 同用户、同 cause、单条 note、相同 restriction 等条件 end

聚合时间窗口的配置

聚合时间窗口由设置项journal_aggregation_time_minutes控制，其定义位于 config/constants/settings/definition.rb 第 730-733 行：

journal_aggregation_time_minutes: { default: 5, allowed: 0..120 }

• 默认值 5（分钟），与发布说明中"前 5 分钟内编辑同一对象"的描述一致；
• 允许范围 0..120，设置为0时聚合功能被关闭（见aggregation_active?判断：Setting.journal_aggregation_time_minutes.to_i > 0）；
• 在 create_service.rb 第 598-600 行 中，within_aggregation_time?会优先读取journable类自身声明的聚合时间，其次回退到全局设置。

聚合的执行方式与缺陷风险点

聚合执行的关键实现在 create_service.rb 第 86-105 行：

def create_journal(notes, internal, cause) predecessor = aggregatable_predecessor(notes, internal, cause) log_journal_creation(predecessor) create_sql = create_journal_sql(predecessor, notes, internal, cause) ... end

源码注释（第 78-79 行）明确指出：不是直接删除前驱记录，而是先将其从创建 SQL 中剥离（stripped），再回填（refilled），这样用户持有的期刊引用可以保持不变。聚合结果由一条复杂 SQL 快照完成：

• 若存在可聚合的前驱，则更新journals表中的既有记录；
• 否则新建一条期刊记录；
• 同时在数据表（如work_package_journals）、attachable_journals、customizable_journals中写入快照数据。

12.2.0 中的缺陷即发生在此聚合路径上——错误对象被移除而非正确的前驱被剥离回填，进而引发通知中心空白、活动缺失与更新报错。12.2.1 通过修正该路径并附加恢复迁移予以解决。

另外，聚合行为的触发开关由 app/models/journal/event_configuration.rb 中的Journal::EventConfiguration管理，它控制创建/更新期刊时是否触发事件回调（工作流、聚合任务），使用线程本地变量（Concurrent::ThreadLocalVar）保证嵌套调用时的状态隔离，默认值为true（第 33 行DEFAULT = true）。

HTTPS 配置变更：OPENPROJECT_HTTPS 环境变量

自 12.2 起，OpenProject默认启用 HTTPS 模式。这一变更对两种部署形态产生了影响：基于 Docker 的部署，以及手动将打包安装（packaged installation）接入既有 Web 服务器的场景。

如果你不在 HTTPS 下运行，需要显式设置环境变量以关闭 HTTPS 模式：

OPENPROJECT_HTTPS=false

Docker 部署

在 docs/installation-and-operations/installation/docker/README.md 中，快速启动命令即为本地 HTTP 访问场景提供了该变量（第 118-125 行）：

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

文档明确解释：

OPENPROJECT_HTTPS=false关闭了 OpenProject 默认开启的 HTTPS 模式，使你能够通过纯 HTTP 访问实例。对于所有生产系统，强烈建议不要设置为false，而应在外部 Web 服务器上配置正规的 TLS/SSL 终止。

同时文档还强调（第 226 行附近）：如果你确实需要关闭 OpenProject 的 HTTPS 响应，就必须设置OPENPROJECT_HTTPS=false；但注意这会禁用会话 cookie 的安全属性（secure cookies），任何生产系统都强烈不建议这样做。

打包安装（Packaged Installation）

在 docs/installation-and-operations/installation/packaged/README.md 中，自 12.2 起 HTTPS 配置已成为默认，官方建议的最佳实践是：

• 在安装向导中选择Yes启用 HTTPS（SSL/TLS），并生成所需证书，否则需要在命令行手动停用 HTTPS（第 414 行）；
• 启用该模式后，OpenProject只响应 HTTPS 请求，并将非安全请求升级为 HTTPS，同时向客户端输出 HTTP Strict Transport Security（HSTS）响应头（第 426 行）；
• 如果由外层服务器终止 SSL，需要在请求头中设置X-Forwarded-Proto https，让 OpenProject 感知到请求已是 HTTPS（第 438 行）；
• 当无请求上下文时（例如发送邮件），需要确保链接以https生成：执行openproject config:set SERVER_PROTOCOL_FORCE_HTTPS="true"后运行openproject configure（第 442 行）；
• 若跳过 Apache2 安装（Step 3），向导会在后续步骤中询问外部主机名与是否使用 HTTPS（第 520-526 行）。

12.2.1 全部缺陷修复清单

本版本除上述关键修复外，还包含以下缺陷修复（均附社区工单编号）：

其中 #43759 与 #43773 分别对应本版本的 HTTPS 配置调整与活动记录修复两大主题，其余为甘特图、看板、时间线等界面功能层面的修复。

升级建议与注意事项

1. 立即升级：该缺陷属于数据损坏级问题（data corruption），升级优先级最高；未升级到 12.2.0 的系统可直接升级到 12.2.1。
2. 恢复活动记录的说明：升级迁移会尽力恢复受影响的活动记录，但恢复后的记录可能缺失部分变更或包含相邻活动的变更；被恢复的记录会带有相应备注，可在界面上识别。
3. 验证通知中心与工作包活动页：升级后应重点检查通知中心是否正常加载、工作包活动时间线是否完整、既有工作包能否正常更新。
4. HTTPS 配置检查：Docker 与打包安装用户若在非 HTTPS 环境运行，需确认已正确设置OPENPROJECT_HTTPS=false（或在外层完成 TLS 终止并配置X-Forwarded-Proto），避免出现安全 cookie 与链接生成异常。
5. 云用户：托管于 OpenProject 云端的实例无需自行处理恢复，受影响实例会由官方单独通知。

贡献者致谢

本版本的缺陷报告与修复离不开社区成员的贡献，官方特别感谢 Daniel Hug、Daniel Narberhaus、Dan W、Kenneth Kallevig 等社区成员对缺陷的发现与反馈。

【免费下载链接】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