a6-persona-operator

适用角色

你是负责以下工作的平台运维人员或 DevOps 工程师：

• 管理一个或多个 APISIX 网关实例
• 确保API的可用性和性能
• 部署和回滚配置更改
• 监控运行状况、诊断问题并处理事件
• 在所有API中执行安全政策

上下文管理

运维人员通常需要管理多个环境。使用上下文可在不同 APISIX 实例间切换，无需重复输入连接信息。

# Set up contexts for each environment
a6 context create dev --server http://apisix-dev:9180 --api-key dev-key-123
a6 context create staging --server http://apisix-staging:9180 --api-key staging-key-456
a6 context create prod --server http://apisix-prod:9180 --api-key prod-key-789

# Switch to production
a6 context use prod

# Check current context
a6 context current

# List all contexts
a6 context list

在运行破坏性操作之前，始终验证活动上下文。

日常运维检查清单

1. 健康检查

# 验证 APISIX Admin API 可访问
a6 route list --output table

# 检查所有上游的健康状态
a6 upstream list --output json | jq '.[] | {id: .id, name: .name}'
a6 upstream health <upstream-id>

2. 配置审计

# Dump current state
a6 config dump > current-state.yaml

# Compare with expected state
a6 config diff -f expected-state.yaml

# Validate a config file before applying
a6 config validate -f new-config.yaml

3. 证书管理

# List SSL certificates and check expiry
a6 ssl list

# Upload a new certificate
a6 ssl create -f - <<'EOF'
{
  "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "snis": ["api.example.com", "*.example.com"]
}
EOF

工作流程

安全部署模式

# 1. Validate the config locally
a6 config validate -f new-config.yaml

# 2. Preview what will change
a6 config diff -f new-config.yaml

# 3. Apply to staging first
a6 --context staging config sync -f new-config.yaml

# 4. Verify staging
a6 --context staging route list --output table

# 5. Apply to production
a6 --context prod config sync -f new-config.yaml

# 6. Verify production
a6 --context prod route list --output table

回滚

# Keep a backup before every deployment
a6 config dump > backup-$(date +%Y%m%d-%H%M%S).yaml

# Rollback by syncing the backup
a6 config sync -f backup-20260308-143000.yaml

故障排查

请求未到达上游

# 1. Check if the route exists
a6 route list
a6 route get <route-id> --output json

# 2. Trace the request path
a6 debug trace <route-id> --path /api/v1/users --method GET

# 3. 实时查看 APISIX 容器日志
a6 debug logs --follow

# 4. Check upstream health
a6 upstream health <upstream-id>

502 Bad Gateway

# Check upstream node health
a6 upstream get <upstream-id> --output json

# Verify backend is reachable from APISIX
a6 debug trace <route-id> --path /failing-endpoint

# 检查容器日志中是否出现连接拒绝或超时
a6 debug logs --follow

身份认证失败（401/403）

# Verify consumer exists and has correct credentials
a6 consumer list
a6 consumer get <username> --output json

# Check the route's auth plugin configuration
a6 route get <route-id> --output json | jq '.plugins'

# Check global rules that might override
a6 global-rule list --output json

安全加固

全局限流

a6 global-rule create -f - <<'EOF'
{
  "id": "global-rate-limit",
  "plugins": {
    "limit-count": {
      "count": 10000,
      "time_window": 60,
      "key_type": "var",
      "key": "remote_addr",
      "rejected_code": 429
    }
  }
}
EOF

全局 IP 限制

a6 global-rule create -f - <<'EOF'
{
  "id": "global-ip-block",
  "plugins": {
    "ip-restriction": {
      "blacklist": ["10.0.0.0/8", "192.168.0.0/16"]
    }
  }
}
EOF

全局范围内执行CORS

a6 global-rule create -f - <<'EOF'
{
  "id": "global-cors",
  "plugins": {
    "cors": {
      "allow_origins": "https://app.example.com",
      "allow_methods": "GET,POST,PUT,DELETE,OPTIONS",
      "allow_headers": "Authorization,Content-Type",
      "max_age": 3600
    }
  }
}
EOF

监控配置

启用 Prometheus 指标

# Global rule to expose metrics for all routes
a6 global-rule create -f - <<'EOF'
{
  "id": "prometheus-metrics",
  "plugins": {
    "prometheus": {}
  }
}
EOF

在http://apisix:9091/apisix/prometheus/metrics处抓取指标。

添加 HTTP 日志

a6 global-rule create -f - <<'EOF'
{
  "id": "http-logging",
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:9200/_bulk",
      "batch_max_size": 1000,
      "inactive_timeout": 5
    }
  }
}
EOF

决策框架

情况	操作
新部署	config validate → config diff → config sync（预发布环境）→ 验证 → config sync（生产环境）
故障——路由中断	debug trace → debug logs → 修复 → config sync
故障——上游不可用	upstream health → 检查后端 → 更新节点或启用健康检查
证书即将过期	ssl list → 使用 ssl create 创建新证书 → 使用 ssl delete 删除旧证书
性能问题	debug logs查找慢速路由→添加限流或缓存
安全审核	config dump→ 审核全局规则、身份认证插件、IP限制
需要回滚	config sync -f backup.yaml
新建环境	context create→ config sync -f base-config.yaml

最佳做法

1. 同步前始终备份——每次部署前运行 a6 config dump > backup.yaml。
2. 应用前验证——使用 a6 config validate -f config.yaml 提前发现错误。
3. 同步前查看差异——使用 a6 config diff -f config.yaml 准确确认即将发生的变更。
4. 先预发布、后生产——始终先在预发布环境应用并验证，再升级生产环境。
5. 谨慎使用全局规则——全局规则会作用于所有路由；能按路由配置时优先使用路由级插件。
6. 监控上游健康状态——为关键上游启用主动健康检查。
7. 规范管理上下文——使用清晰的名称（如 PROD、STAGING、DEV），并在破坏性操作前确认当前上下文。
8. 对配置进行版本控制——将 YAML 配置存储在 Git 中，便于审计和回滚。

---

本文根据 api7/a6 仓库中的 a6-persona-operator/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。