Apache APISIX中log-rotate插件导致其他插件失效的问题分析

问题背景

Apache APISIX作为一款高性能的API网关，其插件系统提供了丰富的功能扩展能力。近期有用户反馈在配置文件中启用log-rotate插件后，其他默认启用的插件会失效，需要手动在plugins下重新启用才能正常工作。本文将深入分析这一问题的成因及解决方案。

问题现象

当用户在APISIX的config.yaml配置文件中添加如下log-rotate插件配置后：

plugins:
    - log-rotate
plugin_attr:
    log-rotate:
        interval: 3600
        max_kept: 168
        max_size: -1
        enable_compression: false

系统会出现以下异常表现：

1. 其他默认启用的插件（如key-auth、openid-connect等）停止工作
2. 需要手动在plugins列表中显式声明所有需要使用的插件
3. 日志中会出现"unknown plugin"的错误提示

问题根源分析

经过深入代码分析，发现问题出在APISIX的插件加载机制上：

1. 配置加载优先级：APISIX会优先加载config.yaml中的配置，当该文件中定义了plugins字段时，系统会完全覆盖默认配置，不再加载config-default.yaml中的插件列表。

2. 插件白名单机制：APISIX采用白名单方式管理插件，只有在plugins列表中显式声明的插件才会被加载和启用。

3. log-rotate的特殊性：log-rotate是一个系统级插件，通常应该在config-default.yaml中配置，而不应该放在用户自定义的config.yaml中。

技术细节

在plugin.lua文件中，插件加载逻辑如下：

local function get_plugin_names(config)
    if not config then
        -- 加载默认配置
        local_conf = core.config.local_conf(true)
        http_plugin_names = local_conf.plugins
    else
        -- 加载用户自定义配置
        http_plugin_names = {}
        for _, conf in ipairs(config.value) do
            core.table.insert(http_plugin_names, conf.name)
        end
    end
    return http_plugin_names
end

当config.yaml中定义了plugins字段时，系统会进入else分支，只加载用户显式声明的插件，而忽略config-default.yaml中的默认插件列表。

解决方案

针对这一问题，我们有以下几种解决方案：

1. 推荐方案：将log-rotate配置移至config-default.yaml中

# config-default.yaml
plugins:
  - log-rotate
  - key-auth
  - openid-connect
  # 其他默认插件...
  
plugin_attr:
  log-rotate:
    interval: 86400
    max_kept: 30
    max_size: -1
    enable_compression: true

2. 兼容方案：在config.yaml中显式声明所有需要的插件

plugins:
  - log-rotate
  - key-auth
  - openid-connect
  # 其他需要使用的插件...

3. 容器化部署方案：对于Docker部署的环境，可以通过volume挂载方式覆盖默认配置

docker run -v /path/to/custom-config-default.yaml:/usr/local/apisix/conf/config-default.yaml ...

最佳实践建议

1. 系统级插件（如log-rotate、prometheus等）建议配置在config-default.yaml中
2. 业务级插件可以配置在config.yaml中
3. 修改配置后，建议通过以下命令检查插件加载状态：

   curl http://127.0.0.1:9092/v1/plugins/list
   

4. 生产环境中，建议通过CI/CD流程管理配置文件的变更

总结

APISIX的插件管理采用白名单机制，当用户在config.yaml中定义plugins字段时，会完全覆盖系统默认配置。log-rotate作为系统级插件，更适合在config-default.yaml中配置。理解这一机制后，开发者可以更合理地规划插件配置，避免类似问题的发生。

对于已经出现问题的环境，可以按照本文提供的解决方案进行修复。未来APISIX可能会优化这一机制，提供更灵活的插件管理方式。