Files

T

xiaohei 0fa39fbd61 docs: 添加认证及后台管理系统设计文档

设计内容:
- 系统概述和目标
- 架构设计（模块划分、系统架构图）
- 认证系统设计（登录流程、Token管理、密码安全）
- 权限管理系统（RBAC、角色定义、权限检查）
- 后台管理功能（用户管理、Agent管理、系统监控、审计日志）
- API设计（认证API、后台管理API）
- 数据库设计（表结构设计）
- 安全设计（认证安全、权限安全、数据安全）
- 实施计划（5个阶段，8-13天）
- 技术选型
- 后续扩展计划
- 风险评估

版本: v1.0

2025-12-22 09:42:35 +00:00

22 KiB

Raw Blame History

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

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

📋 目录

系统概述
架构设计
认证系统设计
权限管理系统
后台管理功能
API 设计
数据库设计
安全设计
实施计划

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

22 KiB Raw Blame History Unescape Escape

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

📋 目录

1. 系统概述

1.1 目标

1.2 核心功能

认证功能

权限管理

后台管理

2. 架构设计

2.1 系统架构图

2.2 模块划分

2.2.1 认证模块 (auth.py)

2.2.2 权限模块 (permissions.py)

2.2.3 后台管理模块 (admin.py)

2.2.4 审计模块 (audit.py)

3. 认证系统设计

3.1 认证流程

3.1.1 用户登录流程

3.1.2 Token 结构

3.2 密码安全

3.3 Token 管理

4. 权限管理系统

4.1 角色定义

4.1.1 系统角色

4.1.2 权限定义

4.2 权限检查机制

4.2.1 装饰器方式

4.2.2 依赖注入方式

4.3 API Key 权限

5. 后台管理功能

5.1 用户管理

功能列表

数据展示

5.2 Agent 管理

功能列表

数据展示

5.3 工具管理

功能列表

5.4 系统监控

功能列表

5.5 审计日志

功能列表

日志内容

5.6 计费管理

功能列表

6. API 设计

6.1 认证 API

6.1.1 用户注册

6.1.2 用户登录

6.1.3 Token 刷新

6.1.4 用户登出

6.1.5 密码重置

6.2 后台管理 API

6.2.1 用户管理

6.2.2 Agent 管理

6.2.3 系统监控

6.2.4 审计日志

7. 数据库设计

7.1 用户表 (users) - 已有

7.2 角色表 (roles) - 新增

7.3 权限表 (permissions) - 新增

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

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

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

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

8. 安全设计

8.1 认证安全

8.2 权限安全

8.3 数据安全

8.4 审计安全

9. 实施计划

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

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

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

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

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

9.6 总工作量估算

10. 技术选型

10.1 认证技术

22 KiB

Raw Blame History

2.2.1 认证模块 (`auth.py`)

2.2.2 权限模块 (`permissions.py`)

2.2.3 后台管理模块 (`admin.py`)

2.2.4 审计模块 (`audit.py`)