Nanako/AIRouter

Fork 0

Files

nanako c5b0b471fe 优化后端模型配置交互，优化后端模型配置可读性

2025-11-11 16:35:02 +08:00

12 KiB

Raw Permalink Blame History

日志自动清理功能文档

概述

AI Gateway 提供了自动清理请求日志的功能，可以定期删除过期的日志记录，防止数据库文件无限增长。此功能通过配置文件进行管理，支持灵活的定时清理策略。

功能特性

1. 定时自动清理

自动执行：在指定时间自动清理过期日志
可配置保留期：灵活设置日志保留天数（默认7天）
空间回收：执行SQLite VACUUM操作，真正回收磁盘空间
详细日志：记录每次清理的详细统计信息

2. 手动触发清理

通过API端点手动触发立即清理
返回详细的清理报告
适用于紧急清理或测试场景

3. 状态监控

查询清理器当前状态
查看下次执行时间
监控清理配置参数

配置说明

配置文件位置

配置文件默认位于项目根目录：config.json

如果配置文件不存在，系统会自动创建并使用默认配置。

配置文件格式

{
  "database": {
    "path": "./gateway.db"
  },
  "server": {
    "port": "8080",
    "host": "0.0.0.0"
  },
  "log_cleaner": {
    "enabled": true,
    "execute_time": "02:00",
    "retention_days": 7,
    "check_interval": 5
  },
  "app": {
    "name": "AI Gateway",
    "version": "1.0.0",
    "environment": "production",
    "log_level": "info"
  }
}

日志清理配置参数详解

参数	类型	默认值	说明
`enabled`	boolean	`true`	是否启用自动清理功能
`execute_time`	string	`"02:00"`	每天执行清理的时间（24小时制，格式：HH:MM）
`retention_days`	integer	`7`	日志保留天数，超过此天数的日志将被删除
`check_interval`	integer	`5`	检查间隔（分钟），系统每隔此时间检查是否到达执行时间

配置示例

示例1：每天凌晨2点清理30天前的日志

{
  "log_cleaner": {
    "enabled": true,
    "execute_time": "02:00",
    "retention_days": 30,
    "check_interval": 5
  }
}

示例2：每天中午12点清理3天前的日志

{
  "log_cleaner": {
    "enabled": true,
    "execute_time": "12:00",
    "retention_days": 3,
    "check_interval": 5
  }
}

示例3：禁用自动清理

{
  "log_cleaner": {
    "enabled": false,
    "execute_time": "02:00",
    "retention_days": 7,
    "check_interval": 5
  }
}

使用方法

1. 启动服务

系统启动时会自动加载配置并启动日志清理器：

cd backend
go run main.go

启动日志会显示清理器状态：

🚀 启动 AI Gateway 服务...
✅ 配置文件加载成功: ./config.json
📋 当前配置:
  🗄️  数据库路径: ./gateway.db
  🌐 服务器地址: 0.0.0.0:8080
  🧹 日志自动清理: true
     ⏰ 执行时间: 02:00
     📅 保留天数: 7天
     🔍 检查间隔: 5分钟
✅ 数据库连接成功
🚀 启动日志自动清理器 - 执行时间: 02:00, 保留天数: 7天
✅ 日志自动清理器已启动
🌐 HTTP服务器启动在 0.0.0.0:8080

2. 查询清理器状态

API端点: GET /api/log-cleaner/status

请求示例:

curl -X GET http://localhost:8080/api/log-cleaner/status \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例:

{
  "enabled": true,
  "execute_time": "02:00",
  "retention_days": 7,
  "check_interval": 5,
  "next_execute_time": "2025-11-12 02:00:00",
  "time_until_next": "18h34m22s"
}

3. 手动触发清理

API端点: POST /api/log-cleaner/force-cleanup

请求示例:

curl -X POST http://localhost:8080/api/log-cleaner/force-cleanup \
  -H "Authorization: Bearer YOUR_API_KEY"

响应示例:

{
  "message": "Manual log cleanup completed",
  "execute_time": "2025-11-11 15:30:45",
  "duration": "1.234s",
  "deleted_count": 5000,
  "total_count_before": 10000,
  "active_count_before": 10000,
  "total_count_after": 5000,
  "cutoff_time": "2025-11-04 15:30:45",
  "vacuum_duration": "0.567s",
  "vacuum_error": "",
  "success": true
}

4. 修改配置

方法1：修改配置文件后重启

编辑 config.json 文件
修改 log_cleaner 配置项
重启服务

方法2：通过环境变量（未来支持）

未来版本将支持通过环境变量覆盖配置。

清理执行流程

自动清理流程

系统启动
    ↓
加载配置文件
    ↓
初始化日志清理器
    ↓
启动定时检查（每5分钟）
    ↓
检查当前时间是否匹配执行时间
    ↓
【匹配】→ 执行清理任务
    ↓
1. 计算截止时间（当前时间 - 保留天数）
2. 硬删除截止时间之前的日志记录
3. 执行VACUUM操作回收磁盘空间
4. 记录清理统计信息
5. 生成并记录清理报告
    ↓
继续定时检查...

清理报告说明

每次清理（自动或手动）都会生成详细的清理报告，包含以下信息：

字段	说明
`execute_time`	清理执行的时间
`duration`	清理操作总耗时
`deleted_count`	删除的日志记录数
`total_count_before`	清理前的总记录数（包括软删除）
`active_count_before`	清理前的活跃记录数
`total_count_after`	清理后的总记录数
`cutoff_time`	清理的截止时间（此时间之前的日志被删除）
`vacuum_duration`	VACUUM操作耗时
`vacuum_error`	VACUUM操作错误信息（如有）
`success`	清理是否成功

日志输出示例

⏰ 开始执行定时日志清理任务 - 当前时间: 2025-11-11 02:00:03
🧹 开始自动清理日志 - 删除 2025-11-04 02:00:03 之前的日志
✅ 自动日志清理完成:
   📊 删除记录数: 5000
   📈 删除前总数: 10000 (活跃: 10000)
   📉 删除后总数: 5000
   🗜️  VACUUM耗时: 0.567s
   ⏱️  总耗时: 1.234s
   📅 清理截止时间: 2025-11-04 02:00:03
📋 清理报告已生成 - 删除 5000 条记录，耗时 1.234s

性能影响

数据库锁定

VACUUM操作：会锁定整个数据库，期间无法进行写操作
建议：将执行时间设置在业务低峰期（如凌晨）
耗时估算：取决于数据库大小，通常几秒到几十秒

磁盘I/O

DELETE操作和VACUUM操作都会产生磁盘I/O
对于大量数据（百万级），建议分批删除或调整保留策略

内存占用

清理过程内存占用较小
VACUUM可能临时占用额外磁盘空间（最多为数据库文件大小）

故障排查

1. 清理器未启动

症状：启动日志显示"日志自动清理功能已禁用"

解决方案：

检查 config.json 中 log_cleaner.enabled 是否为 true
确认配置文件格式正确

2. 配置文件加载失败

症状：启动日志显示"加载配置失败，使用默认配置"

解决方案：

检查 config.json 文件是否存在
验证JSON格式是否正确
检查文件权限是否可读

3. VACUUM失败

症状：清理报告中显示 vacuum_error 不为空

可能原因：

磁盘空间不足
数据库文件被其他进程锁定
数据库文件损坏

解决方案：

确保有足够的磁盘空间（至少为数据库文件大小的2倍）
关闭其他可能访问数据库的进程
使用SQLite工具检查数据库完整性

4. 清理未在预定时间执行

症状：过了执行时间但未看到清理日志

解决方案：

检查系统时间是否正确
确认 check_interval 设置合理（不要太大）
查看应用日志是否有错误信息
验证服务是否正常运行

最佳实践

1. 保留期设置建议

业务场景	建议保留期	说明
开发测试环境	1-3天	快速清理，节省空间
生产环境（高流量）	7-14天	平衡存储和可追溯性
生产环境（低流量）	30-90天	长期保留用于分析
合规要求	根据法规	遵守行业规定

2. 执行时间建议

首选：凌晨2-4点（业务低峰期）
备选：中午12-14点（如果凌晨有定时任务）
避免：业务高峰期

3. 检查间隔建议

推荐值：5分钟
最小值：1分钟（频繁检查会增加CPU开销）
最大值：30分钟（间隔太大可能错过执行时间）

4. 监控建议

定期查看清理器状态API
监控数据库文件大小变化
关注清理报告中的异常信息
设置告警（如清理失败、VACUUM错误）

5. 备份策略

在首次启用清理功能前，备份数据库
定期备份配置文件
保留重要日志的导出副本

与手动清理的对比

特性	定时自动清理	手动清理（API）	前端手动清理
触发方式	自动定时	API调用	前端操作
清理粒度	按天数	按天数	按天数
空间回收	✅ VACUUM	✅ VACUUM	✅ VACUUM
清理报告	✅ 详细	✅ 详细	✅ 基本
适用场景	日常维护	紧急清理/脚本	临时清理
需要权限	无（系统级）	API认证	用户认证

技术实现细节

核心组件

调度器 (backend/internal/scheduler/log_cleaner.go)
- 定时检查逻辑
- 清理执行逻辑
- 报告生成
配置管理 (backend/internal/config/config.go)
- 配置加载和验证
- 默认配置管理
API端点 (backend/api/handlers.go)
- 状态查询接口
- 手动触发接口
主程序集成 (backend/main.go)
- 启动初始化
- 优雅关闭

数据删除机制

系统使用硬删除（Unscoped Delete）而非GORM默认的软删除：

// 硬删除，真正从数据库中移除记录
db.Unscoped().Where("created_at < ?", cutoffTime).Delete(&models.RequestLog{})

// 执行VACUUM回收空间
db.Exec("VACUUM")

这确保：

记录被物理删除
磁盘空间被真正释放
数据库文件大小减小

升级和迁移

从无配置文件版本升级

如果从旧版本升级，系统会自动创建默认配置文件。

配置迁移

备份现有配置（如有）
参考 config.example.json 添加新配置项
重启服务验证

安全考虑

1. 权限控制

所有API端点需要认证（Authorization header）
手动触发清理需要管理员权限

2. 数据安全

删除操作不可逆
建议定期备份重要日志
清理前检查保留期设置

3. 配置安全

配置文件应有适当的文件权限（如644）
不要在配置中存储敏感信息
使用环境变量管理敏感配置（未来版本）

FAQ

Q1: 如何临时禁用自动清理？

A: 修改配置文件，将 log_cleaner.enabled 设置为 false，然后重启服务。

Q2: 清理会影响正在运行的服务吗？

A: VACUUM操作期间会短暂锁定数据库，建议在低峰期执行。正常的DELETE操作影响很小。

Q3: 如何查看已删除的日志？

A: 删除后的日志无法恢复。如需保留，请在清理前导出或调整保留期。

Q4: 可以设置多个清理时间吗？

A: 当前版本仅支持每天一次。如需多次清理，可以通过cron任务调用手动清理API。

Q5: 数据库文件大小没有减小？

A: 确认清理日志中包含VACUUM操作且无错误。如果VACUUM失败，文件大小不会减小。

Q6: 如何测试清理功能？

A: 使用手动触发API进行测试，或将执行时间设置为几分钟后。

Q7: 清理会删除当天的日志吗？

A: 不会。清理只删除 retention_days 天之前的日志。例如保留7天，则只删除7天前的日志。

Q8: 支持按大小清理吗？

A: 当前版本仅支持按时间清理。未来可能添加按大小或按数量清理的选项。

更新日志

v1.0.0 (2025-11-11)

✅ 首次发布
✅ 支持定时自动清理
✅ 支持手动触发清理
✅ 集成VACUUM空间回收
✅ 配置文件管理
✅ 详细清理报告
✅ 优雅关闭支持

未来计划

支持环境变量配置
支持按数据库大小触发清理
支持多个清理时间段
清理历史记录持久化
集成Prometheus监控指标
邮件/webhook通知
增量清理（分批删除大量数据）
清理前自动备份选项

技术支持

如有问题或建议，请提交Issue或联系开发团队。

文档版本: 1.0.0
最后更新: 2025-11-11
适用版本: AI Gateway v1.0.0+

12 KiB Raw Permalink Blame History Unescape Escape

日志自动清理功能文档

概述

功能特性

1. 定时自动清理

2. 手动触发清理

3. 状态监控

配置说明

配置文件位置

配置文件格式

日志清理配置参数详解

配置示例

示例1：每天凌晨2点清理30天前的日志

示例2：每天中午12点清理3天前的日志

示例3：禁用自动清理

使用方法

1. 启动服务

2. 查询清理器状态

3. 手动触发清理

4. 修改配置

方法1：修改配置文件后重启

方法2：通过环境变量（未来支持）

清理执行流程

自动清理流程

清理报告说明

日志输出示例

性能影响

数据库锁定

磁盘I/O

内存占用

故障排查

1. 清理器未启动

2. 配置文件加载失败

3. VACUUM失败

4. 清理未在预定时间执行

最佳实践

1. 保留期设置建议

2. 执行时间建议

3. 检查间隔建议

4. 监控建议

5. 备份策略

与手动清理的对比

技术实现细节

核心组件

数据删除机制

升级和迁移

从无配置文件版本升级

配置迁移

安全考虑

1. 权限控制

2. 数据安全

3. 配置安全

FAQ

Q1: 如何临时禁用自动清理？

Q2: 清理会影响正在运行的服务吗？

Q3: 如何查看已删除的日志？

Q4: 可以设置多个清理时间吗？

Q5: 数据库文件大小没有减小？

Q6: 如何测试清理功能？

Q7: 清理会删除当天的日志吗？

Q8: 支持按大小清理吗？

更新日志

v1.0.0 (2025-11-11)

未来计划

技术支持

12 KiB

Raw Permalink Blame History