准备迁移1

docs/服务器图片迁移到阿里云OSS.md

@@ -0,0 +1,58 @@
+# 服务器图片迁移到阿里云 OSS
+
+本流程只操作服务器上的 MinIO。Mac 本地继续使用 `.env.mac-docker.example` 的 MinIO 配置，不会把本地图片迁走。
+
+## 1. 准备 OSS
+
+在阿里云 OSS 创建与现有 MinIO bucket 对应的 bucket，并创建只允许该 bucket 的 RAM 账号。建议 OSS 使用 S3 兼容端点，例如 `https://oss-cn-hangzhou.aliyuncs.com`，不要把 bucket 名写进 endpoint。
+
+编辑服务器 `.env`，先保留 MinIO 为主存储，并填好 OSS 目标配置：
+
+```dotenv
+STORAGE_MODE=dual
+STORAGE_ENDPOINT=http://minio:9000
+STORAGE_BUCKET=order-site
+STORAGE_ACCESS_KEY_ID=原 MinIO 账号
+STORAGE_SECRET_ACCESS_KEY=原 MinIO 密钥
+STORAGE_REGION=us-east-1
+STORAGE_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+STORAGE_OSS_BUCKET=OSS bucket 名
+STORAGE_OSS_ACCESS_KEY_ID=OSS RAM AccessKey ID
+STORAGE_OSS_SECRET_ACCESS_KEY=OSS RAM AccessKey Secret
+STORAGE_OSS_REGION=oss-cn-hangzhou
+```
+
+重建后端容器使配置生效。`dual` 模式下新上传的原图和缩略图会同时写入 MinIO、OSS；读取仍优先 MinIO，失败时回退 OSS，所以迁移期间无需停机。
+
+## 2. 增量复制与校验
+
+在服务器项目目录执行。容器镜像已内置迁移程序，下面命令不会停止现有后端：
+
+```bash
+docker compose exec backend node dist/storage-migrate.js copy
+docker compose exec backend node dist/storage-migrate.js verify
+```
+
+复制可以重复执行，目标中已有且大小、ETag 一致的对象会跳过。程序默认 8 路并发，可通过 `docker compose exec -e STORAGE_MIGRATION_CONCURRENCY=16 ...` 调整（最大 32）。校验会比较源、目标每个对象的 SHA-256、大小和 Content-Type；复制阶段的 ETag 仅用于幂等跳过，最终仍会对所有对象做完整内容校验。复制期间仍有新上传时，复制完成后再次执行 `copy` 和 `verify`，直到校验通过且没有遗漏。
+
+## 3. 切换到 OSS
+
+确认校验通过后，把服务器 `.env` 的 `STORAGE_MODE` 改为 `oss`，重新创建 backend：
+
+```bash
+docker compose up -d --no-deps backend
+curl -fsS https://你的域名/health/ready
+```
+
+此时新旧图片都只从 OSS 读取，数据库中的对象 key 和访问 URL 不需要改动。
+
+## 4. 停止 MinIO
+
+先观察 OSS 模式运行一段时间，确认图片上传、后台预览、打手端验收图片均正常，再停止并移除 MinIO 容器。不要删除 `minio_data` 卷，至少保留一个回滚窗口：
+
+```bash
+docker compose --profile storage stop minio
+docker compose --profile storage rm -f minio
+```
+
+若需要回滚，恢复 `STORAGE_MODE=dual`（或 `minio`），重新启动 MinIO 即可。确认 OSS 已稳定且备份完成后，再单独评估删除 `minio_data` 卷。