Apache APISIX 日志轮转插件 log-rotate 配置指南

问题背景

在使用 Apache APISIX 3.6.0 版本时，许多用户发现 log-rotate 插件虽然已经配置但并未生效。日志文件持续增长而没有被自动分割和清理，这可能导致磁盘空间不足的问题。

问题分析

通过分析用户提供的配置和日志信息，我们发现 log-rotate 插件未被正确加载的根本原因是配置方式不当。在 APISIX 中，插件的启用需要遵循特定的配置规则：

1. 插件必须在 config.yaml 或 config-default.yaml 中显式声明
2. 插件属性(plugin_attr)需要与插件启用同步配置
3. 仅将插件添加到 plugins 列表而不进行完整配置是不够的

正确配置方法

要使 log-rotate 插件正常工作，需要以下完整配置：

apisix:
  # 基础配置...

deployment:
  # 部署配置...
  
  plugins:
    - log-rotate  # 必须在此处声明启用插件
    - file-logger # 如果使用文件日志也需要启用
    
  plugin_attr:
    log_rotate:
      interval: 60    # 检查间隔(分钟)
      max_kept: 168   # 保留的日志文件数量
      max_size: 36000 # 单个日志文件最大大小(KB)
    file-logger:
      path: "./logs/file.logger/daily.log" # 日志文件路径

关键配置参数说明

1. interval: 日志轮转检查的时间间隔，单位为分钟
2. max_kept: 保留的历史日志文件数量，超出此数量的旧文件会被自动删除
3. max_size: 单个日志文件的最大大小限制，单位为KB
4. path: 日志文件的输出路径，需要确保APISIX有写入权限

常见问题排查

如果配置后插件仍未生效，可以检查以下方面：

1. 确认APISIX版本是否支持log-rotate插件
2. 检查error.log中是否有插件加载失败的记录
3. 确保日志目录有正确的写入权限
4. 验证配置文件的语法是否正确，特别是缩进和格式

最佳实践建议

1. 根据实际业务需求合理设置max_size和max_kept参数
2. 生产环境建议将日志目录挂载到持久化存储
3. 定期检查日志轮转是否正常工作
4. 对于重要日志，考虑增加备份机制

通过以上配置和注意事项，可以确保APISIX的日志轮转功能正常工作，有效管理日志文件大小和数量，避免因日志增长导致的磁盘空间问题。