treg 被屏蔽邮箱域名（TREG_BLOCKED_EMAIL_DOMAINS）机制详解：防批量注册的完整指南
【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg
treg 是一款面向 Agent 工具的数据 API 网关，而它的被屏蔽邮箱域名机制（环境变量TREG_BLOCKED_EMAIL_DOMAINS）是一道轻量但精巧的反作弊防线：通过一条逗号分隔的环境变量，就能在登录、注册、建队的所有入口拒绝一次性邮箱域名，且无需重新部署。本文用大白话讲清它的配置方式、匹配规则和背后的安全设计。
为什么 treg 需要邮箱域名屏蔽？
先说动机，理解了它才理解设计：
- 🎁 在 treg 中，每创建一个新的团队（Org）都会发放一笔促销余额，这对拉新很友好；
- ⚠️ 但对羊毛党来说，用一次性邮箱（throwaway email）批量注册、批量建队，就能白拿大量余额；
- 🛡️ 因此 treg 提供了一份邮箱域名黑名单，把已知的垃圾邮箱域整体拦在门外。
关键取舍是：黑名单完全由配置驱动，代码里不内置任何清单。因为攻击者几分钟就能换一批新域名，如果黑名单要靠发版更新，永远慢一步；而改一条环境变量（或控制台字段）几秒就生效——官方称之为 "speed bump"（路障）。
如何配置 TREG_BLOCKED_EMAIL_DOMAINS？
配置非常简单，核心只有一条环境变量：
# 逗号分隔，大小写不敏感；留空 = 不屏蔽任何域名 TREG_BLOCKED_EMAIL_DOMAINS=throwaway-mail.com,spam-box.net配置与解析逻辑见 src/treg/config.py，环境变量说明表在 README.md 中也有收录。
解析时会做一层"运维容错"（见 _blocked_email_domains）：
| 输入 | 处理 |
|---|---|
Farm-B.example | 自动转小写 |
@farm-c.example、.farm-d.example | 去掉开头误粘的@或. |
| （空格、空项） | 直接丢弃 |
com（无点的裸后缀） | 强制丢弃——防止一次手误就屏蔽全世界 |
解析结果经lru_cache缓存，同一个值只解析一次，而不是每个请求都重新切分字符串。
匹配规则：只认域名，子域名连坐，TLD 绝不连坐
分类器 _is_blocked_email 有两条铁律，规则设计非常克制：
- 只看
@后面的域名部分，绝不匹配整个邮箱。因为如果匹配完整地址，用户名里恰好包含某段字符串的正常用户（如farm-a@company.dev）会被误伤； - 逐级向上级域名回溯匹配：列出
mail.farm.com，则a@mail.farm.com、a@farm.com都被拦截（防"注册一个子域名就绕过"的一行代码）；但永远不会单独拿最后一段 TLD 比对，所以a@id这类地址不可能被误拦。
用测试用例直观感受一下（节选自 tests/test_blocked_email_domains.py）：
| 邮箱地址 | 结果 | 原因 |
|---|---|---|
a@farm-a.example | 🚫 拦截 | 命中清单域名本身 |
A@FARM-B.EXAMPLE | 🚫 拦截 | 大小写不敏感 |
a@deep.mail.farm-c.example | 🚫 拦截 | 命中父域名（子域名连坐） |
farm-a@company.dev | ✅ 放行 | 只匹配域名，不匹配用户名 |
a@notfarm-a.example | ✅ 放行 | 字符串后缀 ≠ 子域名 |
a@farm-a.example.org | ✅ 放行 | 清单域名在中间，不是后缀 |
值得一提的是，项目还尝试过"子串匹配"（域名里含某字符串就拦），实测对公开的垃圾域名语料仅多覆盖 0.17%，却会拦掉域名里恰好含该字符串的正常公司——最终被移除。
哪些入口会被检查？treg 身份门全解析
被屏蔽域名在treg 所有身份入口都会触发检查，包括：
- ✉️ 邮箱验证码登录：发起（
/auth/email/start）与校验（/verify） - 🔁 GitHub / Google 社交登录回调
- 📬 邮箱邀请链接
- 📝 开放注册
POST /users与建队POST /orgs（这两个入口会发放促销余额，是重点防护对象）
决策函数 blocked_email 有两个值得学习的设计：
- 失败放行（fail open）：分类器一旦抛异常，只记一条 error 日志，大门保持敞开——宁可漏拦，也不能让配置错误把正常用户的登录全打断；
- 日志是唯一检测手段：每次拦截都会打一条可统计的结构化日志
event=signup_blocked_domain door=... domain=...，方便从日志里数出拦截量。
被屏蔽后用户看到什么？
答案：几乎什么都不看。所有入口返回的是同一条通用 403 消息：
this address cannot be used to sign in
不透露"你被哪个规则拦了"、不区分新旧账号、不给出申诉通道细节——对自动化脚本来说毫无利用价值。已有的存量账号会被运营侧离线停用，而不是靠接口报错去发现，做到"拦而不扰"。
配套测试与官方文档
该机制的规则几乎每条都被固定为自动化测试，方便你深入了解边界情况：
- 测试：tests/test_blocked_email_domains.py —— 覆盖"未配置不拦任何人"、大小写/空格容错、子域名连坐、裸 TLD 防御、失败放行等全部规则；
- 安全文档：SECURITY.md —— 说明黑名单在"促销额度防刷"体系中的定位；
- 部署文档：docs/context/ops/deploy.md —— 环境变量一览与运维口径；
- API 文档：docs/context/interface/api.md —— 各身份入口的检查点清单；
- 多租户架构：docs/context/architecture/multi-tenancy.md。
总结
treg 的TREG_BLOCKED_EMAIL_DOMAINS机制给出了一个反作弊黑名单的"最小可靠实现"范本：纯配置、秒级生效、只匹配域名、子域名连坐而 TLD 永不连坐、统一模糊提示、失败放行、日志可审计。对于需要防批量注册的开源项目，这 200 行左右的实现（解析 + 分类 + 决策）非常值得一读。
【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
