缓存日志清理任务说明

本文档旨在说明"缓存日志清理任务"定时任务，特别是其中涉及的 MySQL Binlog 清理功能和图片缓存清理功能，以及如何处理相关的权限警告。

1. 背景

应用新增了一个名为 "缓存日志清理任务" 类型的定时任务，其主要功能包括：

• 清理过期的应用日志（如任务历史、API访问记录等）。
• （仅限MySQL） 清理旧的二进制日志（Binary Log，简称 Binlog），以防止其无限增长，占用过多磁盘空间。
• 优化数据库表，保持数据库健康。
• 新增： 清理无效的图片缓存文件，删除文件系统中存在但数据库中不存在的孤立图片文件。

2. 关于 "Binlog 清理失败" 警告

在使用 MySQL 数据库时，你可能会在日志中看到类似以下的警告信息：

[ERROR] - Binlog 清理失败: (pymysql.err.OperationalError) (1227, 'Access denied; you need (at least one of) the SUPER or BINLOG_ADMIN privilege(s) for this operation')

请注意：这是一个常见且可安全忽略的警告，不是一个严重错误。

• 原因：执行 PURGE BINARY LOGS 命令需要较高的数据库权限（SUPER 或 BINLOG_ADMIN）。出于安全考虑，默认创建的数据库用户 danmuapi 并没有这些高级权限。
• 影响：当出现此警告时，仅表示"清理Binlog"这一步操作被跳过。应用的所有核心功能（搜索、导入、匹配弹幕等）均不受任何影响。
• 处理：应用内部已对该特定错误进行了处理，只会记录一条警告信息，不会导致任务失败或产生大量错误日志。

3. 图片缓存清理功能

新增的图片缓存清理功能会：

1. 扫描数据库：查找所有在 anime 表中 local_image_path 字段记录的图片路径
2. 扫描文件系统：检查 /app/config/image/ 目录下的所有图片文件
3. 比对差异：找出文件系统中存在但数据库中不存在的孤立图片文件
4. 安全删除：删除这些孤立的图片文件，释放磁盘空间

这个功能有助于：

• 清理因导入失败、数据删除等原因产生的孤立图片文件
• 节省磁盘空间
• 保持文件系统整洁

4. 如何解决 Binlog 清理权限问题（可选）

如果你希望启用 Binlog 自动清理功能，可以为数据库用户授予相应权限：

方法一：授予 BINLOG_ADMIN 权限（推荐，MySQL 8.0+）

GRANT BINLOG_ADMIN ON *.* TO 'danmuapi'@'%';
FLUSH PRIVILEGES;

方法二：授予 SUPER 权限（不推荐，权限过大）

GRANT SUPER ON *.* TO 'danmuapi'@'%';
FLUSH PRIVILEGES;

注意：

• 授予这些权限会增加安全风险，请根据你的环境谨慎决定。
• 如果你不授予这些权限，应用仍然可以正常工作，只是不会自动清理 Binlog。

5. 配置选项

该任务支持以下配置选项：

• logRetentionDays：日志保留天数，默认为30天
• mysqlBinlogRetentionDays：MySQL Binlog保留天数，默认为3天（仅在有权限时生效）

你可以在系统配置中调整这些值。

6. 任务执行流程

1. 应用日志清理（10%-40%）：清理过期的任务历史、Token访问日志、外部API访问日志
2. MySQL Binlog清理（50%-60%）：仅在MySQL环境下执行，清理过期的二进制日志
3. 数据库表优化（70%-80%）：执行 OPTIMIZE TABLE（MySQL）或 VACUUM（PostgreSQL）
4. 图片缓存清理（85%-100%）：清理孤立的图片缓存文件

7. 故障排除

如果任务执行失败，请检查：

1. 数据库连接：确保数据库连接正常
2. 磁盘空间：确保有足够的磁盘空间进行操作
3. 权限问题：Binlog清理权限不足是正常现象，不影响其他功能
4. 文件系统权限：确保应用有权限访问和删除图片目录中的文件

大多数情况下，即使某个步骤失败，其他步骤仍会继续执行，不会影响应用的正常运行。

---

📚 相关文档

• 🚀 快速开始 - 部署指南
• 💾 MySQL内存优化 - 数据库优化
• ❓ 常见问题 - 故障排除