日志记录和审计、备份配置

2026-04-17 11:20:26 +08:00
parent 1f9b7297a2
commit ec3ba7c60d
49 changed files with 2137 additions and 157 deletions
@@ -0,0 +1,376 @@
+# 管理员操作审计功能设计
+
+## 1. 目标
+
+统一使用 `tms_operation_audit_log` 记录所有敏感管理员操作，覆盖：
+
+- 登录、登出
+- 增删改
+- 执行类操作：初始化、重置、升级、回滚、重启、密钥操作
+- 非法操作：拒绝访问、权限不足、重放、签名失败等
+
+设计原则：
+
+- 只保留一张日志表
+- 敏感操作日志写入失败时，业务直接失败
+- 日志在落库前完成 `SM3` 摘要与 `SM2` 签名
+- 人工审计字段不参与首签
+
+## 2. 表结构
+
+表名：`tms_operation_audit_log`
+
+```sql
+CREATE TABLE IF NOT EXISTS tms_operation_audit_log (
+    id BIGINT PRIMARY KEY,
+    log_id VARCHAR(64) NOT NULL COMMENT '日志唯一标识',
+    operator_role_code VARCHAR(64) NOT NULL COMMENT '操作角色编码',
+    operator_auth_level VARCHAR(32) NULL COMMENT '操作时认证等级',
+    module_code VARCHAR(32) NOT NULL COMMENT '业务模块',
+    action_type VARCHAR(32) NOT NULL COMMENT '操作动作',
+    remote_ip VARCHAR(64) NULL COMMENT '来源IP',
+    operation_result VARCHAR(16) NOT NULL COMMENT '操作结果: SUCCESS/FAILED/DENIED',
+    summary VARCHAR(512) NOT NULL COMMENT '操作摘要',
+    error_message VARCHAR(1024) NULL COMMENT '失败原因',
+    audit_status VARCHAR(16) NOT NULL COMMENT '审计状态: PENDING/REVIEWED',
+    audit_result VARCHAR(16) NULL COMMENT '审计结果: PASS/REJECT/NEED_VERIFY',
+    audit_comment VARCHAR(1024) NULL COMMENT '审计意见',
+    audited_by VARCHAR(64) NULL COMMENT '审计人',
+    audited_at DATETIME(3) NULL COMMENT '审计时间',
+    payload_hash VARCHAR(128) NOT NULL COMMENT 'SM3摘要',
+    sign_value TEXT NOT NULL COMMENT 'SM2签名值',
+    occurred_at DATETIME(3) NOT NULL COMMENT '操作发生时间',
+    create_time DATETIME(3) NOT NULL COMMENT '落库时间',
+    UNIQUE KEY uk_tms_operation_audit_log_log_id (log_id),
+    KEY idx_tms_operation_audit_log_role_code (operator_role_code),
+    KEY idx_tms_operation_audit_log_module_code (module_code),
+    KEY idx_tms_operation_audit_log_action_type (action_type),
+    KEY idx_tms_operation_audit_log_result (operation_result),
+    KEY idx_tms_operation_audit_log_audit_status (audit_status),
+    KEY idx_tms_operation_audit_log_occurred_at (occurred_at)
+);
+```
+
+## 3. 枚举设计
+
+### 3.1 `module_code`
+
+- `AUTH`
+- `INIT`
+- `UPGRADE`
+- `DEVICE`
+- `NETWORK`
+- `KEY`
+- `SYSTEM`
+- `SECURITY`
+
+### 3.2 `action_type`
+
+- `LOGIN`
+- `LOGOUT`
+- `CREATE`
+- `UPDATE`
+- `DELETE`
+- `EXECUTE`
+- `RESET`
+- `ENABLE`
+- `DISABLE`
+- `BIND`
+- `IMPORT`
+- `EXPORT`
+- `BACKUP`
+- `RECOVER`
+- `RESTART`
+- `ACCESS`
+
+### 3.3 `operation_result`
+
+- `SUCCESS`
+- `FAILED`
+- `DENIED`
+
+### 3.4 `audit_status`
+
+- `PENDING`
+- `REVIEWED`
+
+### 3.5 `audit_result`
+
+- `PASS`
+- `REJECT`
+- `NEED_VERIFY`
+
+## 4. 摘要与签名
+
+### 4.1 首签字段
+
+入库前参与 `payload_hash` 和 `sign_value` 计算的字段：
+
+- `log_id`
+- `operator_role_code`
+- `operator_auth_level`
+- `module_code`
+- `action_type`
+- `remote_ip`
+- `operation_result`
+- `summary`
+- `occurred_at`
+
+### 4.2 不参与首签的字段
+
+以下字段属于后续审计动作或补充信息，不参与首签：
+
+- `audit_status`
+- `audit_result`
+- `audit_comment`
+- `audited_by`
+- `audited_at`
+- `error_message`
+
+### 4.3 规范化串
+
+建议按固定字段顺序拼接：
+
+```text
+log_id=...
+operator_role_code=...
+operator_auth_level=...
+module_code=...
+action_type=...
+remote_ip=...
+operation_result=...
+summary=...
+occurred_at=...
+```
+
+规范要求：
+
+- 字段顺序固定
+- `null` 统一为空串
+- 首尾空格统一裁剪
+- 时间统一使用 UTC 与固定格式
+
+### 4.4 签名流程
+
+1. 构造 `canonical_payload`
+2. 计算 `payload_hash = SM3(canonical_payload)`
+3. 计算 `sign_value = SM2(privateKey, canonical_payload)`
+4. 一次性写入数据库
+
+## 5. Java 设计草案
+
+核心对象：
+
+- `OperationAuditLogEntity`
+- `OperationAuditLogRepository`
+- `OperationAuditService`
+- `OperationAuditCommand`
+- `OperationAuditSigner`
+
+服务接口建议：
+
+```java
+public interface OperationAuditService {
+
+    void record(OperationAuditCommand command);
+
+    void review(String logId, AuditResult auditResult, String auditComment, String auditedBy);
+}
+```
+
+`OperationAuditCommand` 建议字段：
+
+- `operatorRoleCode`
+- `operatorAuthLevel`
+- `moduleCode`
+- `actionType`
+- `remoteIp`
+- `operationResult`
+- `summary`
+- `errorMessage`
+
+## 6. 日志记录流程
+
+统一入口：`OperationAuditService.record(...)`
+
+处理流程：
+
+1. 业务侧提交 `OperationAuditCommand`
+2. 服务补齐：
+   - `log_id`
+   - `occurred_at`
+   - `audit_status = PENDING`
+3. 生成 `payload_hash` 与 `sign_value`
+4. 插入 `tms_operation_audit_log`
+5. 若插入失败：
+   - 对敏感操作直接抛异常，业务失败
+
+## 7. 注解与 AOP 接入方案
+
+### 7.1 注解定义
+
+```java
+@Target({ElementType.METHOD, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface AuditedOperation {
+
+    String module();
+
+    String action();
+
+    String summary() default "";
+
+    boolean sensitive() default true;
+}
+```
+
+### 7.2 AOP 职责
+
+切面负责：
+
+- 读取注解元数据
+- 从请求上下文提取：
+  - 当前角色
+  - 当前认证等级
+  - 来源 IP
+- 环绕执行目标方法
+- 成功时记录 `SUCCESS`
+- 捕获业务异常时记录 `FAILED`
+- 捕获权限或安全拒绝时记录 `DENIED`
+- 对 `sensitive = true` 的操作，日志写入失败时重新抛错
+
+### 7.3 设计原则
+
+- AOP 负责公共字段、结果判定和统一落库
+- 业务方法负责提供准确的 `summary`
+- 不在 AOP 中自动抓取完整请求参数，避免日志带入密码、令牌、密钥材料等敏感数据
+
+## 8. 接口清单
+
+### 8.1 首批需要接入审计的接口
+
+#### 认证与角色管理
+
+- `POST /api/v1/auth/password-login`
+- `POST /api/v1/auth/ukey-login`
+- `POST /api/v1/auth/logout`
+- `POST /api/v1/auth/change-password`
+- `POST /api/v1/auth/roles/{roleCode}/enable`
+- `POST /api/v1/auth/roles/{roleCode}/reset-password`
+- `POST /api/v1/auth/roles/{roleCode}/ukeys/bind`
+
+#### 初始化与重置
+
+- `POST /api/v1/init/tasks`
+- `POST /api/v1/init/tasks/{taskId}/execute`
+- `POST /api/v1/init/reset/tasks`
+- `POST /api/v1/init/reset/tasks/{taskId}/execute`
+
+#### 升级管理
+
+- `POST /api/v1/upgrades`
+- `POST /api/v1/upgrades/{taskId}/execute`
+- `POST /api/v1/upgrades/{taskId}/rollback`
+
+#### 设备与网络
+
+- `POST /api/v1/device/restart`
+- 网络配置写接口
+- IP 白名单增删改接口
+
+#### 密钥与密码卡
+
+- LMK / IK / UKey / 密钥导入导出、备份恢复、销毁相关写接口
+
+#### 安全事件
+
+- 认证失败
+- 权限不足
+- 重放拦截
+- 签名校验失败
+
+### 8.2 日志分页查询接口
+
+- `GET /api/v1/audit-logs`
+
+查询条件：
+
+- `operatorRoleCode`
+- `moduleCode`
+- `actionType`
+- `operationResult`
+- `auditStatus`
+- `auditResult`
+- `remoteIp`
+- `dateFrom`
+- `dateTo`
+- `keyword`
+
+默认排序：
+
+- `occurred_at DESC`
+
+### 8.3 日志详情接口
+
+- `GET /api/v1/audit-logs/{logId}`
+
+详情建议返回：
+
+- 基础日志字段
+- 审计字段
+- `payload_hash`
+- `sign_value`
+
+### 8.4 日志审计接口
+
+- `POST /api/v1/audit-logs/{logId}/review`
+
+请求示例：
+
+```json
+{
+  "auditResult": "PASS",
+  "auditComment": "复核通过"
+}
+```
+
+更新规则：
+
+- 仅审计管理员可操作
+- 仅允许 `PENDING -> REVIEWED`
+- 更新字段：
+  - `audit_status`
+  - `audit_result`
+  - `audit_comment`
+  - `audited_by`
+  - `audited_at`
+
+## 9. 失败策略
+
+敏感操作统一采用失败关闭：
+
+- 审计日志写入失败，业务直接失败
+
+敏感操作范围包括：
+
+- 登录与登出
+- 角色管理
+- 口令变更
+- UKey 管理
+- 初始化与重置
+- 升级与回滚
+- 网络配置
+- 白名单变更
+- 密钥与密码卡操作
+- 安全拦截事件
+
+## 10. 推荐实现顺序
+
+1. Flyway 建表，删除旧 `tms_auth_audit_log` / `tms_security_event`
+2. 增加枚举、Entity、Repository
+3. 增加 `OperationAuditSigner`（SM3 / SM2）
+4. 增加 `OperationAuditService`
+5. 增加 `@AuditedOperation` 与 AOP
+6. 增加分页查询与详情接口
+7. 增加审计接口
+8. 在首批敏感接口上补齐注解与摘要