Files

T

v6ole f1f8518985 ```

feat(auth): 添加用户权限获取接口并完善JWT令牌角色信息

- 在JWT令牌中添加用户角色信息
- 新增get_my_permissions接口用于获取当前用户权限码列表
- 重构认证回调逻辑，增加错误日志记录
- 更新用户信息获取接口使用Authorization头验证
```

2026-04-06 00:40:08 +08:00

13 KiB

Raw Blame History

H3C ONU设备管理系统 - 审计日志系统设计方案

项目概述

本方案为 H3C ONU 设备管理系统设计一套完整的审计日志系统，用于记录所有用户操作（手动和自动触发），支持误操作恢复和问责追溯。

设计目标

全面记录：记录所有用户操作，包括认证、设备管理、OLT端口操作等
详细审计：记录操作详情（用户、时间、IP、参数、结果等）
快速查询：提供超级管理员查询界面
长期存储：日志保留90天，支持自动清理
性能友好：异步执行，不影响主业务流程
Docker友好：支持容器化部署，日志映射到宿主机

系统架构

整体架构图

用户操作 → API请求 → 审计日志中间件 → 异步任务队列 → 
    ↓
[数据库] 记录核心信息 + [文件系统] 记录详细日志
    ↓
查询界面 ← 日志服务 ← 定期清理任务

技术栈

后端框架：FastAPI + SQLAlchemy + Celery
数据库：PostgreSQL（核心信息）+ 文件系统（详细日志）
消息队列：Redis（Celery broker）
存储：Docker卷映射到宿主机

详细设计

1. 数据库设计

1.1 审计日志表 (`audit_logs`)

CREATE TABLE audit_logs (
    id SERIAL PRIMARY KEY,
    -- 用户信息
    user_id VARCHAR(100) NOT NULL,
    username VARCHAR(100) NOT NULL,
    user_role VARCHAR(50),
    
    -- 操作信息
    action_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    action_type VARCHAR(50) NOT NULL,        -- 操作类型
    action_subtype VARCHAR(50),              -- 操作子类型
    
    -- 请求信息
    ip_address VARCHAR(45),
    user_agent TEXT,
    request_method VARCHAR(10),
    request_path VARCHAR(500),
    
    -- 操作结果
    status VARCHAR(20) NOT NULL,             -- success, failed, error
    status_code INTEGER,
    
    -- 资源信息
    resource_type VARCHAR(50),               -- device, olt, port, user, etc.
    resource_id VARCHAR(100),
    resource_name VARCHAR(200),
    
    -- 简要信息
    description TEXT NOT NULL,
    
    -- 详细日志
    request_params JSONB,
    response_data JSONB,
    error_message TEXT,
    
    -- 文件存储
    details_file_path VARCHAR(500),
    
    -- 元数据
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

-- 索引设计
CREATE INDEX idx_audit_logs_action_time ON audit_logs(action_time);
CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id);
CREATE INDEX idx_audit_logs_action_type ON audit_logs(action_type);
CREATE INDEX idx_audit_logs_resource_type ON audit_logs(resource_type);
CREATE INDEX idx_audit_logs_status ON audit_logs(status);

1.2 操作类型分类

操作类型	操作子类型	描述	示例
`auth`	`login`, `logout`, `token_refresh`	认证相关操作	用户登录、登出
`device`	`create`, `update`, `delete`, `status_check`, `import`	设备管理操作	创建设备、更新设备信息
`olt`	`create`, `update`, `delete`, `port_enable`, `port_disable`	OLT管理操作	启用/关闭OLT端口
`user`	`create`, `update`, `delete`, `role_change`	用户管理操作	创建用户、修改角色
`system`	`config_update`, `task_trigger`, `cleanup`	系统操作	触发状态检查、清理任务
`inventory`	`stock_in`, `stock_out`, `transfer`, `count`	库存管理操作	入库、出库、盘点

2. 文件存储设计

2.1 目录结构

logs/
├── audit/                          # 审计日志目录
│   ├── 2025-04-05/                # 按日期分目录
│   │   ├── auth/                  # 按操作类型分子目录
│   │   │   ├── login_20250405193500_user123_abc123.json
│   │   │   └── logout_20250405194000_user456_def456.json
│   │   ├── device/
│   │   ├── olt/
│   │   └── ...
│   ├── 2025-04-06/
│   └── ...
├── app/                           # 应用日志目录
│   └── app.log
└── celery/                        # Celery任务日志目录
    └── celery.log

2.2 详细日志文件格式（JSON）

{
  "log_id": "abc123def456",
  "audit_log_id": 12345,
  "timestamp": "2025-04-05T19:35:00+08:00",
  "user": {
    "id": "user123",
    "username": "张三",
    "role": "admin",
    "ip_address": "192.168.1.100"
  },
  "action": {
    "type": "olt_port_enable",
    "subtype": "port_operation",
    "description": "启用OLT端口",
    "resource": {
      "type": "olt_port",
      "id": "olt-1-port-2",
      "name": "OLT-1端口2"
    }
  },
  "request": {
    "method": "POST",
    "path": "/api/olt/1/port/2/enable",
    "headers": {
      "user-agent": "Mozilla/5.0...",
      "content-type": "application/json"
    },
    "body": {
      "reason": "设备上线",
      "operator": "张三"
    },
    "query_params": {}
  },
  "response": {
    "status_code": 200,
    "body": {
      "success": true,
      "message": "端口启用成功",
      "data": {
        "port_id": "olt-1-port-2",
        "status": "enabled",
        "enabled_at": "2025-04-05T19:35:00+08:00"
      }
    }
  },
  "execution": {
    "duration_ms": 1250,
    "start_time": "2025-04-05T19:34:58.750+08:00",
    "end_time": "2025-04-05T19:35:00.000+08:00"
  },
  "system": {
    "service": "backend",
    "version": "v0.7.0",
    "environment": "production"
  }
}

3. 组件设计

3.1 审计日志中间件 (`audit_middleware.py`)

功能：

拦截所有API请求（排除健康检查、文档等）
提取请求和响应信息
异步发送日志到任务队列

关键特性：

支持请求体读取（JSON格式）
支持响应体捕获
异常处理，不影响主流程
性能监控（记录执行时间）

3.2 审计日志服务 (`audit_service.py`)

功能：

解析日志数据，确定操作类型
创建数据库记录
保存详细日志到文件系统
提供查询接口

关键方法：

create_audit_log(): 创建日志记录
query_logs(): 查询日志（支持多条件筛选）
cleanup_old_logs(): 清理90天前的日志
export_logs(): 导出日志

3.3 Celery任务 (`audit_tasks.py`)

功能：

异步处理日志记录
定期清理任务
日志归档任务

任务列表：

create_audit_log_task: 创建审计日志
cleanup_audit_logs_task: 清理旧日志（每天执行）
archive_audit_logs_task: 归档日志（每月执行）

3.4 API接口 (`audit_api.py`)

端点设计：

端点	方法	描述	权限
`/api/audit/logs`	GET	查询审计日志	超级管理员
`/api/audit/logs/{id}`	GET	获取单条日志详情	超级管理员
`/api/audit/logs/export`	POST	导出日志	超级管理员
`/api/audit/stats`	GET	获取日志统计	超级管理员

查询参数：

start_time: 开始时间
end_time: 结束时间
user_id: 用户ID
action_type: 操作类型
resource_type: 资源类型
status: 状态（success/failed/error）
page: 页码
page_size: 每页数量

4. 前端界面设计

4.1 日志查询页面

功能：

时间范围选择器
多条件筛选（用户、操作类型、状态等）
分页显示
导出功能

界面元素：

查询条件表单
日志列表表格
分页控件
导出按钮

4.2 日志详情页面

功能：

显示日志详细信息
查看详细日志文件内容
操作回放（显示请求和响应）

实施步骤

阶段一：基础框架搭建（1-2天）

创建数据库模型
- 创建 audit_logs 表
- 添加数据库迁移
实现基础服务
- 创建 AuditService 类
- 实现日志创建和存储逻辑
配置Docker
- 更新 docker-compose.yml 日志映射
- 确保目录权限正确

阶段二：中间件和异步处理（2-3天）

实现审计中间件
- 创建 AuditMiddleware
- 集成到FastAPI应用
实现Celery任务
- 创建审计日志任务
- 配置任务队列
测试异步流程
- 验证日志记录不阻塞主流程
- 测试异常处理

阶段三：查询接口和界面（2-3天）

实现API接口
- 创建审计日志查询端点
- 实现多条件筛选
开发前端界面
- 创建日志查询页面
- 实现筛选和分页功能
实现导出功能
- 支持JSON/CSV格式导出
- 批量导出功能

阶段四：清理和优化（1-2天）

实现自动清理
- 创建清理任务
- 测试清理逻辑
性能优化
- 数据库查询优化
- 文件IO优化
监控和告警
- 添加日志记录监控
- 设置磁盘空间告警

配置要求

环境变量

# 审计日志配置
AUDIT_LOG_ENABLED=true
AUDIT_LOG_RETENTION_DAYS=90
AUDIT_LOG_DIR=/app/logs/audit
AUDIT_LOG_LEVEL=INFO

# Celery配置
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

Docker配置更新

services:
  backend:
    build: ./backend
    volumes:
      - ./backend/logs:/app/logs  # 应用日志
      - ./logs/audit:/app/logs/audit  # 审计日志专用目录
    environment:
      - AUDIT_LOG_ENABLED=true
      - AUDIT_LOG_DIR=/app/logs/audit

测试方案

单元测试

服务层测试
- 测试 AuditService.create_audit_log()
- 测试 AuditService.query_logs()
- 测试 AuditService.cleanup_old_logs()
中间件测试
- 测试请求拦截
- 测试异常处理
- 测试性能影响

集成测试

端到端测试
- 模拟用户操作，验证日志记录
- 测试查询接口
- 测试导出功能
性能测试
- 高并发下的日志记录性能
- 大数据量下的查询性能

验收测试

功能验收
- 验证所有操作类型都被记录
- 验证查询功能正常工作
- 验证清理功能按预期工作
非功能验收
- 性能：日志记录不影响API响应时间（<50ms）
- 可靠性：日志不丢失，可追溯
- 安全性：只有超级管理员可访问

维护和监控

日常维护

磁盘空间监控
- 监控日志目录大小
- 设置磁盘使用率告警（>80%）
性能监控
- 监控日志记录延迟
- 监控数据库查询性能
定期检查
- 每周检查清理任务执行情况
- 每月检查日志完整性

故障处理

日志记录失败
- 检查Celery worker状态
- 检查磁盘空间
- 检查文件权限
查询性能下降
- 优化数据库索引
- 增加查询缓存
- 考虑分表策略

扩展性考虑

未来扩展

实时告警
- 敏感操作实时通知
- 异常模式检测
日志分析
- 操作趋势分析
- 用户行为分析
审计报告
- 定期生成审计报告
- 合规性报告

性能优化

数据库优化
- 分区表（按时间分区）
- 读写分离
存储优化
- 压缩旧日志
- 冷热数据分离

风险评估和缓解措施

风险	影响	概率	缓解措施
磁盘空间不足	日志记录失败	中	1. 设置磁盘监控告警 2. 实现自动清理 3. 使用日志轮转
性能影响	API响应变慢	低	1. 异步处理 2. 批量写入 3. 性能测试
数据丢失	审计追溯失败	低	1. 双重存储（DB+文件） 2. 定期备份 3. 监控告警
安全风险	日志泄露	中	1. 严格权限控制 2. 日志加密存储 3. 访问审计

成功标准

功能完整性
- 所有用户操作都被记录
- 支持多条件查询
- 支持日志导出
性能指标
- 日志记录延迟 < 100ms
- 查询响应时间 < 2s（1000条记录）
- 系统资源占用 < 5%
可靠性
- 日志不丢失率 > 99.9%
- 自动清理任务成功率 100%
- 系统可用性 > 99.5%

附录

A. 文件清单

backend/
├── app/
│   ├── models/
│   │   └── audit_log.py          # 审计日志模型
│   ├── middleware/
│   │   └── audit_middleware.py   # 审计中间件
│   ├── services/
│   │   └── audit_service.py      # 审计服务
│   ├── tasks/
│   │   └── audit_tasks.py        # Celery任务
│   ├── api/
│   │   └── v1/
│   │       └── audit.py          # 审计API
│   └── core/
│       └── config.py             # 配置更新
├── alembic/
│   └── versions/                 # 数据库迁移文件
└── tests/
    └── test_audit.py             # 测试文件

frontend/
└── src/
    ├── views/
    │   └── AuditLogView.vue      # 审计日志页面
    ├── api/
    │   └── audit.js              # 审计API调用
    └── stores/
        └── audit.js              # 审计状态管理

B. 依赖更新

后端依赖：

# requirements.txt 新增
python-json-logger==2.0.7
celery==5.3.4
redis==5.0.1

前端依赖：

// package.json 新增
"date-fns": "^3.0.0",
"xlsx": "^0.18.5"

C. 部署检查清单

数据库迁移已执行
环境变量已配置
Docker卷映射已更新
目录权限已设置
Celery worker已启动
清理任务已调度

13 KiB Raw Blame History Unescape Escape