请求协助：APISIX服务器Python插件开发、使用及报错排查

基础环境校验 #

• 确认Python版本≥3.7，执行python --version查看结果，低于3.7直接升级版本
• 检查apisix-runner-python依赖是否安装：执行pip list | grep apisix-runner-python，未安装则运行pip install apisix-runner-python
• 核对APISIX的config.yaml配置，确保插件运行器已启用：

  plugin_runner:
    enabled: true
    plugins:
      - 你的插件名称
    python:
      path: /usr/local/lib/python3.x/site-packages/apisix/runner/runner.py
  

  注意path需指向实际的runner脚本路径，且APISIX进程拥有该路径的读写权限

插件代码规范检查 #

• 插件类必须继承apisix.runner.plugin.Plugin，且实现三个核心方法：

  from apisix.runner.plugin import Plugin
  from apisix.runner.http.request import Request
  from apisix.runner.http.response import Response
  
  class YourPlugin(Plugin):
      def name(self) -> str:
          return "your-plugin"  # 需和配置中的插件名称完全一致
  
      def configure(self, conf: dict):
          # 插件配置初始化逻辑，比如读取配置参数
          pass
  
      def filter(self, request: Request, response: Response):
          # 核心业务逻辑，比如修改响应头、处理请求参数
          response.headers["X-Custom-Header"] = "Python Plugin Works"
  

• 插件目录下的__init__.py需正确注册插件：

  from .your_plugin import YourPlugin
  
  __all__ = ["YourPlugin"]
  

常见报错修复 #

若启动APISIX或调用路由时报错，按以下步骤排查：

1. 查看APISIX错误日志：logs/error.log中会包含具体报错信息，比如依赖缺失、权限不足、插件路径错误
2. 手动运行runner脚本：直接执行python /path/to/runner.py，观察是否有报错输出，可快速定位环境类问题
3. 检查插件目录权限：确保APISIX进程能读取插件所在目录的所有文件

验证流程 #

1. 重启APISIX服务：apisix restart
2. 通过Admin API将插件绑定到路由：

   curl http://127.0.0.1:9180/apisix/admin/routes/1 \
   -H "X-API-KEY: 你的Admin API密钥" \
   -X PUT -d '
   {
       "uri": "/test",
       "plugins": {
           "your-plugin": {}
       },
       "upstream": {
           "type": "roundrobin",
           "nodes": {
               "httpbin.org:80": 1
           }
       }
   }'
   

3. 测试路由：执行curl http://127.0.0.1:9080/test，检查响应是否符合插件预期逻辑

内容的提问来源于stack exchange，提问作者STTL User