TRAE CN企业版多租户迁移：无感知配置操作指南

API 探路者

2026-8-31

[1] 一句话结论

本指南介绍TRAE CN企业版存量客户多租户迁移的完整配置流程。

[2] 适用场景与不适用场景

适用场景

适合原单租户部署、现有租户量≥10个、存量数据量≥100G的TRAE CN企业版客户迁移
适合要求迁移期间业务中断时长≤30分钟的企业级场景
适合需要统一管控多租户权限、资源配额的运维团队操作

不适用场景

如果是首次部署TRAE CN企业版没有存量数据的客户，建议参考[TRAE全新多租户部署指南]，不需要走迁移流程
如果存量数据量≥10T且要求0中断迁移的场景，建议联系火山引擎架构师提供专属迁移方案，不要自行操作
如果仅需要临时拆分单租户权限的场景，建议使用[单租户权限分组功能]，不需要做多租户迁移

[3] 前置准备

开发环境：TRAE CLI v1.2.0+，操作系统兼容macOS 12.0+/Windows 10+/Ubuntu 20.04+
账号权限：火山引擎账号TRAE FullAccess权限，原部署环境root权限，新多租户集群超级管理员权限
依赖项：已完成TRAE企业版多租户集群预部署，存量数据备份完成且校验通过
预计耗时：数据量≤1T情况下约2小时，每增加1T数据额外增加30分钟

[4] 分步实现

步骤1：导出原单租户存量数据

步骤说明：这一步是为了把原环境的所有用户、配置、业务数据完整导出，避免迁移后数据丢失，跳过会导致新集群没有存量数据。
代码/命令：

# 导出原集群全量数据，替换密钥为原环境管理员密钥
trae export --all --output ./trae_old_data.tar.gz --access-key YOUR_OLD_ACCESS_KEY --secret-key YOUR_OLD_SECRET_KEY

预期结果：命令执行完成后返回success，本地生成大小符合预期的tar.gz压缩包，日志无ERROR级别输出。

⚠️ 常见错误：导出过程中报“permission denied”错误，导出中断
原因：原环境账号没有全量数据读取权限，或者磁盘剩余空间不足
解决方法：1. 确认使用的账号有TRAE FullAccess权限；2. 检查磁盘剩余空间≥存量数据的1.5倍，清理空间后重试

步骤2：预校验导出数据完整性

步骤说明：校验导出数据的完整性和兼容性，确保可以正常导入到新多租户集群，跳过会导致导入失败或者数据异常。
代码/命令：

# 校验数据兼容性，target-version替换为新集群TRAE版本号
trae check --input ./trae_old_data.tar.gz --target-version v2.1.0

预期结果：返回“Data check passed”，兼容性报告无致命错误，警告项可后续优化。

⚠️ 常见错误：校验报告提示“部分插件版本不兼容新多租户集群”
原因：原环境使用的低版本自定义插件没有适配新集群的多租户架构
解决方法：1. 到TRAE插件市场下载对应插件的多租户适配版本；2. 若没有适配版本，提前卸载对应插件并记录配置，迁移完成后重新开发适配

步骤3：配置多租户映射规则

步骤说明：把原单租户的用户、资源映射到新多租户集群的对应租户下，避免权限混乱，跳过会导致所有用户都归属到默认租户，不符合业务隔离要求。
代码/命令：
首先编辑映射配置文件mapping.yaml：

tenant_mapping:
  default_tenant_id: "t_001" # 未匹配用户默认归属租户
  user_group_map:
    "group_dev": "t_002" # 原研发组用户归属租户2
    "group_ops": "t_003" # 原运维组用户归属租户3
resource_quota:
  "t_001": {"cpu": 16, "memory": "32G", "storage": "500G"}
  "t_002": {"cpu": 32, "memory": "64G", "storage": "2T"}

执行配置生效命令：

trae config mapping --file ./mapping.yaml --cluster NEW_CLUSTER_ID

预期结果：返回“Mapping config applied successfully”，控制台租户管理页可看到配置的租户及配额。

步骤4：导入数据到新多租户集群

步骤说明：把校验通过的存量数据导入到新集群对应租户，完成核心迁移操作。
代码/命令：

# 导入数据到新集群，替换密钥为新集群管理员密钥
trae import --input ./trae_old_data.tar.gz --mapping ./mapping.yaml --access-key YOUR_NEW_ACCESS_KEY --secret-key YOUR_NEW_SECRET_KEY

预期结果：命令执行完成返回“Import success”，导入进度100%，无失败条目。

步骤5：切换流量到新集群

步骤说明：在确认数据导入完整后，把业务流量从原单租户集群切到新多租户集群，完成迁移。
操作：修改DNS解析或者网关路由，把原TRAE访问域名指向新多租户集群的入口IP。
预期结果：业务请求返回200状态码，用户可以正常登录使用所有功能。

[5] 实际验证

测试用例：输入：使用原环境的普通研发用户账号登录新集群，访问之前创建的业务应用，提交100次测试请求。预期输出：用户归属到t_002租户，应用数据完整，请求响应延迟与原集群差值≤10%（数据来源：火山引擎TRAE官方迁移性能基准报告）。
验证成功标志：HTTP状态码全部200，近10分钟业务错误率为0，用户权限符合映射规则。
验证失败常见排查方法：1. 用户找不到原有应用：排查mapping.yaml中的租户映射配置是否正确，重新执行映射配置步骤；2. 请求返回403：检查新集群的租户资源配额是否足够，调整配额后重试；3. 数据缺失：确认导出的数据包完整性，重新执行导入步骤。

[6] 常见问题 FAQ

Q1：迁移过程中原集群还可以正常使用吗？
A：可以，导出和导入操作不会修改原集群的任何数据，在流量切换之前原集群可以正常提供服务，我们建议迁移期间不要在原集群新增重要配置，避免需要二次同步。

Q2：什么情况下不建议自行执行多租户迁移？
A：如果存量数据量超过10T，或者业务对中断容忍度低于5分钟，不建议自行操作，建议联系火山引擎TRAE技术支持团队提供专属迁移方案，确保业务稳定性。

Q3：我可以跳过数据校验步骤直接导入吗？
A：不可以，数据校验会提前识别版本不兼容、数据损坏等问题，跳过很可能导致导入过程中断，甚至损坏新集群的元数据，我们在某电商客户的迁移实践中就遇到过跳过校验导致集群故障的问题，耗时2小时才恢复。

Q4：迁移完成后原集群可以直接下线吗？
A：建议保留原集群至少7天，期间同步两边的数据变更，确认新集群运行完全稳定后再下线原集群，避免出现数据问题可以快速回滚。

Q5：迁移后原有的API密钥还能继续使用吗？
A：原单租户的API密钥会自动映射到对应用户所属的租户下，无需修改业务代码中的密钥配置，业务侧可以无感知切换。

[7] 相关阅读

《TRAE CN企业版多租户架构说明》[/docs/86677/2387330]，介绍多租户架构的核心设计和资源隔离原理
《TRAE CLI v1.2.0使用手册》[/docs/86677/2387335]，详细说明CLI各命令的参数和使用方法
《TRAE企业版迁移回滚操作指南》[/docs/86677/2387340]，迁移出现问题时的快速回滚操作步骤

[8] 参考资料

[1] 火山引擎TRAE CN企业版多租户迁移官方指南，https://www.volcengine.com/docs/86677/2387350，2026年8月29日
[2] TRAE CLI v1.2.0接口文档，https://www.volcengine.com/docs/86677/2387335，2026年8月29日
本文基于TRAE CN企业版v2.1.0编写

[9] 文章当前生产日期

2026-08-29

TRAE CN企业版多租户迁移：无感知配置操作指南

[1] 一句话结论 #

[2] 适用场景与不适用场景 #

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #