Jarvis_java/doc/图片转换功能说明.md

评论图片WebP转JPG功能说明

功能概述

评论模块中的图片如果是webp格式，会自动转换为jpg格式。转换后的图片会被缓存，下次不需要再次转换。

功能特性

1. 自动检测：自动检测图片URL中的webp格式
2. 格式转换：将webp格式图片转换为jpg格式
3. 结果缓存：转换结果存储在数据库中，避免重复转换
4. 文件存储：转换后的jpg图片保存到本地目录
5. HTTP访问：通过ImageController提供HTTP访问接口

配置说明

在 application.yml 中配置：

image:
    convert:
        # 图片存储路径（转换后的jpg图片存储目录）
        storage-path: ${user.home}/comment-images
        # 图片访问基础URL（如果配置，转换后的图片将通过此URL访问）
        # 例如: http://your-domain.com/images 或 http://localhost:6666/images
        # 如果为空，则返回本地文件路径
        base-url: http://localhost:6666/images

配置项说明

• storage-path：转换后的jpg图片存储目录，默认使用 ${user.home}/comment-images
• base-url：图片访问的基础URL，如果配置，转换后的图片URL将使用此地址；如果不配置，则返回本地文件路径

数据库表

需要执行以下SQL创建图片转换记录表：

-- 执行 sql/image_conversions.sql

表结构：

• id：主键ID
• original_url：原始webp图片URL（唯一索引）
• converted_url：转换后的jpg图片URL或路径
• converted_at：转换时间
• file_size：文件大小（字节）
• created_at：创建时间

工作流程

1. 图片URL解析：从评论数据中解析出图片URL列表
2. 格式检测：检查URL中是否包含webp格式标识
3. 缓存查询：查询数据库，检查是否已转换过
4. 格式转换（如果未转换过）：
   • 下载原始webp图片
   • 使用webp-imageio库读取webp格式
   • 转换为BufferedImage
   • 保存为jpg格式到本地目录
   • 保存转换记录到数据库
5. 返回结果：返回转换后的图片URL（或原URL，如果不是webp）

依赖库

项目已添加以下依赖：

1. Thumbnailator (0.4.20)：图片处理库

注意：WebP格式支持需要系统或JVM本身支持webp格式。如果系统不支持webp，转换功能会跳过webp图片并返回原URL，不会影响系统正常运行。

如需支持webp格式转换，可以：

• 使用支持webp的JVM版本
• 手动添加webp-imageio库到项目中
• 使用其他webp解码库

API接口

图片访问接口

GET /images/{filename}

访问转换后的jpg图片文件。

参数：

• filename：文件名（通常是MD5值.jpg）

返回：

• 成功：图片文件（Content-Type: image/jpeg）
• 失败：404 Not Found 或 400 Bad Request

安全特性：

• 防止路径遍历攻击
• 文件路径验证
• 仅允许访问存储目录内的文件

使用示例

前端调用

评论生成接口返回的图片URL列表已经过转换处理：

{
  "list": [
    {
      "commentText": "评论内容",
      "images": [
        "http://localhost:6666/images/abc123.jpg",
        "http://localhost:6666/images/def456.jpg"
      ]
    }
  ]
}

后端调用

图片转换服务会自动集成到评论生成流程中：

// 在 JDInnerController.commentGenerate 方法中
List<String> imageUrls = parsePictureUrls(commentToUse.getPictureUrls());
List<String> convertedImageUrls = imageConvertService.convertImageUrls(imageUrls);

注意事项

1. 首次转换：首次转换webp图片时，需要下载图片并转换，可能耗时较长
2. 存储空间：转换后的jpg图片会占用磁盘空间，建议定期清理旧文件
3. 网络依赖：转换过程需要下载原始图片，确保网络连接正常
4. WebP支持：确保webp-imageio库正确加载，否则转换会失败
5. 并发处理：多个请求同时转换同一张图片时，可能会导致重复转换（建议后续优化为加锁机制）

故障排查

问题1：转换失败，提示"无法读取webp图片格式"

解决方案：

1. 确认 webp-imageio 依赖已正确添加到pom.xml
2. 确认依赖已成功下载（检查Maven本地仓库）
3. 检查日志中的WebP支持检测信息

问题2：图片无法访问（404）

解决方案：

1. 检查 storage-path 配置是否正确
2. 确认图片文件已成功转换并保存
3. 检查文件权限
4. 如果配置了 base-url，确认URL是否正确

问题3：转换后的图片URL是本地路径

解决方案： 在 application.yml 中配置 base-url：

image:
    convert:
        base-url: http://your-domain:6666/images

性能优化建议

1. 异步转换：对于大量图片，可以考虑异步转换
2. CDN加速：将转换后的图片上传到CDN，提供更快的访问速度
3. 定期清理：定期清理长时间未使用的转换图片
4. 缓存预热：提前转换常用的图片

后续优化

1. 添加转换任务队列，支持批量转换
2. 添加转换状态监控和统计
3. 支持其他图片格式转换（如png、gif等）
4. 添加图片压缩功能，减小文件大小