OpenProject 12.4.4 补丁版本解析:缓存清理、图标删除、Sendmail 回归与 OAuth 竞态修复

原创2026-09-15 17:25:391,873 阅读
文章标签:项目管理研发协作缺陷追踪协同办公企业应用后端前端工作流自动化数据可视化

OpenProject 12.4.4 补丁版本解析:缓存清理、图标删除、Sendmail 回归与 OAuth 竞态修复

导读

本文基于 OpenProject 12.4.4 官方发布说明(docs/release-notes/12/12-4-4/README.md),逐条拆解该补丁版本包含的 5 项缺陷修复:定时任务清理 tmp/cache 失效、自定义 favicon/touch icon 无法删除、12.4.3 引入的 Sendmail 回归、OAuth refresh token 竞态条件,以及前端模态框拖拽误关闭问题。结合仓库当前源码,本文将为每一项修复给出底层实现位置、触发场景与验证线索,帮助你判断当前部署是否受这些缺陷影响,并理解 OpenProject 邮件、OAuth 与定时任务体系的工作原理。

版本背景与升级建议

OpenProject 12.4.4 发布于 2023-02-15(release_date 字段见 docs/release-notes/12/12-4-4/README.md),是 12.4 系列的第 4 个补丁版本。官方发布说明明确写道:本次发布包含若干 bug 修复,建议所有用户升级到最新版本。

作为一个典型的补丁版本(Patch Release),12.4.4 不含新功能,聚焦于修复 12.4.3 及此前版本中暴露的稳定性问题,覆盖范围横跨:

  • 后端定时任务(Cron Job)与文件缓存清理;
  • 管理员自定义样式(Custom Styles)中的站点图标管理;
  • 邮件发送链路(ActionMailer 与 Sendmail);
  • OAuth2 令牌刷新流程;
  • 前端 Angular 模态框交互。

修复一:定时任务手动可删、调度却不执行 —— tmp/cache 清理缺陷

缺陷现象:手动执行 tmp/cache 清理可以成功,但由定时任务(scheduled jobs)触发时却始终不生效。

相关工作包:#44182

底层实现:ClearTmpCacheJob

该功能由定时任务 Cron::ClearTmpCacheJob 承载,定义于 app/workers/cron/clear_tmp_cache_job.rb:

module Cron
  class ClearTmpCacheJob < ApplicationJob
    ##
    # Clear the tmp/cache directory in case a file caching is configured
    def perform
      FileUtils.rm_rf(Dir["tmp/cache/[^.]*"], verbose: false)
    end
  end
end

关键点在于删除命令的 glob 写法:Dir["tmp/cache/[^.]*"] 只匹配 不以点号开头 的条目,且路径为相对路径。这意味着:

  1. 工作目录(Dir.pwd)决定了实际清理范围——若定时任务进程的工作目录与预期不符,glob 匹配不到任何文件,rm_rf 静默无事发生;
  2. 以 . 开头的隐藏缓存文件(如 .lock、临时隐藏文件)会被刻意跳过,这是避免误删活跃缓存锁的防御性设计;
  3. 该任务仅在文件缓存(file caching)被配置时才有实际意义,注释也明确写了 "in case a file caching is configured"。

12.4.4 修复的正是调度场景下工作目录或执行上下文不一致导致 glob 落空的问题:手动执行(在 Rails root 下运行)成功,而定时任务运行环境不同导致失败。同类定时任务(如 clear_old_sessions_job.rb、clear_uploaded_files_job.rb、clear_outbound_mail_recipients_job.rb)都位于 app/workers/cron/ 目录,共同构成 OpenProject 的周期清理体系。

运维验证建议

升级到 12.4.4 后,可在 Rails 控制台手动触发该任务验证清理是否生效:

# 在 RAILS_ROOT 下执行
Cron::ClearTmpCacheJob.perform_now

随后检查 tmp/cache 目录内容是否被清空。若仍异常,需检查定时任务调度器(如 GoodJob 等后台队列)配置的工作目录是否为 RAILS_ROOT。

修复二:favicon 与 touch icon 无法删除

缺陷现象:管理员无法删除自定义的 favicon(站点图标)与 touch icon(移动端触摸图标)。

相关工作包:#45997

底层实现:CustomStylesController

该功能属于"外观与感觉"(Custom Styles,企业版特性)模块,控制器为 app/controllers/custom_styles_controller.rb。控制器中与 favicon/touch icon 相关的动作如下:

  • 下载(公开访问,无需登录):favicon_download、touch_icon_download,通过 file_download(:favicon_path) / file_download(:touch_icon_path) 发送文件(L123-L129);
  • 删除(需管理员):favicon_delete、touch_icon_delete,分别调用 file_delete(:remove_favicon) / file_delete(:remove_touch_icon)(L151-L153、L171-L173)。

file_delete 的通用实现(L261-L269):

def file_delete(remove_method)
  @custom_style = CustomStyle.current
  if @custom_style.nil?
    return render_404
  end

  @custom_style.send("#{remove_method}!")
  redirect_to custom_style_path, status: :see_other
end

注意这里的参数白名单:custom_style_params 中包含了 favicon remove_favicon、touch_icon remove_touch_icon(L241-L242)。12.4.4 之前版本中,删除动作未正确触发对应 attachment 的移除逻辑,导致 favicon/touch icon 上传后无法清除;本次修复完善了删除链路的调用。

权限模型补充

控制器对下载动作采用了"免守卫"设计(L38-L47):

UNGUARDED_ACTIONS = %i[logo_download
                       logo_mobile_download
                       favicon_download
                       touch_icon_download].freeze

before_action :require_admin, except: UNGUARDED_ACTIONS

即 favicon/touch icon 的下载面向所有访客公开(浏览器加载站点图标所需),而上传、删除、主题/配色修改全部受 require_admin 与 guard_enterprise_feature(:define_custom_style) 保护,后者表明该功能属于企业版(Enterprise)特性。

修复三:12.4.3 引入的 Sendmail 回归

缺陷现象:从 12.4.3 开始,使用 Sendmail 作为投递方式的实例邮件发送失效。

相关工作包:#46152

底层实现:Setting::MailSettings

OpenProject 的邮件投递方式通过设置项 email_delivery_method 控制,可选值包括 smtp、sendmail、letter_opener 等(见 app/forms/admin/settings/mail_notifications_setting_form.rb 中的表单枚举)。投递配置的加载集中在 app/models/setting/mail_settings.rb:

def reload_mailer_settings!
  ActionMailer::Base.delivery_method = Setting.email_delivery_method if Setting.email_delivery_method

  case Setting.email_delivery_method
  when :smtp
    reload_smtp_settings!
  when :sendmail
    ActionMailer::Base.sendmail_settings = {
      location: Setting.sendmail_location,
      arguments: Setting.sendmail_arguments
    }
  end
rescue StandardError => e
  Rails.logger.error "Unable to set ActionMailer settings (#{e.message}). " \
                     "Email sending will most likely NOT work."
end

当 email_delivery_method = :sendmail 时,ActionMailer::Base.sendmail_settings 由两个设置项驱动:

设置项 含义 对应 ActionMailer 字段
sendmail_location sendmail 可执行文件路径 location
sendmail_arguments 传递给 sendmail 的参数 arguments

回归原因与验证

12.4.3 中对邮件设置表单(app/forms/admin/settings/mail_notifications_setting_form.rb)或配置加载逻辑的改动,破坏了 sendmail 分支的参数装配,导致 sendmail_settings 未按预期写入。12.4.4 修复后,可在"管理 → 邮件通知"(Administration → Email notifications)界面点击发送测试邮件验证:

若在 12.4.4 之前遇到该问题,可临时通过环境变量或 config/configuration.yml.example 中的 email_delivery_method: sendmail 相关配置排查,升级后无需改动配置即可恢复。

修复四:OAuth refresh token 竞态条件防护

缺陷现象:OAuth 刷新令牌(refresh token)在并发刷新时存在竞态条件,可能导致令牌失效或数据不一致。

相关工作包:#46195

底层实现:OAuth 客户端令牌刷新链路

OpenProject 中与外部 OAuth 客户端集成相关的令牌管理代码集中在 app/services/oauth_clients/:

  • token_request.rb:构造刷新请求,使用 grant_type: OpenProject::OAuth2::REFRESH_TOKEN_GRANT_TYPE 与 refresh_token 参数;
  • token_fetcher.rb:解析响应并将新的 access_token、refresh_token、expires_in 写回 OAuthClientToken:
refresh_token_request(token).bind do |json|
  access_token, refresh_token, expires_in = json.values_at("access_token", "refresh_token", "expires_in")
  if access_token.blank?
    log_error("Received invalid JSON response from token endpoint. Expected at least 'access_token', got #{json.keys}.")
  end
  token.update!(access_token:, refresh_token:, expires_in:)
  Success(token.access_token)
end
  • connection_manager.rb:写入刷新时的请求选项,并在更新失败时返回 oauth_client.errors.refresh_token_updated_failed 错误。

竞态条件分析

竞态发生在多个请求同时携带同一个 refresh token 向授权服务器发起刷新的场景:

  1. 两个并发请求都读取了旧的 OAuthClientToken;
  2. 各自携带同一个 refresh token 请求新令牌;
  3. 授权服务器通常会让后到的刷新请求失效(旧的 refresh token 已旋转),先到的成功、后到的返回错误;
  4. 若后到的响应覆盖先到的结果,或错误处理不当,客户端拿到的是已失效的令牌。

12.4.4 通过加固刷新流程(如对令牌更新的原子性/串行化、错误分支处理)避免此类覆盖与失效传播。token.update! 与 ServiceResult 的错误包装(connection_manager.rb)正是保证"要么成功写入新令牌、要么明确失败"的关键。

排查建议

如果集成了外部 OAuth 客户端(如 Nextcloud 等文件存储对接,参考 modules/storages/ 下的实现),升级后应重点观察:

  • 日志中是否还出现 refresh_token_updated_failed 类错误;
  • oauth_client_tokens 表中的 refresh_token 是否在并发刷新场景下保持有效且唯一。

修复五:模态框内点击后拖出导致误关闭

缺陷现象:用户在模态框(modal)内部按下鼠标开始操作,但拖拽到模态框外部松开时,模态框被意外关闭。

相关工作包:#46217

底层实现:spot-modal-overlay

这是纯前端(Angular)缺陷。模态框遮罩组件为 frontend/src/app/shared/components/modal/modal-overlay.component.html,关闭逻辑绑定在遮罩层的 mousedown 事件上:

<div
  class="spot-modal-overlay"
  ...
  (mousedown)="close($event, false)"
  role="dialog"
  aria-modal="true"
  ...
>

问题根源:关闭事件绑定在 mousedown 而非"在遮罩上点击"的完整语义(如 mousedown + mouseup 都发生在遮罩上)。当用户在模态框内容区按下、拖拽到遮罩区后松开时,mousedown 事件若被冒泡到遮罩层(或事件监听器未区分事件源),就会触发 close($event, false) 关闭模态框。

12.4.4 修复后,关闭判定需要同时满足"点击起始与结束位置均在遮罩上"(或等价的事件守卫),避免拖拽动作误触发关闭。由于这是交互层修复,升级前端构建产物即可生效。

贡献与致谢

官方发布说明特别感谢了社区成员 Sven Kunze 与 Lars Jørgensen 的报告与修复帮助(docs/release-notes/12/12-4-4/README.md)。这也体现了 OpenProject 的缺陷修复流程:社区在 community.openproject.org 报告问题并附带工作包编号,官方在补丁版本中逐条修复并在发布说明中留痕,便于用户追溯每个修复的来源与影响面。

升级清单速查

针对 12.4.4 的五项修复,升级后可按下表逐一验证:

缺陷 验证方式
tmp/cache 定时清理失效(#44182) 手动执行 Cron::ClearTmpCacheJob.perform_now,确认 tmp/cache 内容被清除
favicon/touch icon 无法删除(#45997) 管理 → 外观与感觉,上传后再次删除 favicon/touch icon,确认文件被移除
Sendmail 回归(#46152) 管理 → 邮件通知 → 发送测试邮件,确认 sendmail 投递成功
OAuth refresh token 竞态(#46195) 观察日志中是否仍有 refresh_token_updated_failed 类错误
模态框拖拽误关闭(#46217) 打开任意模态框,内容区按下后拖出再松开,确认模态框保持打开

相关实现文件索引:定时任务 app/workers/cron/clear_tmp_cache_job.rb、自定义样式控制器 app/controllers/custom_styles_controller.rb、邮件设置 app/models/setting/mail_settings.rb、OAuth 令牌刷新 app/services/oauth_clients/token_fetcher.rb 与 app/services/oauth_clients/connection_manager.rb、模态框组件 frontend/src/app/shared/components/modal/modal-overlay.component.html。

登录后查看全文
openproject