Unified_Authentication_Platform

统一认证平台 (UAP)

1. 项目简介

统一认证平台 (Unified Authentication Platform, UAP) 是一个企业级的身份管理系统，旨在解决多应用间的账号统一、认证标准化及新老系统融合问题。

核心能力：

• 多协议支持：同时支持现代 OIDC (OpenID Connect) 协议和传统 API Ticket 认证。
• 账号中心：以手机号为核心标识，支持密码登录和短信验证码登录。
• 账号映射：解决老旧系统账号体系不一致问题，支持将统一手机号映射为特定系统的用户名、邮箱等。
• 安全集成：内置图形验证码、短信验证码、操作审计、Webhook 通知等安全机制。
• 开箱即用：提供完整的前后端界面和 Docker 容器化部署方案。

---

2. 技术栈

后端 (Backend)

• 核心框架: FastAPI (Python 3.10+) - 高性能异步 Web 框架。
• 数据库 ORM: SQLAlchemy (2.0+) - 强大的 ORM 工具。
• 数据验证: Pydantic (2.0+) - 数据解析与验证。
• 认证引擎: Ory Hydra - 经过认证的 OAuth2/OIDC 服务器。
• 缓存/消息: Redis - 用于验证码存储、Session 管理和任务队列。
• 验证码: captcha + Pillow - 本地生成图形验证码。
• 短信服务: 阿里云 SMS (可扩展 Mock 模式)。
• 任务调度: FastAPI BackgroundTasks (轻量级异步任务)。
• 数据处理: Pandas - 用于 Excel 数据的导入导出处理。

前端 (Frontend)

• 核心框架: Vue 3 (Composition API)。
• 语言: TypeScript。
• 构建工具: Vite - 极速开发环境。
• UI 组件库: Element Plus - 企业级后台组件库。
• 状态管理: Pinia。
• 网络请求: Axios。

基础设施 (Infrastructure)

• 容器化: Docker & Docker Compose。
• Web 服务器: Nginx (反向代理与静态资源服务)。
• 应用服务器: Uvicorn (ASGI)。
• 数据库: MySQL 8.0。

---

3. 项目结构与文件说明

3.1 目录概览

Unified_Authentication_Platform/
├── sql/                  # 数据库迁移脚本 (Flyway)
├── backend/                  # 后端项目 (FastAPI)
│   ├── app/                  # 应用源码
│   │   ├── api/v1/           # API 接口层
│   │   │   ├── endpoints/    # 具体业务接口实现
│   │   │   │   ├── apps.py         # 应用管理 (增删改查, Secret重置)
│   │   │   │   ├── auth.py         # 平台登录认证 (JWT)
│   │   │   │   ├── backup.py       # 数据备份与恢复接口
│   │   │   │   ├── login_logs.py   # 登录日志查询
│   │   │   │   ├── logs.py         # 操作审计日志查询 (DB)
│   │   │   │   ├── oidc.py         # OIDC 协议集成 (Login/Consent Provider)
│   │   │   │   ├── open_api.py     # 开放接口 (短信发送, 改密) - 需签名
│   │   │   │   ├── simple_auth.py  # 简易 Ticket 认证 (登录, 验证, 换票)
│   │   │   │   ├── system_logs.py  # 系统运行日志 (文件流, WebSocket实时)
│   │   │   │   ├── users.py        # 用户管理 (管理员用)
│   │   │   │   └── utils.py        # 通用工具 (验证码图片生成)
│   │   │   ├── api.py        # 路由注册汇总
│   │   │   └── deps.py       # 依赖注入 (DB Session, Current User, Token)
│   │   ├── core/             # 核心配置
│   │   │   ├── config.py       # 环境变量加载 (.env)与全局配置
│   │   │   ├── security.py     # 密码哈希, JWT 生成与校验
│   │   │   ├── database.py     # SQLAlchemy 引擎与 SessionLocal
│   │   │   ├── scheduler.py    # 任务调度配置 (APScheduler/BackgroundTasks)
│   │   │   └── hydra_config.py # Ory Hydra 客户端配置
│   │   ├── models/           # SQLAlchemy 数据模型 (MySQL Tables)
│   │   │   ├── user.py         # 用户表 (Users)
│   │   │   ├── application.py  # 应用表 (Applications)
│   │   │   ├── mapping.py      # 账号映射表 (AppUserMappings)
│   │   │   ├── backup.py       # 备份记录表
│   │   │   ├── login_log.py    # 登录日志表
│   │   │   └── operation_log.py# 操作日志表
│   │   ├── schemas/          # Pydantic 数据模型 (Request/Response Validation)
│   │   │   ├── user.py         # 用户相关 Schema
│   │   │   ├── token.py        # Token 响应 Schema
│   │   │   ├── application.py  # 应用管理 Schema
│   │   │   ├── mapping.py      # 映射导入/查询 Schema
│   │   │   ├── simple_auth.py  # 简易认证参数 Schema
│   │   │   ├── backup.py       # 备份相关 Schema
│   │   │   ├── login_log.py    # 登录日志 Schema
│   │   │   └── operation_log.py# 操作日志 Schema
│   │   ├── services/         # 业务逻辑服务层 (解耦 Controller 与 Logic)
│   │   │   ├── backup_service.py   # 备份逻辑 (Zip打包, SQL导出)
│   │   │   ├── captcha_service.py  # 验证码生成与 Redis 校验
│   │   │   ├── hydra_service.py    # Hydra Admin API 封装
│   │   │   ├── mapping_service.py  # Excel 解析与批量导入逻辑
│   │   │   ├── signature_service.py# API 签名算法实现
│   │   │   ├── sms_service.py      # 短信发送 (阿里云/Mock)
│   │   │   ├── webhook_service.py  # 变更通知推送逻辑
│   │   │   ├── ticket_service.py   # Ticket 生成与验证逻辑
│   │   │   ├── log_service.py      # 操作日志记录服务
│   │   │   └── login_log_service.py# 登录日志记录服务
│   │   └── main.py           # FastAPI APP 入口, 中间件配置, 异常处理
│   ├── backups/              # 自动生成的数据库备份文件存储目录
│   ├── logs/                 # 后端运行日志目录
│   ├── scripts/              # 维护脚本 (如初始化管理员)
│   ├── Dockerfile            # 后端容器构建定义
│   └── requirements.txt      # Python 依赖包列表
│
├── frontend/                 # 前端项目 (Vue 3 + TS)
│   ├── public/               # 静态资源 (Logo, Favicon)
│   ├── src/
│   │   ├── api/              # 后端接口封装 (Axios)
│   │   │   ├── apps.ts         # 应用管理接口
│   │   │   ├── users.ts        # 用户管理接口
│   │   │   ├── oidc.ts         # OIDC 相关接口
│   │   │   ├── public.ts       # 公开接口 (验证码, 短信, 注册, 找回密码)
│   │   │   ├── mapping.ts      # 映射管理接口
│   │   │   ├── backup.ts       # 备份管理接口
│   │   │   ├── logs.ts         # 操作日志接口
│   │   │   └── login_logs.ts   # 登录日志接口
│   │   ├── components/       # 公共组件
│   │   │   └── PlatformIcon.vue # 平台图标组件
│   │   ├── data/             # 静态数据 (如更新日志)
│   │   ├── router/           # 路由定义 (Vue Router)
│   │   ├── store/            # 状态管理 (Pinia)
│   │   │   └── auth.ts         # 用户登录状态, 权限控制
│   │   ├── utils/            # 前端工具库
│   │   │   ├── request.ts      # Axios 拦截器 (Token 注入, 错误处理)
│   │   │   └── color.ts        # 颜色生成工具
│   │   ├── views/            # 页面视图组件
│   │   │   ├── admin/          # 管理员专区
│   │   │   │   ├── maintenance/  # 运维管理
│   │   │   │   │   ├── DataBackup.vue  # 数据备份与恢复
│   │   │   │   │   ├── LoginLogs.vue   # 登录日志审计
│   │   │   │   │   ├── SystemLogs.vue  # 系统运行日志
│   │   │   │   │   └── DataRestore.vue # 数据恢复弹窗
│   │   │   │   └── UserList.vue  # 全局用户管理
│   │   │   ├── apps/           # 应用相关
│   │   │   │   ├── AppList.vue     # 应用列表管理
│   │   │   │   └── MappingImport.vue # 账号映射导入向导
│   │   │   ├── Login.vue       # 统一登录页
│   │   │   ├── Register.vue    # 用户注册页
│   │   │   ├── Dashboard.vue   # 用户/管理员仪表盘
│   │   │   ├── Consent.vue     # OIDC 授权确认页
│   │   │   ├── PlatformLaunchpad.vue # 应用启动台
│   │   │   ├── MyMappings.vue  # 我的账号映射
│   │   │   ├── ResetPassword.vue # 重置密码页
│   │   │   ├── Changelog.vue   # 更新日志
│   │   │   ├── Help.vue        # 帮助中心
│   │   │   └── SetupAdmin.vue  # 初始化管理员页
│   │   ├── App.vue           # 根组件
│   │   └── main.ts           # 入口文件 (挂载 Vue, Pinia, Router)
│   ├── nginx.conf            # 前端 Nginx 配置 (反向代理, Gzip)
│   ├── Dockerfile            # 前端容器构建 (Multi-stage build)
│   ├── package.json          # Node.js 依赖与脚本
│   └── vite.config.ts        # Vite 构建配置
│
├── docker-compose.yml        # 容器编排 (Backend, Frontend, MySQL, Redis, Hydra)
└── .env                      # 环境变量配置文件 (不入库)

---

4. 核心模块说明

4.1 认证模块 (Auth)

• OIDC 集成:
  • 集成 Ory Hydra，实现完整的 Authorization Code Flow。
  • 提供自定义的 Login Provider (/auth/login) 和 Consent Provider (/auth/consent) 页面及接口。
  • 支持 openid, offline, profile scopes。
• 简易认证 (Simple Auth):
  • 为不支持 OIDC 的老旧系统提供基于 Ticket 的认证机制。
  • 流程：登录 -> 获取 Ticket -> 重定向 -> 验签换取用户信息。
• 安全机制:
  • 图形验证码：防止暴力破解。
  • 短信验证码：用于敏感操作（注册、重置密码）。
  • 签名校验：开放 API (/api/v1/open/*) 强制要求 HMAC-SHA256 签名。

4.2 应用管理 (Applications)

• 应用注册: 管理员可创建应用，分配 App ID 和 App Secret。
• 账号映射:
  • 定义应用特定的账号字段（如 mapped_key）。
  • 支持 Excel 批量导入映射关系。
  • 支持通过 Webhook 实时推送映射变更。

4.3 运维管理

• 日志审计:
  • 登录日志 (LoginLogs)：记录所有登录尝试及结果。
  • 操作日志 (SystemLogs)：记录管理员的关键操作。
  • Webhook 日志：记录对下游系统的推送记录及响应。
• 数据备份: 支持数据库的备份与恢复功能。

---

5. 环境配置 (.env)

项目配置主要通过环境变量管理。虽然开发环境有默认值，但生产环境建议通过 .env 文件覆盖：

变量名	说明	默认值/示例
MYSQL_SERVER	MySQL 地址	localhost
MYSQL_USER	MySQL 用户名	root
MYSQL_PASSWORD	MySQL 密码	secret
MYSQL_DB	数据库名	uap_db
REDIS_HOST	Redis 地址	localhost
SECRET_KEY	JWT/加密密钥	change_me_...
SMS_PROVIDER	短信服务商	aliyun 或 mock
ALIYUN_ACCESS_KEY_ID	阿里云 AK	-
ALIYUN_ACCESS_KEY_SECRET	阿里云 SK	-

---

6. 安装与运行

6.1 容器化部署 (推荐)

本项目支持一键启动：

# 构建并启动所有服务
docker-compose up -d --build

启动后可访问：

• 前端页面: http://localhost:5173 (开发) 或 http://localhost (Nginx)
• 后端 API 文档: http://localhost:8000/docs
• Ory Hydra: http://localhost:4444

6.2 本地开发运行

后端:

cd backend
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 启动服务
uvicorn app.main:app --reload

前端:

cd frontend
# 安装依赖
npm install
# 启动开发服务器
npm run dev

6.3 数据库运维 (自动升级与恢复)

本项目集成了 Flyway 和 Backup Sidecar，实现了企业级的数据库运维能力。

1. 自动升级数据库 (Flyway)

• 原理: db-migration 容器启动时会自动比对 sql/ 目录下的脚本与数据库状态，自动执行增量更新。
• 操作步骤:
  1. 在项目根目录的 sql/ 文件夹中创建 SQL 文件。
  2. 命名需遵循 Flyway 规范：V<版本号>__<描述>.sql (注意是双下划线)。
     • 示例: sql/V1__init_schema.sql, sql/V2__add_phone_field.sql
  3. 执行 docker-compose up -d。容器会自动检测并应用新的 SQL 变更。

2. 灾难恢复 (Disaster Recovery)

• 自动备份: db-backup 容器每天凌晨 3:00 自动将数据库备份至 backups/ 目录 (保留7天)。
• 手动恢复步骤: 假设需要从 backups/uap_db_xxxx.sql.gz 恢复数据：
  

  # 1. 停止应用服务，防止写入
  docker-compose stop

  # 2. 仅启动数据库
  docker-compose up -d mysql

  # 3. 执行恢复 (使用 Docker 临时容器执行导入，无需本地安装 MySQL 客户端)
  # 注意：替换下方文件名
  docker run --rm -i \
    --network container:uap_mysql \
    mysql:8.0 \
    sh -c 'exec mysql -h mysql -u root -proot_password uap_db' < <(gzip -dc ./backups/uap_db_xxxx.sql.gz)

  # 4. 恢复完成后重启所有服务
  docker-compose restart

---

7. 常见问题 (FAQ)

• Q: 默认管理员账号是什么？

  • A: 如果执行了初始化脚本，通常为手机号 13800000001，密码 admin。
    

• Q: 验证码图片加载失败？

  • A: 检查 Redis 连接是否正常，以及字体文件是否存在（通常由 Pillow 自带）。

• Q: 短信发送失败？

  • A: 检查 SMS_PROVIDER 配置。开发环境可设置为 mock，验证码将直接打印在后端日志中。

---

最后更新时间: 2026-01-09