H3ConuMS-v2/审计日志系统设计方案.md

# 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已启动
- [ ] 清理任务已调度
-