在线迁移服务：准备工作

源 Bucket 归属于本账号

自动授权（推荐）

创建源数据地址时，在“授权角色”中完成自动授权，无需提前手动创建角色。

手动授权

需要复用角色管理多个 Bucket、角色数量受限或无法使用自动授权时，可选择手动授权。

创建 RAM 角色

使用步骤一准备的 RAM 用户登录 RAM 控制台，在角色页面创建角色：

1. 信任主体类型选择云服务。

2. 信任主体名称选择闪电立方（mgw.aliyuncs.com）。

3. 输入角色名称，例如 role-test，并完成创建。

角色名称使用小写字母，支持数字、连字符（-）和点号（.），长度不超过 64 个字符。已有符合要求的角色时，可为该角色补充相应权限。

授予源 Bucket 读取权限

创建以下自定义策略并附加到 RAM 角色，将 <srcBucket> 替换为源 Bucket 的实际名称。

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["oss:List*", "oss:Get*"],
      "Resource": [
        "acs:oss:*:*:<srcBucket>",
        "acs:oss:*:*:<srcBucket>/*"
      ]
    }
  ]
}

源 Bucket 不归属于本账号

创建 RAM 角色

使用步骤一准备的 RAM 用户登录 RAM 控制台，在角色页面创建角色：

1. 信任主体类型选择云服务。

2. 信任主体名称选择闪电立方（mgw.aliyuncs.com）。

3. 输入角色名称，例如 role-test，并完成创建。

角色名称使用小写字母，支持数字、连字符（-）和点号（.），长度不超过 64 个字符。已有符合要求的角色时，可为该角色补充相应权限。

配置源 Bucket Policy

使用源 Bucket 所属账号登录 OSS 管理控制台，选择源 Bucket，进入权限控制 > Bucket 授权策略，在按语法策略添加页签中添加以下授权。

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["oss:List*", "oss:Get*"],
      "Principal": [
        "arn:sts::<migrationUid>:assumed-role/<roleName>/*"
      ],
      "Resource": [
        "acs:oss:*:<bucketOwnerUid>:<srcBucket>",
        "acs:oss:*:<bucketOwnerUid>:<srcBucket>/*"
      ]
    }
  ]
}

Inventory

通用清单（Inventory）支持自定义清单及已适配的存储厂商原生清单。

支持的源与原生清单

通用清单（Inventory）支持以下 13 种对象存储源。其中，原生清单的支持范围如下。

使用厂商原生清单时，在源存储服务中配置清单生成规则，并等待文件生成。使用自定义清单时，按以下格式制作文件。

制作自定义清单

以下格式适用于 Inventory 自定义清单。使用厂商原生清单时，按厂商的清单功能生成文件。

自定义清单由一个 manifest.json 和一个或多个 .csv.gz 列表文件组成。每个列表文件记录一批待迁移对象，manifest.json 描述列表文件的位置和字段格式。

创建 CSV 列表文件

CSV 每行记录一个对象，各列以英文逗号分隔，字段如下。

URL 编码规则

对源对象的实际名称进行一次 URL 编码后，写入 Key，DestKey同理。

中文、多语言和已含编码文本的对象名示例

第三行的源对象名称实际包含 %2F 字符，编码时应将其中的百分号转换为 %25，不要先将它解码为斜杠。

文件格式要求

• 使用 UTF-8 编码，不包含 BOM。

• 每行必须以换行符结束，包括最后一行。

• 各行列数保持一致，并与 manifest.json 中的 fileSchema 字段数量和顺序一致。

• CSV 只包含对象记录，不添加字段名称行；字段名称在 fileSchema 中声明。

例如，采用 Key,Size 两列时，example.csv 内容如下：

path%2Fto%2F1.txt,1024
a%2Bb%25c%2Cd.file,2048

需要指定目的对象名称时，可使用 Key,Size,DestKey 三列：

path%2Fto%2F1.txt,1024,archive%2F1.txt

此时将 fileSchema 同步设为 Key,Size,DestKey。若目的前缀为 backup/，该对象迁移后的名称为 backup/archive/1.txt。

编码示例

以下 Python 3 示例读取未编码的 plain_example.csv，输出符合 Key,Size 格式的 example.csv。输入文件不包含字段名称行。

如果原始名称包含英文逗号，应按 CSV 规则用双引号包围该字段，例如：

path/to/1.txt,1024
"a+b%c,d.file",2048

import csv
from urllib.parse import quote_plus

with open("plain_example.csv", encoding="utf-8-sig", newline="") as src, \
     open("example.csv", "w", encoding="utf-8", newline="") as dst:
    reader = csv.reader(src)
    writer = csv.writer(dst, lineterminator="\n")
    for line_number, row in enumerate(reader, start=1):
        if len(row) != 2 or not row[0]:
            raise ValueError(f"第 {line_number} 条记录必须包含非空 Key 和 Size 两列")
        key, size = row
        writer.writerow([quote_plus(key, safe=""), size])

示例使用 CSV 解析器处理带引号和逗号的字段。需要添加 DestKey 时，在输入文件中增加对应列，并对该列执行相同的 URL 编码；同时更新 fileSchema。

压缩 CSV 文件

将各 CSV 文件分别压缩为 .csv.gz。单个压缩文件不得超过 100 MB。

gzip -c example.csv > example.csv.gz

该命令保留原始 example.csv。存在多个 CSV 文件时，分别压缩，并在 manifest.json 的 files 数组中列出各压缩文件。

多个 CSV 文件的处理示例

在仅包含待压缩 CSV 文件的目录中，可执行以下命令逐个生成同名的 .csv.gz 文件，并保留原始 CSV：

for file in ./*.csv; do
  [ -f "$file" ] || continue
  gzip -c "$file" > "$file.gz"
done

例如，将 example.csv.gz 和 example_part2.csv.gz 上传到清单 Bucket 的 inventory/ 目录后，可在同一个 manifest.json 中列出这两个文件：

{
  "fileFormat": "CSV",
  "fileSchema": "Key,Size",
  "files": [
    {"key": "inventory/example.csv.gz", "MD5checksum": "", "size": 0},
    {"key": "inventory/example_part2.csv.gz", "MD5checksum": "", "size": 0}
  ],
  "mgwInventoryVersion": "1.0"
}

各 CSV 的字段数量和顺序必须一致，并与 fileSchema 保持一致。每个压缩文件均不得超过 100 MB。

创建 manifest.json

以下示例对应 Key,Size 两列的 CSV 文件：

{
  "fileFormat": "CSV",
  "fileSchema": "Key,Size",
  "files": [
    {
      "key": "inventory/example.csv.gz",
      "MD5checksum": "",
      "size": 0
    }
  ],
  "mgwInventoryVersion": "1.0"
}

上传并记录清单位置

将 manifest.json 和所有 .csv.gz 文件上传到清单存储位置。确保 files[].key 与实际上传路径一致，并记录 manifest.json 的路径。

上传完成后，按下文“配置清单访问权限”完成授权。

HTTP/HTTPS

HTTP/HTTPS 清单由一个 manifest.json 和一个或多个 .csv.gz 列表文件组成。每行指定文件的访问链接及迁移后的目的对象名称。

确认文件链接可以访问

请在迁移前使用原始文件链接分别测试 HEAD 和 GET 请求：

# 检查元数据请求
curl -I 'https://example.com/files/1.txt'
# 检查文件下载请求，丢弃响应正文并显示响应头
curl -sS -D - -o /dev/null 'https://example.com/files/1.txt'

请将示例链接替换为实际文件链接，确认两类请求均成功。测试时不要添加 -L 参数，以免自动跟随重定向而掩盖问题。若返回 301、302 等重定向响应，请改用能够直接访问文件的最终链接。

对可正常访问的完整链接再进行一次 URL 编码后，写入 CSV 的 Url 字段。链接原本包含的百分号也需要编码。

例如，可访问链接中的路径包含 %E6%96%87 时，再次编码后该部分为 %25E6%2596%2587。

创建 CSV 列表文件

例如，文件的原始链接为 https://example.com/files/1.txt，期望的目的对象名称为 archive/1.txt，采用 Url,Key 两列时，CSV 记录为：

https%3A%2F%2Fexample.com%2Ffiles%2F1.txt,archive%2F1.txt

以上链接仅用于展示格式，使用时请替换为实际可访问的文件链接。

含中文、多语言路径的完整编码示例

以下原始 CSV 的第一列是可访问的完整链接，第二列是期望的目的对象名称：

https://example.com/files/%E6%96%87%E4%BB%B6.txt,archive/文件.txt
https://example.com/files/%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt,archive/ファイル.txt

对两列分别执行一次 URL 编码后，写入清单的记录为：

https%3A%2F%2Fexample.com%2Ffiles%2F%25E6%2596%2587%25E4%25BB%25B6.txt,archive%2F%E6%96%87%E4%BB%B6.txt
https%3A%2F%2Fexample.com%2Ffiles%2F%25E3%2583%2595%25E3%2582%25A1%25E3%2582%25A4%25E3%2583%25AB.txt,archive%2F%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB.txt

原始链接中已有的百分号会编码为 %25。迁移服务解码清单后，得到的仍是原始可访问链接；不要先将链接解码后再制作清单。以上链接仅用于展示格式。

压缩列表并创建 manifest.json

按Inventory 标签页中“制作自定义清单”中的压缩方法，将每个 CSV 分别压缩为 .csv.gz，单个压缩文件不得超过 100 MB。

以下 manifest.json 对应 Url,Key 两列的 CSV：

{
  "fileFormat": "CSV",
  "fileSchema": "Url,Key",
  "files": [
    {
      "key": "inventory/example.csv.gz",
      "MD5checksum": "",
      "size": 0
    }
  ]
}

fileFormat、fileSchema 和 files 的含义见Inventory 标签页中“制作自定义清单”中的字段说明。HTTP/HTTPS 清单按本节示例填写，不套用 Inventory 自定义清单的版本字段。

上传清单

将 manifest.json 及其引用的 .csv.gz 文件上传到 OSS 或 AWS S3。确认列表文件路径与 files[].key 一致，并记录 manifest.json 的路径。

上传完成后，按下文“配置清单访问权限”配置读取清单所需的权限。

编码示例

以下 Python 3 示例读取未编码的 plain_example.csv，输出 Url,Key 两列的 example.csv。输入文件不包含字段名称行，包含英文逗号的字段按 CSV 规则加双引号。

import csv
from urllib.parse import quote_plus

with open("plain_example.csv", encoding="utf-8-sig", newline="") as src, \
     open("example.csv", "w", encoding="utf-8", newline="") as dst:
    reader = csv.reader(src)
    writer = csv.writer(dst, lineterminator="\n")
    for line_number, row in enumerate(reader, start=1):
        if len(row) != 2 or not all(row):
            raise ValueError(f"第 {line_number} 条记录必须包含非空 Url 和 Key 两列")
        url, key = row
        writer.writerow([quote_plus(url, safe=""), quote_plus(key, safe="")])

OSS Inventory

在源 OSS Bucket 上配置存储空间清单，并等待清单文件生成。具体操作请参见存储空间清单。

记录清单所在的 Bucket 和清单路径，准备读取源对象及清单文件所需的权限。创建源数据地址时，按“OSS Inventory”类型填写清单参数。

S3 Inventory

在源 AWS S3 Bucket 上配置清单，并等待清单文件生成。具体操作请参见配置 Amazon S3 清单。

记录清单所在的 Bucket、地域和清单路径，准备读取源对象及清单文件所需的访问凭证和权限。创建源数据地址时，按“S3 Inventory”类型填写清单参数。

清单存放于本账号 OSS

创建源数据地址时，通过“列表授权角色”完成自动授权。

需要手动授权时，在本账号下创建或选择 RAM 角色，使用 阿里云 OSS 标签页中的同账号读取策略，将 <srcBucket> 替换为清单 Bucket 名称，授予列举和读取权限。

清单存放于其他账号 OSS

由清单 Bucket 所属账号配置 Bucket Policy，允许本账号下的 RAM 角色读取清单。

使用 阿里云 OSS 标签页中的跨账号读取策略，将 <srcBucket> 和 <bucketOwnerUid> 分别替换为清单 Bucket 名称及其所属主账号 UID。

清单存放于其他存储服务

准备对应存储服务的访问凭证，授予读取 manifest.json 及其引用的全部列表文件所需的权限。可选存储类型及填写方式见迁移实施。

HTTP/HTTPS 清单可存放于 OSS 或 AWS S3。Inventory 清单按控制台支持的清单存储类型配置。