OSS 迁移与 CDN 切换实施记录

实施日期：2026-07-19
当前状态：河源新 Bucket 已成为生产写入端和 CDN 主源站；旧深圳 Bucket、跨区域复制和 CDN 备用源站暂时保留。
注意：本文不记录数据库密码、AccessKey、SSH 私钥等敏感信息。

1. 调整目标

本次调整的目标是：

将 OSS 数据从华南1（深圳）的旧 Bucket 迁移到与 ECS 同地域的华南2（河源）新 Bucket。
历史资源和新上传资源统一使用 https://cdn.xiedao888.cn 访问。
新上传由 ECS 通过阿里云内网写入河源 OSS，减少公网链路和流量。
新 Bucket 保持私有，通过阿里云 CDN 私有 OSS 回源授权读取。
迁移过程中保留数据库备份、旧 Bucket、跨区域复制和 CDN 备用源站，确保具备回滚条件。

2. 调整后的链路

text

客户端
  ↓ HTTPS
cdn.xiedao888.cn
  ↓ 私有 OSS 回源授权
主源站：xiedao-oss（河源）
备源站：xielioss（深圳，仅作为迁移期备用）

ECS 后端（河源）
  ↓ OSS 内网 Endpoint
xiedao-oss（河源）

数据库中的资源 URL 统一保存为：

text

https://cdn.xiedao888.cn/{ObjectKey}

3. OSS 资源配置

3.1 旧 Bucket

项目	配置
Bucket	`xielioss`
地域	华南1（深圳）
用途	原生产 Bucket、迁移期 CDN 备用源站
当前处理	暂不删除

3.2 新 Bucket

项目	配置
Bucket	`xiedao-oss`
地域	华南2（河源）
存储类型	标准存储
冗余类型	ZRS
访问权限	私有
阻止公共访问	已开启
服务端加密	OSS 完全托管 AES256
版本控制	关闭

3.3 跨区域复制

复制方向：

text

xielioss（深圳） → xiedao-oss（河源）

当前策略：

已执行历史全量复制；
保持持续增量复制；
不同步删除操作；
不复制 KMS 加密对象；
用户已人工核对历史数据复制完整。

迁移稳定前不得停止复制或删除旧 Bucket。

4. CDN 配置

4.1 域名和源站

CDN 域名：

text

cdn.xiedao888.cn

当前源站：

源站	优先级	端口
`xiedao-oss.oss-cn-heyuan.aliyuncs.com`	主	80
`xielioss.oss-cn-shenzhen.aliyuncs.com`	备	80

配置要求：

CDN 回源必须使用公网 OSS 域名，不使用 -internal；
河源源站指定回源 HOST 为 xiedao-oss.oss-cn-heyuan.aliyuncs.com；
深圳备用源站继续使用对应的深圳 OSS HOST；
已开启“阿里云 OSS 私有 Bucket 回源”；
CDN 已获得同账号 OSS 只读回源权限；
不将 cdn.xiedao888.cn 绑定为 OSS 自定义域名。

4.2 HTTPS

项目	状态
HTTPS	已开启
证书	Let's Encrypt `*.xiedao888.cn` 通配符证书
当前到期时间	2026-09-29 16:54:08
HTTP/2	已开启并验证
HTTP → HTTPS	已开启并验证301跳转
HTTPS 请求计费	阿里云 CDN 按 HTTPS 请求数单独计费

自定义上传的 CDN 证书不会跟随服务器 Certbot 自动更新。后续自动化方案见：

阿里云CDN证书自动续期部署方案.md

5. CDN 验证结果

历史图片访问验证通过：

text

HTTP/2 200
x-oss-cdn-auth: success
X-Cache: MISS / HIT
Age: 正常增长
Via: 阿里云 CDN 节点

已验证：

HTTPS TLS 握手正常；
HTTP/2 正常；
HTTP 自动301跳转 HTTPS；
私有 OSS 回源授权成功；
首次访问可回源；
后续访问可命中 CDN 内存缓存；
河源源站切换为主后，历史资源重新回源成功。

6. 数据库历史 URL 迁移

6.1 扫描范围

对 xiedao_dev 全库的字符、文本和 JSON 字段进行扫描，查找：

text

xielioss.oss-cn-shenzhen.aliyuncs.com
hainanxieli.oss-cn-heyuan.aliyuncs.com

扫描定位到14张业务表、29个字段，涉及：

用户头像；
商品、房型、车辆、摄影、套餐图片；
商户 Logo；
身份证、营业执照等商户入驻资料；
游记图片和视频；
订单商品快照；
富文本内容和 JSON 快照。

6.2 精确备份

备份表：

text

xiedao_dev.bak_oss_url_20260719

备份标签：

text

oss_to_cdn_20260719
oss_to_cdn_20260719_final

最终备份结果：

项目	数量
备份字段	1325
涉及业务行	562
涉及表字段组合	29

6.3 替换规则

text

https://xielioss.oss-cn-shenzhen.aliyuncs.com
→
https://cdn.xiedao888.cn

替换通过备份表中的表名、主键、字段名和旧值约束执行，没有进行无条件全库盲目更新。

6.4 最终核验

核验项	结果
备份字段数	1325
精确转换成功	1325
转换不匹配	0
旧深圳域名引用	0
`hainanxieli` 域名引用	0
CDN 域名引用字段	1325

数据库备份表暂时保留，不得提前删除。

7. 后端生产配置切换

生产服务器 /opt/xiedao/api/env.sh 已新增：

bash

export ALIYUN_OSS_ENDPOINT=oss-cn-heyuan-internal.aliyuncs.com
export ALIYUN_OSS_BUCKET_NAME=xiedao-oss
export ALIYUN_OSS_URL_PREFIX=https://cdn.xiedao888.cn
export ALIYUN_OSS_LEGACY_URL_PREFIXES=https://xielioss.oss-cn-shenzhen.aliyuncs.com

说明：

后端 OSS SDK 使用河源内网 Endpoint；
CDN 回源仍使用公网 OSS Endpoint；
url-prefix 决定上传接口返回给客户端的 URL；
legacy-url-prefixes 供后续新版代码兼容旧 URL 提取 ObjectKey。

本次没有执行 Api/deploy.bat，没有替换生产 JAR。原因是本地工作区存在大量与 OSS 无关的未提交修改，直接部署会把其他未完成改动一起发布。

生产服务通过读取新环境变量重启现有 JAR，启动结果：

text

Started RuoYiApplication
携岛启动成功
WxTradeReadiness 前置检查全部通过

8. 新上传验证

已通过商户上传/OCR接口执行受控上传：

text

POST /api/merchant/upload-and-ocr-idcard

接口返回：

text

https://cdn.xiedao888.cn/merchant/2026/07/19/28daccafae1b44509d732fb0154f0e70.jpg

这证明现有生产 JAR 已读取：

河源新 Bucket 名称；
CDN URL 前缀。

仍需完成以下最终核验：

[ ] 使用 CDN URL 请求该新对象并确认 HTTP/2 200；
[ ] 在 xiedao-oss 搜索该 ObjectKey，确认存在；
[ ] 在 xielioss 搜索该 ObjectKey，确认不存在；
[ ] 确认后再全面恢复上传。

如果上传的是普通测试图片，OCR 返回 null 属于正常情况；如果上传的是真实身份证图片，则需单独排查 OCR。

9. 本地代码改动状态

本地已修改但尚未提交、尚未部署：

Api/ruoyi-admin/src/main/resources/application.yml
- OSS 配置支持环境变量；
- 默认值调整为河源新 Bucket 和 CDN URL；
- 增加旧 URL 前缀配置。
Api/ruoyi-system/src/main/java/com/xiedao/system/service/OssService.java
- 支持从 CDN URL 和旧深圳 OSS URL 提取相同 ObjectKey；
- 删除历史 URL 对应对象时操作当前河源 Bucket；
- 不处理无关外部 URL。
Api/ruoyi-system/src/test/java/com/xiedao/system/service/OssServiceUrlTest.java
- 增加 URL 兼容测试。

验证情况：

本次生产代码和新增测试源码曾成功编译；
全量测试没有通过；
测试执行被仓库中与 OSS 无关的既有测试编译错误阻断；
后续还出现本地依赖缺失和受限网络无法下载依赖的问题；
不得声称新增测试已经完整通过。

后续不得在当前脏工作区直接执行 deploy.bat。应先隔离 OSS 改动、完成测试，再使用中文 Git commit 注释提交和部署。

10. 视频和其他文档情况

10.1 迁移层面

OSS 跨区域复制按 Object 复制，不区分图片、视频、PDF、压缩包等类型。因此 Bucket 中符合复制规则的对象均已纳入迁移，不是只复制图片。

数据库 URL 替换也不区分扩展名。备份数据中确认有1条 xd_note.video_url 视频引用已完成转换，未发现旧 OSS 域名下的 PDF、Office 或压缩包数据库引用。

10.2 上传能力

通用上传接口当前允许：

图片；
mp4、avi、rmvb 视频；
PDF；
Word、PPT、文本；
ZIP、RAR、GZ、BZ2 等压缩文件。

限制：

单文件最大50MB；
单请求最大200MB；
商户证件和业务图片专用接口只允许图片；
MimeTypeUtils.DEFAULT_ALLOWED_EXTENSION 中 Excel 扩展名疑似误写为 Xds、Xdsx，可能导致 xls、xlsx 无法通过通用 OSS 上传；
当前 CDN 业务类型为“图片小文件”，短视频可以使用，但不适合大量或大体积视频，后续应评估阿里云 VOD。

11. 当前存在的问题和风险

P0：敏感资料通过公开 CDN URL 访问

当前商户身份证、营业执照、工作证明、付款凭证、合同等资料如果保存为 cdn.xiedao888.cn 永久 URL，则获得 URL 的任何人都可能直接访问。

OSS Bucket 私有只限制直接 OSS 访问；CDN 获得私有回源授权后，如果 CDN 域名本身没有 URL 鉴权，资源仍可通过 CDN 公开访问。

建议后续拆分：

公共资源：商品图、头像、游记、旅游指南、公开视频走公共 CDN；
敏感资源：身份证、执照、合同、付款凭证等保存在私有 OSS，通过短期签名 URL或后端鉴权下载接口访问；
不把 Referer 防盗链当作敏感数据鉴权方案。

P0：新上传对象没有反向复制到深圳

当前复制方向只有：

text

深圳旧 Bucket → 河源新 Bucket

切换后产生的新对象只写入河源，不会复制回深圳。因此：

深圳备用源站只保证历史对象的备用能力；
河源切换后新增的文件，在深圳备用源站中不存在；
如果立即把后端回滚到深圳，新上传对象会缺失；
真正回滚前必须先处理河源新增对象的反向补数据。

P1：CDN 证书不会自动同步 Certbot 续期

当前证书将于2026-09-29到期。服务器 Certbot 自动续期后，CDN 自定义上传证书不会自动变化。

在自动化实施前，必须提前手工更新；后续方案见证书自动续期文档。

P1：本地 OSS 兼容代码尚未正式部署

生产现有 JAR 已能通过环境变量写入新 Bucket 并返回 CDN URL，但本地新增的旧 URL 兼容逻辑尚未部署。

数据库旧 URL 当前为0，因此现有生产功能可以工作；若后续仍收到旧 URL 输入，现有 JAR 可能无法按新兼容逻辑处理。

P1：新上传对象的双 Bucket 核验尚未完成

受控上传已返回 CDN URL，但尚未在记录中确认：

CDN 实际可读取；
河源 Bucket 存在；
深圳 Bucket 不存在。

完成该核验前不应宣布迁移全部完成。

P1：KMS 加密对象不在复制范围

复制任务配置为不复制 KMS 对象。用户已人工确认总体数据完整，但仍建议在旧 Bucket 清理前单独确认是否存在历史 KMS 加密对象。

P2：视频和文档上传规则需要整理

Excel 扩展名疑似配置错误；
MOV、MKV 等常见视频格式不在当前允许列表；
50MB 单文件上限不适合较长视频；
CDN 缓存规则目前未按视频、文档和敏感路径分类配置。

P2：不复制删除会保留旧 Bucket 陈旧对象

当前不复制删除操作是为了迁移期安全和回滚，但会导致两侧对象长期不一致。稳定期结束后需要制定旧 Bucket 清理和数据保留策略。

P2：HTTPS 请求产生独立费用

阿里云 CDN HTTPS 请求数单独计费，不能使用普通 CDN 流量包抵扣，需要关注账单并评估 HTTPS 请求资源包。

12. 回滚原则

12.1 CDN 回滚

历史资源异常时，可以把深圳 xielioss 临时恢复为 CDN 主源站，河源改为备用。

注意：该回滚不能覆盖河源切换后新增的对象。

12.2 后端回滚

生产 JAR 本次没有替换，程序级回滚只需恢复 env.sh 备份并重启。但在切回深圳写入前，必须先处理河源新增对象，否则会造成新文件缺失。

12.3 数据库回滚

数据库可使用 bak_oss_url_20260719 中 oss_to_cdn_20260719_final 标签进行字段级精确回滚。

除非 CDN 域名整体不可恢复，否则不建议回滚数据库 URL；CDN URL 与具体源站解耦，通常只需调整 CDN 源站即可。

13. 后续操作清单

切换完成前

[ ] 验证新上传测试文件 CDN 返回 HTTP/2 200。
[ ] 确认新对象只存在于河源 Bucket。
[ ] 再次扫描数据库，确认旧深圳域名仍为0。
[ ] 恢复业务上传。

稳定观察期（建议7～14天）

[ ] 抽查历史头像、商品、房型、车辆、游记和订单快照。
[ ] 测试商户入驻 OCR、身份证、营业执照上传。
[ ] 测试头像和商品图片删除、替换。
[ ] 观察 CDN 4xx/5xx、回源流量、缓存命中率和 HTTPS 请求费用。
[ ] 对比河源 Bucket 对象数量、容量和新增趋势。
[ ] 确认是否存在 KMS 加密历史对象。
[ ] 保留深圳旧 Bucket 和数据库备份表。

后续整改

[ ] 设计敏感资料私有访问方案。
[ ] 实施 CDN 证书自动续期部署和到期告警。
[ ] 修复 Excel 扩展名配置。
[ ] 评估视频使用 CDN 还是阿里云 VOD。
[ ] 隔离、测试、提交并部署本地 OSS 兼容代码。
[ ] 制定河源新增对象的灾备复制方案。
[ ] 稳定期结束后决定是否停止旧→新复制以及如何清理旧 Bucket。

14. 禁止提前执行的操作

在全部验证和稳定观察完成前，不要执行：

删除 xielioss；
删除数据库备份表 bak_oss_url_20260719；
停止跨区域复制；
删除深圳 CDN 备用源站；
在当前脏工作区直接运行 Api/deploy.bat；
将 OSS Bucket 改为公共读以规避私有回源问题；
把 CDN 回源地址改为 -internal 域名。

OSS 迁移与 CDN 切换实施记录 ​

1. 调整目标 ​

2. 调整后的链路 ​

3. OSS 资源配置 ​

3.1 旧 Bucket ​

3.2 新 Bucket ​

3.3 跨区域复制 ​

4. CDN 配置 ​

4.1 域名和源站 ​

4.2 HTTPS ​

5. CDN 验证结果 ​

6. 数据库历史 URL 迁移 ​

6.1 扫描范围 ​

6.2 精确备份 ​

6.3 替换规则 ​

6.4 最终核验 ​

7. 后端生产配置切换 ​

8. 新上传验证 ​

9. 本地代码改动状态 ​

10. 视频和其他文档情况 ​

10.1 迁移层面 ​

10.2 上传能力 ​

11. 当前存在的问题和风险 ​

P0：敏感资料通过公开 CDN URL 访问 ​

P0：新上传对象没有反向复制到深圳 ​

P1：CDN 证书不会自动同步 Certbot 续期 ​

P1：本地 OSS 兼容代码尚未正式部署 ​

P1：新上传对象的双 Bucket 核验尚未完成 ​

P1：KMS 加密对象不在复制范围 ​

P2：视频和文档上传规则需要整理 ​

P2：不复制删除会保留旧 Bucket 陈旧对象 ​

P2：HTTPS 请求产生独立费用 ​

12. 回滚原则 ​

12.1 CDN 回滚 ​

12.2 后端回滚 ​

12.3 数据库回滚 ​

13. 后续操作清单 ​

切换完成前 ​

稳定观察期（建议7～14天） ​

后续整改 ​

14. 禁止提前执行的操作 ​

OSS 迁移与 CDN 切换实施记录

1. 调整目标

2. 调整后的链路

3. OSS 资源配置

3.1 旧 Bucket

3.2 新 Bucket

3.3 跨区域复制

4. CDN 配置

4.1 域名和源站

4.2 HTTPS

5. CDN 验证结果

6. 数据库历史 URL 迁移

6.1 扫描范围

6.2 精确备份

6.3 替换规则

6.4 最终核验

7. 后端生产配置切换

8. 新上传验证

9. 本地代码改动状态

10. 视频和其他文档情况

10.1 迁移层面

10.2 上传能力

11. 当前存在的问题和风险

P0：敏感资料通过公开 CDN URL 访问

P0：新上传对象没有反向复制到深圳

P1：CDN 证书不会自动同步 Certbot 续期

P1：本地 OSS 兼容代码尚未正式部署

P1：新上传对象的双 Bucket 核验尚未完成

P1：KMS 加密对象不在复制范围

P2：视频和文档上传规则需要整理

P2：不复制删除会保留旧 Bucket 陈旧对象

P2：HTTPS 请求产生独立费用

12. 回滚原则

12.1 CDN 回滚

12.2 后端回滚

12.3 数据库回滚

13. 后续操作清单

切换完成前

稳定观察期（建议7～14天）

后续整改

14. 禁止提前执行的操作