Apache APISIX 中 ext-plugin 配置错误的排查与解决方案

Apache APISIX 作为云原生 API 网关，其插件系统是其核心功能之一。在使用外部插件（ext-plugin）时，开发者可能会遇到一些配置问题。本文将详细分析一个典型的配置错误案例，帮助开发者理解正确的配置方式。

问题现象

当开发者尝试通过 Docker 容器运行 APISIX 并配置外部插件时，访问网关端点会出现连接 Unix socket 失败的错误。具体错误信息显示无法找到 /usr/local/apisix/conf/apisix-1.sock 文件。

错误分析

通过分析问题描述，我们可以发现几个关键点：

1. 开发者将 ext-plugin 配置错误地放在了 apisix.yaml 文件中
2. 容器环境中确实缺少了应有的 socket 文件
3. 环境变量配置看似正确但未生效

根本原因

APISIX 的配置体系有明确的层级结构：

• config.yaml：包含系统级配置，如部署模式、管理员密钥等
• apisix.yaml：包含路由、上游等业务配置

ext-plugin 属于系统级配置，必须放在 config.yaml 中才能被正确加载。放在 apisix.yaml 中会导致插件运行器无法正常启动，进而无法创建所需的 Unix socket 文件。

正确配置方法

config.yaml 配置

deployment:
  role: data_plane
  role_data_plane:
    config_provider: yaml
  admin:
    admin_key:
      - name: admin
        key: edd1c9f034335f136f87ad84b625c8f1
        role: admin
ext-plugin:
  cmd: ["/usr/local/apisix-go-plugin-runner/go-runner", "run"]

apisix.yaml 配置

routes:
  - uri: /
    plugin_config_id: 1
    upstream:
      nodes:
        "upstream-nlb-9780037035286027.elb.ap-northeast-2.amazonaws.com": 1
      type: roundrobin

plugin_configs:  
  - id: 1
    plugins:
      ext-plugin-pre-req:
        name: ext-plugin-pre-req
        config:
          name: "say"
          value:
            body: "Hello, APISIX!"

Docker 构建最佳实践

在 Docker 环境中部署时，需要注意以下几点：

1. 确保两个配置文件都正确复制到容器中
2. 插件运行器需要有可执行权限
3. 推荐使用多阶段构建来减小最终镜像体积

示例 Dockerfile：

FROM golang:1.22.5 AS plugin-builder
WORKDIR /builder
COPY apisix-go-plugin-runner/. .
RUN go env -w GOPROXY='https://goproxy.cn,direct'
RUN go env -w GOFLAGS=-buildvcs=false
RUN CGO_ENABLED=0 make build

FROM apache/apisix:3.9.1-debian
ENV APISIX_STAND_ALONE=true
EXPOSE 9080 9180 9091 9443 9092
COPY apisix.yaml /usr/local/apisix/conf/apisix.yaml
COPY config.yaml /usr/local/apisix/conf/config.yaml
COPY --from=plugin-builder /builder/go-runner /usr/local/apisix-go-plugin-runner/go-runner

验证方法

部署完成后，可以通过以下命令验证服务是否正常运行：

curl -I localhost:9080

预期应该能看到 APISIX 的正常响应头，而不再出现 socket 连接错误。

总结

正确理解 APISIX 的配置文件层级对于成功部署至关重要。系统级配置必须放在 config.yaml 中，而业务配置则放在 apisix.yaml 中。通过本文的分析和正确配置示例，开发者可以避免类似的配置错误，确保外部插件能够正常工作。

对于初学者来说，建议在开发环境中先验证配置，再部署到生产环境。同时，APISIX 的日志系统会提供详细的错误信息，遇到问题时应该首先检查日志输出。