ClouisleClouisle

审计日志

查看、筛选、导出与归档系统操作审计日志

审计日志记录系统内的资源操作：操作者、动作、资源、变更前后快照与来源 IP。敏感字段在落库与展示时自动脱敏，原始密钥不会出现在日志中。查看审计日志需要 audit:read，导出需要 audit:export。

审计日志事件

审计日志覆盖以下事件类型，每种事件记录操作者、时间戳、资源、操作类型、状态及变更详情。

认证事件

用户登录、登出与注册行为：

事件说明记录内容
login_success登录成功用户、时间、IP、User Agent、认证方式、是否使用 2FA
login_failed登录失败用户、时间、IP、失败原因、尝试次数
logout登出用户、时间、IP、会话时长
register注册用户、时间、IP、注册方式、邮箱是否已验证

用户管理事件

管理员对用户账号的创建、更新与删除操作：

事件说明记录内容
create_user创建用户操作者、时间、新用户邮箱、姓名、角色、状态
update_user更新用户操作者、时间、变更前后字段（如角色、状态）
delete_user删除用户操作者、时间、被删除用户标识

团队管理事件

团队的创建与成员变更：

事件说明记录内容
create_team创建团队操作者、时间、团队名称、描述、所有者
add_team_member添加团队成员操作者、时间、团队、成员 ID、成员邮箱、角色
remove_team_member移除团队成员操作者、时间、团队、成员 ID、移除原因

Agent 事件

Agent 的创建、更新、发布与删除：

事件说明记录内容
create_agent创建 Agent操作者、时间、Agent 名称、所属团队、模型
update_agent更新 Agent操作者、时间、变更前后字段（如 max_iterations、system_prompt）
publish_agent发布 Agent操作者、时间、可见性、是否上架市场
delete_agent删除 Agent操作者、时间、Agent 标识

API Key 事件

API Key 的创建与状态变更：

事件说明记录内容
create_api_key创建 API Key操作者、时间、Key 名称、权限范围、关联 Agent/工作流数、过期时间
activate_api_key激活 API Key操作者、时间、Key 标识
deactivate_api_key停用 API Key操作者、时间、Key 标识、停用原因

系统设置事件

站点配置的变更：

事件说明记录内容
update_site_setting更新单项设置操作者、时间、设置项、变更前后值
bulk_update_site_settings批量更新设置操作者、时间、更新项数、设置项列表
reset_site_settings重置设置操作者、时间、重置分类、重置项数

安全事件

账号安全相关操作：

事件说明记录内容
change_password修改密码用户、时间、IP
reset_password重置密码用户、时间、重置方式、发起者
activate_user激活账号操作者、时间、目标用户
deactivate_user停用账号操作者、时间、目标用户、停用原因

查看与筛选

在管理后台 > 审计日志查看。每条记录包含：时间、用户、动作、资源类型、资源名称、操作（创建/读取/更新/删除）、状态、IP 地址与详情。

搜索与过滤

列表接口 GET /api/v1/admin/audit-logs 支持以下查询参数：

参数说明
user_id按用户 UUID 过滤
team_id按团队 UUID 过滤
action按精确动作值过滤；支持多次传入进行 action__in 匹配（不支持通配符）
resource_type按资源类型过滤（user、team、agent、workflow 等）
resource_id按资源 UUID 过滤
status按状态过滤（success、failed 等）
start_date / end_date按时间范围过滤
search对资源名称、资源 ID、IP 地址进行不区分大小写的子串（icontains）搜索

没有专门的 IP 地址过滤参数，但 search 字段支持对 IP 进行子串匹配（如 192.168.1.）。search 不解释 * 或其他 glob 模式。

Roadmap： 无法按变更字段、变更前/后值进行筛选。字段级 changes 仅在日志详情和导出中可见。

Roadmap： 暂无保存搜索功能，需手动重新执行过滤条件。

查看日志详情

点击日志条目可查看完整详情，包括：

  • 基本信息：ID、时间戳、用户、用户 ID、动作、状态
  • 资源信息：资源类型、资源 ID、资源名称、操作类型
  • 请求信息：IP 地址、User Agent、认证方式
  • 变更详情：before / after 字段级变更快照（敏感值已脱敏）
  • 元数据：团队 ID/名称、模型、执行时长等

Roadmap： 暂无「关联日志」视图。如需查找相关条目，请按相同 user_id、resource_id 或时间范围过滤。

敏感数据脱敏

字段级变更的 before / after 数据在存储前会经过 AuditLogService.sanitize_changes 处理：

  • 敏感字段掩码：键名包含 password、hashed_password、api_key、secret_key、access_token、refresh_token、private_key、secret 或 token 的字段会被掩码。字符串超过 8 个字符只显示前 8 位加 ***，其余值替换为 ***。
  • 邮箱部分掩码：本地部分超过 2 个字符时首尾各留 1 个（a***e@example.com）；不超过 2 个字符时只留首字符（a***@example.com）。
  • 嵌套字典递归处理。
  • 值截断：单字段最大 500 字符，超大结构替换为预览字符串。

由于落库时即脱敏，原始密钥不会出现在审计日志的任何位置。

导出审计日志

导出格式

支持 CSV 和 JSON 两种格式。导出接口 GET /api/v1/admin/audit-logs/export?format=csv|json 支持列表接口除 resource_id 之外的全部筛选参数（user_id、team_id、action、resource_type、status、start_date、end_date、search），最多返回 10,000 条，按时间倒序。

导出的 search 与列表不同

列表接口的 search 匹配资源名称、资源 ID 与 IP 地址；导出接口的 search 只匹配资源名称与 IP 地址（不含资源 ID），也没有 resource_id 参数。用「资源 ID」搜索后导出，结果会比列表页多——排查问题时请以资源名称或 IP 作为导出条件。

CSV 列： ID、Time、User、Action、Resource Type、Resource Name、Operation、Status、IP Address、Error Message

JSON： 导出完整序列化条目（含 changes）。

curl -X GET "https://your-domain.com/api/v1/admin/audit-logs/export?format=csv" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Roadmap： 暂无定时导出（日/周/月）或邮件/S3 投递功能，导出为手动操作。

保留与归档

保留策略

保留天数由站点设置 audit_log_retention_days 控制，默认 365 天，范围 30-3650。

配置方式： 前往管理后台 > 站点设置 > 存储，设置审计日志保留天数与归档文件存储路径（默认 /var/log/clouisle/audit_archives）。

手动归档

  1. 前往管理后台 > 站点设置 > 存储。
  2. 在审计日志分区点击归档并确认。
  3. 任务异步执行（需要 audit:export）；界面每 2 秒轮询一次任务状态，5 分钟后超时。

注意： 手动归档入口在存储设置页，不在审计日志页——审计日志页只提供查看、筛选和导出。

调用的端点：

方法路径说明
POST/api/v1/admin/site-settings/archive-audit-logs触发归档，返回 { "task_id", "status": "pending" }
GET/api/v1/admin/site-settings/archive-audit-logs/{task_id}查询任务状态：PENDING / STARTED / SUCCESS（含 result.archived_count）/ FAILURE（含 error）
POST/api/v1/admin/audit-logs/archive审计日志路由下的等价触发器：同样提交 tasks.archive_old_audit_logs，但只返回 task_id，没有配套的状态查询端点

三个端点都要求 audit:export；触发成功与失败都会写入审计日志（trigger_audit_log_archive）。

归档机制：

  • 归档任务 tasks.archive_old_audit_logs 选取超过保留截止日期（now - audit_log_retention_days）的日志
  • 日志按月导出为本地 JSON 文件，如 /var/log/clouisle/audit_archives/audit_logs_202602.json（已存在的月度文件会追加）
  • 归档完成后已归档日志从数据库中删除

归档会从数据库删除已归档日志，只留下本地 JSON 文件。归档路径必须落在持久卷上，否则容器重建即丢失唯一副本；同时确认 audit_log_retention_days 已被合规要求确认过再触发。

Roadmap： 没有定时自动归档，必须手动触发；也没有 S3/Azure/Blob 等远程归档目标，归档输出只写入本地 audit_log_archive_path 配置的路径。

Roadmap： 暂无归档日志恢复工作流。归档路径下的月度 JSON 文件可供手动检查。

归档状态查询

GET /api/v1/admin/audit-logs/stats/retention 返回：已配置的保留天数（retention_days）、截止日期（cutoff_date）、待归档日志数（logs_to_archive）、最旧日志时间（oldest_log_date）与 next_archive_date。

next_archive_date 是接口按「次日 03:00」计算出来的展示值，背后没有对应的 Celery Beat 定时任务——归档始终是手动触发的。不要把它当作「系统会在该时间自动归档」的承诺（app/core/celery.py 的 beat_schedule 里没有归档任务）。

统计接口

GET /api/v1/admin/audit-logs/stats 返回聚合统计：总日志数、今日日志数、失败日志数、近 7 天活跃用户数、Top 5 动作、Top 5 用户。

Roadmap： 暂无审计报告生成器（用户活动、管理员操作、安全事件、资源变更、失败操作等报告），以上统计端点提供当前可用的聚合数据。

Roadmap： 暂无审计日志实时监控仪表盘。站点设置中的 audit_alert_enabled、audit_alert_webhook 及失败登录阈值等配置项当前未被任何监控或通知代码消费（见站点设置的「审计告警」小节）。

API 端点参考

方法路径说明权限
GET/api/v1/admin/audit-logs查询审计日志列表（支持筛选）audit:read
GET/api/v1/admin/audit-logs/{id}获取单条审计日志详情audit:read
GET/api/v1/admin/audit-logs/export?format=csv|json导出审计日志（最多 10,000 条）audit:export
GET/api/v1/admin/audit-logs/stats获取审计统计聚合audit:read
GET/api/v1/admin/audit-logs/stats/retention获取保留与归档状态audit:read
POST/api/v1/admin/audit-logs/archive触发手动归档任务（仅返回 task_id）audit:export
POST/api/v1/admin/site-settings/archive-audit-logs触发手动归档任务（存储设置页使用，返回 task_id + status）audit:export
GET/api/v1/admin/site-settings/archive-audit-logs/{task_id}查询归档任务状态与结果audit:export

最佳实践

审计日志配置

  • 启用所有操作的审计日志记录
  • 同时记录成功与失败操作
  • 包含足够的上下文信息
  • 保护日志完整性
  • 定期审查日志
  • 适当归档日志
  • 监控异常行为
  • 为关键事件设置告警

日志分析

  • 定期审查日志
  • 寻找模式与趋势
  • 调查异常事件
  • 生成定期报告
  • 与团队分享发现
  • 记录事件与处置
  • 使用日志满足合规要求

安全

  • 限制日志访问权限
  • 加密归档日志
  • 使用安全存储
  • 监控日志访问行为
  • 审计审计者自身
  • 维护日志完整性
  • 遵守相关法规

参见：

这篇文章对你有帮助吗？

本页目录

审计日志事件认证事件用户管理事件团队管理事件Agent 事件API Key 事件系统设置事件安全事件查看与筛选搜索与过滤查看日志详情敏感数据脱敏导出审计日志导出格式保留与归档保留策略手动归档归档状态查询统计接口API 端点参考最佳实践审计日志配置日志分析安全