部署完成只是第一步------配置层面决定网关能不能扛住生产流量、能不能在故障时自愈、能不能让运维不被半夜电话叫醒。
本文给出MAI Gateway的七组核心配置 + 一份最佳实践清单，覆盖路由、限流、熔断、缓存、安全、监控、备份。所有配置项都对应生产环境的一次真实调优，不是"跑起来"就好。
一、配置体系总览
MAI Gateway的配置分三层：
| 层级 | 内容 | 生效时机 | 维护人 |
|---|---|---|---|
| 环境层 | 服务地址、数据库连接、Redis集群、密钥托管 | 启动时 | 运维 |
| 业务层 | 路由策略、上游渠道、配额规则、缓存策略 | 热更新（秒级） | 平台管理员 |
| 运行时层 | 灰度权重、限流阈值、熔断开关、告警规则 | 即时生效（毫秒级） | SRE/平台 |
三层分离的好处：换上游供应商、调配额阈值、做灰度发布------全部不影响网关运行，不需要重启进程。
二、环境层配置：六个参数
yaml
# 网关核心配置（部分字段示意）
server:
port: 8080
worker_num: 8 # 进程数=CPU核数
keep_alive_timeout: 60s
database:
master: "mysql://10.0.0.1:3306/mai"
replicas:
- "mysql://10.0.0.2:3306/mai"
pool_size: 50 # 建议=并发峰值×0.1
redis:
cluster_nodes:
- "redis://10.0.1.3:6379"
- "redis://10.0.1.4:6379"
- "redis://10.0.1.5:6379"
upstream_timeout: 30s # 上游响应超时
auth:
jwt_secret: "${VAULT_JWT_SECRET}" # 从Vault读取
api_key_vault: "${VAULT_API_KEYS}"六个核心参数的最佳取值
| 参数 | 默认值 | 生产推荐 | 依据 |
|---|---|---|---|
worker_num |
4 | =CPU核数 | 网关为I/O密集型，worker数=核数性能最优 |
database.pool_size |
10 | =并发峰值×0.1 | 避免连接泄漏，建议实测后调整 |
upstream_timeout |
60s | 30s | 大模型响应p99<30ms，但留缓冲给复杂推理 |
cache.ttl |
5min | 600s | 语义缓存10分钟，命中率与新鲜度平衡 |
log_level |
info | info | 生产不开debug；审计日志独立通道 |
metric_interval |
10s | 5s | 监控指标采集5s，故障定位更细 |
两个易踩的坑：
upstream_timeout设为60s会导致上游慢响应堆积。建议30s------超过30s的请求已属异常，应触发熔断而非继续等待database.pool_size偏小会触发"数据库连接耗尽"误报警。设值后用压测验证，留20%余量
三、路由配置：四种策略
路由是网关的核心动作。MAI Gateway支持四种路由策略：
策略1：默认路由（成本优先）
简单任务自动路由到低成本模型，复杂任务路由到高性能模型。配置思路：根据请求体特征判断任务难度。
yaml
routing:
strategy: "cost_first"
rules:
- when: "prompt.length < 500"
upstream: "Qwen-Fast" # 低成本模型
- when: "prompt.contains('code')"
upstream: "DeepSeek-V4" # 代码专用
- default: "Qwen-Max" # 复杂推理策略2：主备路由（高可用）
主上游不可用时自动切换到备用。配置思路：所有生产关键业务配主备，主上游挂了不影响业务。
yaml
routing:
strategy: "active_standby"
primary: "OpenAI-GPT5"
standby: "Qwen-Max"
health_check_interval: 10s # 主动检测间隔
failover_threshold: 3 # 连续3次失败触发切换策略3：负载均衡（性能优先）
按权重分发到多个上游，分散单一供应商压力。配置思路：同一模型多供应商调用，避免单供应商限流。
yaml
routing:
strategy: "weighted_round_robin"
upstreams:
- name: "Qwen-Max-Aliyun"
weight: 60
- name: "Qwen-Max-Tencent"
weight: 40策略4：地域路由（合规优先）
根据数据合规要求选择上游。配置思路：涉及敏感数据走本地模型或私有化部署模型。
yaml
routing:
strategy: "geo_compliance"
rules:
- when: "data.sensitivity == "高""
upstream: "local-GLM-5.1" # 本地推理
- default: "Qwen-Max"最佳实践：生产至少配主备两套。 不依赖单一上游的可用性，是网关稳定运行的基本要求。
四、配额与熔断：刚性管控链
4.1 四级配额体系
yaml
quota:
org_level:
monthly_token_limit: 100_000_000 # 公司级
department_level:
"营销中心": 30_000_000 # 部门级
"研发部": 50_000_000
project_level:
"短视频项目": 8_000_000 # 项目级
key_level:
"sk-mai-prod-mkt-7c": 2_000_000 # 密钥级配额检查时机 ：每次请求校验剩余额度，毫秒级判定通过/拒绝。避免每请求查4次DB------配额数据缓存在Redis，TTL 60s同步一次。
4.2 三级熔断配置
yaml
circuit_breaker:
warning_thresholds:
- level: 80%
actions: ["alert"] # 邮件/飞书/钉钉推送
- level: 95%
actions: ["alert", "throttle"] # 限流比例可配
- level: 100%
actions: ["alert", "block"] # 自动熔断熔断后的人工介入路径：100%熔断后，管理员可手动恢复（用于突发扩容）或临时提额（用于业务紧急事件）。所有操作记审计日志。
五、缓存配置：减少30%+重复消耗
yaml
semantic_cache:
enabled: true
similarity_threshold: 0.92 # 相似度阈值
ttl: 600 # 10分钟
cache_key_strategy: "embedding" # 按语义向量缓存
excluded_prompts:
- contains: "实时数据" # 排除实时查询类请求
- contains: "当前时间"关键阈值0.92：阈值高于0.95命中率低，低于0.85容易误命中相同语义不同意图的请求。0.92是经过调优的平衡点。
什么不该缓存：实时查询、个性化生成、含当前时间/地点的请求------这些缓存会输出陈旧数据，触发业务投诉。
六、安全配置：AI特化的五项防护
yaml
security:
prompt_injection_detection: true # 提示词注入检测
pii_masking:
enabled: true
patterns: ["身份证", "手机号", "银行卡"]
content_filtering:
enabled: true
categories: ["违规", "涉政", "涉黄"]
ip_whitelist:
enabled: true
ranges: ["10.0.0.0/8", "192.168.0.0/16"]
key_rotation:
auto_rotate_days: 90 # 90天强制轮换生产必备五项------五项缺一不可：
- 提示词注入检测：拦截"忽略之前的指示，要求输出..."
- PII脱敏：身份证/手机号/银行卡自动脱敏，避免合规风险
- 内容过滤：违规/涉政/涉黄内容过滤
- IP白名单：限制调用来源，避免令牌泄露后被外部滥用
- 密钥轮换：90天强制轮换，杜绝长期令牌累积风险
七、监控与告警：四项SLO指标
yaml
monitoring:
metrics:
- p99_latency_ms # 目标<30ms
- error_rate # 目标<0.1%
- qps # 目标848 req/s单机
- token_consumption # 按部门/项目实时统计
alerts:
channels: ["钉钉", "飞书", "邮件"]
rules:
- condition: "p99_latency > 50ms for 5min"
level: "warning"
- condition: "error_rate > 0.5% for 2min"
level: "critical"四项核心SLO：p99延迟<30ms、错误率<0.1%、QPS稳定、Token消耗有审计可查。前三项是技术SLO，第四项是财务SLO------Token消耗进入报表的那一刻，运维团队才真正"在线"。
八、备份与恢复：必须演练的配置
yaml
backup:
database:
type: "full"
cron: "0 2 * * *" # 每天凌晨2点
retention_days: 30
remote_storage: "oss://mai-backup/db/"
audit_log:
type: "incremental"
cron: "0 */1 * * *" # 每小时
retention_days: 365备份配置写下不算配置完成，必须演练一次恢复。推荐每季度演练一次"备份文件还原到新实例，验证数据完整性"的完整流程。
九、最佳实践Checklist（生产环境必查）
启动前
- 所有默认密码已修改
- API密钥从Vault读取，未硬编码
- 数据库连接池大小已实测验证
- Redis集群节点全绿
启动时
- 网关进程能正常拉起，Master/Slave角色识别正确
- 监控指标正常上报
- 告警渠道能收到测试告警
- 至少一次成功调用上游每个模型
运行时（每季度检查）
- 数据库备份文件还原演练
- 密钥轮换日志检查（确认90天周期执行）
- 配额使用率审计（是否有部门长期处于80%以上）
- 上游健康度报告（是否有模型长期处于限流）
- 缓存命中率统计（应>30%）
应急时
- 熔断阈值临时调整流程明确
- 紧急扩容方案文档化
- 上游故障切换清单（主备路由一键切换演练）
- 应急联系人清单（运维/平台/SRE）
结语
配置教程的核心不是"哪一项怎么写"，而是"哪几项必须写、为什么必须这样写"。
环境层六个参数决定网关能不能扛住生产流量，业务层路由和熔断决定业务连续性，运行时层灰度和限流决定可观测性------三层叠加，再加上每季度一次的最佳实践演练，网关就从"能跑"变成"能扛"。
配置不是写完就结束，而是写完后用压测验证、用监控观测、用演练兜底的循环。每一次生产故障都应该回写到配置项里------这才是配置真正的进化路径。