跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：ext-plugin 插件

概览​

API7 企业版外部插件系统支持通过插件 Runner 进程运行 Go、Java、Python 或 JavaScript 编写的插件。API7 企业版使用 FlatBuffers 序列化，通过 Unix socket 与 Runner 通信。

三个插件用于控制外部插件的执行时机：

插件阶段优先级说明
ext-plugin-pre-reqrewrite12000在内置 Lua 插件之前
ext-plugin-post-reqaccess−3000在 Lua 插件之后、上游之前
ext-plugin-post-respbefore_proxy−4000在收到上游响应后

适用场景​

  • 使用 Go、Java 或 Python 而不是 Lua 实现自定义逻辑。
  • 复用非 Lua 代码库中的现有业务逻辑。
  • 应用前置处理（认证、校验）或后置处理（响应转换）。
  • 适用于偏好静态类型语言而非 Lua 的团队。

插件配置参考​

三个插件共享相同的 schema：

字段类型是否必填默认值说明
confarray否—要执行的外部插件列表
conf[].namestring是—插件标识符（1–128 个字符）
conf[].valuestring是—传递给插件的 JSON 字符串配置
allow_degradationboolean否false为 true 时，Runner 不可用时请求仍会继续

插件 Runner 架构​

┌─────────────┐    Unix Socket    ┌───────────────┐
│ API7 企业版 │ ◄──────────────► │ Plugin Runner  │
│ (Data Plane)│   FlatBuffers    │ (Go/Java/Py)   │
└─────────────┘                   └───────────────┘
  1. API7 企业版将 Runner 作为子进程启动（并管理其生命周期）。
  2. ext-plugin-* 触发时，API7 企业版通过 Unix socket 发送 RPC。
  3. Runner 执行外部插件并返回结果。
  4. API7 企业版将修改（请求头、请求体、状态码）应用到请求或响应。

RPC 协议​

  • PrepareConf：同步插件配置，并返回会缓存的 conf Token。
  • HTTPReqCall：每个请求使用序列化的 HTTP 数据和 conf Token 执行。
  • ExtraInfo：Runner 可以请求其他数据（变量、请求体、响应）。

支持的插件 Runner​

语言仓库状态
Goapache/apisix-go-plugin-runnerGA
Javaapache/apisix-java-plugin-runnerGA
Pythonapache/apisix-python-plugin-runner实验性
JavaScriptzenozeng/apisix-javascript-plugin-runner社区

API7 企业版配置​

生产环境配置​

API7 企业版将 Runner 作为子进程管理。该配置位于网关组配置中（通过控制台或 CLI 同步）。

ext-plugin:
  cmd: ["/path/to/runner-executable", "run"]

Runner 专用命令​

# Go runner
ext-plugin:
  cmd: ["/opt/api7-go-runner", "run"]

# Java runner
ext-plugin:
  cmd: ["java", "-jar", "-Xmx1g", "-Xms1g", "/opt/api7-runner.jar"]

# Python runner
ext-plugin:
  cmd: ["python3", "/opt/api7-python-runner/apisix/main.py", "start"]

开发环境配置（独立 Runner）​

对于本地开发，请单独运行 Runner：

# API7 企业版配置——不要设置 cmd
ext-plugin:
  path_for_test: "/tmp/runner.sock"
# 手动启动 Runner
API7_LISTEN_ADDRESS=unix:/tmp/runner.sock ./runner run

环境变量​

向 Runner 传递环境变量：

nginx_config:
  envs:
    - MY_ENV_VAR
    - DATABASE_URL

分步示例​

1. 单个外部插件​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "ext-auth",
  "uri": "/api/*",
  "plugins": {
    "ext-plugin-pre-req": {
      "conf": [
        {"name": "AuthFilter", "value": "{\"token_required\":true}"}
      ]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

2. 使用降级模式运行多个外部插件​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "ext-chain",
  "uri": "/api/*",
  "plugins": {
    "ext-plugin-pre-req": {
      "conf": [
        {"name": "AuthFilter", "value": "{\"token_required\":true}"},
        {"name": "RateLimiter", "value": "{\"requests_per_second\":100}"}
      ],
      "allow_degradation": true
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

3. 三类插件全部使用（完整请求生命周期）​

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "full-ext",
  "uri": "/api/*",
  "plugins": {
    "ext-plugin-pre-req": {
      "conf": [{"name": "auth-check", "value": "{}"}]
    },
    "ext-plugin-post-req": {
      "conf": [{"name": "request-transform", "value": "{}"}]
    },
    "ext-plugin-post-resp": {
      "conf": [{"name": "response-logger", "value": "{}"}]
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

**执行顺序：**pre-req →（Lua 插件）→ post-req →（上游）→ post-resp。

配置同步示例​

version: "1"
gateway_group: default
routes:
  - id: ext-plugin-demo
    uri: /api/*
    plugins:
      ext-plugin-pre-req:
        conf:
          - name: AuthFilter
            value: '{"token_required":true}'
        allow_degradation: true
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

兼容性矩阵​

特性ext-plugin-pre-reqext-plugin-post-reqext-plugin-post-resp
阶段rewriteaccessbefore_proxy
执行时机在 Lua 插件之前在 Lua 插件之后在上游响应之后
proxy-mirror✅✅❌
proxy-cache✅✅❌
proxy-control✅✅❌
mTLS 到 上游✅✅❌

**ext-plugin-post-resp 的限制：**它使用内部传输机制，因此与 proxy-mirror、proxy-cache、proxy-control 以及到上游的 mTLS 不兼容。

性能注意事项​

  • Unix socket + FlatBuffers：低延迟 IPC，无 TCP 开销。
  • Conf Token 缓存：每次配置变更只调用一次 PrepareConf，而不是每个请求调用一次。
  • 进程管理：API7 企业版在 reload 时先发送 SIGTERM，再发送 SIGKILL（宽限期为 1 秒）。
  • 降级模式：对非关键插件启用 allow_degradation: true。
  • 连接复用：Runner 应复用 socket 连接。

故障排查​

现象原因解决方法
failed to receive RPC_PREPARE_CONFRunner 未监听或 socket 路径不匹配验证配置中的 socket 路径是否与 API7_LISTEN_ADDRESS 匹配
503 Service UnavailableRunner 崩溃或未启动检查 Runner 日志，并确认 cmd 路径正确
Runner 未收到环境变量NGINX 默认隐藏环境变量将变量添加到网关组配置的 nginx_config.envs 中
响应缓慢外部插件执行了繁重工作分析 Runner 性能，并考虑异步处理
ext-plugin-post-resp 冲突与 proxy-* 插件不兼容改用 ext-plugin-post-req，或移除 proxy-mirror/cache

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