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

部署架构

本文档引用的文件

• DEPLOY.md
• DEPLOY_PROD.md
• docker-nginx/docker-compose.yml
• docker-nginx/bookapi.conf
• server/src/app.ts
• server/src/config/index.ts
• server/src/services/logger.service.ts
• server/src/services/sentry.service.ts
• server/src/middleware/errorHandler.ts
• server/prisma/schema.prisma
• server/package.json

目录

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

简介

本文件面向AI有声书生成平台的运维与开发团队，提供一套完整的部署架构文档，覆盖容器化部署策略、Nginx反向代理配置、多环境差异化配置、数据库部署与备份恢复、以及监控与日志体系。文档以仓库中的实际部署脚本、Nginx配置、后端应用入口与服务模块为依据，结合Prisma数据库模型，形成可落地的实施蓝图。

项目结构

该仓库包含后端服务、前端构建产物、Nginx代理配置与多套部署文档。后端采用Koa框架，通过PM2进行进程守护；Nginx负责反向代理与静态资源服务；数据库使用Prisma管理MySQL；日志与错误监控分别由Winston与Sentry提供。

graph TB
subgraph "服务器"
FE["前端静态资源<br/>/data/ai/audio/frontend/build/h5"]
BE["后端服务<br/>server/dist/app.js"]
DB["MySQL 8.0<br/>单容器 single-mysql"]
REDIS["Redis 缓存"]
OSS["阿里云 OSS"]
end
subgraph "反向代理"
NGINX["Nginx<br/>book.rrbrr.com -> /api -> 3100"]
end
Client["客户端浏览器"] --> NGINX
NGINX --> BE
BE --> DB
BE --> REDIS
BE --> OSS
FE -. 静态直出 .-> NGINX

图表来源

• DEPLOY_PROD.md: 35-46:35-46
• DEPLOY_PROD.md: 146-239:146-239
• server/src/app.ts: 133-166:133-166

章节来源

• DEPLOY_PROD.md: 33-46:33-46
• DEPLOY.md: 10-116:10-116

核心组件

• 反向代理与负载均衡
  • Nginx作为统一入口，负责HTTP/HTTPS终止、静态资源缓存、API反向代理与基础安全头设置。
  • 生产环境使用宝塔面板管理Nginx配置，支持SSL证书与HTTP/2。
• 应用服务
  • 后端基于Koa，提供REST接口、健康检查、性能指标、静态文件挂载与WebSocket。
  • 使用PM2进行进程守护、开机自启与日志采集。
• 数据层
  • Prisma管理MySQL Schema，支持迁移与查询。
  • 支持本地存储与阿里云OSS两种存储后端。
• 监控与日志
  • Winston统一日志输出至控制台与文件，包含HTTP请求日志。
  • Sentry进行错误监控与性能采样，支持过滤与上下文注入。
• 配置与模型
  • 环境变量驱动端口、数据库URL、存储类型等关键参数。
  • 统一的模型配置与切换逻辑，便于多供应商TTS能力扩展。

章节来源

• server/src/app.ts: 57-131:57-131
• server/src/config/index.ts: 69-117:69-117
• server/src/services/logger.service.ts: 67-114:67-114
• server/src/services/sentry.service.ts: 7-43:7-43
• server/prisma/schema.prisma: 1-8:1-8

架构总览

下图展示了服务器拓扑、网络配置与服务依赖关系，映射到实际的部署文档与配置文件。

graph TB
Client["客户端"] --> |"HTTP/HTTPS"| NGINX["Nginx 反向代理"]
NGINX --> |"反代 /api/*"| APP["后端应用 server/dist/app.js"]
APP --> |"Prisma"| MYSQL["MySQL 单实例"]
APP --> |"Redis"| REDIS["Redis 缓存"]
APP --> |"OSS"| OSS["阿里云 OSS"]
FE["前端静态资源"] --> |"静态直出"| NGINX

图表来源

• DEPLOY_PROD.md: 146-239:146-239
• server/src/app.ts: 133-166:133-166
• server/prisma/schema.prisma: 5-8:5-8

详细组件分析

Nginx反向代理与静态资源服务

• 生产环境配置
  • 域名book.rrbrr.com，强制跳转HTTPS，启用TLSv1.1/1.2/1.3与HSTS头。
  • 前端静态资源根目录指向/data/ai/audio/frontend/build/h5，开启缓存与压缩。
  • /api前缀反向代理至后端3100端口，透传Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto。
• 开发环境配置
  • docker-nginx提供最小化Nginx容器，将bookapi.rrbrr.com:80代理至宿主机3000端口，便于本地联调。

• 负载均衡策略

  • 当前为单实例部署，未见多实例LB配置；若需扩展，可在Nginx层增加upstream与轮询/权重策略。

    sequenceDiagram
    participant C as "客户端"
    participant N as "Nginx(book.rrbrr.com)"
    participant A as "后端应用(3100)"
    participant D as "数据库/存储"
    C->>N : "GET /api/health"
    N->>A : "proxy_pass /api/..."
    A->>D : "Prisma/Redis/OSS访问"
    A-->>N : "200 {status : healthy}"
    N-->>C : "200 OK"
    

图表来源

• DEPLOY_PROD.md: 194-201:194-201
• server/src/app.ts: 92-94:92-94

章节来源

• DEPLOY_PROD.md: 146-239:146-239
• docker-nginx/bookapi.conf: 1-15:1-15
• docker-nginx/docker-compose.yml: 1-12:1-12

容器化与编排策略

• Docker Compose（开发）
  • 单容器Nginx，映射80端口，挂载bookapi.conf，通过host.docker.internal访问宿主机服务。
  • 适用于本地联调，无需生产级SSL与高可用。
• 生产编排现状
  • 文档未提供生产级Docker Compose或Kubernetes清单；当前为传统PM2+Nginx部署。
  • 若引入容器化，建议：
  • 将后端、Nginx、MySQL、Redis分别容器化，并通过网络隔离。
  • 使用卷管理持久化数据（uploads、videos、logs）。
  • 使用环境变量与Secrets管理敏感配置。
  • 引入健康检查与重启策略，配合负载均衡。

章节来源

• docker-nginx/docker-compose.yml: 1-12:1-12
• docker-nginx/bookapi.conf: 1-15:1-15

多环境部署架构

• 开发环境
  • 本地Docker Nginx + 本地后端3000端口，便于快速迭代。
  • 可通过hosts解析bookapi.rrbrr.com至127.0.0.1。
• 测试/预发布环境
  • 建议复用生产Nginx配置模板，但将后端指向测试集群或独立容器。

• 生产环境

  • 宝塔面板管理Nginx，HTTPS/TLS、HSTS、HTTP/2、缓存头齐全。
  • 后端PM2守护，端口3100，/api反代至该端口。

  • 数据库存放在Docker单实例容器，提供备份与迁移命令。

    flowchart TD
    Dev["开发环境<br/>Docker Nginx -> 3000"] --> Test["测试环境<br/>独立容器/Nginx"]
    Test --> Prod["生产环境<br/>宝塔Nginx -> 3100"]
    

图表来源

• docker-nginx/README.md:1-41
• DEPLOY_PROD.md: 146-239:146-239

章节来源

• docker-nginx/README.md: 1-41:1-41
• DEPLOY.md: 10-116:10-116
• DEPLOY_PROD.md: 146-239:146-239

数据库部署策略

• 部署形态
  • 生产使用Docker单实例MySQL 8.0（容器名single-mysql），端口映射至主机3306。
  • 数据库名为audio_book，默认root密码为password。
• 读写分离与主从复制
  • 当前未见主从复制或读写分离配置；如需扩展，建议：
  • 引入主从拓扑或Galera Cluster/ProxySQL。
  • 在应用侧区分只读查询走从库，写操作走主库。

• 备份与恢复

  • 提供mysqldump备份命令与迁移命令，建议纳入自动化脚本与定时任务。

  • 建议对uploads、videos、logs等目录做独立备份。

    erDiagram
    USER {
    int id PK
    string phone
    string openid
    }
    BOOK {
    int id PK
    int user_id FK
    string title
    }
    BOOK_CHAPTER {
    int id PK
    int book_id FK
    string title
    }
    USER ||--o{ BOOK : "创建"
    BOOK ||--o{ BOOK_CHAPTER : "包含"
    

图表来源

• server/prisma/schema.prisma: 10-38:10-38
• server/prisma/schema.prisma: 130-194:130-194

章节来源

• DEPLOY_PROD.md: 266-294:266-294
• server/prisma/schema.prisma: 1-8:1-8

监控与日志系统

• Winston日志
  • 输出至控制台与多个文件（error/combined/http），支持按级别滚动与时间戳。
  • 提供HTTP请求日志中间件，记录方法、URL、状态、耗时、IP与UA。
• Sentry错误监控
  • 初始化时根据SENTRY_DSN决定是否启用；生产环境降低采样率。
  • 提供Koa错误中间件，自动附加请求方法、URL、用户上下文。
  • 内置错误过滤（如忽略特定Redis连接拒绝错误）。

• 性能指标

  • 提供/health健康检查与/api/metrics指标端点，便于接入Prometheus/Grafana。

    sequenceDiagram
    participant C as "客户端"
    participant N as "Nginx"
    participant A as "后端应用"
    participant L as "Winston日志"
    participant S as "Sentry"
    C->>N : "请求 /api/..."
    N->>A : "反向代理"
    A->>L : "记录HTTP请求日志"
    A->>S : "捕获异常/错误上下文"
    A-->>N : "响应"
    N-->>C : "响应"
    

图表来源

• server/src/app.ts: 64-130:64-130
• server/src/services/logger.service.ts: 74-102:74-102
• server/src/services/sentry.service.ts: 92-110:92-110

章节来源

• server/src/services/logger.service.ts: 67-114:67-114
• server/src/services/sentry.service.ts: 7-43:7-43
• server/src/app.ts: 92-98:92-98

依赖关系分析

• 后端服务依赖
  • 数据库：Prisma驱动MySQL连接。
  • 缓存：Redis用于会话/限流/队列等场景。
  • 存储：支持本地存储与阿里云OSS。
  • 监控：Sentry与Winston。

• 外部依赖

  • Nginx作为统一入口，负责TLS终止与静态资源缓存。

  • Docker（开发）或宝塔面板（生产）管理Nginx配置。

    graph LR
    APP["server/src/app.ts"] --> PRISMA["Prisma(schema.prisma)"]
    APP --> REDIS["Redis"]
    APP --> OSS["OSS"]
    APP --> WINSTON["Winston"]
    APP --> SENTRY["Sentry"]
    NGINX["Nginx配置"] --> APP
    

图表来源

• server/src/app.ts: 12-25:12-25
• server/prisma/schema.prisma: 1-8:1-8
• server/src/services/logger.service.ts: 67-72:67-72
• server/src/services/sentry.service.ts: 7-43:7-43

章节来源

• server/src/app.ts: 12-25:12-25
• server/package.json: 11-44:11-44

性能与监控

• 性能监控
  • /api/metrics端点可用于采集性能指标；建议接入Prometheus与Grafana。
  • Nginx层面可统计请求量、响应时间与错误率。
• 日志轮转与保留
  • Winston按大小与文件数限制滚动，建议结合系统日志服务集中化。
• 错误采样与过滤
  • Sentry在生产降低采样率，避免噪声；内置过滤提升关键问题可见性。

[本节为通用指导，无需具体文件引用]

故障排查指南

• 后端无法启动
  • 检查端口占用与环境变量（尤其是DATABASE_URL与SENTRY_DSN）。
  • 查看PM2日志与后端HTTP日志。
• 前端无法访问
  • 检查Nginx配置语法与静态资源目录权限。
  • 关注Nginx访问/错误日志。
• 数据库连接失败
  • 检查Docker容器状态与mysqldump连通性。
  • 对比.env中DATABASE_URL与容器内连接方式。

章节来源

• DEPLOY.md: 199-250:199-250
• DEPLOY_PROD.md: 318-375:318-375

结论

本部署架构以Nginx为入口、PM2守护后端、Prisma管理MySQL为核心，辅以Winston与Sentry实现可观测性。当前生产环境采用宝塔面板管理Nginx，具备完善的TLS与缓存策略。建议后续引入容器化编排、主从复制与读写分离、自动化备份与灰度发布流程，以进一步提升稳定性与可扩展性。

[本节为总结性内容，无需具体文件引用]

附录

• 关键端点与文件
  • 健康检查：/api/health
  • 指标端点：/api/metrics
  • 日志目录：server/logs（error/combined/http）
  • Nginx配置：宝塔面板vhost目录或docker-nginx配置
• 常用命令
  • PM2：status、logs、restart、save、startup
  • Nginx：-t、-s reload
  • MySQL：docker exec进入容器、mysqldump备份、npx prisma migrate deploy

[本节为补充信息，无需具体文件引用]