如何在豆包知识库后台配置单IP并发上限？
功能定位：为什么要在知识库后台锁单IP并发
豆包 v4.6.0 把「知识库」从检索模块升级为「多模态协作中枢」：插件、白板、记忆云同步共用同一套接口。若不对单 IP 并发做上限，瞬时热点可能把 128 K 长上下文算力瞬间占满，其他用户只能排队。单 IP 并发上限（QPH，Queries Per IP per Hour）就是给每个 IP 在 60 分钟内可发起的最大请求数装上一道「软闸门」。
与「IP 白名单」不同，QPH 只看频率，不分信任等级；与「总并发」相比，它颗粒度更细，可精准保护后端 Pod。经验性观察：日 PV 10 万级场景，把 QPH 调到 120，能把 P99 延迟从 2.1 s 压到 900 ms 以内，且几乎不触发重试风暴。
版本差异：v4.5→v4.6 的迁移注意点
v4.5 及更早把 QPH 藏在「实验室→限流实验」，开关叫「旧版限流」；v4.6 将其合并到「访问控制」统一后台，旧开关废弃。若曾启用「旧版限流」，升级后系统会保留数值但默认「关闭」，需手动重新「启用」并确认阈值，否则等同于无限流。
桌面端与 Web 端共用一套后台，移动端仅做只读展示；通过 Open API 接入时，限流同样生效，返回码统一为 429 Too Many Requests，并在 Header 附带 X-RateLimit-Reset 时间戳，方便客户端退避。
操作路径：三端最短入口与可替代入口
桌面端（Win/Mac）
- 打开豆包→左下「管理后台」→「知识库」→「访问控制」→「单 IP 并发上限」。
- 若左侧无「管理后台」，说明账号无超级管理员权限，需让创建者在「权限→角色」里打开「知识库管理员」开关。
Web 端
- 直接访问
doubao.cn/admin→登录→「知识库」→「访问控制」→「单 IP 并发上限」。 - 若域名被企业内网 DNS 改写，可在「设置→实验室→备用管理域名」手动指定。
移动端（iOS/Android）
- App→「我的」→「管理后台（仅查看）」→「知识库」→「访问控制」。移动端只能查看实时 QPH 曲线，修改仍需跳 Web 或桌面端。
阈值计算：如何得出「既不被刷也不卡业务」的数字
官方未给统一公式，后台提供「近 7 天峰值 QPS」折线图。经验性做法：取最高峰 QPS×120 %×3600 秒，再除以预估独立 IP 数，得到「平均 IP 峰值 QPH」。示例：高峰 QPS=5，独立 IP≈200，则 QPH≈5×1.2×3600/200≈108，可向上取整到 120。
提示：若知识库被集成到飞书多维表格的「智能列」，每打开一次表格会并发拉取 3~5 条摘要，计算时要把「飞书共享 IP 出口」数量折算进去，否则易误触限流。
设置完成后，后台会给出「预计拦截率」模拟条，仅作参考；真实拦截率受重试策略、CDN 节点分布影响，需结合日志验证。
回退与热更：改错数字如何秒级恢复
QPH 规则采用「热更新」机制，保存后约 10~30 秒全局生效，无需重启 Pod。若发现业务用户被大面积拦截，可立即把滑块拉到 0（关闭限流），系统实时放行，但已返回 429 的请求不会重放，需客户端自行重试。
建议首次上线先把「超限后行为」设为「仅记录日志」观察 24 小时，确认阈值合理后再切「拒绝请求」。即使数值估错，也不会直接断开用户。
例外与绕行：白名单、机器人与插件
IP 白名单
在「访问控制」同页下方可输入 CIDR 格式白名单，白名单 IP 不受 QPH 限制，但仍受「总并发」约束，适合放企业出口、监控探针、第三方归档机器人。
插件集市里的高频插件
如「Notion 一键导入」插件在拉取大文档时会连续调用 /knowledge/append 接口，经验性观察：每篇 3 000 字符笔记约产生 4 次请求。若团队一次性导入 500 篇，最好临时把插件服务器 IP 加入白名单，或将任务拆成 ≤100 篇的批次，并在脚本里加指数退避。
故障排查：出现 429 但后台没超标时的四条检查法
- 确认是否「共享出口」：很多公司飞书与知识库共用 NAT，查看 Header 里的
X-Real-IP是否与员工本地 IP 一致。 - 检查「插件加速节点」：若开启「字节边缘节点」，部分插件流量会走另一出口，导致 IP 识别漂移。
- 核对「统计粒度」：后台默认按 IP+UserAgent 聚合，若客户端未固定 UA，同一 IP 会被拆成多条，看似未超，实际已超。
- 观察「时钟偏差」：限流按 GMT+8 整点滑动，若服务器本地时间偏差>30 秒，可能出现「提前被限」或「延迟放行」。
适用/不适用场景清单
| 场景 | 建议 QPH | 备注 |
|---|---|---|
| 10 人内测小队 | 600 | 几乎无影响，可不开 |
| 公开课直播，观众 2000 | 80 | 配合 PPT 同步推送，需预演 |
| 飞书多维表格+智能列 | 150 | 把共享出口 IP 加入白名单 |
| 第三方归档机器人 | 0（白名单） | 机器人 UA 固定，可单独放行 |
| 内部压测 | 临时关闭 | 压测完立即恢复，避免遗忘 |
最佳实践：决策检查表（可直接打印）
2. 首次上线选「仅记录日志」→24 h 后看拦截曲线
3. 确认白名单已放企业出口、监控、插件机
4. 移动端通知值班群：出现 429 先截图 Header
5. 每季度回顾一次，峰值翻倍时提前调阈值
6. 任何临时关闭操作，必须设日历提醒当天恢复
验证与观测：三条可复现的命令
以下示例假设知识库域名是 knowledge.example.com，且具备 curl 与 jq 环境。请把 your_ip 换成真实出口 IP，your_token 在「设置→API 密钥」里生成。
- 看实时 QPH 余量：
curl -H "Authorization: Bearer your_token" https://knowledge.example.com/api/v1/rate-limit/your_ip | jq .remaining，返回数字即剩余次数。 - 模拟超限：
for i in {1..200}; do curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer your_token" https://knowledge.example.com/api/v1/search?q=test; done | sort | uniq -c，观察何时出现 429。 - 检查 Header 时间戳：
curl -I -H "Authorization: Bearer your_token" https://knowledge.example.com/api/v1/search，找到X-RateLimit-Reset，与本地时间对比，偏差>30 s 需校准 NTP。
FAQ：三条最高频疑问（FAQPage Schema）
单 IP 并发上限与「总并发」冲突吗？
不冲突。总并发是全局硬顶，QPH 是单 IP 频率限制。即使 QPH 放行，若总并发已满，请求仍会被拒，返回 503。
为什么我把 QPH 调到 300 还是出现 429？
大概率是「共享出口」或「插件加速节点」导致 IP 识别漂移。先查 Header 里的 X-Real-IP，再把实际出口 IP 加入白名单即可验证。
限流规则多久生效？需要重启吗？
规则热更新，10~30 秒全局生效，无需重启任何 Pod。若 30 秒后仍见 429，请检查是否缓存了旧 DNS 或本地时钟偏差。
收尾：核心结论与下一步行动
单 IP 并发上限不是「越低越安全」，而是「越准越流畅」。先用后台给出的 7 天峰值算出合理 QPH，再白名单掉可信出口，最后把「超限行为」切成「日志→拒绝」两段式上线，就能把知识库接口保护在「可预测」的延迟区间。
下一步：把检查表贴进团队 Wiki，设季度提醒；若计划接入「插件集市」或「飞书妙记转导图」，提前把插件机 IP 与共享出口一次性纳入白名单，避免上线当天被自己的流量误杀。