wecom_it_smart_desk/docs/安全审计报告.md

# IT智能服务台 — 安全审计报告

> **编制日期**: 2026-06-14
> **版本**: v1.0

---

## 1. 系统概述

| 项目 | 说明 |
|------|------|
| 系统名称 | IT智能服务台 |
| 部署环境 | 企业内网 (10.90.5.110) |
| 访问方式 | 企微工作台应用 / HTTPS |
| 用户规模 | ~6000人 |

---

## 2. 安全架构

### 2.1 认证与授权

| 特性 | 实现方式 | 状态 |
|------|----------|------|
| **身份认证** | 企微OAuth2 + JWT Token | ✅ 已实现 |
| **OTP双因素** | TOTP (Google Authenticator) | ✅ 已实现 |
| **角色权限** | RBAC (user/agent/admin) | ✅ 已实现 |
| **会话管理** | Redis Token + 过期时间 | ✅ 已实现 |
| **密码策略** | 企微账户策略 | ✅ 依赖企微 |

### 2.2 网络安全

| 特性 | 实现方式 | 状态 |
|------|----------|------|
| **HTTPS** | Nginx SSL终止 | ✅ 已配置 |
| **CORS** | 白名单域名 | ✅ 已配置 |
| **IP白名单** | Nginx allow/deny | ⚠️ 待配置 |
| **API限流** | Nginx rate_limit | ⚠️ 待配置 |
| **WAF** | 腾讯WAF | ✅ 已接入 |

### 2.3 数据安全

| 特性 | 实现方式 | 状态 |
|------|----------|------|
| **数据库** | PostgreSQL (内网) | ✅ 已实现 |
| **传输加密** | TLS 1.2+ | ✅ 已配置 |
| **敏感脱敏** | 日志脱敏 | ⚠️ 待实现 |
| **备份策略** | 定时备份 | ⚠️ 待配置 |
| **加密存储** | 字段加密 | ❌ MVP不考虑 |

### 2.4 应用安全

| 特性 | 实现方式 | 状态 |
|------|----------|------|
| **SQL注入** | SQLAlchemy ORM | ✅ 已防护 |
| **XSS** | 前端转义 | ✅ 已实现 |
| **CSRF** | JWT Token | ✅ 已防护 |
| **文件上传** | 类型限制 + 存储隔离 | ✅ 已实现 |
| **API认证** | Token验证 | ✅ 已实现 |

---

## 3. 审计日志

### 3.1 已记录事件

| 事件 | 记录位置 | 状态 |
|------|----------|------|
| 登录/登出 | 日志 | ✅ |
| 消息发送 | 数据库 + 日志 | ✅ |
| 会话创建/关闭 | 数据库 + 日志 | ✅ |
| 管理员操作 | 日志 | ✅ |
| 配置变更 | 数据库 | ✅ |

### 3.2 待记录事件

| 事件 | 优先级 | 说明 |
|------|--------|------|
| **敏感数据查询** | P1 | 查询用户信息、联系方式 |
| **角色变更** | P1 | 管理员分配权限 |
| **系统配置变更** | P1 | 功能开关、集成配置 |
| **API调用统计** | P2 | 接口调用频率 |
| **异常登录** | P1 | 异地登录、频繁失败 |

---

## 4. 安全检查项

### 4.1 MVP必须通过

| # | 检查项 | 当前状态 | 建议 |
|---|--------|----------|------|
| 1 | 企微OAuth2认证 | ✅ | - |
| 2 | JWT Token有效期 | ✅ 2小时 | - |
| 3 | OTP绑定/验证 | ✅ | - |
| 4 | 角色权限控制 | ✅ | - |
| 5 | 数据库内网访问 | ✅ | - |
| 6 | HTTPS全站加密 | ✅ | - |
| 7 | 日志脱敏 | ⚠️ | 上线前完成 |
| 8 | IP访问限制 | ⚠️ | 上线前完成 |

### 4.2 生产建议项

| # | 检查项 | 优先级 | 说明 |
|---|--------|--------|------|
| 9 | API限流 | P2 | 防DDoS |
| 10 | 操作审计日志 | P2 | 合规要求 |
| 11 | 数据库定时备份 | P2 | 灾备 |
| 12 | 入侵检测 | P3 | 长期 |

---

## 5. 消息状态功能（待实现）

### 5.1 需求

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 已读未读状态 | 每条消息独立跟踪已读/未读 | P2 |
| 已读时间戳 | 记录何时已读 | P2 |
| 已读回执推送 | WS实时推送已读状态 | P2 |
| 未读计数 | 会话未读消息数 | P2 |

### 5.2 现有代码

```python
# 当前 Message 模型
is_read: bool  # 单字段，只能记录"是否已读"
```

问题：多用户场景下无法区分用户独立已读状态

### 5.3 实现方案

```python
# 新增 MessageStatus 表
class MessageStatus(Base):
    message_id: str
    user_id: str      # 读取者ID
    user_type: str   # employee/agent
    status: Enum    # sent/delivered/read
    read_at: datetime
```

### 5.4 API设计

| API | 方法 | 说明 |
|-----|------|------|
| `/api/messages/{id}/read` | PUT | 标记消息已读 |
| `/api/messages/{id}/status` | GET | 获取消息状态 |
| `/api/conversations/{id}/unread-count` | GET | 未读计数 |

---

## 6. 风险评估

| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| 企微API限制 | 中 | 保持降级通道 |
| 内网暴露面 | 中 | IP白名单 |
| 社工攻击 | 低 | OTP + 安全培训 |
| 数据泄露 | 低 | 内网 + HTTPS |

---

## 7. 架构优化（2026-06-14 讨论）

### 7.1 高可用方案

| 特性 | 状态 | 说明 |
|------|------|------|
| restart: unless-stopped | ✅ 已配置 | 容器崩溃自动重启 |
| healthcheck 后端 | ✅ 已配置 | curl /health |
| healthcheck nginx | ✅ 已配置 | curl /itdesk/health |
| healthcheck postgres | ✅ 已配置 | pg_isready |
| healthcheck redis | ✅ 已配置 | redis-cli ping |

### 7.2 AI Gateway 设计

| 特性 | 状态 | 说明 |
|------|------|------|
| 内部抽象 | ⚠️ 待实现 | 抽离 AI 层为 Gateway |
| 多模型支持 | ⚠️ 待实现 | dify/wingman/其他 |
| 热切换 | ⚠️ 待实现 | 配置化切换 |
| 降级机制 | ⚠️ 待实现 | 失败自动切换 |

设计目标：
- 统一入口，支持 dify/wingman/其他模型
- 配置化启用/禁用，无需改代码
- 失败自动降级到备用模型

---

## 8. 结论

### 8.1 MVP可上线条件

- [x] 企微OAuth2认证
- [x] OTP双因素
- [x] 角色权限
- [x] HTTPS
- [x] Docker健康检查+自动重启
- [ ] 日志脱敏（上线前完成）
- [ ] IP访问限制（上线前完成）
- [ ] AI Gateway（V2前完成）

### 8.2 下一步行动

| 行动 | 负责人 | 截止 | 状态 |
|------|--------|------|------|
| 日志脱敏 | 开发 | 上线前 | pending |
| IP白名单 | 运维 | 上线前 | pending |
| AI Gateway | 开发 | V2前 | pending |
| 消息状态功能 | 开发 | V2 | pending |

---

> **编制人**: 宋献
> **审核人**: 待定
> **更新日期**: 2026-06-14