# 部署架构

<cite>
**本文档引用的文件**
- [DEPLOY.md](file://DEPLOY.md)
- [DEPLOY_PROD.md](file://DEPLOY_PROD.md)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf)
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/services/logger.service.ts](file://server/src/services/logger.service.ts)
- [server/src/services/sentry.service.ts](file://server/src/services/sentry.service.ts)
- [server/src/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/package.json](file://server/package.json)
</cite>

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

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

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

```mermaid
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](file://DEPLOY_PROD.md#L35-L46)
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)
- [server/src/app.ts: 133-166:133-166](file://server/src/app.ts#L133-L166)

**章节来源**
- [DEPLOY_PROD.md: 33-46:33-46](file://DEPLOY_PROD.md#L33-L46)
- [DEPLOY.md: 10-116:10-116](file://DEPLOY.md#L10-L116)

## 核心组件
- 反向代理与负载均衡
  - 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](file://server/src/app.ts#L57-L131)
- [server/src/config/index.ts: 69-117:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/services/logger.service.ts: 67-114:67-114](file://server/src/services/logger.service.ts#L67-L114)
- [server/src/services/sentry.service.ts: 7-43:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/prisma/schema.prisma: 1-8:1-8](file://server/prisma/schema.prisma#L1-L8)

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

```mermaid
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](file://DEPLOY_PROD.md#L146-L239)
- [server/src/app.ts: 133-166:133-166](file://server/src/app.ts#L133-L166)
- [server/prisma/schema.prisma: 5-8:5-8](file://server/prisma/schema.prisma#L5-L8)

## 详细组件分析

### 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与轮询/权重策略。

```mermaid
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](file://DEPLOY_PROD.md#L194-L201)
- [server/src/app.ts: 92-94:92-94](file://server/src/app.ts#L92-L94)

**章节来源**
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)
- [docker-nginx/bookapi.conf: 1-15:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [docker-nginx/docker-compose.yml: 1-12:1-12](file://docker-nginx/docker-compose.yml#L1-L12)

### 容器化与编排策略
- 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](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf: 1-15:1-15](file://docker-nginx/bookapi.conf#L1-L15)

### 多环境部署架构
- 开发环境
  - 本地Docker Nginx + 本地后端3000端口，便于快速迭代。
  - 可通过hosts解析bookapi.rrbrr.com至127.0.0.1。
- 测试/预发布环境
  - 建议复用生产Nginx配置模板，但将后端指向测试集群或独立容器。
- 生产环境
  - 宝塔面板管理Nginx，HTTPS/TLS、HSTS、HTTP/2、缓存头齐全。
  - 后端PM2守护，端口3100，/api反代至该端口。
  - 数据库存放在Docker单实例容器，提供备份与迁移命令。

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

**图表来源**
- [docker-nginx/README.md:1-41](file://docker-nginx/README.md#L1-L41)
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)

**章节来源**
- [docker-nginx/README.md: 1-41:1-41](file://docker-nginx/README.md#L1-L41)
- [DEPLOY.md: 10-116:10-116](file://DEPLOY.md#L10-L116)
- [DEPLOY_PROD.md: 146-239:146-239](file://DEPLOY_PROD.md#L146-L239)

### 数据库部署策略
- 部署形态
  - 生产使用Docker单实例MySQL 8.0（容器名single-mysql），端口映射至主机3306。
  - 数据库名为audio_book，默认root密码为password。
- 读写分离与主从复制
  - 当前未见主从复制或读写分离配置；如需扩展，建议：
    - 引入主从拓扑或Galera Cluster/ProxySQL。
    - 在应用侧区分只读查询走从库，写操作走主库。
- 备份与恢复
  - 提供mysqldump备份命令与迁移命令，建议纳入自动化脚本与定时任务。
  - 建议对uploads、videos、logs等目录做独立备份。

```mermaid
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](file://server/prisma/schema.prisma#L10-L38)
- [server/prisma/schema.prisma: 130-194:130-194](file://server/prisma/schema.prisma#L130-L194)

**章节来源**
- [DEPLOY_PROD.md: 266-294:266-294](file://DEPLOY_PROD.md#L266-L294)
- [server/prisma/schema.prisma: 1-8:1-8](file://server/prisma/schema.prisma#L1-L8)

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

```mermaid
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](file://server/src/app.ts#L64-L130)
- [server/src/services/logger.service.ts: 74-102:74-102](file://server/src/services/logger.service.ts#L74-L102)
- [server/src/services/sentry.service.ts: 92-110:92-110](file://server/src/services/sentry.service.ts#L92-L110)

**章节来源**
- [server/src/services/logger.service.ts: 67-114:67-114](file://server/src/services/logger.service.ts#L67-L114)
- [server/src/services/sentry.service.ts: 7-43:7-43](file://server/src/services/sentry.service.ts#L7-L43)
- [server/src/app.ts: 92-98:92-98](file://server/src/app.ts#L92-L98)

## 依赖关系分析
- 后端服务依赖
  - 数据库：Prisma驱动MySQL连接。
  - 缓存：Redis用于会话/限流/队列等场景。
  - 存储：支持本地存储与阿里云OSS。
  - 监控：Sentry与Winston。
- 外部依赖
  - Nginx作为统一入口，负责TLS终止与静态资源缓存。
  - Docker（开发）或宝塔面板（生产）管理Nginx配置。

```mermaid
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](file://server/src/app.ts#L12-L25)
- [server/prisma/schema.prisma: 1-8:1-8](file://server/prisma/schema.prisma#L1-L8)
- [server/src/services/logger.service.ts: 67-72:67-72](file://server/src/services/logger.service.ts#L67-L72)
- [server/src/services/sentry.service.ts: 7-43:7-43](file://server/src/services/sentry.service.ts#L7-L43)

**章节来源**
- [server/src/app.ts: 12-25:12-25](file://server/src/app.ts#L12-L25)
- [server/package.json: 11-44:11-44](file://server/package.json#L11-L44)

## 性能与监控
- 性能监控
  - /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](file://DEPLOY.md#L199-L250)
- [DEPLOY_PROD.md: 318-375:318-375](file://DEPLOY_PROD.md#L318-L375)

## 结论
本部署架构以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

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