hospital_performance/.qoder/repowiki/zh/content/系统架构/部署架构.md

部署架构

**本文引用的文件** - [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)

目录

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

简介

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

项目结构

系统由前后端分离构成：

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

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
• backend/app/main.py
• backend/app/core/config.py
• backend/app/core/database.py
• backend/app/core/logging_config.py
• backend/requirements.txt
• backend/.env.example
• backend/alembic.ini
• backend/init_db.py

章节来源

• docs/backend.md
• AGENTS.md

核心组件

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

章节来源

• backend/app/main.py
• backend/app/core/config.py
• backend/app/core/database.py
• backend/app/core/logging_config.py
• frontend/vite.config.js

架构总览

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

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 轮转日志，自动按日期创建日志文件。

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
• backend/app/core/database.py
• backend/app/core/logging_config.py

章节来源

• backend/app/main.py
• backend/app/core/config.py
• backend/app/core/database.py
• backend/app/core/logging_config.py

数据库与迁移

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

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
• backend/alembic.ini
• backend/init_db.py

章节来源

• backend/app/core/config.py
• backend/alembic.ini
• backend/init_db.py

前端开发与构建

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

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
• backend/app/main.py

章节来源

• frontend/vite.config.js
• frontend/package.json

部署流程（概念性）

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

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 等。
• 开发与测试命令：文档提供了安装、迁移、启动与测试的参考命令。

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
• backend/requirements.txt
• AGENTS.md

章节来源

• frontend/package.json
• backend/requirements.txt
• AGENTS.md

性能考虑

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

故障排查指南

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

章节来源

• test_frontend_connection.py
• backend/app/main.py
• backend/app/core/logging_config.py

结论

本部署架构文档基于现有仓库配置，明确了后端配置、数据库连接、前端开发与构建的关键点，并给出了生产环境的通用建议。后续可在企业环境中补充容器化与编排、数据库高可用、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
• backend/app/core/config.py

生产/测试/开发环境配置差异建议

• 开发环境
  • 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 级别，确保关键问题及时通知。

说明

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