# 部署架构

<cite>
**本文引用的文件**
- [backend/.env.example](file://backend/.env.example)
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
- [backend/init_db.py](file://backend/init_db.py)
- [backend/alembic.ini](file://backend/alembic.ini)
- [frontend/package.json](file://frontend/package.json)
- [frontend/vite.config.js](file://frontend/vite.config.js)
- [docs/backend.md](file://docs/backend.md)
- [AGENTS.md](file://AGENTS.md)
- [test_frontend_connection.py](file://test_frontend_connection.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向医院绩效系统，提供从开发到生产的部署架构说明，覆盖生产、测试与开发环境的配置差异，容器化与编排策略，数据库部署与高可用设计，静态资源与 CDN 缓存策略，以及部署流程、环境变量、监控告警与故障恢复方案。内容基于仓库现有后端与前端工程配置进行归纳与扩展建议。

## 项目结构
系统由前后端分离构成：
- 后端采用 FastAPI + SQLAlchemy 2.0 异步 ORM，使用 Alembic 进行数据库迁移，支持异步 PostgreSQL 连接。
- 前端采用 Vue 3 + Vite，开发时通过代理将 /api 请求转发至后端本地服务。
- 文档与脚本提供了开发与测试命令参考。

```mermaid
graph TB
subgraph "前端"
FE_PKG["frontend/package.json"]
FE_VITE["frontend/vite.config.js"]
FE_DIST["frontend/dist/*"]
end
subgraph "后端"
BE_MAIN["backend/app/main.py"]
BE_CFG["backend/app/core/config.py"]
BE_DB["backend/app/core/database.py"]
BE_LOG["backend/app/core/logging_config.py"]
BE_REQ["backend/requirements.txt"]
BE_ENV["backend/.env.example"]
BE_ALEMBIC["backend/alembic.ini"]
BE_INIT["backend/init_db.py"]
end
FE_VITE --> |"开发代理 /api"| BE_MAIN
FE_PKG --> |"构建产物"| FE_DIST
BE_MAIN --> BE_DB
BE_MAIN --> BE_CFG
BE_DB --> |"连接"| BE_ENV
BE_ALEMBIC --> |"迁移配置"| BE_DB
BE_INIT --> |"初始化数据"| BE_DB
```

图表来源
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [backend/init_db.py](file://backend/init_db.py#L1-L83)

章节来源
- [docs/backend.md](file://docs/backend.md#L1-L58)
- [AGENTS.md](file://AGENTS.md#L15-L53)

## 核心组件
- 应用入口与路由注册：后端通过应用工厂创建 FastAPI 实例，注册跨域中间件与 API 路由，并提供健康检查端点与全局异常处理。
- 配置管理：通过 pydantic-settings 读取 .env 文件，集中管理数据库连接、JWT 密钥、CORS 来源、分页参数等。
- 数据库层：异步 SQLAlchemy 引擎与会话工厂，支持连接池大小与溢出配置；提供依赖注入式会话生命周期管理。
- 日志模块：按日期轮转输出应用日志与错误日志，便于运维定位问题。
- 前端开发与构建：Vite 提供开发服务器与代理，构建生成静态资源目录。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L21)

## 架构总览
系统采用“前端静态 + 后端 API”的典型分层架构。前端通过 /api 前缀调用后端接口，后端通过异步数据库连接访问 PostgreSQL。开发阶段通过 Vite 代理实现跨域联调；生产阶段建议通过反向代理或网关统一暴露 API 并托管前端静态资源。

```mermaid
graph TB
Client["浏览器/移动端"] --> Proxy["反向代理/Nginx"]
Proxy --> FE["前端静态资源<br/>frontend/dist"]
Proxy --> API["后端 API<br/>FastAPI"]
API --> DB["PostgreSQL"]
API --> Redis["可选缓存/会话存储"]
```

说明
- 该图为概念性架构示意，用于指导部署拓扑与流量走向。

## 详细组件分析

### 后端应用与配置
- 应用工厂与中间件：创建 FastAPI 实例、注册 CORS、挂载路由前缀、健康检查与异常处理。
- 配置项：应用名称、版本、调试开关、API 前缀、数据库 URL、连接池参数、JWT 签发参数、CORS 允许来源、分页默认值与最大值。
- 数据库连接：异步引擎与会话工厂，支持回滚与关闭，配合依赖注入提供事务级会话。
- 日志：控制台 INFO 输出与文件 DEBUG/ERROR 轮转日志，自动按日期创建日志文件。

```mermaid
classDiagram
class Settings {
+APP_NAME : string
+APP_VERSION : string
+DEBUG : bool
+API_PREFIX : string
+DATABASE_URL : string
+DATABASE_POOL_SIZE : int
+DATABASE_MAX_OVERFLOW : int
+SECRET_KEY : string
+ALGORITHM : string
+ACCESS_TOKEN_EXPIRE_MINUTES : int
+CORS_ORIGINS : string[]
+DEFAULT_PAGE_SIZE : int
+MAX_PAGE_SIZE : int
}
class Database {
+engine
+async_session_maker
+get_db()
}
class Logging {
+logger
+get_logger(name)
}
Settings <.. Database : "提供连接配置"
Settings <.. Logging : "被应用使用"
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L27-L65)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)

### 数据库与迁移
- 连接配置：通过 Settings 的 DATABASE_URL 指定异步 PostgreSQL 连接字符串。
- 迁移配置：Alembic 默认使用 SQLite 路径示例，实际生产需调整为 PostgreSQL 连接。
- 初始化脚本：提供创建表与插入测试数据的异步初始化流程。

```mermaid
flowchart TD
Start(["开始"]) --> CheckURL["检查 DATABASE_URL 配置"]
CheckURL --> IsPG{"是否为 PostgreSQL?"}
IsPG --> |是| UsePG["使用 asyncpg 异步驱动"]
IsPG --> |否| UseSQLite["使用 SQLite仅开发/测试"]
UsePG --> Migrate["执行 Alembic 迁移"]
UseSQLite --> LocalInit["运行 init_db 初始化表与测试数据"]
Migrate --> Done(["完成"])
LocalInit --> Done
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
- [backend/init_db.py](file://backend/init_db.py#L11-L18)

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
- [backend/init_db.py](file://backend/init_db.py#L1-L83)

### 前端开发与构建
- 开发服务器：Vite 默认端口，开启代理将 /api 请求转发至后端本地地址。
- 构建产物：生产构建输出至 dist 目录，建议由反向代理或对象存储提供静态托管。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Vite as "Vite 开发服务器"
participant Proxy as "反向代理/Nginx"
participant API as "后端 API"
Dev->>Vite : 访问 http : //localhost : 5173
Vite->>Proxy : 发起 /api 请求
Proxy->>API : 转发请求
API-->>Proxy : 返回响应
Proxy-->>Vite : 返回响应
Vite-->>Dev : 渲染页面
```

图表来源
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L21)
- [backend/app/main.py](file://backend/app/main.py#L54-L56)

章节来源
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [frontend/package.json](file://frontend/package.json#L1-L27)

### 部署流程（概念性）
以下流程图展示从代码到上线的通用步骤，具体镜像与编排参数需结合企业环境定制。

```mermaid
flowchart TD
Dev["开发者提交代码"] --> CI["CI 构建镜像"]
CI --> Push["推送镜像到镜像仓库"]
Push --> Deploy["部署到目标环境"]
Deploy --> Health["健康检查"]
Health --> Ready{"就绪?"}
Ready --> |否| Rollback["回滚至上一版本"]
Ready --> |是| Monitor["监控与告警"]
Monitor --> Ops["运维观察"]
```

说明
- 该图为通用流程示意，不直接映射具体源文件。

## 依赖关系分析
- 后端依赖：FastAPI、SQLAlchemy 2.0、asyncpg、Alembic、Pydantic/Settings、Uvicorn 等。
- 前端依赖：Vue 3、Element Plus、Pinia、Axios、Vite 等。
- 开发与测试命令：文档提供了安装、迁移、启动与测试的参考命令。

```mermaid
graph LR
FE_PKG["frontend/package.json"] --> FE_DEPS["前端依赖"]
BE_REQ["backend/requirements.txt"] --> BE_DEPS["后端依赖"]
AGENTS["AGENTS.md"] --> FE_CMD["前端命令"]
AGENTS --> BE_CMD["后端命令"]
```

图表来源
- [frontend/package.json](file://frontend/package.json#L11-L25)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [AGENTS.md](file://AGENTS.md#L15-L53)

章节来源
- [frontend/package.json](file://frontend/package.json#L1-L27)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [AGENTS.md](file://AGENTS.md#L15-L53)

## 性能考虑
- 数据库连接池：根据并发与硬件能力调整连接池大小与溢出参数，避免连接争用。
- 异常处理：全局异常与验证异常记录日志，有助于定位性能瓶颈与错误热点。
- 前端静态资源：生产构建后由 CDN 或反向代理缓存，减少后端带宽压力。
- 日志级别：生产环境建议提升控制台日志级别，降低磁盘与 I/O 压力。

## 故障排查指南
- CORS 配置：确认前端开发代理与后端允许来源一致，避免跨域失败。
- 登录接口：使用测试脚本验证登录流程与 Token 获取。
- 健康检查：通过后端健康端点快速判断服务状态。
- 日志定位：查看按日期命名的日志文件，区分应用日志与错误日志。

章节来源
- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L59)

## 结论
本部署架构文档基于现有仓库配置，明确了后端配置、数据库连接、前端开发与构建的关键点，并给出了生产环境的通用建议。后续可在企业环境中补充容器化与编排、数据库高可用、CDN 与缓存、监控告警与灾备等方案。

## 附录

### 环境变量与配置清单
- 数据库连接：通过 DATABASE_URL 指定 PostgreSQL 异步连接字符串。
- JWT 密钥：SECRET_KEY 用于签发与校验 Token。
- 调试与 API 前缀：DEBUG 控制 SQL 与日志输出；API_PREFIX 作为路由前缀。
- CORS 来源：CORS_ORIGINS 控制允许跨域来源。
- 分页参数：DEFAULT_PAGE_SIZE 与 MAX_PAGE_SIZE 控制分页范围。

章节来源
- [backend/.env.example](file://backend/.env.example#L3-L11)
- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L34)

### 生产/测试/开发环境配置差异建议
- 开发环境
  - DEBUG: True
  - CORS_ORIGINS: 允许本地开发域名
  - DATABASE_URL: 本地 PostgreSQL 或 Docker 内部网络地址
- 测试环境
  - DEBUG: False
  - CORS_ORIGINS: 限定测试域名
  - DATABASE_URL: 测试专用数据库实例
- 生产环境
  - DEBUG: False
  - CORS_ORIGINS: 限定正式域名
  - DATABASE_URL: 使用高可用数据库集群地址
  - 配置密钥与证书，启用 HTTPS

说明
- 以上为通用建议，具体值需结合企业安全与合规要求设定。

### 容器化与编排（建议）
- 镜像构建
  - 后端：基于 Python 基础镜像，复制 requirements.txt 并安装依赖，复制源码，暴露端口，设置启动命令。
  - 前端：基于 Nginx 或 Node 生态镜像，构建静态资源，配置反向代理指向后端 API。
- 编排与负载均衡
  - 使用编排平台部署后端多副本，配置健康检查与滚动更新。
  - 前端静态资源由对象存储或 CDN 托管，反向代理统一入口。
- 数据库高可用
  - 建议使用 PostgreSQL 主从或托管集群，配置只读副本与自动故障转移。
- 备份策略
  - 定期逻辑备份与增量备份，结合 WAL 归档与时间点恢复（PITR）。
- 缓存与会话
  - 可选引入 Redis 作为会话存储与缓存，提升热点数据访问性能。

说明
- 以上为通用实践建议，需结合企业基础设施与合规要求落地。

### 监控与告警（建议）
- 应用层
  - 指标：请求延迟、错误率、并发连接数、数据库连接池使用率。
  - 日志：结构化日志，按服务聚合，保留关键字段以便检索。
- 基础设施层
  - CPU、内存、磁盘、网络 I/O、数据库可用性与延迟。
- 告警策略
  - 设定阈值与静默窗口，区分 P1/P2/P3 级别，确保关键问题及时通知。

说明
- 以上为通用监控建议，需结合企业监控体系与团队流程制定。