README 外链图片转存 OSS

This commit is contained in:
lxp
2026-11-03 17:27:22 +08:00
parent c5be9835bf
commit 175c49e0e7
35 changed files with 1557 additions and 99 deletions
+27 -1
View File
@@ -59,6 +59,7 @@ prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token
| API 跨域来源 | `https://dev-vibemake.robotquan.com` | `https://vibemake.robotquan.com` |
| OSS 封面目录 | vibemake_dev/project-covers/ | vibemake/project-covers/ |
| OSS URDF 目录 | vibemake_dev/urdf/{projectCode}/{batchCode}/ | vibemake/urdf/{projectCode}/{batchCode}/ |
| OSS README 图片目录 | vibemake_dev/readme-images/ | vibemake/readme-images/ |
| 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 |
| 项目日志级别 | DEBUG | INFO |
| 日志目录 | logs,可用 LOG_PATH 覆盖 | logs,可用 LOG_PATH 覆盖 |
@@ -220,6 +221,31 @@ Fork 不受普通在线文件读取的 50 MiB 限制,文件浏览、下载和
## 项目短编码与 GitHub 初始化导入
### README 外链图片转存 OSS
GitHub 后台迁移和 Excel 命令行导入在分支适配后自动检查根目录 `README.md`(文件名不区分大小写)。支持 Markdown 图片、引用式图片、HTML `img src`、`srcset` 和 `picture` 图片;仓库相对路径、代码示例、普通超链接及已配置的 OSS/CDN 地址保持原样。动态徽章(shields.io、GitHub Actions、ROS 构建状态、常见覆盖率徽章)保留原链,普通静态 SVG 通过安全校验后可以转存;仅外部 DTD 声明会移除,脚本、内部实体和远程资源引用仍禁止。其他语言的 README 或子目录文档不在本次处理范围。
设置 `README_IMAGES_ENABLED=false` 可以暂停转存;默认启用,单图上限 `README_IMAGE_MAX_BYTES=20971520`,图片并发 `README_IMAGE_CONCURRENCY=2`(1~4)。可在配置的 `vibemake.readme-images.preserve-url-patterns` 中追加需要保留的完整 URL 正则。图片只下载公开 HTTP/HTTPS 地址,不携带业务凭据;单图总预算 45 秒,每次 DNS 解析及重定向都禁止内网地址。JPG、PNG、GIF、WebP 和安全 SVG 按内容摘要写入 `{环境根目录}/readme-images/{SHA256}.{扩展名}`,不覆盖已有对象;上传核验并从公开地址读取核验成功后才替换 README。RAM 账号需要对应前缀的 PutObject/GetObject 权限,资源需要公开可读或通过公开 CDN 访问。
存量项目在项目根目录运行:
```bash
# 仅扫描数据库与仓库,不下载外链、不上传图片、不修改项目。
bash scripts/migrate-readme-images.sh --dry-run
# 先处理一个含待转存图片的项目。
bash scripts/migrate-readme-images.sh --execute --limit 1
# 同一状态目录断点续跑其余项目。
bash scripts/migrate-readme-images.sh --execute
# 指定项目重新尝试仍失败的图片,使用新的状态目录保存独立收据。
bash scripts/migrate-readme-images.sh --execute --project-code 项目编码 --state-dir logs/readme-image-retry
```
默认状态目录 `logs/readme-image-migration` 绑定 Gitea、组织、OSS Bucket、环境目录和公开基础地址,禁止跨环境复用;同时只允许一个进程使用。保存精确预览、原 README 备份、原发布 SHA、每一步操作收据和结果报告,目录/文件权限分别为 0700/0600,写入原子替换并持久化。脚本使用 `java-with-env.py` 安全读取 `.env` 字面量,不进行 shell 求值;含 `&` 的 JDBC 地址可正常读取,文件中的配置覆盖同名进程变量,与原有启动脚本一致。不会修改 `.env` 或输出配置值。
未删除且仓库 READY 的项目才进入批处理。main 与原发布版本一致时复用一个图片提交;不一致时从原发布 SHA 创建 `maintenance/readme-oss/...` 维护分支,确认仅 README 变化后更新发布引用。维护分支保留以确保快照可下载和 Fork;不将 main 上其他未发布代码带入社区,不改变撤回/下架状态或发布时间。GitHub 后台迁移仍由管理员手动发布,Excel 导入仍自动发布处理后的版本,来源 SHA 与图片提交 SHA 分开保存,兼容历史迁移收据。
图片下载失败、格式不支持或 OSS 不可用时保留原链并记录告警,其余图片继续;Git 写入结果不明确则保持待核对状态,续跑只查收据,不重发提交。报告的 `failed` 是保留原链的图片引用数。恢复业务展示可在项目锁中对照备份条件回写原发布 SHA;恢复 main 需基于当前版本提交 README 的反向修改,不能强制重置分支。不要删除共享 OSS 对象或维护分支。一般日志只记录项目编码、来源主机、阶段和错误码,含完整图片地址的原文只保存在受限备份中。
### 历史外链封面转存 OSS
`scripts/migrate-project-covers.sh` 读取本项目 `.env`,将数据库现有外链图片下载并转存至当前环境 OSS,上传并核验成功后才更新 `cover_url`。配置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`;带 `&` 的 JDBC 地址必须加引号。环境根目录沿用 test 的 `vibemake_dev` 或 prod 的 `vibemake`。
@@ -251,7 +277,7 @@ bash scripts/migrate-project-covers.sh --execute
外部封面保留原 URL 和 GIF,不转存 OSS;当前环境的平台封面统一转换为相对路径。描述由原中文简介和技术资料组合,不调用 AI。轮式、四足、人形分别映射对应类型,机械臂映射 ROBOTIC_ARM,其他和硬件映射 GENERAL,原始分类保留在描述里。
脚本加载本项目 `.env`,依赖 Java 21、Maven,以及正式执行时可用的 MySQL 和 Gitea。独立导入模块不启动 Web 服务,也不加载登录、AI 或 OSS 客户端;只读取资源地址配置,不需要 OSS 凭据。test/prod 根目录与在线应用一致,历史公开地址使用 `OSS_LEGACY_PUBLIC_BASE_URLS`。Gitea 技术账号需具备组织所有者及仓库写权限,实例需开启迁移、HTTP Git 和 LFS。`GITHUB_TOKEN` 可选,仅用于 GitHub 元数据 API;API 限流时读取同一公开仓库的 GitHub 网页,交叉核验仓库 ID、规范地址、公开状态和默认分支,缺失或不一致则预检失败。网页和图片请求均不携带凭据。`GITEA_TOKEN` 仅访问配置的 Gitea,不能代替 `GITHUB_TOKEN`;切勿把 Token 放进 URL 或命令参数。
脚本加载本项目 `.env`,依赖 Java 21、Maven,以及正式执行时可用的 MySQL 和 Gitea。独立导入模块不启动 Web 服务,也不加载登录或 AI。资源地址转换无需 OSS 凭据;README 图片转存按需初始化 OSS 客户端,未配置凭据时保留原链并产生告警。test/prod 根目录与在线应用一致,历史公开地址使用 `OSS_LEGACY_PUBLIC_BASE_URLS`。Gitea 技术账号需具备组织所有者及仓库写权限,实例需开启迁移、HTTP Git 和 LFS。`GITHUB_TOKEN` 可选,仅用于 GitHub 元数据 API;API 限流时读取同一公开仓库的 GitHub 网页,交叉核验仓库 ID、规范地址、公开状态和默认分支,缺失或不一致则预检失败。网页和图片请求均不携带凭据。`GITEA_TOKEN` 仅访问配置的 Gitea,不能代替 `GITHUB_TOKEN`;切勿把 Token 放进 URL 或命令参数。
```bash
IMPORT_EXCEL='/绝对路径/项目.xlsx'