taiji-AI-PAD/Docs/项目文档/认证及后台管理系统设计.md

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

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

---

📋 目录

1. 系统概述
2. 架构设计
3. 认证系统设计
4. 权限管理系统
5. 后台管理功能
6. 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 结构

{
  "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 装饰器方式

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

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

4.2.2 依赖注入方式

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) - 已有

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) - 新增

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) - 新增

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) - 新增

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) - 新增

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) - 已有，需增强

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) - 已有，需增强

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日
下一步: 开始实施第一阶段（基础认证）