Rails 8.2 Active Storage 更新全解：媒体分析器、变体处理与安全加固源码剖析

本文基于 Rails 仓库 activestorage 组件的 8.2 版变更日志（activestorage/CHANGELOG.md，当前仓库版本号为 8.2.0.alpha），系统梳理这一轮 Active Storage 在媒体分析（ffmpeg/ffprobe 参数化）、变体处理后端（自定义 Transformer 与 libvips 安全收紧）、镜像服务（MirrorService 并行化与元数据修复）、Blob 分析时序（analyze / process 选项）以及 DiskService 安全修复等方面的关键变更，并结合仓库源码印证每项功能的实际实现位置，帮助你在升级到 8.2 时准确评估影响面并调整配置。

本次变更的总体背景

这份 CHANGELOG 记录的是 Rails 8.2 开发周期内 activestorage gem 的累计变更，文末指向 8-1-stable 分支的历史变更记录。变更可归纳为五个方向：

1. 可配置性增强：ffmpeg/ffprobe 输入参数、自定义 Transformer 类、BaseController 父类、流式分块上限等；
2. 分析/变体时序控制：analyze: 与 process: 选项、after_upload 回调、attach! 等；
3. 安全加固：libvips 未 fuzz 加载器禁用（关联 CVE-2026-66066）、DiskService 路径穿越与 glob 注入防护、流式分块上限防止 DoS；
4. 可靠性修复：MirrorService 元数据丢失与并行化、Blob 元数据同步竞态、STI 转换丢失附件变更等；
5. 依赖升级：适配 ImageProcessing 2.0，提前加载图像处理后端。

让 ffmpeg 与 ffprobe 输入参数可配置

变更日志新增了 config.active_storage.video_preview_input_arguments 与 config.active_storage.ffprobe_arguments 两个配置项，两者默认值均为空字符串。由于 ffmpeg 的命令行参数是位置敏感的，这两个参数专门承载“作用于输入端”的标志位（位于 -i 之前），例如 -codec_whitelist、-f、-protocol_whitelist。一个只接受 H.264 视频加 AAC 音频的应用可以这样配置：

config.active_storage.video_preview_input_arguments = "-codec_whitelist h264,aac"
config.active_storage.ffprobe_arguments = "-codec_whitelist h264,aac"

从源码可以确认这两处配置的落地位置：

• VideoPreviewer 在 draw_relevant_frame_from 中按 Shellwords.split(ActiveStorage.video_preview_input_arguments) 展开参数，并放在 -i file.path 之前；输出端参数仍由既有的 video_preview_arguments（默认 -y -vframes 1 -f image2）控制。
• VideoAnalyzer#probe_from 在拼装 ffprobe 命令时插入 *Shellwords.split(ActiveStorage.ffprobe_arguments)，位于文件路径之前。变更日志说明 ffprobe_arguments 同时作用于 ActiveStorage::Analyzer::VideoAnalyzer 与 ActiveStorage::Analyzer::AudioAnalyzer。
• 两个全局访问器在 activestorage/lib/active_storage.rb 中以 mattr_accessor 定义（默认均为 ""），并在 Engine 的 active_storage.configs 初始化块 中从 app.config.active_storage 覆盖读取。

参数经 Shellwords.split 拆分，因此配置值应写成完整的空格分隔字符串，而不是数组。

variant_processor 支持自定义 Transformer 类

config.active_storage.variant_processor 现在除了 :vips、:mini_magick、:disabled 三个符号外，还可以直接指定一个类：

config.active_storage.variant_processor = CustomTransformer

自定义类必须实现 ActiveStorage::Transformers::Transformer 定义的接口。需要注意的约束是：内置图像分析器（ImageAnalyzer）只有在 variant_processor 为 :vips 或 :mini_magick 时才接受 blob，因此改为自定义类后，还要向 config.active_storage.analyzers 中补充一个能处理 blob 的自定义分析器。

在 engine.rb 的启动逻辑 中可以看到完整的分发逻辑：:disabled 映射到 NullTransformer，:vips / :mini_magick 映射到对应 Transformer，值为 Class 时直接使用该类，其余情况在启动阶段直接抛出 ArgumentError。这比旧行为（生成变体时才以 NoMethodError 失败）要友好得多，能在启动时暴露配置错误。此外，LoadError 仍会被捕获并转换为针对 libvips、image_processing、ruby-vips、mini_magick 缺失的具体警告日志。

安全：禁用 libvips 的未 fuzz 加载器与保存器

这是本轮变更中影响面最大的一条。libvips 将部分加载器/保存器标记为 "unfuzzed" 或 "untrusted"（仅对可信内容安全）。Active Storage 现在会在启动时调用 Vips.block_untrusted(true) 禁用它们——实现位于 activestorage/lib/active_storage/vips.rb，并带版本校验：

• 最低支持版本提升为 libvips 8.13 与 ruby-vips 2.2.1（最早能禁用未信任操作的版本）；
• 若 ruby-vips 已安装但任一最低版本不满足，Active Storage 会在启动时抛出 RuntimeError，而不是运行在“不可加固”的环境中。

对应用的实际影响（来自 CHANGELOG）：

• BMP、ICO、PSD 附件的变体转换会抛 Vips::Error；这些类型以及 SVG、JPEG XL、JPEG 2000、Netpbm 等的分析不再记录 width/height；
• 请求未 fuzz 的输出格式（常见为 FITS、JXL，或任何委托给 ImageMagick 的输出）同样会抛 Vips::Error；
• 附件的上传、存储、下载行为不变。

若你的应用在请求期间（而非后台任务中）转换图像，失败会以错误响应的形式暴露，建议把受影响的内容类型从可变列表中移除，让 Active Storage 不再为它们生成变体：

Rails.application.config.active_storage.variable_content_types -=
  %w[ image/bmp image/vnd.microsoft.icon image/vnd.adobe.photoshop ]

variable_content_types 的默认清单（含上述三种类型）可在 engine.rb 中核对。如果应用使用 :mini_magick 处理器，附件处理本身不受影响，但只要 ruby-vips 被安装，未 fuzz 的加载/保存器仍会被进程级禁用；此类应用可以从 Gemfile 中移除 ruby-vips 以规避版本要求。该变更关联安全公告 GHSA-xr9x-r78c-5hrm 与 CVE-2026-66066。

MirrorService：元数据保留、并行化与无校验和修复

镜像服务（primary + mirrors 的复制拓扑）本轮有三处修复与优化，全部集中在 MirrorService：

1. 修复 mirror 丢失 blob 元数据：此前复制到 S3、Azure、GCS 的镜像对象以 application/octet-stream 提供，因为 content_type、filename、disposition、custom_metadata 在复制时丢失（Fixes #57270）。现在 mirror 方法 会取出 ActiveStorage::Blob 的 service_metadata，以 **metadata 展开传给各镜像的 upload，把元数据完整地转发到每次上传。
2. exist? 检查与上传并行化：mirror 利用构造时创建的 Concurrent::ThreadPoolExecutor（线程数上限等于镜像数，队列深度为 0，采用 caller_runs 回退策略），对“哪些镜像缺少该对象”的 exist? 探测以及随后的上传全部以 Concurrent::Promise 并发执行。N 个镜像的镜像化从 O(N) 次网络往返压缩为 O(1) 轮次。
3. 修复无校验和场景的 IntegrityError：当以 track_variants: false 等方式镜像、没有提供 checksum 时，mirror 不再错误地抛出 ActiveStorage::IntegrityError（注意 primary.open 的 verify: 只在 checksum.present? 时才启用）。

此外，delete / delete_prefixed 也走 perform_across_services，同样在 primary 与所有镜像上并发执行。

Blob 元数据同步下沉到后台任务

当 HTTP 服务器与后台分析任务（ActiveStorage::AnalyzeJob）同时更新同一 blob 的元数据时会产生数据竞争，在 GCS 上表现为 409 冲突并让请求 500。修复方式是 把元数据上传下沉到 ActiveStorage::SyncMetadataJob：该 Job 调用 blob.sync_metadata，并对 RecordNotFound 类异常 discard_on、对 Deadlocked 指数退避重试 10 次。应用侧还可以在自己的 SyncMetadataJob 上追加 retry_on 来适配具体服务的 409。

对扩展存储服务的开发者有一个接口变更：ActiveStorage::Service#update_metadata 现在只负责打点（instrumentation），实际工作委托给新的 update_metadata_for 方法；此前覆写了 update_metadata 的自定义服务应改为覆写 update_metadata_for，以保证工作运行在 instrumentation 范围内。

分析时序：analyze 选项与“验证前分析”

这是本轮对日常开发影响最直接的一组能力：

• 验证前完成分析：has_one_attached / has_many_attached 新增 analyze: 选项，配合 before_validation { attachment_changes[name.to_s]&.analyze } 回调（见 attached/model.rb），使 blob 的 metadata（宽、高、时长等）在模型验证阶段即可用：

class User < ApplicationRecord
  has_one_attached :avatar, analyze: :immediately

  validate :validate_avatar_dimensions, if: -> { avatar.attached? }

  def validate_avatar_dimensions
    if avatar.metadata[:width] < 200 || avatar.metadata[:height] < 200
      errors.add(:avatar, "must be at least 200x200")
    end
  end
end

可选取值：:immediately（验证前分析，8.2 下的语义为“分析后校验”）、:later（本地 IO 上传后或经后台任务分析，全局默认）、:lazily（跳过自动分析，按需触发）。全局默认通过 config.active_storage.analyze 设置，engine.rb 中当前默认值为 :later，active_storage.rb 的 mattr_accessor 亦以 :later 为兜底默认。

• 直接上传（direct upload）的退化行为：直传绕过了服务端，本地没有文件可供分析，此时 :immediately 会退化为 :later（上传完成后由后台任务分析），验证阶段拿不到元数据，需要改为客户端校验。
• 本地文件复用：process: :immediately 的变体与 blob 分析现在直接使用本地文件，而不是上传后重新下载；仅对“附加可上传 IO”的场景生效，对附加已有 Blob 的场景不适用。
• after_upload 回调：ActiveStorage::Attachment.after_upload { ... } 在附件 blob 上传完成后触发，让分析与处理可以确定性地运行，而不必依赖 after-commit 回调的执行顺序假设。
• 立即变体（immediate variants）：variant 声明支持 process 选项——:lazily（默认，请求时动态生成）、:later（附加后由后台任务生成，取代已废弃的 preprocessed: true）、:immediately（与附件一起生成）：

has_one_attached :avatar do |attachable|
  attachable.variant :thumb, resize_to_limit: [100, 100], process: :immediately
end

同时 Variant#processed? 与 VariantWithRecord#processed? 变为公开方法，应用可以主动检查变体生成状态。

附件 API 的细节增强

• 接受 Tempfile 作为 attachable：export.csv.attach(tempfile) 现在可以直接附加 Tempfile，省去先 open 再传 IO 的步骤。
• attach!：作为 attach 的 bang 版本，附件未能保存时抛异常，语义与 save! 一致。
• byte_size 聚合：通过 has_many_attached 关联可直接取得所有 blob 的总字节数，如 document.images.byte_size # => 2048。
• STI 转换保留附件变更：把记录转换为另一个 STI 子类时，未提交的 attachment_changes 不再丢失——实现可见 Attached::Model#becomes，它将每个 change 的 record 重定向到目标对象并整体迁移。
• touch_attachment_records = false 修复：此前该开关为 false 时，把一个已有 Blob 再次附加到记录会直接报错，现已修复（开关本身在 engine.rb 中于 before_initialize 阶段生效）。
• Blob#open 支持无 block 形式：与 Tempfile.open 一致，不带 block 调用时返回的临时文件需手动 unlink。
• as_json 防递归：Attached::One / Attached::Many 代理在 @record 上持有对宿主记录的引用，默认的 Object#as_json 会序列化 instance_values，当附件名与模型属性重名（如 ignored_columns 列被 select('*') 带回）时 record.to_json 会无限递归。现在 Attached::One#as_json 已附加时返回附件记录的 JSON、否则返回 nil；Attached::Many#as_json 返回附件记录 JSON 数组。

流式传输、缓存与控制器行为

• 可配置的最大流式分块：新增 streaming_chunk_max_size（默认 100 MB，见 active_storage.rb 与 engine.rb），保证单个 blob 的字节范围请求不会超过该上限，防止超大 Content-Range 带来的拒绝服务风险。
• ProxyController 的 Last-Modified：ProxyController 现在把 Last-Modified 设为 Blob#created_at，取代过去硬编码的 2011-01-01，HTTP 条件请求与缓存行为因此更真实。
• BaseController 父类可配置：新增 config.active_storage.base_controller_parent，engine.rb 中其缺省逻辑为：api-only 应用回落到 ::ActionController::API，否则为 ::ActionController::Base，纯 API 应用无需再手动调整 Active Storage 的路由控制器。

DiskService 安全修复：路径穿越与 glob 注入

针对本地磁盘服务（DiskController 亦配合调整）：

• 路径穿越：DiskService#path_for 对含 . / .. 段、或解析后落在存储根目录之外的 key 抛 InvalidKeyError；并且对一切非法 key（含 null 字节、不兼容编码）统一抛 InvalidKeyError，取代过去不确定的 ArgumentError / Encoding::CompatibilityError。DiskController 显式 rescue InvalidKeyError 并映射为恰当的 HTTP 状态码。
• glob 注入：delete_prefixed 现在会在把路径交给 Dir.glob 之前转义通配元字符。注意这是一处破坏性变更：依赖 delete_prefixed 展开通配符的既有代码会失效——其他存储服务并不尊重这些元字符，Rails 判定这是非预期行为。

云服务与生态适配

• GCS 签名 URL 恢复 ADC：使用 IAM 为 GCS 签名 URL 时，恢复使用应用默认凭据（ADC），并内存化 auth client，仅在凭据过期时重新获取；也可以通过设置 ActiveStorage::Service::GCSService#iam_client 的 authorization 换成其他认证方式，例如：

ActiveStorage::Blob.service.iam_client.authorization =
  Google::Auth::ImpersonatedServiceAccountCredentials.new(options)

这比设置 Google::Apis::RequestOptions.default.authorization 更安全，因为只作用于 Active Storage。

• 校验和职责下沉到存储服务：计算与校验 checksum 的责任移交给具体存储服务实现，核心 Service 不再内聚这些细节。
• 适配 ImageProcessing 2.0：ImageProcessing 2.0 不再自带后端，需要在 Gemfile 中显式添加 ruby-vips 或 mini_magick（engine.rb 的告警文案 也据此更新，提示 gem "image_processing", "~> 2.0" 与 gem "ruby-vips", "~> 2.3"）。
• 启动期预加载图像处理后端：加载 Active Storage 时即加载图像后端，消除部署后首次处理变体的额外开销，并改善预 fork Web 服务器的写时复制（copy-on-write）表现。
• EXIF 镜像方向修复：rotated_image? 此前对方向 2、4（仅翻转、无 90° 旋转）错误地交换了宽高，且遗漏了方向 5、7（翻转 + 90° 旋转）。现在只有方向 5、6、7、8（真正含 90°/270° 旋转）才触发宽高交换。

升级检查清单

结合上述变更，升级到 8.2 时的建议核对项：

1. 若使用 :vips 处理器：确认 libvips ≥ 8.13、ruby-vips ≥ 2.2.1，否则启动即失败；评估 BMP/ICO/PSD/SVG 等类型的变体与元数据行为变化，必要时用 variable_content_types -= 收缩清单；
2. 若 variant_processor 写的是符号以外的值：启动会立刻 ArgumentError，自定义类需实现 Transformers::Transformer 接口并补配 analyzers；
3. 若覆写过 Service#update_metadata：迁移到 update_metadata_for；
4. 若使用 track_variants: false 的镜像流程或依赖 delete_prefixed 通配展开：分别确认无 checksum 镜像与 glob 转义的影响；
5. 若 Gemfile 依赖 ImageProcessing：显式声明 ruby-vips / mini_magick 后端；
6. 需要验证期元数据时，为相应附件声明 analyze: :immediately，并注意直传场景的退化行为。

完整条目与作者署名见 activestorage/CHANGELOG.md，更早的历史变更可在 8-1-stable 分支的同名文件中追溯。