审计日志

概述

审计日志（Audit Logs）记录 Code Bird Cloud 平台中所有关键操作的详细信息，便于管理员进行安全审计、问题排查和合规追踪。审计日志为只读数据，不可修改或删除，确保记录的完整性和可信度。

日志条目字段

每条审计日志包含以下字段：

字段	类型	说明
id	string	日志记录的唯一标识
key	string	事件类型标识（如 SignIn.Password、Token.Exchange）
payload	object	事件的详细数据（JSON 格式，内容因事件类型而异）
user_id	string/null	触发事件的用户 ID（未认证的操作可能为 null）
application_id	string/null	关联的应用 ID
ip	string	客户端请求的 IP 地址
user_agent	string	客户端的浏览器/设备标识
created_at	string	事件发生时间（ISO 8601 格式）

日志筛选

支持以下筛选条件精确查询日志：

参数	类型	说明
user_id	string	按用户 ID 筛选，查看特定用户的操作记录
application_id	string	按应用 ID 筛选，查看特定应用相关的日志
key	string	按事件类型筛选，查看特定类型的事件
page	integer	页码（默认 1）
page_size	integer	每页条数（默认 20）

日志详情

每条日志的 payload 字段包含事件的上下文数据，其内容因事件类型而异：

• 登录事件：包含登录方式、用户名、登录结果（成功/失败）、失败原因等
• 令牌事件：包含授权类型（Grant Type）、资源范围等
• 注册事件：包含注册方式、用户名等
• 验证码事件：包含验证码类型、发送目标等

响应示例：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "log_001",
    "key": "SignIn.Password",
    "payload": {
      "username": "john_doe",
      "result": "success",
      "session_id": "sess_abc123"
    },
    "user_id": "usr_abc123",
    "application_id": "app_001",
    "ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "created_at": "2025-06-15T10:30:00Z"
  }
}

常见事件类型

以下为平台中常见的日志事件类型：

事件类型	说明
SignIn.Password	用户名密码登录
SignIn.VerificationCode	验证码登录
SignIn.Social	社交账号登录
Register.Username	用户名注册
Register.Email	邮箱注册
Register.Phone	手机号注册
Token.Exchange	令牌交换（授权码换令牌）
Token.Refresh	令牌刷新
Token.Revoke	令牌撤销
ForgotPassword	忘记密码 / 密码重置
VerificationCode.Send	发送验证码
VerificationCode.Verify	验证码校验

说明：具体的事件类型列表取决于系统配置和已启用的功能模块。随着功能迭代，事件类型可能会增加。

API 参考

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

获取日志列表

GET /api/v1/logs

查询参数：

参数	类型	必填	默认值	说明
page	integer	否	1	页码
page_size	integer	否	20	每页条数
user_id	string	否	-	按用户 ID 筛选
application_id	string	否	-	按应用 ID 筛选
key	string	否	-	按事件类型筛选

响应示例：

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "log_001",
        "key": "SignIn.Password",
        "payload": {
          "username": "john_doe",
          "result": "success"
        },
        "user_id": "usr_abc123",
        "application_id": "app_001",
        "ip": "192.168.1.100",
        "user_agent": "Mozilla/5.0 ...",
        "created_at": "2025-06-15T10:30:00Z"
      }
    ],
    "total": 1280,
    "page": 1,
    "page_size": 10
  }
}

获取日志详情

GET /api/v1/logs/:id

路径参数	类型	说明
id	string	日志 ID

详细的请求和响应格式请参阅 审计日志 API 参考。

使用场景

安全审计

• 定期检查登录失败事件，识别可疑的暴力破解行为
• 关注异常 IP 地址的访问记录，发现潜在的未授权访问
• 追踪敏感操作（如密码重置、权限变更）的执行者和执行时间
• 审查令牌签发和撤销记录，确保令牌生命周期管理正常

问题排查

• 用户反馈登录失败时，通过 user_id 筛选查看具体的错误日志和 payload 中的失败原因
• 应用集成异常时，通过 application_id 筛选查看令牌交换日志，定位授权流程中的问题
• 查看 payload 中的详细上下文数据，快速定位问题根因

合规追踪

• 记录所有用户认证和授权操作，满足合规审计要求
• 提供完整的、不可篡改的操作审计记录
• 支持按时间范围和条件检索日志数据，便于生成合规报告

最佳实践

1. 定期审查：建立定期审查审计日志的机制，至少每周检查一次异常事件
2. 告警配置：对高频登录失败、异常 IP 访问等事件设置告警规则（可结合外部监控系统）
3. 日志归档：对于合规要求较高的场景，建议将审计日志定期导出并长期保存
4. 权限控制：限制审计日志的查看权限，仅授予安全管理员和合规审计人员
5. 关联分析：结合用户 ID、应用 ID 和 IP 地址进行多维度关联分析，提升安全事件检测能力

相关文档

• 审计日志 API 参考 -- 完整的 API 接口文档
• 签名密钥管理 -- 密钥操作也会记录在审计日志中
• 用户管理 -- 用户操作相关的审计追踪