# taiji-AI-PAD 认证及后台管理系统设计文档

**版本**: v1.0  
**创建时间**: 2025年12月22日  
**设计者**: 项目组

---

## 📋 目录

1. [系统概述](#系统概述)
2. [架构设计](#架构设计)
3. [认证系统设计](#认证系统设计)
4. [权限管理系统](#权限管理系统)
5. [后台管理功能](#后台管理功能)
6. [API 设计](#api-设计)
7. [数据库设计](#数据库设计)
8. [安全设计](#安全设计)
9. [实施计划](#实施计划)

---

## 1. 系统概述

### 1.1 目标

构建一个完整的认证和后台管理系统，包括：
- 用户认证（登录、注册、密码管理）
- 基于角色的权限控制（RBAC）
- 后台管理界面和 API
- 审计日志和操作追踪
- API Key 管理
- 多租户支持

### 1.2 核心功能

#### 认证功能
- ✅ 用户注册/登录
- ✅ JWT Token 认证
- ✅ 密码加密存储（bcrypt）
- ✅ Token 刷新机制
- ✅ 密码重置
- ✅ 账户激活/禁用

#### 权限管理
- ✅ 基于角色的访问控制（RBAC）
- ✅ 权限粒度控制
- ✅ API Key 权限管理
- ✅ 资源级别的权限控制

#### 后台管理
- ✅ 用户管理（CRUD）
- ✅ Agent 管理
- ✅ 工具管理
- ✅ 系统监控
- ✅ 审计日志查看
- ✅ 计费管理
- ✅ 系统配置

---

## 2. 架构设计

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────┐
│                    前端层 (Admin UI)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │ 登录页面  │  │ 用户管理  │  │ Agent管理 │  │ 系统监控  │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
                        │ HTTPS
                        ▼
┌─────────────────────────────────────────────────────────┐
│                  API Gateway (Nginx)                     │
│              ┌──────────────────────────┐                │
│              │  认证中间件 (JWT验证)      │                │
│              │  权限检查中间件 (RBAC)     │                │
│              └──────────────────────────┘                │
└──────────────────────┬──────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│              MCP Server (FastAPI)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ 认证模块      │  │ 权限管理模块  │  │ 后台管理模块  │   │
│  │ - 登录/注册   │  │ - RBAC       │  │ - 用户管理    │   │
│  │ - JWT Token  │  │ - 权限检查    │  │ - Agent管理   │   │
│  │ - 密码管理    │  │ - API Key    │  │ - 系统监控    │   │
│  └──────────────┘  └──────────────┘  └──────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  PostgreSQL  │ │    Redis     │ │     NATS     │
│  - 用户数据   │ │  - Token缓存  │ │  - 事件发布   │
│  - 权限数据   │ │  - 会话管理   │ │  - 审计日志   │
│  - 审计日志   │ │  - 限流数据   │ │              │
└──────────────┘ └──────────────┘ └──────────────┘
```

### 2.2 模块划分

#### 2.2.1 认证模块 (`auth.py`)
- 用户注册/登录
- JWT Token 生成和验证
- 密码加密和验证
- Token 刷新
- 密码重置

#### 2.2.2 权限模块 (`permissions.py`)
- 角色定义和管理
- 权限检查装饰器
- API Key 权限验证
- 资源权限验证

#### 2.2.3 后台管理模块 (`admin.py`)
- 用户管理 API
- Agent 管理 API
- 工具管理 API
- 系统监控 API
- 审计日志 API

#### 2.2.4 审计模块 (`audit.py`)
- 操作日志记录
- 登录日志
- API 调用日志
- 异常日志

---

## 3. 认证系统设计

### 3.1 认证流程

#### 3.1.1 用户登录流程

```
用户 → 提交用户名/密码
  ↓
验证用户名和密码 (bcrypt)
  ↓
生成 JWT Token (包含用户ID、角色、权限)
  ↓
返回 Token 和用户信息
  ↓
客户端存储 Token (localStorage/cookie)
  ↓
后续请求携带 Token (Authorization Header)
  ↓
服务器验证 Token
  ↓
允许/拒绝访问
```

#### 3.1.2 Token 结构

```json
{
  "sub": "user_id",
  "username": "admin",
  "email": "admin@example.com",
  "roles": ["admin", "user"],
  "permissions": ["user:read", "user:write", "agent:manage"],
  "iat": 1234567890,
  "exp": 1234571490,
  "type": "access"  // access 或 refresh
}
```

### 3.2 密码安全

- **加密算法**: bcrypt (cost factor: 12)
- **密码要求**:
  - 最小长度: 8 字符
  - 必须包含: 大小写字母、数字
  - 可选: 特殊字符
- **密码重置**: 
  - 通过邮箱发送重置链接
  - 重置链接有效期: 1 小时
  - 使用临时 Token

### 3.3 Token 管理

- **Access Token**: 
  - 有效期: 60 分钟
  - 用途: API 访问认证
- **Refresh Token**:
  - 有效期: 7 天
  - 用途: 刷新 Access Token
  - 存储: Redis (可撤销)
- **Token 撤销**:
  - 登出时撤销 Refresh Token
  - 支持强制撤销所有 Token

---

## 4. 权限管理系统

### 4.1 角色定义

#### 4.1.1 系统角色

| 角色 | 描述 | 权限范围 |
|------|------|----------|
| **super_admin** | 超级管理员 | 所有权限 |
| **admin** | 管理员 | 用户管理、Agent管理、系统配置 |
| **developer** | 开发者 | Agent创建、工具使用、API调用 |
| **user** | 普通用户 | 基础功能、自己的Agent |
| **viewer** | 只读用户 | 查看权限，无修改权限 |

#### 4.1.2 权限定义

```
资源:操作 格式

用户权限:
- user:read      - 查看用户
- user:write     - 创建/修改用户
- user:delete    - 删除用户
- user:manage    - 完整用户管理

Agent权限:
- agent:read     - 查看Agent
- agent:write    - 创建/修改Agent
- agent:delete   - 删除Agent
- agent:execute  - 执行Agent
- agent:manage   - 完整Agent管理

工具权限:
- tool:read      - 查看工具
- tool:write     - 创建/修改工具
- tool:delete    - 删除工具
- tool:use       - 使用工具

系统权限:
- system:read    - 查看系统信息
- system:config  - 系统配置
- system:monitor - 系统监控
- audit:read     - 查看审计日志
```

### 4.2 权限检查机制

#### 4.2.1 装饰器方式

```python
@require_permission("agent:manage")
async def create_agent(...):
    pass

@require_role("admin")
async def admin_function(...):
    pass
```

#### 4.2.2 依赖注入方式

```python
from auth import get_current_user, require_permission

async def endpoint(
    current_user: User = Depends(get_current_user),
    _: None = Depends(require_permission("agent:read"))
):
    pass
```

### 4.3 API Key 权限

- **API Key 类型**:
  - `readonly`: 只读权限
  - `write`: 读写权限
  - `admin`: 管理员权限
- **API Key 限制**:
  - 速率限制
  - IP 白名单
  - 过期时间

---

## 5. 后台管理功能

### 5.1 用户管理

#### 功能列表
- ✅ 用户列表（分页、搜索、筛选）
- ✅ 创建用户
- ✅ 编辑用户信息
- ✅ 禁用/启用用户
- ✅ 重置用户密码
- ✅ 查看用户详情
- ✅ 用户权限管理
- ✅ 用户 Agent 列表
- ✅ 用户使用统计

#### 数据展示
- 用户基本信息
- 注册时间、最后登录时间
- 状态（活跃/禁用）
- 角色和权限
- Agent 数量
- API 调用统计

### 5.2 Agent 管理

#### 功能列表
- ✅ Agent 列表（分页、搜索、筛选）
- ✅ 查看 Agent 详情
- ✅ 编辑 Agent 配置
- ✅ 启用/禁用 Agent
- ✅ 删除 Agent
- ✅ Agent 执行历史
- ✅ Agent 性能统计
- ✅ Agent 权限管理

#### 数据展示
- Agent 基本信息
- 所属用户
- 状态和版本
- 执行统计（总数、成功率、平均耗时）
- 工具列表
- 配置信息

### 5.3 工具管理

#### 功能列表
- ✅ 工具列表（分页、搜索、筛选）
- ✅ 工具详情查看
- ✅ 工具分类管理
- ✅ 工具权限配置
- ✅ 工具使用统计
- ✅ 工具健康检查

### 5.4 系统监控

#### 功能列表
- ✅ 系统健康状态
- ✅ 服务运行状态（Redis、NATS、数据库）
- ✅ 实时指标（请求数、响应时间、错误率）
- ✅ 资源使用情况（CPU、内存、磁盘）
- ✅ 活跃用户数
- ✅ API 调用统计
- ✅ 错误日志查看

### 5.5 审计日志

#### 功能列表
- ✅ 操作日志列表（分页、搜索、筛选）
- ✅ 登录日志
- ✅ API 调用日志
- ✅ 异常日志
- ✅ 日志导出
- ✅ 日志统计分析

#### 日志内容
- 操作时间
- 操作用户
- 操作类型
- 操作对象
- 操作结果
- IP 地址
- User Agent

### 5.6 计费管理

#### 功能列表
- ✅ 用户计费记录
- ✅ 计费统计
- ✅ 账单生成
- ✅ 配额管理
- ✅ 使用量统计

---

## 6. API 设计

### 6.1 认证 API

#### 6.1.1 用户注册
```
POST /api/v1/auth/register
Request:
{
  "username": "string",
  "email": "string",
  "password": "string",
  "full_name": "string"
}
Response:
{
  "user_id": "uuid",
  "username": "string",
  "email": "string",
  "message": "注册成功"
}
```

#### 6.1.2 用户登录
```
POST /api/v1/auth/login
Request:
{
  "username": "string",
  "password": "string"
}
Response:
{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "uuid",
    "username": "string",
    "email": "string",
    "roles": ["string"],
    "permissions": ["string"]
  }
}
```

#### 6.1.3 Token 刷新
```
POST /api/v1/auth/refresh
Headers:
  Authorization: Bearer <refresh_token>
Response:
{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 3600
}
```

#### 6.1.4 用户登出
```
POST /api/v1/auth/logout
Headers:
  Authorization: Bearer <access_token>
Response:
{
  "message": "登出成功"
}
```

#### 6.1.5 密码重置
```
POST /api/v1/auth/password/reset
Request:
{
  "email": "string"
}
Response:
{
  "message": "重置链接已发送到邮箱"
}

POST /api/v1/auth/password/reset/confirm
Request:
{
  "token": "string",
  "new_password": "string"
}
Response:
{
  "message": "密码重置成功"
}
```

### 6.2 后台管理 API

#### 6.2.1 用户管理
```
GET    /api/v1/admin/users              # 用户列表
GET    /api/v1/admin/users/{user_id}    # 用户详情
POST   /api/v1/admin/users               # 创建用户
PUT    /api/v1/admin/users/{user_id}     # 更新用户
DELETE /api/v1/admin/users/{user_id}     # 删除用户
POST   /api/v1/admin/users/{user_id}/disable  # 禁用用户
POST   /api/v1/admin/users/{user_id}/enable   # 启用用户
POST   /api/v1/admin/users/{user_id}/reset-password  # 重置密码
GET    /api/v1/admin/users/{user_id}/agents    # 用户Agent列表
GET    /api/v1/admin/users/{user_id}/stats     # 用户统计
```

#### 6.2.2 Agent 管理
```
GET    /api/v1/admin/agents              # Agent列表
GET    /api/v1/admin/agents/{agent_id}  # Agent详情
PUT    /api/v1/admin/agents/{agent_id}   # 更新Agent
DELETE /api/v1/admin/agents/{agent_id}   # 删除Agent
POST   /api/v1/admin/agents/{agent_id}/disable  # 禁用Agent
POST   /api/v1/admin/agents/{agent_id}/enable   # 启用Agent
GET    /api/v1/admin/agents/{agent_id}/executions  # 执行历史
GET    /api/v1/admin/agents/{agent_id}/stats      # 性能统计
```

#### 6.2.3 系统监控
```
GET    /api/v1/admin/system/health      # 系统健康
GET    /api/v1/admin/system/metrics     # 系统指标
GET    /api/v1/admin/system/stats       # 系统统计
GET    /api/v1/admin/system/logs        # 系统日志
```

#### 6.2.4 审计日志
```
GET    /api/v1/admin/audit/logs         # 审计日志列表
GET    /api/v1/admin/audit/logs/{log_id} # 日志详情
GET    /api/v1/admin/audit/login-logs   # 登录日志
GET    /api/v1/admin/audit/api-logs     # API调用日志
GET    /api/v1/admin/audit/error-logs   # 错误日志
POST   /api/v1/admin/audit/logs/export  # 导出日志
```

---

## 7. 数据库设计

### 7.1 用户表 (users) - 已有

```sql
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    hashed_password VARCHAR(255) NOT NULL,
    full_name VARCHAR(100),
    is_active BOOLEAN DEFAULT TRUE,
    is_admin BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

### 7.2 角色表 (roles) - 新增

```sql
CREATE TABLE roles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(50) UNIQUE NOT NULL,
    description TEXT,
    is_system BOOLEAN DEFAULT FALSE,  -- 系统角色不可删除
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

### 7.3 权限表 (permissions) - 新增

```sql
CREATE TABLE permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    resource VARCHAR(50) NOT NULL,  -- user, agent, tool, system
    action VARCHAR(50) NOT NULL,    -- read, write, delete, manage
    description TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(resource, action)
);
```

### 7.4 用户角色关联表 (user_roles) - 新增

```sql
CREATE TABLE user_roles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    assigned_at TIMESTAMP DEFAULT NOW(),
    assigned_by UUID REFERENCES users(id),
    UNIQUE(user_id, role_id)
);
```

### 7.5 角色权限关联表 (role_permissions) - 新增

```sql
CREATE TABLE role_permissions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    permission_id UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
    granted_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(role_id, permission_id)
);
```

### 7.6 API Key 表 (api_keys) - 已有，需增强

```sql
CREATE TABLE api_keys (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    key_hash VARCHAR(255) NOT NULL,  -- 存储哈希值
    name VARCHAR(100),  -- Key名称
    permissions JSONB,  -- 权限列表
    rate_limit INTEGER DEFAULT 100,  -- 速率限制
    ip_whitelist TEXT[],  -- IP白名单
    expires_at TIMESTAMP,  -- 过期时间
    last_used_at TIMESTAMP,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

### 7.7 审计日志表 (audit_logs) - 已有，需增强

```sql
CREATE TABLE audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    action VARCHAR(50) NOT NULL,  -- login, logout, create, update, delete
    resource_type VARCHAR(50),  -- user, agent, tool, system
    resource_id UUID,
    details JSONB,  -- 详细信息
    ip_address INET,
    user_agent TEXT,
    status VARCHAR(20),  -- success, failure, error
    error_message TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

## 8. 安全设计

### 8.1 认证安全

- **密码安全**:
  - bcrypt 加密（cost factor: 12）
  - 密码复杂度要求
  - 密码历史记录（防止重复使用）
- **Token 安全**:
  - JWT 签名验证
  - Token 过期时间
  - Refresh Token 轮换
  - Token 黑名单（Redis）

### 8.2 权限安全

- **最小权限原则**: 默认无权限，需要显式授权
- **权限继承**: 角色权限可继承
- **资源级权限**: 支持资源级别的权限控制
- **API Key 安全**:
  - Key 哈希存储
  - 速率限制
  - IP 白名单
  - 过期时间

### 8.3 数据安全

- **SQL 注入防护**: 使用 ORM 参数化查询
- **XSS 防护**: 输入验证和输出转义
- **CSRF 防护**: Token 验证
- **敏感数据加密**: 
  - 密码: bcrypt
  - API Key: 哈希存储
  - 配置信息: 环境变量

### 8.4 审计安全

- **操作日志**: 所有关键操作记录
- **登录日志**: 记录所有登录尝试
- **异常监控**: 记录异常和错误
- **日志保留**: 至少保留 90 天

---

## 9. 实施计划

### 9.1 第一阶段：基础认证（1-2天）

**任务清单**:
- [ ] 创建认证模块 (`auth.py`)
  - [ ] 密码加密和验证函数
  - [ ] JWT Token 生成和验证
  - [ ] 登录/注册 API
  - [ ] Token 刷新 API
- [ ] 创建认证中间件
  - [ ] JWT 验证中间件
  - [ ] 用户信息注入
- [ ] 更新数据库模型
  - [ ] 确认 User 模型
  - [ ] 创建 Role、Permission 模型
  - [ ] 创建关联表
- [ ] 创建认证 API 端点
  - [ ] POST /api/v1/auth/register
  - [ ] POST /api/v1/auth/login
  - [ ] POST /api/v1/auth/refresh
  - [ ] POST /api/v1/auth/logout

**预计工作量**: 1-2 天

### 9.2 第二阶段：权限管理（2-3天）

**任务清单**:
- [ ] 创建权限模块 (`permissions.py`)
  - [ ] 角色定义和管理
  - [ ] 权限检查装饰器
  - [ ] 权限验证函数
- [ ] 初始化系统角色和权限
  - [ ] 创建系统角色（super_admin, admin, developer, user, viewer）
  - [ ] 创建系统权限
  - [ ] 分配角色权限
- [ ] 创建权限管理 API
  - [ ] 角色管理 API
  - [ ] 权限管理 API
  - [ ] 用户角色分配 API
- [ ] 实现权限检查中间件
  - [ ] 装饰器方式
  - [ ] 依赖注入方式

**预计工作量**: 2-3 天

### 9.3 第三阶段：后台管理 API（3-4天）

**任务清单**:
- [ ] 创建后台管理模块 (`admin.py`)
  - [ ] 用户管理 API
  - [ ] Agent 管理 API
  - [ ] 工具管理 API
  - [ ] 系统监控 API
- [ ] 实现审计日志模块 (`audit.py`)
  - [ ] 日志记录函数
  - [ ] 日志查询 API
  - [ ] 日志导出功能
- [ ] 创建后台管理 API 端点
  - [ ] 用户管理 API（CRUD）
  - [ ] Agent 管理 API
  - [ ] 系统监控 API
  - [ ] 审计日志 API

**预计工作量**: 3-4 天

### 9.4 第四阶段：API Key 管理（1-2天）

**任务清单**:
- [ ] 增强 API Key 功能
  - [ ] API Key 生成和验证
  - [ ] API Key 权限管理
  - [ ] API Key 速率限制
  - [ ] API Key IP 白名单
- [ ] 创建 API Key 管理 API
  - [ ] 创建 API Key
  - [ ] 查看 API Key 列表
  - [ ] 更新 API Key
  - [ ] 删除 API Key
  - [ ] 撤销 API Key

**预计工作量**: 1-2 天

### 9.5 第五阶段：测试和优化（1-2天）

**任务清单**:
- [ ] 单元测试
  - [ ] 认证功能测试
  - [ ] 权限功能测试
  - [ ] 后台管理 API 测试
- [ ] 集成测试
  - [ ] 端到端测试
  - [ ] 安全测试
- [ ] 性能优化
  - [ ] 查询优化
  - [ ] 缓存优化
- [ ] 文档完善
  - [ ] API 文档
  - [ ] 使用示例

**预计工作量**: 1-2 天

### 9.6 总工作量估算

| 阶段 | 工作量 | 优先级 |
|------|--------|--------|
| 第一阶段：基础认证 | 1-2 天 | P0 |
| 第二阶段：权限管理 | 2-3 天 | P0 |
| 第三阶段：后台管理 API | 3-4 天 | P0 |
| 第四阶段：API Key 管理 | 1-2 天 | P1 |
| 第五阶段：测试和优化 | 1-2 天 | P0 |
| **总计** | **8-13 天** | - |

---

## 10. 技术选型

### 10.1 认证技术

- **JWT**: python-jose[cryptography]
- **密码加密**: passlib[bcrypt]
- **Token 存储**: Redis（用于刷新 Token 和黑名单）

### 10.2 权限管理

- **RBAC**: 自定义实现
- **权限检查**: FastAPI 依赖注入

### 10.3 数据库

- **ORM**: SQLAlchemy 2.0
- **数据库**: PostgreSQL
- **迁移工具**: Alembic

### 10.4 缓存

- **Redis**: Token 缓存、会话管理、限流

---

## 11. 后续扩展

### 11.1 OAuth 2.0 支持

- Google OAuth
- GitHub OAuth
- 企业 SSO

### 11.2 多因素认证 (MFA)

- TOTP (Time-based One-Time Password)
- 短信验证码
- 邮箱验证码

### 11.3 细粒度权限

- 资源级别的权限控制
- 动态权限分配
- 权限继承和覆盖

### 11.4 后台管理界面

- React/Vue 前端
- 实时监控面板
- 数据可视化

---

## 12. 风险评估

### 12.1 安全风险

- **Token 泄露**: 使用 HTTPS、Token 过期时间
- **密码泄露**: bcrypt 加密、密码复杂度要求
- **权限绕过**: 严格的权限检查、审计日志

### 12.2 性能风险

- **Token 验证性能**: Redis 缓存、JWT 验证优化
- **权限检查性能**: 权限缓存、批量检查

### 12.3 兼容性风险

- **现有 API 兼容**: 逐步迁移、版本控制
- **数据库迁移**: Alembic 迁移脚本

---

**文档版本**: v1.0  
**最后更新**: 2025年12月22日  
**下一步**: 开始实施第一阶段（基础认证）