跳到主要内容

白名单配置

概述​

MBS 使用 Callback URL 白名单机制控制哪些地址可以作为消息订阅的推送目标。创建订阅时，MBS 会从 Callback URL 中提取主机名或 IP，与白名单进行匹配。如果不在白名单中，订阅请求会被拒绝。

警告

白名单为空时，所有订阅请求都会被拒绝。使用 Subscribe Action 前，请确保管理员已正确配置白名单。

白名单类型​

类型格式说明示例
精确 IP纯 IP 地址精确匹配 Callback URL 解析后的 IP10.0.0.1
CIDRIP/掩码匹配指定网段内的所有 IP172.16.0.0/16
主机名纯主机名精确匹配 Callback URL 中的主机名api.example.com

主机名格式要求​

危险

主机名格式必须严格遵守以下规则，否则匹配会失败：

正确格式错误格式说明
api.example.comhttps://api.example.com不要带协议前缀
api.example.comapi.example.com:8080不要带端口
api.example.comapi.example.com/callback不要带路径
my-service.prod.internalhttp://my-service.prod.internal/webhook纯主机名即可

匹配流程​

MBS 在收到订阅请求时，会按以下流程校验 Callback URL：

从 Callback URL 提取主机名部分
例: https://api.example.com:8080/webhook → api.example.com
        │
        ▼
主机名是 IP 地址？
        │
    ┌───┴───┐
    是       否
    │        │
    ▼        ▼
直接匹配    先尝试精确匹配
IP/CIDR    HOSTNAME 白名单
白名单          │
    │        匹配成功？
    │     ┌───┴───┐
    │     是       否
    │     │        │
    │     ▼        ▼
    │   通过     DNS 解析为 IP
    │           再匹配 IP/CIDR
    │              │
    └──────────────┘
            │
            ▼
    匹配成功 → 允许创建订阅
    匹配失败 → 拒绝请求

配置方式​

通过管理后台配置​

  1. 登录 MBS 管理后台（http://mbs-host:8080/mbs/ui/）
  2. 进入 "白名单配置" 页面
  3. 添加白名单条目（选择类型，填写值）
  4. 保存

通过管理 API 配置​

curl -X PUT http://localhost:8080/mbs/api/admin/whitelist \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '[
    {"entryType": "CIDR", "value": "10.0.0.0/8"},
    {"entryType": "CIDR", "value": "172.16.0.0/12"},
    {"entryType": "HOSTNAME", "value": "my-service.prod.internal"},
    {"entryType": "IP", "value": "192.168.1.100"}
  ]'

条目字段：

字段说明可选值
entryType白名单类型IP、CIDR、HOSTNAME
value白名单值对应类型的格式

常见配置场景​

内网服务（固定 IP）​

[
  {"entryType": "IP", "value": "10.0.1.50"},
  {"entryType": "IP", "value": "10.0.1.51"}
]

内网服务（网段）​

[
  {"entryType": "CIDR", "value": "10.0.0.0/8"},
  {"entryType": "CIDR", "value": "172.16.0.0/12"}
]

K8s 集群内部服务​

[
  {"entryType": "CIDR", "value": "172.31.0.0/16"},
  {"entryType": "HOSTNAME", "value": "order-service.default.svc.cluster.local"},
  {"entryType": "HOSTNAME", "value": "notify-service.prod.svc.cluster.local"}
]

外部域名​

[
  {"entryType": "HOSTNAME", "value": "api.partner-company.com"},
  {"entryType": "HOSTNAME", "value": "webhook.third-party.io"}
]

多实例同步​

修改白名单后，通过 PostgreSQL 的 NOTIFY 机制实时同步到所有 MBS 实例。通常无需手动干预，变更会在几秒内生效。

常见问题​

Q: 配置了主机名白名单但订阅还是报错？​

排查步骤：

  1. 确认主机名是纯域名格式（不带 https://、端口、路径）
  2. 确认拼写完全一致（大小写敏感）
  3. 如果还不行，可能是白名单缓存未刷新，等待 NOTIFY 同步或重启服务

Q: 使用 K8s 内部域名时如何配置？​

两种方式（推荐同时使用）：

  1. 添加 CIDR 类型覆盖 Pod 网段（如 172.31.0.0/16）
  2. 添加 HOSTNAME 类型填写 K8s Service 完整域名（如 my-service.default.svc.cluster.local）

Q: Callback URL 中有端口号怎么办？​

白名单只匹配主机名部分，端口会被忽略。例如 Callback URL 为 http://10.0.1.50:3000/webhook，白名单中只需添加 IP 10.0.1.50。

Q: 如何允许所有地址？​

不建议这样做。如果确实需要（如测试环境），可以添加 0.0.0.0/0 的 CIDR 条目，但生产环境务必配置精确的白名单。