提交文件

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,337 @@
+# 部署运维
+
+<cite>
+**本文引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/.env.example](file://backend/.env.example)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/init_db.py](file://backend/init_db.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/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [docs/backend.md](file://docs/backend.md)
+- [docs/database.md](file://docs/database.md)
+- [frontend/package.json](file://frontend/package.json)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向医院绩效系统的生产部署与运维，覆盖以下主题：
+- 生产环境部署流程与环境变量配置
+- Docker 容器化部署与 Nginx 反向代理、SSL 证书管理
+- 数据库备份策略、日志管理与性能监控
+- 负载均衡、高可用架构与灾难恢复计划
+- 运维脚本、自动化部署与版本升级流程
+- 安全加固、漏洞扫描与合规性检查
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 2.0 异步架构，前端为 Vue 3 + Vite。系统通过 .env 管理运行时配置，支持 Alembic 数据库迁移。
+
+```mermaid
+graph TB
+subgraph "后端"
+A["app/main.py<br/>应用入口与路由注册"]
+B["app/core/config.py<br/>配置管理"]
+C["app/core/database.py<br/>异步数据库引擎"]
+D["app/core/logging_config.py<br/>日志配置"]
+E["app/api/v1/__init__.py<br/>路由聚合"]
+F["init_db.py<br/>初始化与测试数据"]
+end
+subgraph "前端"
+G["frontend/package.json<br/>构建与依赖"]
+end
+A --> E
+A --> B
+A --> D
+E --> C
+F --> C
+G --> A
+```
+
+图表来源
+- [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/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/init_db.py](file://backend/init_db.py#L1-L83)
+- [frontend/package.json](file://frontend/package.json#L1-L27)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [docs/backend.md](file://docs/backend.md#L1-L475)
+
+## 核心组件
+- 应用入口与路由：创建 FastAPI 实例、注册 CORS、健康检查、全局异常处理，并挂载 v1 路由前缀。
+- 配置管理：集中管理应用名称、版本、调试模式、API 前缀、数据库连接、JWT 密钥算法与过期时间、CORS 源、分页参数等。
+- 数据库层：异步 SQLAlchemy 引擎与会话工厂，提供依赖注入式数据库会话。
+- 日志模块：按日轮转的多处理器日志记录，区分应用日志与错误日志。
+- 初始化脚本：自动建表与插入测试数据，避免重复初始化。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [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)
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+## 架构总览
+系统采用前后端分离架构，后端提供 REST API，前端通过 Axios 访问后端接口；数据库为 PostgreSQL，使用异步驱动。
+
+```mermaid
+graph TB
+FE["前端应用<br/>Vue 3 + Vite"] --> API["后端API<br/>FastAPI"]
+API --> DB["数据库<br/>PostgreSQL"]
+API --> LOG["日志系统<br/>按日轮转"]
+API --> CFG["配置中心<br/>.env + pydantic-settings"]
+```
+
+图表来源
+- [docs/backend.md](file://docs/backend.md#L3-L15)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L37)
+
+## 详细组件分析
+
+### 配置管理（Settings）
+- 环境变量文件：.env.example 提供数据库 URL、JWT 密钥、调试开关等示例。
+- 运行时配置：Settings 使用 pydantic-settings 从 .env 加载，支持缓存单例。
+- 关键项：
+  - 应用名称与版本、调试模式、API 前缀
+  - 数据库连接串、连接池大小与溢出
+  - JWT 密钥、算法与过期时间
+  - CORS 源列表
+  - 分页默认与最大页大小
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+
+### 数据库层（异步引擎与会话）
+- 异步引擎：基于配置的 DATABASE_URL 创建 asyncpg 引擎，DEBUG 控制 echo。
+- 会话工厂：异步会话构造与生命周期管理，提供依赖注入。
+- 依赖函数：get_db 提供事务语义（提交/回滚/关闭），确保异常安全。
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+
+### 日志模块（RotatingFileHandler）
+- 日志目录：位于 backend/logs，按日期命名文件。
+- 处理器：
+  - 控制台 INFO 级别输出
+  - 文件 DEBUG 级别轮转（10MB，保留7份）
+  - 错误 ERROR 级别单独文件轮转
+- 获取子日志器：统一命名空间，便于模块化追踪。
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L10-L65)
+
+### 应用入口与路由（FastAPI）
+- 应用实例：设置标题、版本、OpenAPI 文档路径前缀。
+- CORS 中间件：允许指定源、凭证、方法与头。
+- 路由注册：聚合 v1 子路由，统一前缀。
+- 健康检查：/health 返回状态与版本。
+- 异常处理：HTTP、请求校验、全局异常统一记录与抛出。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+
+### 初始化脚本（建表与测试数据）
+- 自动建表：创建所有模型对应的数据表。
+- 测试数据：若 departments 表为空则批量插入默认数据。
+- 管理员账户：创建 admin 用户并设置密码哈希。
+
+章节来源
+- [backend/init_db.py](file://backend/init_db.py#L11-L83)
+
+### 前端构建与依赖
+- 构建脚本：dev/build/preview。
+- 依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js。
+- 与后端交互：通过 Axios 访问后端 API（具体接口见 API 文档）。
+
+章节来源
+- [frontend/package.json](file://frontend/package.json#L6-L26)
+- [docs/backend.md](file://docs/backend.md#L470-L475)
+
+## 依赖关系分析
+后端模块之间的依赖关系如下：
+
+```mermaid
+graph LR
+main_py["app/main.py"] --> api_v1_init["app/api/v1/__init__.py"]
+main_py --> cfg_py["app/core/config.py"]
+main_py --> log_cfg_py["app/core/logging_config.py"]
+api_v1_init --> db_py["app/core/database.py"]
+init_db_py["init_db.py"] --> db_py
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L10-L51)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L27-L65)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/init_db.py](file://backend/init_db.py#L14-L15)
+
+## 性能考虑
+- 数据库连接池：通过配置 DATABASE_POOL_SIZE 与 DATABASE_MAX_OVERFLOW 控制并发与溢出。
+- 异步 I/O：使用 SQLAlchemy 2.0 异步引擎与 asyncpg，减少阻塞。
+- 日志级别：生产建议提升控制台级别至 INFO，避免过多 DEBUG 输出。
+- 分页限制：MAX_PAGE_SIZE 限制单页最大条数，防止资源滥用。
+- 健康检查：/health 用于探活，结合负载均衡实现快速摘除不健康实例。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/main.py](file://backend/app/main.py#L53-L56)
+
+## 故障排查指南
+- 健康检查失败：确认 /health 返回 healthy 与版本号。
+- 数据库连接异常：检查 DATABASE_URL、网络连通性与 PostgreSQL 服务状态。
+- 日志定位：查看 backend/logs 下按日期命名的日志文件，优先关注 ERROR 日志。
+- CORS 问题：确认前端地址在 CORS_ORIGINS 列表中。
+- 初始化未生效：确认 init_db.py 执行顺序与数据库权限。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L53-L77)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L18-L20)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
+- [backend/init_db.py](file://backend/init_db.py#L20-L25)
+
+## 结论
+本指南提供了从配置、部署到运维监控的完整实践路径。建议在生产环境中严格管理 .env，启用 HTTPS 与 TLS，完善数据库备份与日志归档，并结合负载均衡与健康检查实现高可用。
+
+## 附录
+
+### A. 生产环境部署流程
+- 准备阶段
+  - 准备 PostgreSQL 实例，创建数据库与用户。
+  - 生成并妥善保管 SECRET_KEY（至少 32 字符）。
+- 配置
+  - 复制 .env.example 为 .env，填写 DATABASE_URL、SECRET_KEY、DEBUG=false。
+  - 设置 CORS_ORIGINS 为前端域名或 IP。
+- 启动
+  - 安装依赖：pip install -r backend/requirements.txt
+  - 初始化数据库：python backend/init_db.py
+  - 启动服务：uvicorn app.main:app --host 0.0.0.0 --port 8000
+- 验证
+  - 访问 /health 检查服务状态
+  - 访问 /api/v1/docs 或 /api/v1/redoc 查看接口文档
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L1-L11)
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [backend/init_db.py](file://backend/init_db.py#L81-L83)
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+
+### B. 环境变量清单
+- DATABASE_URL：数据库连接串（PostgreSQL）
+- SECRET_KEY：JWT 密钥
+- DEBUG：调试模式开关
+- CORS_ORIGINS：允许跨域的源列表
+- API_PREFIX：API 前缀（如 /api/v1）
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L3-L10)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
+
+### C. Docker 容器化部署（步骤说明）
+- 构建镜像
+  - 基于 Python 3.11+ 镜像
+  - 复制 requirements.txt 并安装依赖
+  - 复制后端代码与 .env
+  - 暴露端口 8000
+- 运行容器
+  - 挂载日志目录 backend/logs 至宿主机
+  - 指定环境变量（DATABASE_URL、SECRET_KEY、DEBUG、CORS_ORIGINS、API_PREFIX）
+  - 通过健康检查 /health 配置探针
+- 注意
+  - 将 .env 放置于受控位置，避免泄露
+  - 使用只读卷挂载代码，仅挂载日志目录为可写
+
+[本节为概念性说明，不直接分析具体文件，故无“章节来源”]
+
+### D. Nginx 反向代理与 SSL 证书
+- 反代配置要点
+  - 将 /api/* 反代至后端服务（如 http://backend:8000）
+  - 静态资源指向前端 dist 目录（如 /dist）
+  - 启用 gzip/ssl，开启 HSTS
+- SSL 证书
+  - 使用 Let’s Encrypt 或企业 CA
+  - 自动续期脚本与监控告警
+- 健康检查
+  - upstream 中配置 /health 探针，失败自动摘除
+
+[本节为概念性说明，不直接分析具体文件，故无“章节来源”]
+
+### E. 数据库备份策略
+- 全量备份：每周日凌晨执行 pg_dump -U <user> -h <host> <db> > backup.sql
+- 增量/归档：开启 WAL 归档，配合 PITR
+- 存储备份：加密存储于对象存储或磁带库，保留 4-8 周
+- 验证恢复：每季度执行恢复演练
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### F. 日志管理与性能监控
+- 日志
+  - 后端：backend/logs 按日轮转，保留 7 天
+  - 前端：浏览器控制台与网络面板排查
+- 监控
+  - 指标：CPU/内存/连接数/慢查询/错误率
+  - 告警：阈值触发与收敛策略
+  - 链路追踪：结合 OpenTelemetry 或 APM
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### G. 负载均衡、高可用与灾难恢复
+- 高可用
+  - 多实例部署（至少 2 个后端实例）
+  - PostgreSQL 主从复制或托管服务
+  - 健康检查与自动摘除
+- 灾难恢复
+  - RTO/RPO 目标明确
+  - 快速恢复流程与角色分工
+  - 定期演练与文档更新
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]
+
+### H. 运维脚本、自动化部署与版本升级
+- 自动化
+  - CI/CD：拉取代码 → 单元测试 → 构建镜像 → 发布
+  - 蓝绿/滚动发布：灰度流量切换
+- 升级流程
+  - 数据库迁移：alembic upgrade head
+  - 前后端版本对齐：锁定依赖版本
+  - 回滚预案：镜像标签回滚与数据库 downgrade
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L438-L452)
+
+### I. 安全加固、漏洞扫描与合规
+- 安全加固
+  - 禁用 DEBUG，最小权限原则
+  - 强密码与密钥轮换，HTTPS 强传输
+  - 输入校验与 SQL 注入防护（ORM 已内置）
+- 漏洞扫描
+  - 依赖扫描：pip-audit/安全扫描工具
+  - 漏洞修复与补丁管理
+- 合规
+  - 数据最小化与访问审计
+  - 签名与完整性校验（如需要）
+
+[本节为通用运维实践，不直接分析具体文件，故无“章节来源”]