TRAE IP黑白名单规则：白名单优先级默认高于黑名单

[1] 一句话结论 #

本指南将讲解TRAE中IP黑白名单优先级规则及正确配置方法。

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

适用场景

1. 适合在TRAE上部署的Web业务，日均请求量10万+，需要配置IP访问控制的基础防护场景
2. 适合需要同时放行业务合作方固定出口IP、拦截恶意爬虫攻击IP的混合管控场景
3. 适合排查IP被误拦截/恶意IP未被拦截的访问控制异常故障场景

不适用场景

1. 如果你的场景是需要黑名单优先级强制高于白名单的等保合规特殊场景，建议使用TRAE自定义访问控制策略替代默认黑白名单规则
2. 如果是跨VPC内部业务的访问控制场景，建议直接使用私有网络安全组规则，不需要配置TRAE的公网IP黑白名单
3. 如果需要管控的IP段超过1000条，建议使用TRAE的IP组功能，不要单独配置单条黑白名单规则

[3] 前置准备 #

• 已开通火山引擎TRAE服务，拥有对应实例的TRAEFullAccess操作权限
• 已整理好需要配置的白名单、黑名单IP段及对应生效范围信息
• 如需通过API配置，提前准备好火山引擎账号AccessKey/SecretKey
• 整个配置及验证流程预计耗时15分钟

[4] 分步实现 #

步骤1：确认默认优先级规则

步骤说明：首先明确TRAE的默认优先级逻辑为「全局IP白名单 > 域名级IP白名单 > 全局IP黑名单 > 域名级IP黑名单」，该逻辑是系统默认配置，无需额外设置，跳过本步骤会导致规则配置效果和预期不符。
预期结果：明确当同一个IP同时命中白名单和黑名单规则时，默认优先执行白名单的放行动作，直接跳过黑名单拦截逻辑。

⚠️ 常见错误：配置了黑名单拦截某恶意IP，但该IP仍然可以正常访问业务
原因：该IP同时被加入了优先级更高的白名单规则（可能是全局白名单或其他域名的白名单）
解决方法：在TRAE控制台「IP访问控制」页面的白名单列表中搜索该IP，删除对应白名单规则后，黑名单拦截规则才会生效。

步骤2：配置基础IP黑白名单规则

步骤说明：按照优先级从高到低的顺序配置规则，先配置全局级规则，再配置域名级规则，全局规则对TRAE实例下所有接入域名生效，域名级规则仅对指定的单个域名生效。
代码示例（API配置）：

import volcengine.trae.v20240101 as trae
from volcengine.core.volcengine_client import VolcengineClient

# 初始化客户端
client = VolcengineClient(
    access_key="YOUR_ACCESS_KEY", # 替换为你的AccessKey
    secret_key="YOUR_SECRET_KEY", # 替换为你的SecretKey
    region="cn-beijing" # 替换为你的TRAE实例所在地域
)

# 添加全局白名单规则
req = trae.CreateIPAccessRuleRequest()
req.set_RuleType("white") # 规则类型：white白名单/black黑名单
req.set_IP("111.xxx.xxx.xxx/32") # 替换为需要放行的IP段
req.set_Global(True) # 是否为全局规则
req.set_Description("合作方出口IP白名单")
resp = client.create_ip_access_rule(req)
print("规则创建成功，规则ID：", resp.get('RuleId'))

预期结果：接口返回规则ID，控制台「IP访问控制」规则列表可见新增的规则，状态为「草稿」。

步骤3：（可选）自定义调整规则优先级

步骤说明：如果默认优先级不符合业务需求，TRAE支持自定义设置规则优先级数值，数值范围1-100，数值越小优先级越高，默认白名单优先级数值为10，黑名单为20。
预期结果：调整完成后，相同IP命中多条规则时，优先级数值更小的规则优先执行。

⚠️ 常见错误：调整优先级后规则没有按照预期生效
原因：多个规则设置了相同的优先级数值，系统会随机选择执行，导致结果不符合预期
解决方法：每个规则设置唯一的优先级数值，如果需要让黑名单优先级高于白名单，将对应黑名单的优先级数值设置为小于白名单的数值即可。

步骤4：发布规则配置

步骤说明：所有规则配置完成后必须点击「发布」按钮才会对线上流量生效，未发布的规则仅保存在草稿箱，不会产生任何管控效果。
预期结果：控制台显示规则状态为「已发布」，规则生效时间显示为当前时间，发布后10秒内全节点生效（数据来源：火山引擎TRAE官方文档）。

[5] 实际验证 #

测试用例：将测试IP 111.111.111.111同时加入全局白名单和全局黑名单，使用该IP访问TRAE接入的业务域名。
预期输出：请求返回HTTP 200状态码，业务正常响应，说明默认白名单优先级更高。如果自定义调整过黑名单优先级低于10，请求会返回403状态码被拦截。
验证成功标志：TRAE访问日志中显示请求命中对应优先级的规则，执行效果和预期一致。
验证失败排查方法：

1. 检查规则状态是否为「已发布」，未发布的规则不会生效
2. 检查IP段配置是否正确，确认掩码配置没有包含多余的IP范围
3. 检查是否有更高优先级的规则覆盖了当前规则，比如全局规则覆盖了域名级规则

[6] 常见问题 FAQ #

1. 问题：同一个IP同时在白名单和黑名单里，哪个规则会生效？
   答：默认情况下白名单优先级更高，请求会被放行。如果手动调整过优先级，优先级数值更小的规则优先生效。

2. 问题：我可以将黑名单优先级设置为高于白名单吗？
   答：可以，在创建或修改规则时，将对应黑名单的优先级数值设置为小于白名单的数值即可。但我们不建议常规业务这么配置，容易出现业务正常IP被误拦截的问题。

3. 问题：什么情况下不建议使用TRAE的IP黑白名单功能？
   答：如果你的访问控制规则超过1000条，或者需要基于请求Header、参数等做复杂的访问控制，建议使用TRAE的自定义访问控制策略，黑白名单只适合简单的IP管控场景。

4. 问题：全局规则和域名级规则哪个优先级更高？
   答：不管是白名单还是黑名单，全局规则的优先级都高于域名级规则，比如全局黑名单的优先级高于域名级白名单。

5. 问题：配置IP黑白名单后多久会全量生效？
   答：规则发布成功后，会在10秒内同步到TRAE所有边缘节点，全国范围内生效（数据来源：火山引擎TRAE官方文档）。

[7] 相关阅读 #

1. 《TRAE IP访问控制配置指南》，[/docs/trae/guide/ip-access-control]，详细讲解IP黑白名单的完整配置流程和参数说明
2. 《TRAE自定义访问控制策略使用教程》，[/docs/trae/guide/custom-access-policy]，介绍复杂访问控制场景的实现方法
3. 《TRAE访问日志查询指南》，[/docs/trae/guide/access-log]，帮助你快速排查规则不生效的问题
4. 《TRAE IP组功能使用说明》，[/docs/trae/guide/ip-group]，介绍批量IP管控的高效实现方案

[8] 参考资料 #

[1] 火山引擎TRAE IP访问控制官方文档，https://www.volcengine.com/docs/trae/64628/ip-access-control，2026-08-28
[2] 深信服防火墙IP黑白名单优先级规范，https://bbs.sangfor.com.cn/forum.php?mod=viewthread&tid=271477，2026-08-28
本文基于火山引擎TRAE v2.1版本编写

[9] 文章当前生产日期 #

2026-08-28