1

2025-11-03 11:54:11 +08:00
parent 5f75603532
commit 6b36f0ee52
9 changed files with 741 additions and 2 deletions
--- a/doc/图片转换功能说明.md
+++ b/doc/图片转换功能说明.md
@@ -0,0 +1,170 @@
+# 评论图片WebP转JPG功能说明
+
+## 功能概述
+
+评论模块中的图片如果是webp格式，会自动转换为jpg格式。转换后的图片会被缓存，下次不需要再次转换。
+
+## 功能特性
+
+1. **自动检测**：自动检测图片URL中的webp格式
+2. **格式转换**：将webp格式图片转换为jpg格式
+3. **结果缓存**：转换结果存储在数据库中，避免重复转换
+4. **文件存储**：转换后的jpg图片保存到本地目录
+5. **HTTP访问**：通过ImageController提供HTTP访问接口
+
+## 配置说明
+
+在 `application.yml` 中配置：
+
+```yaml
+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
+-- 执行 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)：图片处理库
+2. **webp-imageio** (0.1.0)：WebP格式支持库
+
+## API接口
+
+### 图片访问接口
+
+**GET** `/images/{filename}`
+
+访问转换后的jpg图片文件。
+
+**参数：**
+- `filename`：文件名（通常是MD5值.jpg）
+
+**返回：**
+- 成功：图片文件（Content-Type: image/jpeg）
+- 失败：404 Not Found 或 400 Bad Request
+
+**安全特性：**
+- 防止路径遍历攻击
+- 文件路径验证
+- 仅允许访问存储目录内的文件
+
+## 使用示例
+
+### 前端调用
+
+评论生成接口返回的图片URL列表已经过转换处理：
+
+```json
+{
+  "list": [
+    {
+      "commentText": "评论内容",
+      "images": [
+        "http://localhost:6666/images/abc123.jpg",
+        "http://localhost:6666/images/def456.jpg"
+      ]
+    }
+  ]
+}
+```
+
+### 后端调用
+
+图片转换服务会自动集成到评论生成流程中：
+
+```java
+// 在 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`：
+
+```yaml
+image:
+    convert:
+        base-url: http://your-domain:6666/images
+```
+
+## 性能优化建议
+
+1. **异步转换**：对于大量图片，可以考虑异步转换
+2. **CDN加速**：将转换后的图片上传到CDN，提供更快的访问速度
+3. **定期清理**：定期清理长时间未使用的转换图片
+4. **缓存预热**：提前转换常用的图片
+
+## 后续优化
+
+1. 添加转换任务队列，支持批量转换
+2. 添加转换状态监控和统计
+3. 支持其他图片格式转换（如png、gif等）
+4. 添加图片压缩功能，减小文件大小
+