```
feat(auth): 添加用户权限获取接口并完善JWT令牌角色信息 - 在JWT令牌中添加用户角色信息 - 新增get_my_permissions接口用于获取当前用户权限码列表 - 重构认证回调逻辑，增加错误日志记录 - 更新用户信息获取接口使用Authorization头验证 ```
This commit is contained in:
+535
@@ -0,0 +1,535 @@
|
||||
# H3C ONU设备管理系统 - 审计日志系统设计方案
|
||||
|
||||
## 项目概述
|
||||
|
||||
本方案为 H3C ONU 设备管理系统设计一套完整的审计日志系统，用于记录所有用户操作（手动和自动触发），支持误操作恢复和问责追溯。
|
||||
|
||||
## 设计目标
|
||||
|
||||
1. **全面记录**：记录所有用户操作，包括认证、设备管理、OLT端口操作等
|
||||
2. **详细审计**：记录操作详情（用户、时间、IP、参数、结果等）
|
||||
3. **快速查询**：提供超级管理员查询界面
|
||||
4. **长期存储**：日志保留90天，支持自动清理
|
||||
5. **性能友好**：异步执行，不影响主业务流程
|
||||
6. **Docker友好**：支持容器化部署，日志映射到宿主机
|
||||
|
||||
## 系统架构
|
||||
|
||||
### 整体架构图
|
||||
|
||||
```
|
||||
用户操作 → API请求 → 审计日志中间件 → 异步任务队列 →
|
||||
↓
|
||||
[数据库] 记录核心信息 + [文件系统] 记录详细日志
|
||||
↓
|
||||
查询界面 ← 日志服务 ← 定期清理任务
|
||||
```
|
||||
|
||||
### 技术栈
|
||||
- **后端框架**：FastAPI + SQLAlchemy + Celery
|
||||
- **数据库**：PostgreSQL（核心信息）+ 文件系统（详细日志）
|
||||
- **消息队列**：Redis（Celery broker）
|
||||
- **存储**：Docker卷映射到宿主机
|
||||
|
||||
## 详细设计
|
||||
|
||||
### 1. 数据库设计
|
||||
|
||||
#### 1.1 审计日志表 (`audit_logs`)
|
||||
|
||||
```sql
|
||||
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）
|
||||
|
||||
```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天）
|
||||
|
||||
1. **创建数据库模型**
|
||||
- 创建 `audit_logs` 表
|
||||
- 添加数据库迁移
|
||||
|
||||
2. **实现基础服务**
|
||||
- 创建 `AuditService` 类
|
||||
- 实现日志创建和存储逻辑
|
||||
|
||||
3. **配置Docker**
|
||||
- 更新 `docker-compose.yml` 日志映射
|
||||
- 确保目录权限正确
|
||||
|
||||
### 阶段二：中间件和异步处理（2-3天）
|
||||
|
||||
1. **实现审计中间件**
|
||||
- 创建 `AuditMiddleware`
|
||||
- 集成到FastAPI应用
|
||||
|
||||
2. **实现Celery任务**
|
||||
- 创建审计日志任务
|
||||
- 配置任务队列
|
||||
|
||||
3. **测试异步流程**
|
||||
- 验证日志记录不阻塞主流程
|
||||
- 测试异常处理
|
||||
|
||||
### 阶段三：查询接口和界面（2-3天）
|
||||
|
||||
1. **实现API接口**
|
||||
- 创建审计日志查询端点
|
||||
- 实现多条件筛选
|
||||
|
||||
2. **开发前端界面**
|
||||
- 创建日志查询页面
|
||||
- 实现筛选和分页功能
|
||||
|
||||
3. **实现导出功能**
|
||||
- 支持JSON/CSV格式导出
|
||||
- 批量导出功能
|
||||
|
||||
### 阶段四：清理和优化（1-2天）
|
||||
|
||||
1. **实现自动清理**
|
||||
- 创建清理任务
|
||||
- 测试清理逻辑
|
||||
|
||||
2. **性能优化**
|
||||
- 数据库查询优化
|
||||
- 文件IO优化
|
||||
|
||||
3. **监控和告警**
|
||||
- 添加日志记录监控
|
||||
- 设置磁盘空间告警
|
||||
|
||||
## 配置要求
|
||||
|
||||
### 环境变量
|
||||
|
||||
```bash
|
||||
# 审计日志配置
|
||||
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配置更新
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
## 测试方案
|
||||
|
||||
### 单元测试
|
||||
|
||||
1. **服务层测试**
|
||||
- 测试 `AuditService.create_audit_log()`
|
||||
- 测试 `AuditService.query_logs()`
|
||||
- 测试 `AuditService.cleanup_old_logs()`
|
||||
|
||||
2. **中间件测试**
|
||||
- 测试请求拦截
|
||||
- 测试异常处理
|
||||
- 测试性能影响
|
||||
|
||||
### 集成测试
|
||||
|
||||
1. **端到端测试**
|
||||
- 模拟用户操作，验证日志记录
|
||||
- 测试查询接口
|
||||
- 测试导出功能
|
||||
|
||||
2. **性能测试**
|
||||
- 高并发下的日志记录性能
|
||||
- 大数据量下的查询性能
|
||||
|
||||
### 验收测试
|
||||
|
||||
1. **功能验收**
|
||||
- 验证所有操作类型都被记录
|
||||
- 验证查询功能正常工作
|
||||
- 验证清理功能按预期工作
|
||||
|
||||
2. **非功能验收**
|
||||
- 性能：日志记录不影响API响应时间（<50ms）
|
||||
- 可靠性：日志不丢失，可追溯
|
||||
- 安全性：只有超级管理员可访问
|
||||
|
||||
## 维护和监控
|
||||
|
||||
### 日常维护
|
||||
|
||||
1. **磁盘空间监控**
|
||||
- 监控日志目录大小
|
||||
- 设置磁盘使用率告警（>80%）
|
||||
|
||||
2. **性能监控**
|
||||
- 监控日志记录延迟
|
||||
- 监控数据库查询性能
|
||||
|
||||
3. **定期检查**
|
||||
- 每周检查清理任务执行情况
|
||||
- 每月检查日志完整性
|
||||
|
||||
### 故障处理
|
||||
|
||||
1. **日志记录失败**
|
||||
- 检查Celery worker状态
|
||||
- 检查磁盘空间
|
||||
- 检查文件权限
|
||||
|
||||
2. **查询性能下降**
|
||||
- 优化数据库索引
|
||||
- 增加查询缓存
|
||||
- 考虑分表策略
|
||||
|
||||
## 扩展性考虑
|
||||
|
||||
### 未来扩展
|
||||
|
||||
1. **实时告警**
|
||||
- 敏感操作实时通知
|
||||
- 异常模式检测
|
||||
|
||||
2. **日志分析**
|
||||
- 操作趋势分析
|
||||
- 用户行为分析
|
||||
|
||||
3. **审计报告**
|
||||
- 定期生成审计报告
|
||||
- 合规性报告
|
||||
|
||||
### 性能优化
|
||||
|
||||
1. **数据库优化**
|
||||
- 分区表（按时间分区）
|
||||
- 读写分离
|
||||
|
||||
2. **存储优化**
|
||||
- 压缩旧日志
|
||||
- 冷热数据分离
|
||||
|
||||
## 风险评估和缓解措施
|
||||
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|----------|
|
||||
| 磁盘空间不足 | 日志记录失败 | 中 | 1. 设置磁盘监控告警<br>2. 实现自动清理<br>3. 使用日志轮转 |
|
||||
| 性能影响 | API响应变慢 | 低 | 1. 异步处理<br>2. 批量写入<br>3. 性能测试 |
|
||||
| 数据丢失 | 审计追溯失败 | 低 | 1. 双重存储（DB+文件）<br>2. 定期备份<br>3. 监控告警 |
|
||||
| 安全风险 | 日志泄露 | 中 | 1. 严格权限控制<br>2. 日志加密存储<br>3. 访问审计 |
|
||||
|
||||
## 成功标准
|
||||
|
||||
1. **功能完整性**
|
||||
- 所有用户操作都被记录
|
||||
- 支持多条件查询
|
||||
- 支持日志导出
|
||||
|
||||
2. **性能指标**
|
||||
- 日志记录延迟 < 100ms
|
||||
- 查询响应时间 < 2s（1000条记录）
|
||||
- 系统资源占用 < 5%
|
||||
|
||||
3. **可靠性**
|
||||
- 日志不丢失率 > 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. 依赖更新
|
||||
|
||||
**后端依赖**：
|
||||
```txt
|
||||
# requirements.txt 新增
|
||||
python-json-logger==2.0.7
|
||||
celery==5.3.4
|
||||
redis==5.0.1
|
||||
```
|
||||
|
||||
**前端依赖**：
|
||||
```json
|
||||
// package.json 新增
|
||||
"date-fns": "^3.0.0",
|
||||
"xlsx": "^0.18.5"
|
||||
```
|
||||
|
||||
### C. 部署检查清单
|
||||
|
||||
- [ ] 数据库迁移已执行
|
||||
- [ ] 环境变量已配置
|
||||
- [ ] Docker卷映射已更新
|
||||
- [ ] 目录权限已设置
|
||||
- [ ] Celery worker已启动
|
||||
- [ ] 清理任务已调度
|
||||
-
|
||||
Reference in New Issue
Block a user