【插件发布】Rhex 图片自动压缩 v1.0.3（需宿主 transformFile 支持）

最近基于 Rhex 1.1.0 开发了一个“图片自动压缩”插件。它可以在图片写入本地或对象存储前，自动调整尺寸、编码质量和输出格式；处理完成后仍由 Rhex 负责真实 MIME 校验、哈希去重、上传配额、上传记录以及 local / S3 / OSS 存储。

主要功能

• 后台启用或停用自动压缩
• 两种处理策略：仅调整编码质量、限制尺寸并调整质量
• 保持原格式，或统一转换为 JPEG / WebP / AVIF
• 设置编码质量、最大宽度、最大高度和最小处理体积
• 可选择仅在压缩结果更小时采用新图片
• 可设置 JPEG 透明区域的填充颜色
• 可按帖子正文、评论、封面、私信、图片附件、头像及后台素材选择应用范围
• GIF、SVG、动画 WebP / AVIF 默认跳过，避免丢失动画或矢量内容
• 单张图片解码或编码失败时自动回退原图，不中断上传请求

重要：当前需要修改后的 Rhex 宿主

本插件目前不能直接运行在未经修改的 Rhex 1.1.0 官方镜像中。

当前官方版本的 upload provider 只有 uploadFile() 存储接管能力，没有“水印完成后、保存之前修改图片 Buffer”的扩展点。如果插件直接接管存储，就需要重复实现 Rhex 已有的配额、去重、上传记录以及 local / S3 / OSS 逻辑。

为此，我在宿主中增加了通用的 transformFile() upload provider hook。插件只负责压缩、缩放或转码，之后继续交给 Rhex 原有上传流程处理。

宿主处理顺序如下：

text
上传格式与原始大小校验
-> Rhex 水印
-> 插件压缩、缩放或转码
-> 宿主重新检测真实 MIME、文件大小和 SHA-256
-> 去重与上传配额
-> local / S3 / OSS 保存

在该宿主扩展被上游合并并进入正式版本或官方镜像之前，使用插件需要满足以下任一条件：

1. 使用包含 transformFile() 扩展的 Rhex Fork 镜像；或
2. 在 Rhex 官方源码上应用对应补丁并自行构建镜像。

仅在 GitHub 上合并 PR 还不代表当前官方镜像已经包含修改，仍需等待新版本发布或官方镜像重新构建。

为插件可用性提交的三个上游 PR

这次开发和生产部署过程中，我向 Rhex 上游拆分提交了三个互相独立的 PR：

1. PR #23：修复 PostgreSQL advisory lock 参数类型

   • 修复上传配额事务调用 pg_advisory_xact_lock(bigint, bigint) 导致 /api/upload 返回 500 的问题。
   • 这是通用上传修复，不只影响本插件。

2. PR #24：补齐生产镜像运行时 CLI 依赖

   • 将 setup 所需的 cross-env 纳入生产依赖，并在 Docker 构建阶段验证 cross-env 与 tsx。
   • 解决修改版镜像中 setup 容器提示 cross-env: not found 的问题。

3. PR #25：为 upload provider 增加 transformFile() hook

   • 这是图片自动压缩插件的直接宿主依赖。
   • 支持插件在水印之后、去重和存储之前串行处理图片，并在转换后重新校验 MIME、大小和哈希。

截至本文整理时，三个 PR 均已提交并处于 Open 状态，请通过以上链接查看最新审核和合并进度。其中 PR #25 是本插件必需的宿主能力；PR #23 与 PR #24 是开发和部署过程中发现的上传及生产镜像配套修复。

安装方法

1. 先部署包含 PR #25 transformFile() 扩展的 Rhex 宿主。
2. 确认已按照 Rhex 插件文档启用可信插件代码执行环境。
3. 在后台进入“插件管理”，上传本帖附件 image-compressor-1.0.3.zip。
4. 安装或升级插件并启用。
5. 打开插件详情页，设置压缩方式、编码质量、尺寸和应用范围。
6. 建议首次测试使用：保持原格式、质量 82、最大 2560×2560、200 KB 起压缩。

如果选择统一输出为 WebP 或 AVIF，需要同时在 Rhex 后台允许上传类型中加入对应扩展名，否则转换后的真实格式仍会被宿主白名单拒绝。

禁用插件后，transformFile() 不会修改图片，上传将继续走 Rhex 原有流程。

已验证

• Rhex 1.1.0 修改版
• JPEG、PNG、WebP、AVIF 的压缩与转码
• 本地存储及 Rhex 现有对象存储流程
• 后台设置保存和即时生效
• 转换后 MIME、大小与哈希重新计算
• 损坏图片或处理失败时回退原图
• 插件禁用后恢复宿主原上传行为
• Web、Worker 与 setup 容器生产部署

下载、宿主代码与校验

• 插件包：本帖附件 image-compressor-1.0.3.zip
• 修改版宿主源码：Jiosanity/Rhex
• 宿主上游 PR：#23、#24、#25

插件包 SHA-256：

text
de3fa4fe73128ec5715a3f48d3677b2c3b4a46a5bc1a3d62962a8e9de0443975  image-compressor-1.0.3.zip

注意事项

• 使用修改版宿主或第三方构建镜像前，请先备份数据库、上传目录和插件目录。
• 图片压缩在 Web/API 进程内同步执行，大图或高并发环境需要关注 CPU 占用和接口耗时。
• 插件服务端代码按 Rhex 的可信代码模型运行，请只安装自己信任的插件包。
• 当前版本不会处理 GIF、SVG，以及检测到多帧的 WebP / AVIF。
• 升级 Rhex 前应检查上游是否已经原生提供 transformFile()，避免重复应用宿主补丁。
• 如果三个 PR 后续被合并，请以正式发布版本和官方镜像实际包含的代码为准。

欢迎反馈实际使用效果、图片格式兼容问题，以及更适合论坛场景的默认压缩参数。