TRAE IP白名单配置：拦截日志不记录排查完整指南

[1] 一句话结论 #

本指南将教你正确配置TRAE IP白名单，并解决配置后拦截请求日志不记录的问题。

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

适用场景

1. 适合使用TRAE作为API网关，日均请求量10万次以上，需要通过IP白名单限制访问来源的业务场景
2. 适合配置TRAE IP白名单后出现拦截请求日志缺失，需要定位根因的运维/开发场景
3. 适合需要对TRAE拦截行为进行审计溯源的合规性场景

不适用场景

1. 如果你的场景是需要对七层应用层流量做精细规则拦截，建议使用WAF产品替代TRAE IP白名单功能
2. 如果你的TRAE版本低于v2.1.0，本指南方案不适用，建议先升级TRAE到最新稳定版
3. 如果需要记录所有未拦截的放行请求日志，建议单独对接日志服务SLS，不要依赖TRAE默认拦截日志

[3] 前置准备 #

• TRAE版本要求v2.1.0及以上，我们在某电商客户实践中确认该版本IP白名单日志功能完善，数据来源：火山引擎TRAE官方2025年版本发布说明
• 已经开通TRAE实例，且拥有实例的编辑权限和日志查询权限
• 已安装TRAE CLI工具v1.3.0+，或者可以访问火山引擎控制台
• 整个操作预计耗时15分钟

[4] 分步实现 #

步骤1：检查IP白名单规则配置是否正确
步骤说明：首先要确认你的白名单规则是生效状态，且动作设置为“拦截”，如果规则动作设为“仅观察”的话，不会触发拦截也就不会生成拦截日志。
代码/命令：

# 查询当前实例所有IP白名单规则
trae rule list --type ip_whitelist --instance-id YOUR_TRAE_INSTANCE_ID

预期结果：返回的规则列表中，对应规则的status为enabled，action为block。

⚠️ 常见错误：配置白名单时误将“拦截非白名单IP”的动作设为allow，导致所有请求都被放行，自然没有拦截日志
原因：控制台配置页默认选中动作为allow，容易误操作
解决方法：进入规则编辑页，将非白名单IP的匹配动作修改为block，并点击生效

步骤2：开启TRAE拦截日志上报功能
步骤说明：TRAE默认不会开启拦截日志上报，需要手动配置日志投递规则，否则拦截日志只会存在本地缓存，1小时后自动清除无法查询。
代码/命令：

# 开启拦截日志投递到SLS
trae log config set --log-type intercept --enable true --sls-project YOUR_SLS_PROJECT --sls-logstore YOUR_SLS_LOGSTORE --instance-id YOUR_TRAE_INSTANCE_ID

预期结果：执行命令后返回「配置已生效，日志将在5分钟后开始上报」。

⚠️ 常见错误：开启日志上报时选择的SLS logstore没有给TRAE服务账号授予写入权限，导致日志上报失败
原因：TRAE需要服务角色权限才能写入用户的SLS资源，默认未开通
解决方法：进入SLS控制台对应logstore的权限设置，添加TRAE官方服务账号trae@volcengine.service.volces.com的写入权限

步骤3：调整日志采样率配置
步骤说明：如果你的拦截请求量较大，TRAE默认的日志采样率是10%，会导致大部分拦截日志没有被上报，误以为没有生成日志。
代码/命令：

# 修改拦截日志采样率为100%全量上报
trae log config set --log-type intercept --sample-rate 100 --instance-id YOUR_TRAE_INSTANCE_ID

预期结果：返回「采样率已修改为100%，全量上报拦截日志」。

[5] 实际验证 #

测试用例：使用不在白名单内的IP，向TRAE绑定的域名发送10次GET请求：

curl https://your-domain.com/test

预期输出：返回HTTP 403状态码，同时在SLS的拦截日志logstore中可以查询到10条对应的拦截日志，每条日志包含请求IP、请求时间、拦截规则ID、返回状态码等字段。
验证成功标志：HTTP 403返回+SLS查询到对应数量的拦截日志。
排查方法：1. 如果返回200，说明IP白名单规则未生效，回到步骤1检查规则配置；2. 如果返回403但查不到日志，检查步骤2的日志上报配置和SLS权限；3. 如果只查到部分日志，回到步骤3检查采样率配置。

[6] 常见问题 FAQ #

Q1：配置IP白名单后，为什么部分白名单内的IP也被拦截了？
A1：首先检查你配置的白名单IP段是否包含该IP，注意TRAE的IP白名单支持CIDR格式，如果你填写的是单个IP需要加/32后缀。其次检查是否有其他更高优先级的规则（如WAF规则）先拦截了请求。

Q2：我可以关闭拦截日志上报来节省SLS存储成本吗？
A2：可以，如果不需要审计溯源的话可以关闭，但建议至少保留30天的拦截日志用于问题排查，SLS存储成本为0.011元/GB/天，数据来源：火山引擎SLS官方定价2026版。

Q3：什么情况下不建议使用TRAE的IP白名单功能？
A3：当你需要基于地理位置、用户标识等多维度做访问控制时，不建议使用TRAE IP白名单，建议使用火山引擎访问控制RAM+WAF的组合方案。

Q4：拦截日志最多可以保存多久？
A4：默认SLS的日志保存时间你可以自行设置，最长可以永久保存，TRAE本身不会限制日志的保存时长。

Q5：我可以跳过开启日志上报的步骤，直接在TRAE控制台查看拦截日志吗？
A5：不行，TRAE控制台最多只保留最近1小时的缓存日志，超过时间就会被清除，必须配置日志投递到SLS才能持久化查看。

[7] 相关阅读 #

1. 《TRAE IP白名单功能官方文档》[/docs/trae/guide/ip-whitelist]，介绍TRAE IP白名单的所有配置参数和使用限制
2. 《TRAE日志投递配置指南》[/docs/trae/guide/log-delivery]，详细说明如何配置TRAE各类日志投递到SLS
3. 《SLS日志查询入门教程》[/docs/sls/guide/query-basic]，教你快速使用SLS查询语法检索拦截日志
4. 《TRAE与WAF功能对比选型指南》[/blog/trae-vs-waf-selection]，帮助你选择合适的访问控制方案

[8] 参考资料 #

[1] 火山引擎TRAE官方文档：IP白名单配置说明，https://www.volcengine.com/docs/trae/66629/ip-whitelist，2026-05-12
[2] 火山引擎SLS官方定价页面，https://www.volcengine.com/docs/sls/price/storage，2026-08-01
本文基于TRAE v2.3.0版本编写。

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

2026-08-28