TRAE IP白名单配置：IPv6地址添加操作全指南
[1] 一句话结论
本指南将介绍TRAE企业专属版IPv6地址加入IP白名单的完整操作与验证方法。
[2] 适用场景与不适用场景
适用场景
- 适合使用TRAE企业专属版、需要通过固定IPv6地址访问TRAE开发/沙箱环境的开发者场景；
- 适合TRAE API调用方为IPv6网络架构、需要限制访问来源的安全管控场景；
- 适合日均TRAE API调用量在500次以上、有明确访问源管控需求的企业级用户场景。
不适用场景
- 如果你使用的是TRAE免费个人版，无IP白名单功能，建议升级到TRAE企业专属版；
- 如果你的场景仅需要IPv4地址访问，不需要额外配置IPv6白名单，建议仅维护IPv4白名单即可；
- 如果你的访问源为动态IPv6地址段且变动频率大于每天1次，不建议使用固定IP白名单，建议参考TRAE API密钥鉴权方案。
[3] 前置准备
- 账号权限：TRAE企业版管理员账号，拥有访问控制配置权限；
- 环境要求：Chrome 100+ / Edge 100+ 浏览器，无特殊开发环境要求；
- 前置信息：待添加的完整IPv6地址（精确到单地址或CIDR段）；
- 预计耗时：单条地址配置全程约2分钟，批量配置10条以内约5分钟。
[4] 分步实现
步骤1：进入TRAE访问控制配置页
步骤说明：首先登录TRAE企业版管理后台，找到「安全设置」板块下的「IP白名单」入口，这一步是所有配置的入口，跳过的话无法找到配置入口。
预期结果：进入页面后可以看到当前已配置的所有IPv4/IPv6白名单条目。
⚠️ 常见错误：登录普通成员账号后找不到「安全设置」菜单。
原因：只有企业版管理员账号才有IP白名单配置权限，普通成员无权限。
解决方法：联系企业内TRAE管理员授权，或由管理员直接操作配置。
步骤2：选择IPv6地址类型
步骤说明：在白名单添加页面，切换地址类型为「IPv6」，系统默认选中的是IPv4，不切换的话IPv6地址会被判定为格式错误。
预期结果：地址输入框的格式提示变为IPv6格式规范。
步骤3：输入待添加的IPv6地址
步骤说明：输入完整的IPv6地址，支持单地址（如2409:8c20:1830:100::2）和CIDR段（如2409:8c20:1830:100::/64），可以填写备注标记地址用途，方便后续维护。
预期结果：输入后系统实时校验格式，格式正确的话输入框无红色报错。
⚠️ 常见错误：输入缩写的IPv6地址（如省略前导零、用::压缩多段零）后系统提示格式错误。
原因：根据我们的实践，TRAE当前版本（v2.1）对压缩格式的IPv6地址兼容性不足。
解决方法：将IPv6地址补全为8段完整格式后再输入，可通过在线IPv6格式转换工具快速补全。
步骤4：提交并确认配置
步骤说明：点击「添加」按钮后，在弹出的二次确认窗口中核对地址和备注信息，确认无误后点击「确认提交」，这一步二次校验是为了避免误添加陌生地址带来的安全风险。
预期结果：页面弹出「添加成功」提示，新添加的IPv6地址出现在白名单列表中。
步骤5：等待配置生效
步骤说明：TRAE白名单配置生效时间为1-3分钟（数据来源：TRAE官方文档v2.1），生效前新添加的地址仍然无法访问，不要立即测试。
预期结果：3分钟后配置正式生效。
[5] 实际验证
测试用例：使用已添加到白名单的IPv6地址的服务器，调用TRAE沙箱环境的ping接口，请求地址为https://api.trae.cn/v1/ping，请求方法GET。
预期输出：HTTP状态码200，返回体为{"code":0,"msg":"pong","data":{}}。
验证成功标志：返回上述结果即说明配置生效。
验证失败常见排查方法：
- 配置还未生效：等待3分钟后重试即可；
- 地址配置错误：核对白名单中的IPv6地址与实际出口IPv6地址是否一致，可通过访问https://6.ipw.cn 获取当前服务器的出口IPv6地址；
- 地址类型选择错误：确认配置时选择的是IPv6类型，而非默认的IPv4。
[6] 常见问题 FAQ
Q1：TRAE IP白名单最多可以添加多少条IPv6地址？
A：根据TRAE官方文档，企业版最多支持添加200条IP白名单（含IPv4和IPv6），超过上限需要联系商务申请扩容。
Q2：我可以同时添加IPv4和IPv6地址到白名单吗？
A：可以，两种地址类型的白名单是并行生效的，只要访问源匹配其中任意一条就可以正常访问。
Q3：什么情况下不建议配置IPv6白名单？
A：如果你的业务没有IPv6访问需求，或者你的访问源IPv6地址是动态变化的，不建议配置IPv6白名单，否则会出现地址变动后无法访问的问题，建议使用API密钥鉴权替代。
Q4：添加IPv6白名单后多久可以生效？
A：正常情况下1-3分钟即可生效，如果超过10分钟仍未生效，可以提交工单联系TRAE技术支持排查。
Q5：我可以删除已配置的IPv6白名单地址吗？
A：可以，在白名单列表中点击对应条目后的删除按钮，二次确认后即可删除，删除后生效时间同样为1-3分钟。
[7] 相关阅读
- 《TRAE访问控制官方文档》，[/docs/settings/access-control]，详细介绍TRAE企业版所有访问控制功能的配置方法。
- 《TRAE API鉴权指南》，[/docs/api/authentication]，介绍除IP白名单外的其他API鉴权方案。
- 《TRAE沙箱环境使用手册》，[/docs/ide/sandbox]，介绍TRAE沙箱环境的访问限制与配置方法。
- 《IPv6地址格式转换工具使用教程》，[/tools/ipv6-format]，帮助快速转换符合TRAE要求的IPv6地址格式。
[8] 参考资料
[1] TRAE官方文档：访问控制（仅企业专属版），https://www.w3cschool.cn/traedocs/settings-for-trae-enterprise-exclusive-edition.html，2026-08-28[2] TRAE官方文档：Appsecret配置IP白名单的具体步骤与实践指南，https://www.trae.cn/article/660485634，2026-08-28
本文基于TRAE企业版v2.1编写。
[9] 文章当前生产日期
2026-08-28
