# 统一认证平台 (UAP)

## 1. 项目简介

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

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

---

## 2. 技术栈

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

### 前端 (Frontend)
- **核心框架**: [Vue 3](https://vuejs.org/) (Composition API)。
- **语言**: TypeScript。
- **构建工具**: [Vite](https://vitejs.dev/) - 极速开发环境。
- **UI 组件库**: [Element Plus](https://element-plus.org/) - 企业级后台组件库。
- **状态管理**: Pinia。
- **网络请求**: Axios。

### 基础设施 (Infrastructure)
- **容器化**: Docker & Docker Compose。
- **Web 服务器**: Nginx (反向代理与静态资源服务)。
- **应用服务器**: Uvicorn (ASGI)。
- **数据库**: MySQL 8.0。

---

## 3. 项目结构与文件说明

### 3.1 目录概览

```text
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 容器化部署 (推荐)
本项目支持一键启动：

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

启动后可访问：
- **前端页面**: `http://localhost:5173` (开发) 或 `http://localhost` (Nginx)
- **后端 API 文档**: `http://localhost:8000/docs`
- **Ory Hydra**: `http://localhost:4444`

### 6.2 本地开发运行

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

**前端**:
```bash
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` 恢复数据：
  
  ```bash
  # 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_