wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-04 Audit & Security 基础版 #4

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端统一审计与安全日志模块，为所有高危操作提供不可篡改的审计追踪能力。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

Admin 修改用户状态、处理注销申请、变更配置、操作密钥、审批 Agent 任务——这些操作必须留下完整的审计日志，包括谁、什么时间、做了什么、操作前值、操作后值、操作原因、IP 和 UA。

Audit & Security 模块是所有 Admin 高危操作的统一审计出口，各业务模块不直接写审计表，而是通过 AuditService 或 Domain Event 写入。

模块职责

  1. 本模块负责：

    • Admin 操作审计日志记录
    • 用户安全事件日志（登录成功/失败、异常登录）
    • 高危操作定义和分级（查看/修改/删除/审批等风险等级）
    • 审计日志查询和筛选（Admin 视图）
    • 审计日志保留策略（多长时间后归档或删除）
    • 操作前后数据快照（before/after）
    • 操作原因记录

  2. 本模块不负责：

    • C 端用户行为分析
    • 系统性能指标监控（走 Observability）
    • 服务器健康状态（走 Server Monitor）
    • 内容安全违规记录（走 Content Safety）

候选数据对象

  • AdminAuditLog（Admin 操作审计记录）
  • SecurityEvent（安全事件：登录失败/异常IP/风险操作）
  • LoginLog（C 端和 Admin 登录记录）
  • OperationReason（操作原因枚举或模板）
  • RiskFlag（风险标记）

基础设施依赖判断

  • MySQL：是，审计日志持久化
  • Redis：否（审计日志不需要缓存）
  • BullMQ：是（审计日志异步写入，不阻塞主操作）
  • Qdrant：否
  • AI Gateway：否
  • COS：否（审计日志归档可走 COS，当前阶段不需要）

API 设计

  1. Internal Provider（供其他模块调用）：

    • AuditService.log(operation)：记录审计
    • AuditService.logSecurityEvent(event)：记录安全事件

  2. AAPI（Admin 审计视图）：

    • 审计日志列表（支持按操作人、操作类型、时间范围、风险等级筛选）
    • 审计日志详情（含 before/after 对比）
    • 安全事件列表
    • 登录日志列表

Domain Event 设计

  • AdminOperationLogged：审计记录写入后发布
  • SecurityEventDetected：安全事件检测后发布

Admin 视图设计

  1. 审计日志页：

    • 列表：操作人、操作类型、目标对象、时间、IP、风险等级
    • 详情：操作前后数据对比、操作原因
    • 高级筛选：按模块、操作类型、风险等级、时间范围

  2. 安全事件页：

    • 列表：事件类型、关联用户/IP、风险等级、时间
    • 处置操作：标记已处理、关联处罚

交付检查

  • 路由归属：Internal Provider + AAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：否
  • 是否需要 BullMQ：是（异步写入）
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否
  • 是否需要 AuditLog：本模块自身高危操作需要自审计
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. AdminAuditLog Prisma schema 设计
  2. AuditService 接口设计（同步/异步写入）
  3. 高危操作分级定义文档
  4. Admin 审计日志视图设计
  5. 安全事件日志设计
  6. 审计日志归档策略
  7. 集成测试覆盖审计写入、查询、筛选

禁止事项

  • 禁止业务模块直接写 AdminAuditLog 表（必须通过 AuditService）
  • 禁止审计日志被修改或删除（只追加，不更新）
  • 禁止在审计日志中记录敏感信息明文（如密码、完整 token）
  • 禁止审计写入阻塞主业务流程（应异步写入）
  • 禁止跳过操作原因记录

不建议当前阶段实现

  • 审计日志自动归档到 COS
  • 审计异常自动告警
  • 审计日志全文搜索
  • 基于审计日志的异常行为检测
## 目标 设计知习后端统一审计与安全日志模块，为所有高危操作提供不可篡改的审计追踪能力。 本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明 Admin 修改用户状态、处理注销申请、变更配置、操作密钥、审批 Agent 任务——这些操作必须留下完整的审计日志，包括谁、什么时间、做了什么、操作前值、操作后值、操作原因、IP 和 UA。 Audit & Security 模块是所有 Admin 高危操作的统一审计出口，各业务模块不直接写审计表，而是通过 AuditService 或 Domain Event 写入。 ## 模块职责 1. 本模块负责： - Admin 操作审计日志记录 - 用户安全事件日志（登录成功/失败、异常登录） - 高危操作定义和分级（查看/修改/删除/审批等风险等级） - 审计日志查询和筛选（Admin 视图） - 审计日志保留策略（多长时间后归档或删除） - 操作前后数据快照（before/after） - 操作原因记录 2. 本模块不负责： - C 端用户行为分析 - 系统性能指标监控（走 Observability） - 服务器健康状态（走 Server Monitor） - 内容安全违规记录（走 Content Safety） ## 候选数据对象 - AdminAuditLog（Admin 操作审计记录） - SecurityEvent（安全事件：登录失败/异常IP/风险操作） - LoginLog（C 端和 Admin 登录记录） - OperationReason（操作原因枚举或模板） - RiskFlag（风险标记） ## 基础设施依赖判断 - MySQL：是，审计日志持久化 - Redis：否（审计日志不需要缓存） - BullMQ：是（审计日志异步写入，不阻塞主操作） - Qdrant：否 - AI Gateway：否 - COS：否（审计日志归档可走 COS，当前阶段不需要） ## API 设计 1. Internal Provider（供其他模块调用）： - AuditService.log(operation)：记录审计 - AuditService.logSecurityEvent(event)：记录安全事件 2. AAPI（Admin 审计视图）： - 审计日志列表（支持按操作人、操作类型、时间范围、风险等级筛选） - 审计日志详情（含 before/after 对比） - 安全事件列表 - 登录日志列表 ## Domain Event 设计 - AdminOperationLogged：审计记录写入后发布 - SecurityEventDetected：安全事件检测后发布 ## Admin 视图设计 1. 审计日志页： - 列表：操作人、操作类型、目标对象、时间、IP、风险等级 - 详情：操作前后数据对比、操作原因 - 高级筛选：按模块、操作类型、风险等级、时间范围 2. 安全事件页： - 列表：事件类型、关联用户/IP、风险等级、时间 - 处置操作：标记已处理、关联处罚 ## 交付检查 - [ ] 路由归属：Internal Provider + AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：否 - [ ] 是否需要 BullMQ：是（异步写入） - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：本模块自身高危操作需要自审计 - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. AdminAuditLog Prisma schema 设计 2. AuditService 接口设计（同步/异步写入） 3. 高危操作分级定义文档 4. Admin 审计日志视图设计 5. 安全事件日志设计 6. 审计日志归档策略 7. 集成测试覆盖审计写入、查询、筛选 ## 禁止事项 - 禁止业务模块直接写 AdminAuditLog 表（必须通过 AuditService） - 禁止审计日志被修改或删除（只追加，不更新） - 禁止在审计日志中记录敏感信息明文（如密码、完整 token） - 禁止审计写入阻塞主业务流程（应异步写入） - 禁止跳过操作原因记录 ## 不建议当前阶段实现 - 审计日志自动归档到 COS - 审计异常自动告警 - 审计日志全文搜索 - 基于审计日志的异常行为检测
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#4
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?