本页提供 运维角色场景的 API7 企业版操作指南。

API7 网关 AI Agent Skill：运维角色

适用对象

你是企业平台运维人员或 DevOps 工程师，负责：

• 编排跨环境、跨区域的多个网关组。
• 管理企业 RBAC 和 API Token，确保控制面安全访问。
• 确保 API7 企业版基础设施达到 99.99% 可用性。
• 实现零停机配置发布和回滚。
• 通过跨网关组的全局规则和企业插件强化安全性。

核心企业版概念

在 API7 企业版中，运维模型会从管理单实例转向管理多租户平台：

1. 网关组：隔离和部署的主要单元。
2. 控制面（控制台）：集中管理入口，默认使用 7443 HTTPS 端口。
3. 数据面（网关）：执行配置的分布式实例。
4. API Token：所有 CLI 操作都需要使用（--token）。

上下文与网关组管理

运维人员会管理多个网关组。请使用 a7 context 和 -g 标志保持操作范围清晰。

# 配置企业版控制台访问权限
a7 context create prod-ee \
  --server https://dashboard.enterprise.com:7443 \
  --token <your-long-lived-api-token>

# 切换上下文
a7 context use prod-ee

# 列出可用的网关组
a7 gateway-group list

日常运维检查清单

1. 平台健康状态与连通性

# 检查控制台和 CLI 是否已连接
a7 gateway-group list

# 验证指定网关组的状态
a7 gateway-group get internal-apps

# 查看网关组中已部署的服务和路由
a7 service list -g internal-apps
a7 route list -g internal-apps

2. 配置审计与漂移检测

# 备份指定网关组的状态
a7 config dump -g finance-dept > finance-backup-$(date +%F).yaml

# 检测本地事实来源与控制台之间的配置漂移
a7 config diff -g finance-dept -f finance-infra.yaml

# 同步前校验企业版插件配置
a7 config validate -g finance-dept -f updated-config.yaml

3. 企业版安全与 SSL

# 列出网关组中的 SSL 证书
a7 ssl list -g public-gateway

# 向网关组添加新的 SSL 证书
a7 ssl create -g public-gateway -f - <<'EOF'
{
  "cert": "...",
  "key": "...",
  "snis": ["api.acme.com"]
}
EOF

高级部署工作流

零停机发布

# 1. 在开发网关组中校验
a7 config sync -g dev-group -f infra-v2.yaml

# 2. 预览生产网关组的变更
a7 config diff -g prod-group -f infra-v2.yaml

# 3. 将变更应用到生产环境并保留完整审计记录
a7 config sync -g prod-group -f infra-v2.yaml

# 4. 验证生产环境中的流量
a7 debug trace -g prod-group --uri /v1/status

紧急回滚

# 找到最近一次可用的备份
ls *-backup-*.yaml

# 立即恢复网关组状态
a7 config sync -g prod-group -f last-good-backup.yaml

故障排查与事件响应

分析失败请求

# 1. 追踪经过指定网关组的请求
a7 debug trace -g customer-facing --uri /api/v1/checkout --method POST

# 2. 跟踪网关组的实时错误日志
a7 debug logs -g customer-facing --follow --level error

# 3. 检查配置错误的全局规则
a7 global-rule list -g customer-facing --output json

识别性能瓶颈

# 检查追踪中插件的执行时间
a7 debug trace -g api-internal --uri /heavy-endpoint --verbose

# 列出活动路由及其命中次数（如果已启用指标）
a7 route list -g api-internal --output wide

安全加固（企业级）

全局 IP 限制（网关组范围）

a7 global-rule create -g sensitive-apps -f - <<'EOF'
{
  "plugins": {
    "ip-restriction": {
      "whitelist": ["10.0.0.0/16", "172.16.0.0/12"]
    }
  }
}
EOF

强制执行企业认证

# 应用全局规则，为网关组中的所有路由强制启用 OpenID Connect
a7 global-rule create -g public-facing -f - <<'EOF'
{
  "plugins": {
    "openid-connect": {
      "client_id": "...",
      "client_secret": "...",
      "discovery": "https://idp.example.com/.well-known/openid-configuration"
    }
  }
}
EOF

运维人员决策框架

场景	操作	命令
新团队接入	创建网关组并分配 RBAC	a7 gateway-group create <name>
配置漂移	比较本地 YAML 与线上配置	a7 config diff -g <group> -f <file>
后端超时	检查路由/服务配置和日志	a7 route get <id> -g <group> 和 a7 debug logs
安全事件	通过全局规则封禁 IP	a7 global-rule create -g <group> -f block.json
合规审计	导出全部配置以供审查	a7 config dump -g <group>
版本升级	先校验再同步	先执行 a7 config validate，再执行 a7 config sync

运维最佳实践

1. 网关组隔离：不要在同一网关组中混用开发和生产资源。
2. Token 安全：像保护 root 密码一样保护 API7 企业版 Token。CI/CD 中请使用短期 Token。
3. 始终使用 -g：明确指定网关组，避免误改错误环境。
4. 审计日志：定期查看控制台审计日志，检查 CLI 发起的变更。
5. 仅使用 HTTPS：控制面始终使用 HTTPS 端口（7443）。
6. 配置即代码：将所有网关组配置存储在 Git 中，并将控制台视为仓库状态的投影。
7. 后端健康状态：通过服务/路由上游配置和网关可观测性管理后端健康状态。
8. 上下文感知：为上下文使用描述性名称，例如 hk-region-prod、us-west-staging，避免多区域环境中混淆。

---

本页面由 api7/a7 仓库中的 a7-persona-operator/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。