# 部署运维

<cite>
**本文引用的文件**
- [DEPLOY.md](file://DEPLOY.md)
- [DEPLOY_PROD.md](file://DEPLOY_PROD.md)
- [deploy-prod.sh](file://deploy-prod.sh)
- [deploy.sh](file://deploy.sh)
- [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/middleware/security.ts](file://server/src/middleware/security.ts)
- [server/src/services/sentry.service.ts](file://server/src/services/sentry.service.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/package.json](file://server/package.json)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [AUTO_DEPLOY.md](file://AUTO_DEPLOY.md)
- [server/webhook-deploy.py](file://server/webhook-deploy.py)
</cite>

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

## 简介
本文件面向AI有声书生成平台的部署与运维，覆盖开发、测试与生产三类环境的部署配置与流程，包括：
- Docker容器化部署方案与Nginx反向代理
- MySQL数据库与Redis缓存配置
- 完整部署脚本说明、环境变量与依赖服务安装
- CI/CD流水线设计、自动化部署与回滚策略
- 监控告警、日志收集分析与性能优化
- 故障排查、备份恢复与安全加固

## 项目结构
项目采用前后端分离架构：
- 后端：基于Node.js/Koa的API服务，使用Prisma进行MySQL访问，集成Redis缓存、对象存储（OSS/本地）、任务队列等
- 前端：UniApp Vue3应用，构建产物作为静态资源由Nginx提供
- 运维：提供多套部署脚本与自动化部署方案，支持PM2进程管理与Nginx反代

```mermaid
graph TB
subgraph "客户端"
U["浏览器/移动端"]
end
subgraph "边缘层"
NGINX["Nginx 反向代理<br/>静态资源/HTTPS/重定向"]
end
subgraph "应用层"
API["后端API服务<br/>Koa + Prisma + Redis + OSS"]
WS["WebSocket 服务"]
end
subgraph "数据层"
MYSQL["MySQL 8.0"]
REDIS["Redis 缓存"]
OSS["对象存储(OSS)"]
end
U --> NGINX
NGINX --> API
API --> MYSQL
API --> REDIS
API --> OSS
API --> WS
```

图表来源
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)
- [server/src/config/index.ts:70-117](file://server/src/config/index.ts#L70-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

章节来源
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)
- [DEPLOY_PROD.md:1-393](file://DEPLOY_PROD.md#L1-L393)

## 核心组件
- 应用服务（后端）：负责业务接口、鉴权、TTS生成、播放、订阅、支付、发布等模块；通过PM2管理进程，支持健康检查与性能指标
- Nginx反向代理：前端静态资源直出、HTTPS终止、API反向代理、安全头设置
- 数据库：MySQL 8.0（Docker），Prisma ORM管理Schema与迁移
- 缓存：Redis（可选），用于限流、会话、任务队列等
- 对象存储：OSS或本地存储，用于音视频文件分发
- 自动化部署：Shell脚本与Python Webhook，支持Git推送触发部署

章节来源
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-194)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 架构总览
下图展示从客户端到后端服务、数据库与缓存的整体交互：

```mermaid
sequenceDiagram
participant C as "客户端"
participant N as "Nginx"
participant A as "后端API"
participant P as "Prisma"
participant M as "MySQL"
participant R as "Redis"
participant O as "OSS"
C->>N : HTTPS 请求
N->>A : 反向代理 /api/*
A->>P : 查询/更新
P->>M : SQL 执行
A->>R : 读写缓存
A->>O : 上传/下载媒体
A-->>N : 响应
N-->>C : 返回内容
```

图表来源
- [server/src/app.ts:92-130](file://server/src/app.ts#L92-L130)
- [server/src/config/index.ts:70-117](file://server/src/config/index.ts#L70-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 详细组件分析

### 1) 开发/测试/生产环境部署配置
- 开发环境
  - 本地开发：后端使用TypeScript运行时，前端H5构建
  - Docker本地反代：通过docker-compose将Nginx容器映射至80端口，代理到宿主机3000端口
- 测试/生产环境
  - 服务器：/data/ai 或 /data/ai/audio
  - 前端：静态资源目录，Nginx提供HTTP/HTTPS与缓存头
  - 后端：PM2守护进程，监听3100端口，健康检查路径 /health
  - 数据库：Docker MySQL 8.0，容器名为single-mysql，端口映射3306
  - 缓存：Redis（可选），通过环境变量配置

章节来源
- [DEPLOY.md:10-160](file://DEPLOY.md#L10-L160)
- [DEPLOY_PROD.md:26-93](file://DEPLOY_PROD.md#L26-L93)
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

### 2) Docker容器化部署方案
- 单容器Nginx反向代理
  - 映射80:80，挂载bookapi.conf
  - 通过host.docker.internal将请求转发至宿主机3000端口
- 适用场景：本地联调、快速预览

章节来源
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

### 3) Nginx反向代理配置
- 前端域名：book.rrbrr.com，HTTPS，静态资源缓存与安全头
- 后端域名：bookapi.rrbrr.com，HTTP反代至127.0.0.1:3000/3100
- 宝塔面板管理：Nginx配置文件位于 /www/server/panel/vhost/nginx/
- 关键点：重定向、SSL证书、安全头、访问/错误日志

章节来源
- [DEPLOY.md:61-116](file://DEPLOY.md#L61-L116)
- [DEPLOY_PROD.md:146-246](file://DEPLOY_PROD.md#L146-L246)

### 4) MySQL数据库部署与配置
- Docker部署：容器名 single-mysql，版本8.0，端口3306，密码 password，数据库 audio_book
- Schema定义：Prisma schema.prisma集中定义用户、订单、播放记录、收藏、书稿、章节、视频工程等模型
- 迁移与备份：使用npx prisma migrate deploy执行迁移；mysqldump备份数据库

章节来源
- [DEPLOY_PROD.md:264-294](file://DEPLOY_PROD.md#L264-L294)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

### 5) Redis缓存配置
- 用途：限流、会话、任务队列、速率限制等
- 配置项：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DB
- 运行时检测：启动时测试连接，失败则降级为内存模式

章节来源
- [server/src/app.ts:142-151](file://server/src/app.ts#L142-L151)
- [server/src/config/index.ts:129-134](file://server/src/config/index.ts#L129-L134)

### 6) 环境变量与依赖服务
- 后端环境变量（示例）：NODE_ENV、SERVER_PORT、JWT_SECRET、DASHSCOPE_*、DATABASE_URL、STORAGE_TYPE、REDIS_*、OSS_*、MINIMAX_API_KEY
- 前端依赖：Vue3、Pinia、UniApp生态
- 后端依赖：Koa、Prisma、ioredis、bull、axios、langchain、mysql2、ali-oss、sentry等

章节来源
- [DEPLOY_PROD.md:105-144](file://DEPLOY_PROD.md#L105-L144)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [server/package.json:1-60](file://server/package.json#L1-L60)

### 7) 部署脚本说明
- deploy-prod.sh：一键部署脚本，包含前端构建、打包上传、服务器端安装依赖、复制生产配置、生成Prisma Client、PM2启动、Nginx配置提示
- deploy.sh：通用部署脚本，支持备份、同步、安装依赖、生成Prisma Client、PM2启动、Nginx配置
- 自动化部署：AUTO_DEPLOY.md提供Webhook部署方案，支持Gogs/GitHub推送触发

章节来源
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)

### 8) CI/CD流水线设计与自动化部署
- 方案一：Webhook（推荐）
  - 服务器端：Python HTTP服务监听端口，校验签名后执行部署脚本
  - Nginx：将/webhook转发至本地端口
  - Gogs：推送事件触发webhook
- 方案二：Git Hook（简化）
  - 服务器Git仓库post-receive钩子，拉取代码、构建后PM2重启

```mermaid
sequenceDiagram
participant Dev as "开发者(Gogs)"
participant N as "Nginx"
participant W as "Webhook服务"
participant S as "服务器"
participant D as "部署脚本"
participant P as "PM2"
Dev->>N : 推送代码触发webhook
N->>W : 转发 /webhook
W->>S : 验证签名/解析payload
S->>D : 执行部署脚本
D->>P : pm2 restart server
P-->>Dev : 部署完成
```

图表来源
- [AUTO_DEPLOY.md:51-78](file://AUTO_DEPLOY.md#L51-L78)
- [server/webhook-deploy.py:79-125](file://server/webhook-deploy.py#L79-L125)

章节来源
- [AUTO_DEPLOY.md:1-142](file://AUTO_DEPLOY.md#L1-L142)
- [server/webhook-deploy.py:1-139](file://server/webhook-deploy.py#L1-L139)

### 9) 回滚策略
- 备份机制：部署前自动创建备份目录（包含server与frontend），便于回滚
- 回滚步骤：停止PM2服务，恢复备份目录内容，重新安装依赖与生成Prisma Client，PM2重启

章节来源
- [DEPLOY.md:27-59](file://DEPLOY.md#L27-L59)
- [DEPLOY_PROD.md:377-393](file://DEPLOY_PROD.md#L377-L393)

### 10) 监控告警与日志
- 错误监控：Sentry集成，支持性能采样与错误过滤
- 日志：Nginx访问/错误日志；PM2后端日志；应用层Winston日志
- 健康检查：/health；性能指标：/api/metrics

章节来源
- [server/src/services/sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [server/src/app.ts:92-98](file://server/src/app.ts#L92-L98)
- [DEPLOY.md:187-197](file://DEPLOY.md#L187-L197)

### 11) 安全加固
- 安全中间件：XSS防护、SQL注入检测、敏感数据脱敏
- Nginx安全头：X-XSS-Protection、X-Content-Type-Options、X-Frame-Options、Content-Security-Policy
- 认证与授权：JWT密钥配置；鉴权中间件
- 传输安全：HTTPS、Strict-Transport-Security、TLS协议与密码套件

章节来源
- [server/src/middleware/security.ts:1-154](file://server/src/middleware/security.ts#L1-L154)
- [server/src/config/index.ts:77-81](file://server/src/config/index.ts#L77-L81)
- [DEPLOY_PROD.md:173-186](file://DEPLOY_PROD.md#L173-L186)

## 依赖关系分析

```mermaid
graph LR
APP["server/src/app.ts"] --> CFG["server/src/config/index.ts"]
APP --> SEC["server/src/middleware/security.ts"]
APP --> SEN["server/src/services/sentry.service.ts"]
APP --> PRISMA["server/prisma/schema.prisma"]
APP --> MYSQL["MySQL 8.0"]
APP --> REDIS["Redis"]
APP --> OSS["OSS"]
NGINX["Nginx"] --> APP
FE["前端静态资源"] --> NGINX
```

图表来源
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

章节来源
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 性能考虑
- Nginx缓存与压缩：静态资源长缓存、HTTP/2提升传输效率
- 后端限流与熔断：速率限制中间件、模型自动切换逻辑
- 数据库优化：索引设计、连接池、慢查询日志
- 缓存策略：热点数据缓存、任务队列异步化
- 监控与剖析：Sentry性能采样、指标暴露

章节来源
- [server/src/config/index.ts:45-67](file://server/src/config/index.ts#L45-L67)
- [server/src/services/sentry.service.ts:15-43](file://server/src/services/sentry.service.ts#L15-L43)

## 故障排查指南
- 后端无法启动
  - 检查端口占用与环境变量；查看PM2日志
- 前端无法访问
  - 检查Nginx配置与静态资源目录权限
- 数据库连接失败
  - 检查MySQL容器状态与连接串
- Nginx 502错误
  - 检查后端进程监听端口与健康检查
- 自动化部署失败
  - 检查Webhook服务状态、签名与日志

章节来源
- [DEPLOY.md:199-214](file://DEPLOY.md#L199-L214)
- [DEPLOY_PROD.md:318-375](file://DEPLOY_PROD.md#L318-L375)
- [AUTO_DEPLOY.md:97-111](file://AUTO_DEPLOY.md#L97-L111)

## 结论
本部署运维文档提供了从开发到生产的完整落地方案，涵盖容器化、反向代理、数据库与缓存、自动化部署与回滚、监控告警与安全加固。建议在生产环境中结合宝塔面板与Webhook自动化部署，并定期进行备份与演练。

## 附录

### A. 环境变量清单（摘录）
- NODE_ENV、SERVER_PORT、AUTH_ENABLED
- JWT_SECRET、JWT_EXPIRES_IN
- DASHSCOPE_*（API密钥、模型、语音、实时模式）
- DATABASE_URL（MySQL）
- STORAGE_TYPE（oss或本地）
- REDIS_*（主机、端口、密码、DB）
- OSS_*（Endpoint、AccessKey、Secret、Bucket、Region）
- MINIMAX_API_KEY

章节来源
- [DEPLOY_PROD.md:105-144](file://DEPLOY_PROD.md#L105-L144)

### B. 常用命令速查
- 后端管理：PM2状态、日志、重启、停止
- Nginx管理：配置测试、重载、重启
- 数据库：进入容器、查看数据库、执行SQL、备份、迁移

章节来源
- [DEPLOY.md:161-197](file://DEPLOY.md#L161-L197)
- [DEPLOY_PROD.md:276-294](file://DEPLOY_PROD.md#L276-L294)