soul-yongping/soul-api/scripts/README-migrate-base64-images.md

文章 base64 图片迁移脚本

将 chapters 表中 content 字段内嵌的 base64 图片提取为独立文件，并替换为 /uploads/book-images/xxx 的 URL，减小文章体积。

适用场景

• 历史文章中有大量粘贴的 base64 图片
• 保存时因 content 过大导致超时或失败
• 需要将 base64 转为文件存储

执行方式

1. 测试环境（建议先执行）

cd soul-api

# 加载测试环境配置（.env.development）
$env:APP_ENV="development"

# 先 dry-run 预览，不写入
go run ./cmd/migrate-base64-images --dry-run

# 确认无误后正式执行
go run ./cmd/migrate-base64-images

2. 生产环境

cd soul-api
$env:APP_ENV="production"
go run ./cmd/migrate-base64-images --dry-run   # 先预览
go run ./cmd/migrate-base64-images            # 正式执行

3. 指定 DSN（覆盖 .env）

$env:DB_DSN="user:pass@tcp(host:port)/db?charset=utf8mb4&parseTime=True"
go run ./cmd/migrate-base64-images --dry-run

参数

参数	说明
--dry-run	仅统计和预览，不写入文件与数据库

行为说明

1. 查询 content LIKE '%data:image%' 的章节
2. 用正则提取 src="data:image/xxx;base64,..." 或 src='...'
3. 解码 base64，保存到 uploads/book-images/{timestamp}_{random}.{ext}
4. 将 content 中的 base64 src 替换为 /uploads/book-images/xxx
5. 更新数据库

注意事项

• 务必先在测试环境验证，确认无误后再跑生产
• 脚本依赖 UPLOAD_DIR 或默认 uploads 目录
• 图片格式支持：png、jpeg、jpg、gif、webp