feat: 支持创建邮箱 API 的子域名后缀匹配开关 (#929)

* feat: 支持创建邮箱 API 的子域名后缀匹配开关 * fix: 修复 review 提到的开关三态与域名校验问题 * fix: 补充域名归一化与子域名匹配回归测试 * fix: 修复后台开关跟随 env 回退与 account_settings 半成功保存 * fix: 收口账号设置刷新提示与子域名状态重复读取 * fix: 拦截超长域名并透传账号设置刷新失败
2026-09-05 07:27:27 +08:00 · 2026-04-04 00:11:23 +08:00
parent d2c940aa2c
commit 1a7cfb8c95
21 changed files with 776 additions and 23 deletions
@@ -39,6 +39,31 @@ res = requests.post(
 print(res.json())
 ```

+### 创建子域名邮箱地址
+
+如果你已经把基础域名配置进 `DOMAINS` / `DEFAULT_DOMAINS` / `USER_ROLES`，并且开启了
+`ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH`（管理后台也可单独开关），那么创建地址 API 可以直接接收子域名：
+
+```python
+res = requests.post(
+    "https://xxxx.xxxx/admin/new_address",
+    json={
+        "enablePrefix": True,
+        "name": "project001",
+        "domain": "team.example.com",
+    },
+    headers={
+        'x-admin-auth': "<你的网站admin密码>",
+        "Content-Type": "application/json"
+    }
+)
+```
+
+- 如果允许域名里有 `example.com`，则 `team.example.com`、`dev.team.example.com` 都可以匹配成功
+- `badexample.com` 这种**不是点分后缀**的域名不会被误判为 `example.com`
+- 这与 `RANDOM_SUBDOMAIN_DOMAINS` 不同：这里是**由调用方显式指定子域名**，不是系统自动生成随机子域名
+- 管理后台可以把该能力设置为“跟随环境变量 / 强制开启 / 强制关闭”；其中“跟随环境变量”会清空后台覆盖，恢复到未设置后按 env 回退
+
 ## 批量创建随机用户名邮箱地址 API 示例

 ### 通过 admin API 批量新建邮箱地址
@@ -33,3 +33,25 @@ RANDOM_SUBDOMAIN_LENGTH = 8
 > 这个功能只是在“创建地址”时自动补一个随机二级域名。
 >
 > 它不会自动帮你创建 Cloudflare 侧的子域名收件路由或 DNS 配置，请先确保基础域名/子域名路由本身已经可用。
+
+## 允许 API 直接指定子域名
+
+如果你不想让系统随机生成子域名，而是希望调用方在创建地址时直接指定 `team.abc.com` 这种子域名，
+可以开启：
+
+```toml
+ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH = true
+```
+
+开启后，只要允许域名里包含基础域名 `abc.com`，那么：
+
+- `name@team.abc.com`
+- `name@dev.team.abc.com`
+
+都可以通过 `/api/new_address` 或 `/admin/new_address` 创建。
+
+> [!NOTE]
+> 这个能力只放宽“创建地址 API 的域名校验”，不会改动默认域名下拉，也不会自动创建 Cloudflare 侧的
+> 子域名邮箱路由。
+>
+> 如果你在管理后台里保存过这个开关，后续也可以通过“跟随环境变量”把它恢复到未设置状态，再重新回退到 env 默认值。
@@ -32,6 +32,7 @@
 | `ADDRESS_REGEX`                       | 文本      | `邮箱名称` 替换非法符号的正则表达式, 不在其中的符号将被替换，如果不设置，默认为 `[^a-z0-9]`, 需谨慎使用, 有些符号可能导致无法收件 | `[^a-z0-9]`                               |
 | `DEFAULT_DOMAINS`                     | JSON      | 默认用户可用的域名(未登录或未分配角色的用户)                                                                                      | `["awsl.uk", "dreamhunter2333.xyz"]`      |
 | `CREATE_ADDRESS_DEFAULT_DOMAIN_FIRST` | 文本/JSON | 创建新地址时是否优先使用默认域名，如果设置为 true，当未指定域名时将使用第一个域名, 主要用于 telegram bot 场景                     | `false`                                   |
+| `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` | 文本/JSON | 是否允许创建邮箱 API 使用“基础域名后缀匹配”。开启后，如果允许域名里有 `example.com`，则 `/api/new_address` 与 `/admin/new_address` 可以接受 `foo.example.com`、`a.b.example.com` 这类子域名 | `true` |
 | `RANDOM_SUBDOMAIN_DOMAINS`            | JSON      | 允许启用随机子域名的基础域名列表，启用后可把 `name@abc.com` 创建成 `name@随机串.abc.com`                                         | `["abc.com"]`                             |
 | `RANDOM_SUBDOMAIN_LENGTH`             | 数字      | 随机子域名长度，默认 `8`，范围 `1-63`                                                                                            | `8`                                       |
 | `DOMAIN_LABELS`                       | JSON      | 对于中文域名，可以使用 DOMAIN_LABELS 显示域名的中文展示名称                                                                       | `["中文.awsl.uk", "dreamhunter2333.xyz"]` |
@@ -44,6 +45,15 @@
 > 侧的子域名路由。
 >
 > 子域名地址通常更适合收件；如果要发件，仍建议优先使用主域名。
+>
+> `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` 与随机子域名功能不同：它允许 API 调用方**直接指定**
+> `foo.example.com` 这类子域名；而随机子域名功能是系统在创建时自动补一个随机前缀。
+>
+> `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` 的优先级为：当 env 明确设置为 `false` 时，全局硬禁用；
+> 其他情况下优先使用后台持久化设置，后台未设置时再回退到 env 值。
+>
+> 管理后台提供三种显式状态：**跟随环境变量**、**强制开启**、**强制关闭**。当你选择
+> “跟随环境变量”并保存时，会清空后台覆盖，恢复到“未设置”的回退行为。

 ## 接受邮件相关变量