# 服务器图片迁移到阿里云 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 容器（若仍由旧版编排管理）：

```bash
docker compose --profile storage stop minio
docker compose --profile storage rm -f minio
```

生产编排（`docker-compose.yml` 与 `deploy/ubuntu-deploy.sh`）已移除 MinIO 服务与 `storage` profile，此后部署不会再启动 MinIO。

不要删除 `minio_data` 卷（实际名称 `order_site_minio_data`），至少保留一个回滚窗口。若需要回滚，把 `.env` 的 `STORAGE_MODE` 改回 `dual`，并手动用旧卷拉起一个 MinIO 容器接入 compose 网络（`--network-alias minio` 保证 backend 仍可用 `http://minio:9000` 访问它）：

```bash
docker run -d --name minio-rollback \
  --network order_site_default \
  --network-alias minio \
  -v order_site_minio_data:/data \
  docker.m.daocloud.io/minio/minio:latest \
  server /data --address ":9000" --console-address ":9001"
```

确认 OSS 已稳定且完成密钥轮换后，再单独评估删除 `minio_data` 卷释放磁盘。