# 迁移存储渠道 (/zh/docs/operations/migrate-channel)

退役旧渠道、更换桶或前缀、改变加密属性、换服务商时，如何新建渠道、观察补齐进度、处理失败、必要时限速，并安全删除旧渠道。

## 什么时候用 [#什么时候用]

下列情况都按同一套步骤迁移：

- 退役一个渠道，例如服务商停服或不再续费；
- 更换桶、前缀或服务端点；
- 改变渠道的加密属性，见[渠道存储加密](../channels/encryption.mdx#创建后不可变)；
- 换一个服务商。

做法是新建一个渠道。ImgYoung 会把全部存量图片自动补齐到新渠道；补齐完成后，再删除旧渠道。迁移全程不停服，图片链接不变。

不要用「编辑」修改旧渠道的桶、前缀或端点，编辑不会触发补齐，见[编辑渠道](../channels/index.mdx#编辑渠道)。

## 迁移步骤 [#迁移步骤]

<Steps>
<Step>

**新建渠道**：在「存储渠道」页点「新建渠道」，按目标存储填写，加密属性也在这里选定。创建后立即开始补齐，见[新建渠道](../channels/index.mdx#新建渠道)。

</Step>
<Step>

**查看进度**：「副本」列显示新渠道的完成百分比，以及就绪、待补、失败的数量。百分比等于就绪数除以就绪、待补、失败三者之和。

</Step>
<Step>

**需要时限速**：补齐会持续读旧渠道、写新渠道，占用带宽。需要给其他业务让出带宽时，设置 `replicate_limit_mbps`，见[限制补齐带宽](#限制补齐带宽)。

</Step>
<Step>

**处理失败的副本**：「副本」列里「失败」的数字可以点开，进入该渠道的「副本清单」，查看每个失败副本的原因。排除原因后，点清单里的「重试失败的副本」，见[处理失败的副本](#处理失败的副本)。

</Step>
<Step>

**让读取转向新渠道**：「待补」归零、也没有「失败」后，把新渠道的优先级调到比旧渠道更高。访问图片时按优先级读取，之后读取会走新渠道，新上传的图片也会先写到新渠道。见[主渠道与备份渠道](../channels/index.mdx#主渠道与备份渠道)。

</Step>
<Step>

**删除旧渠道**：在旧渠道的行菜单选「删除」。确认新渠道已持有全部图片后，勾选「同时删除本服务写在该渠道上的数据」，点「删除并清理」。见[删除渠道](../channels/index.mdx#删除渠道)。

</Step>
</Steps>

## 处理失败的副本 [#处理失败的副本]

「存储渠道」页的「副本」列里，「待补」和「失败」的数字可以点开，打开该渠道的「副本清单」。清单按最近有变化的在前排列，可以只看待补、失败或就绪的副本。每行显示：

| 列 | 含义 |
|---|---|
| 图片 | 引用这个文件的最早一张图片的短 ID。内容相同的图片合并后共用一个文件，没有图片引用它时为空 |
| 引用数 | 引用这个文件的图片张数 |
| 状态 | 待补、补齐中、就绪或失败 |
| 尝试次数 | 累计补齐尝试次数 |
| 失败原因 | 最近一次失败的归类和原文，写法同渠道的[失败原因](../channels/index.mdx#失败原因) |
| 大小、类型 | 文件的字节数与 MIME |
| 更新时间 | 状态最近一次变化的时间 |

排查顺序：

1. 先看目标渠道的「状态」列。渠道异常时，补齐都会失败，先让它恢复健康。
2. 渠道健康但仍有失败，看失败原因，按原因处理。
3. 处理完点「重试失败的副本」。失败的副本全部改回待补并重新排队，页面提示重新排队的数量。

不点也会重试：渠道健康时，周期对账每 10 分钟把失败的副本改回待补，见[异步补齐](../channels/index.mdx#异步补齐)。「重试失败的副本」用于不想等下一轮对账的时候。渠道此刻不健康，副本会再次失败。接口响应里的 `queued` 为 `false` 表示排队没有全部完成：副本已经是待补，下一次周期对账会把它们排上，不必再点。每次重试记一条审计日志「重试失败的副本」。

## 限制补齐带宽 [#限制补齐带宽]

迁移一个有大量图片的实例时，补齐可能占满出口带宽。「设置 → 运行配置 → 可靠性与渠道」里的 `replicate_limit_mbps` 限制后台补课写入渠道的总带宽。补课指新建渠道的存量补齐，以及周期对账和启动对账重新排队的补齐，它们在独立的补课队列里运行：

- 单位 MB/s，所有渠道合计；
- 默认 `0`，不限速；
- 保存即生效，不需要重启。

它只限制补课，不影响新上传触发的补齐、用户上传时的同步写入，也不限制读取。补课队列与上传补齐所在的默认队列互不占用 worker，所以迁移期间新上传的图片仍然会很快补齐到各渠道。

补课队列同时最多运行 3 个补齐任务，它们共享这个额度，单个任务最长 15 分钟。限速过低时，传不完的大文件会超时并重试；默认的单图上限 50 MB 下，1 MB/s 就够用。取值见[配置](../configuration.mdx#可靠性与渠道)。

## 注意事项 [#注意事项]

- **每个渠道都要放得下全站的图片**。渠道之间是全量镜像，新渠道的容量要不小于现有图片总量，并留出迁移期间的新增。
- **迁移期间旧渠道仍在接收新图的副本**。在新渠道的优先级调高之前，新上传的图片先写旧渠道，再补齐到新渠道。所以「待补」归零是一个会被新上传刷新的状态，调高优先级之后再确认一次。
- **删除受唯一副本保护**。有图片在其他渠道上还没有就绪副本时，删除旧渠道会被拒绝（`channel_sole_replicas`），提示里给出图片张数。等新渠道补齐后再删。
- **编辑渠道不会触发补齐**。换存储位置要新建渠道，不要编辑旧渠道。
- **元数据库快照**：新渠道从下一次备份起也会有快照。旧渠道选「删除并清理」时，上面的快照一并删除，见[备份与恢复](./backup.mdx)。

## 错误码 [#错误码]

| 操作 | 状态码 | 错误码 | 含义 |
|---|---|---|---|
| 重试失败的副本 | 409 | `channel_deleting` | 渠道正在清理，不能重试 |
| 删除旧渠道 | 409 | `channel_sole_replicas` | 渠道持有部分图片的唯一就绪副本，等其他渠道补齐后再删 |

副本清单与重试的接口见[渠道管理接口](../api/admin-channels.mdx)。