提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/系统架构/部署架构.md
+++ b/.qoder/repowiki/zh/content/系统架构/部署架构.md
@@ -0,0 +1,332 @@
+# 部署架构
+
+<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 级别，确保关键问题及时通知。
+
+说明
+- 以上为通用监控建议，需结合企业监控体系与团队流程制定。