---

slug: gateway-manager
name: gateway-manager
version: 1.0.1
displayName: "API网关管理器(专业版)"
summary: "企业级API网关平台，含多租户、熔断、灰度、动态配置、可观测性与插件体系。API网关管理器专业版是面向企业的全功能API网关平台。在免费版的声明式路由、统一认证、基础限流、监控指标基础上，"
summary_zh: '"企业级API网关平台，含多租户、熔断、灰度、动态配置、可观测性与插件体系。API网关管理器专业版是面向企业的全功能API网关平台。在免费版的声明式路由、统一认证、基础限流、监控指标基础上，"'
license: "MIT"
edition: '"pro"'
description: "|-。企业级API网关平台，含多租户、熔断、灰度、动态配置、可观测性与插件体系。API网关管理器专业版是面向企业的全功能API网关平台。在免费版的声明式路由、统一认证、基础限流、监控指标基础上，。支持自动化配置和灵活的参数设置，适适用于不同工作场景，改善操作效率。Use when 需要提升效率、自动化流程、批量处理、工作流优化时使用。不适用于需要人工创意判断的任务。 功能涵盖: gateway, manager。
  |- 功能涵盖: gateway,。Use when 用户需要gateway-manager相关功能时使用。不适用于超出本技能能力范围的复杂需求。适用于开发者、企业团队和自动化集成场景。支持中文交互，无需复杂配置即开即用。提供结构化输出和错误处理机制。
  API网关管理器专...'
tags:
- API网关
- 流量治理
- 熔断降级
- 灰度发布
- 可观测性
- 工具
- 效率
- 写作
- gateway-manager
- 动态配置
- 解决痛点
- 专业版能
- yaml
tools:
- read
- exec
- write
homepage: '""'
category: '"Automation"'

---

> **核心功能**: 本技能提供自动化配置和灵活的参数设置、时使用、、工作流优化时使用、处理、工作流优化时使用等能力。
> **核心功能**: 本技能提供中文交互、化工作流场景等能力。
# API网关管理器(专业版)
## 专业版专属特性
| 能力 | 免费版 | 付费版 |
|---|---|---|
| 基础功能 | 支持 | 支持 |
| API网关管理器(专业版)动态配置 | 不支持 | 支持 |
| 大数据集流式处理 | 不支持 | 支持 |
| 多数据源关联查询 | 不支持 | 支持 |
| 可视化图表自动生成 | 不支持 | 支持 |
| 定时数据同步与增量更新 | 不支持 | 支持 |
## 能力清单
### 功能1：多租户差异化限流
**解决痛点**：SaaS场景下，付费租户和免费租户共享同一网关，限流值不能一刀切.
**专业版能力**：按租户等级配不同限流规则，支持租户级配额管理.
> 详细代码示例已移至 `references/detail.md`
### 功能2：熔断与降级
**解决痛点**：上游服务挂了，网关还在转发请求，导致雪崩.
**专业版能力**：基于错误率/延迟的熔断器，支持半开探测恢复与降级响应.
**熔断状态机**：
```text
CLOSED（正常）
  │ 错误率≥50% (60s窗口)
  ▼
OPEN（熔断，直接返回降级响应）
  │ 30秒后
  ▼
HALF_OPEN（半开，放5个探测请求）
  │ 探测成功≥4个 → CLOSED
  │ 探测失败≥2个 → OPEN
```
### 功能3：灰度发布与AB测试
**解决痛点**：新版本上线全量发布，出问题影响所有用户.
**专业版能力**：支持按比例、按Header、按用户灰度，支持AB测试流量分发.
### 功能4：动态配置下发
**解决痛点**：改个路由要重启网关，影响线上流量.
**专业版能力**：配置热更新，不重启网关，支持版本回滚.
```bash
gateway-manager dynamic apply --config gateway-pro.yaml --validate
# ...
gateway-manager dynamic versions
gateway-manager dynamic rollback --to v1.1.9
# ...
gateway-manager dynamic diff v1.1.9 v1.2.0
```
**动态配置保证**：
- 配置变更前自动validate，语法错不应用
- 配置版本化，支持一键回滚
- 灰度推送：先推一个网关节点，观察5分钟无异常再全量
- 配置变更审计：谁、何时、改了什么
### 功能5：分布式限流
**解决痛点**：多网关实例时，单机限流形同虚设（4实例×100QPS=实际400QPS）.
**专业版能力**：基于Redis集群的分布式限流，多实例共享计数器.
```yaml
rate_limit:
  type: distributed_sliding_window
  qps: 1000  # 全局1000 QPS，所有实例共享
  redis:
    url_env: REDIS_URL
    cluster: true
    key_prefix: gateway:ratelimit:
    ttl: 120s
  local_buffer: 50  # 本地预扣50，减少Redis访问
  sync_interval: 100ms  # 每100ms同步一次
```
> 详细内容已移至 `references/detail.md` -
### 功能6：可观测性套件
### 功能7：插件体系
**解决痛点**：标准认证/限流不满足，需要自定义逻辑，但改网关源码太重.
**专业版能力**：插件SDK，支持自定义认证、日志、转换、限流插件.
```yaml
routes:
  - name: sensitive-api
    path: /api/v1/payments/*
    upstream: http://payment-service:8001
    plugins:
      - name: audit_log
        config:
          audit_url: http://audit-service:9000/log
          sensitive_fields: [card_number, cvv]
```
### 功能8：配置dry-run
**解决痛点**：网关配置改了，上线怕出事，不上线又没法验证.
**专业版能力**：用录制的真实流量回放，验证新配置影响.
## 快速入门教程
1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理
> 详细的输入输出格式请参考下方章节说明。
## 操作流程
### 基础搭建（<60秒）：继承免费版能力
专业版完全兼容免费版的所有配置与生成能力。首次使用时，直接对Agent说：
Agent会按免费版的规则生成声明式YAML与多网关配置，并额外提示：是否要启用熔断、灰度等高级能力？
### 标准搭建（<120秒）：启用熔断与灰度
### 完整搭建（<300秒）：启用可观测性与动态配置
```bash
gateway-manager dynamic init --control-plane http://gateway-cp:9000
# ...
# ...
gateway-manager observe enable --tracing --exporter otlp --endpoint http://otel-collector:4317
# ...
gateway-manager observe enable --logging --exporter loki --endpoint http://loki:3100
# ...
gateway-manager observe enable --alerting --rules ./alert-rules.yaml
# ...
gateway-manager dry-run --config gateway-pro.yaml --traffic replay --recording ./traffic-sample.json
```
## 请求格式
| 参数名 | 类型 | 必填 | 说明 |
|:-----|:-----|:-----|:-----|
| content | string | 否 | gateway-manager处理的内容输入 |, 默认: 全部维度 |
| strict_level | string | 否 | 审查严格度, 可选: strict/normal/loose, 默认: normal |
## 结果格式
```json
{
  "success": true,
  "data": {
    "overall_grade": "A",
    "total_score": 92,
    "max_score": 100,
    "summary": "处理完成",
    "details": [
      {
        "item": "代码风格",
        "status": "pass",
        "score": 95,
        "comment": "符合规范"
      },
      {
        "item": "安全合规",
        "status": "warn",
        "score": 80,
        "comment": "符合规范"
      }
    ],
    "improvements": [
      {
        "priority": "high",
        "suggestion": "建议优化",
        "expected_gain": "+5分"
      },
      {
        "priority": "medium",
        "suggestion": "建议优化",
        "expected_gain": "+3分"
      }
    ]
  },
  "error": null
}
```
## 异常管理
| 问题 | 可能原因 | 解决方案 | 优先级 |
|---:|---:|---:|---:|
| 分布式限流不准确 | Redis延迟或本地buffer过大 | 减小local_buffer，缩短sync_interval | 高 |
| 熔断器频繁误触发 | 阈值过低或窗口太小 | 调高threshold，增大window | 中 |
| 灰度分流不均 | hash算法或key选择不当 | 检查key配置，用一致性hash | 中 |
| 动态配置不生效 | 控制面连接异常或版本不一致 | 检查控制面连通性，强制reconcile | 高 |
| 链路追踪断链 | 采样率过低或传播头丢失 | 提高采样率，检查W3C传播配置 | 中 |
| 告警风暴 | 规则过敏感或未分组 | 调整规则阈值，启用告警分组 | 高 |
| 插件执行慢 | 插件逻辑重或同步阻塞 | 改异步执行，精简插件逻辑 | 中 |
| dry-run结果不准 | 流量样本不具代表性 | 延长录制时间，提高采样率 | 低 |
| 网关配置冲突 | 多人同时改同一配置 | 用PR评审流程，配置锁机制 | 高 |
| 熔断后不恢复 | 半开探测失败率仍高 | 检查上游服务健康，延长open_duration | 高 |
## 安全实践准则
| 风险类型 | 防范措施 |
|----------|---------|
| API密钥泄露 | 通过环境变量配置，禁止硬编码到代码或配置文件中 |
| 命令执行风险 | 仅执行白名单命令，避免拼接用户输入到命令行参数中 |
| 网络通信安全 | 使用HTTPS协议，验证SSL证书有效性 |
| 敏感数据暴露 | 输出结果中不包含密钥、令牌等敏感信息 |
使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。
## 安装与配置
### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux
- **Node.js**: 18+（用于CLI工具）
- **目标网关**: Kong / APISIX / Nginx / Envoy（任选其一或多个）
### 依赖说明(补充)
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:---:|:---:|:---:|:---:|
| LLM API | API | 必需 | 由Agent平台内置LLM提供（专业版路由GPT-4o） |
| Node.js 18+ | 运行时 | 必需 | 从nodejs.org安装 |
| Redis集群 | 数据库 | 分布式限流必需 | 从redis.io安装 |
| OpenTelemetry Collector | 监控 | 链路追踪必需 | 从opentelemetry.io安装 |
| Prometheus | 监控 | 指标采集推荐 | 从prometheus.io安装 |
| Loki | 日志 | 日志聚合可选 | 从grafana.com安装 |
### API Key 配置
- 控制面需配置管理Token：`gateway-manager login`
- Redis连接串通过环境变量配置
- 所有Token与密钥禁止硬编码
- 建议存储在 `~/.gateway/credentials/` 目录（已gitignore）
- 生产环境建议用HashiCorp Vault或K8s Secret
### 可用性分类
- **分类**: MD+EXEC（）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent管理与治理API网关
## 案例展示
### 示例1: 基础用法
**输入**:
```json
{
  "content": "示例内容",
  "strict_level": "normal"
}
```
**输出**:
```
评级: B级(良好) - 总分: 85/100
# ...
检查详情:
- 代码风格: 通过(95分) - 检查通过
- 安全合规: 警告(75分) - 检查通过
- 无障碍性: 通过(85分) - 检查通过
# ...
改进建议:
1. [高优先级] 建议优化
2. [中优先级] 建议优化
```
### 示例2: 进阶用法
**输入**:
```json
{
  "content": "示例内容",
  "strict_level": "strict"
}
```
**输出**:
```
评级: C级(及格) - 总分: 70/100
# ...
检查详情:
- 代码风格: 通过(90分) - 检查通过
- 安全合规: 不通过(50分) - 检查通过
- 无障碍性: 警告(70分) - 检查通过
# ...
改进建议:
1. [高优先级] 建议优化
2. [高优先级] 建议优化
3. [低优先级] 建议优化
```
### 示例3: 边界情况 - 边界情况
**输入**:
```json
{
  "content": "示例内容"
}
```
**输出**:
```
评级: D级(不及格) - 总分: 45/100
# ...
检查详情:
- 代码风格: 不通过(40分) - 检查通过
- 安全合规: 不通过(30分) - 检查通过
- 无障碍性: 通过(65分) - 检查通过
# ...
改进建议:
1. [紧急] 建议优化
2. [高优先级] 建议优化
```
## 错误恢复流程
| 错误码 | 场景描述 | 可能原因 | 解决方案 |
|:-------|:---------|:---------|:---------|
| AUTH_FAIL | 身份验证失败 | Key未设置/已过期/格式错 | 确认环境变量,重新获取Key |
| RATE_LIMIT | 触发限流 | 请求频率超过阈值 | 降低频率,指数退避重试 |
| TIMEOUT | 请求超时 | 网络不稳定或服务端慢 | 增加超时阈值,检查网络 |
| INVALID_PARAM | 参数无效 | 缺失必填项或值超范围 | 检查参数表,修正后重试 |
| SERVER_ERROR | 服务端异常 | 平台内部故障 | 等待1-2分钟后重试 |
## 注意事项
- 需要API Key，无Key环境无法使用
## 创新优势
### 效率提升量化分析
| 操作场景 | 手动耗时 | 自动化耗时 | 效率提升 |
|----------|---------|-----------|---------|
| 数据解析与处理 | 5-10分钟 | <5秒 | 60-120x |
| 批量任务执行 | 因任务而异 | 线性缩减 | 5-50x |
| 错误排查与修复 | 10-30分钟 | <30秒 | 20-60x |
## 特色分析
| 对比维度 | API网关管理器(专业版) | 传统手动方式 | 通用脚本工具 |
|---------|------------|-------------|------------|
| 自动化程度 | 全流程自动 | 完全手动 | 部分自动 |
| 错误处理 | 内置错误恢复 | 依赖人工经验 | 基本try-catch |
| 可复用性 | 参数化配置 | 一次性脚本 | 模板化 |
| 安全合规 | 内置安全检查 | 无安全保障 | 无安全保障 |
| 适用场景 | 企业级API网关平台，含多租户、熔断、灰度、动态配置、可观测性与插件体系。API | 通用场景 | 通用场景 |
## 问答整理
### Q1: 如何在API网关管理器(专业版)中创建新的API？
A: 在API网关管理器(专业版)中，您可以通过以下步骤创建新的API：
1. 登录到API网关管理器。
2. 在左侧菜单中选择“API管理”。
3. 点击“创建API”按钮。
4. 输入API名称、描述和选择对应的API类型。
5. 配置API的请求和响应参数。
6. 设置API的安全策略和路由规则。
7. 完成配置后，点击“保存”按钮。
### Q2: 我如何在API网关管理器(专业版)中配置API的权限控制？
A: 在API网关管理器(专业版)中配置API权限控制的步骤如下：
1. 进入API管理页面，找到需要配置权限的API。
2. 点击API右侧的“设置”按钮。
3. 在“安全设置”部分，选择“权限控制”。
4. 选择合适的认证方式，如API密钥、OAuth等。
5. 配置权限规则，包括用户角色、IP白名单等。
6. 保存设置后，权限控制将应用于所选API。
### Q3: 如果API网关管理器(专业版)中的API访问量过高，应该如何处理？
A: 当API网关管理器(专业版)中的API访问量过高时，您可以采取以下措施：
1. 检查API性能监控，确定瓶颈所在。
2. 调整API配置，如增加并发限制、优化请求处理逻辑。
3. 如果需要，可以增加更多的API实例以分散负载。
4. 使用缓存策略，如本地缓存或分布式缓存，减少数据库访问。
5. 如果负载持续过高，考虑升级API网关管理器的硬件资源。
### Q4: 如何在API网关管理器(专业版)中监控API性能？
A: 在API网关管理器(专业版)中监控API性能的步骤如下：
1. 登录到API网关管理器。
2. 在左侧菜单中选择“监控”或“性能监控”。
3. 选择需要监控的API。
4. 查看实时监控数据和图表，包括响应时间、错误率、请求量等。
5. 可以设置告警规则，当性能指标超过阈值时，系统会自动发送通知。
### Q5: API网关管理器(专业版)支持哪些类型的API认证？
A: API网关管理器(专业版)支持多种类型的API认证，包括：
- API密钥认证
- OAuth 2.0认证
- 单点登录(SSO)认证
- IP白名单认证
- 基于角色的访问控制(RBAC)
您可以根据实际需求选择合适的认证方式。
## 帮助指南
### Q1: "API网关管理器(专业版)"支持哪些输入格式？
A1: "企业级API网关平台，含多租户、熔断、灰度、动态配置、可观测性与插件体系。API网关管理器专业版是面向企业的全功能API网关平台。在免费版的声明式路由、统一认。支持文本指令和结构化参数输入，具体格式参考使用流程章节。
### Q2: 需要配置API Key吗？
A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。
### Q3: 命令行执行失败怎么办？
A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。
## 错误恢复方案
针对"API网关管理器(专业版)"使用中可能遇到的常见问题,提供以下排查方案:
| 错误类型 | 原因分析 | 解决方案 |
|---------|---------|---------|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |
### "API网关管理器(专业版)"通用排查步骤
1. **检查输入参数**: 确认所有必填参数已提供且格式正确
2. **查看日志输出**: 定位具体错误行和异常类型
3. **验证环境配置**: 确认依赖库版本和运行环境满足要求
4. **逐步调试**: 缩小问题范围,隔离故障模块
## 异常修复
针对"API网关管理器(专业版)"使用中可能遇到的常见问题,提供以下排查方案:
| 错误类型 | 原因分析 | 解决方案 |
|---------|---------|---------|
| API认证失败(401) | API密钥错误或过期 | 检查密钥配置,重新生成token |
| 接口限流(429) | 请求频率超出限制 | 降低调用频率,启用重试退避策略 |
| 响应超时(504) | 网络延迟或服务端负载过高 | 增加超时阈值,检查网络连接 |
| 文件不存在 | 路径错误或文件未创建 | 检查路径拼写,确认文件已生成 |
| 文件格式不支持 | 扩展名不在支持列表中 | 转换为支持的格式后重试 |
| 权限不足 | 当前用户无读写权限 | 检查文件权限,以管理员身份运行 |
| 命令执行失败 | 参数错误或环境依赖缺失 | 检查命令语法,确认依赖已安装 |
| 进程超时 | 命令执行时间过长 | 增加超时设置,优化命令参数 |
| 网络连接失败 | DNS解析失败或防火墙拦截 | 检查网络配置,确认代理设置 |

## 问题汇总解答