# 部署与环境问题

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

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

## 简介
本文件面向AI有声书生成平台的运维与开发团队，提供从开发到生产的全链路部署与环境问题排查指南。内容覆盖：
- Docker容器化部署与Nginx反向代理配置
- 环境变量与配置文件管理
- SSL证书与安全加固
- 数据库连接池与外部服务连通性问题
- 容器启动失败、端口冲突、文件权限、网络异常等常见故障定位
- 自动化部署脚本调试、环境一致性检查、服务健康检查与回滚策略
- 生产环境与开发环境差异处理

## 项目结构
该仓库包含后端Node.js服务、前端UniApp应用、Docker化的Nginx反代、部署脚本与自动化部署配置。关键目录与文件如下：
- 后端服务：server/src/app.ts、server/src/config/*
- 前端应用：my-uniapp-vue3/
- Docker反代：docker-nginx/
- 部署脚本：deploy.sh、deploy-prod.sh、deploy-server.sh
- 自动化部署：server/webhook-deploy.py、AUTO_DEPLOY.md
- 文档：DEPLOY.md、DEPLOY_PROD.md

```mermaid
graph TB
subgraph "前端"
FE["my-uniapp-vue3<br/>构建产物 dist/"]
end
subgraph "后端"
APP["server/src/app.ts<br/>Koa 应用"]
CFG[".env / models.json<br/>配置加载"]
DB["MySQL 8.0 (Docker)"]
REDIS["Redis"]
OSS["阿里云 OSS"]
end
subgraph "反向代理"
NGINX["Nginx (宝塔/Compose)"]
end
subgraph "自动化"
WH["webhook-deploy.py"]
SCRIPTS["deploy.sh / deploy-prod.sh"]
end
FE --> NGINX
NGINX --> APP
APP --> DB
APP --> REDIS
APP --> OSS
WH --> SCRIPTS
SCRIPTS --> NGINX
SCRIPTS --> APP
```

图表来源
- [server/src/app.ts:132-194](file://server/src/app.ts#L132-L194)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [server/webhook-deploy.py:38-78](file://server/webhook-deploy.py#L38-L78)

章节来源
- [DEPLOY.md:10-116](file://DEPLOY.md#L10-L116)
- [DEPLOY_PROD.md:33-46](file://DEPLOY_PROD.md#L33-L46)
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)

## 核心组件
- 后端应用启动与健康检查
  - 应用通过HTTP服务器监听配置端口，提供 /health 健康检查接口；启动时初始化数据库连接、Redis连接、存储连接，并注册路由与队列处理器。
- 配置体系
  - 通过dotenv加载 .env；模型配置来自 models.json；支持多厂商TTS与文本模型自动切换。
- 反向代理
  - 生产使用宝塔管理Nginx；开发使用Docker Compose运行Nginx并代理至宿主机3000端口。
- 自动化部署
  - webhook服务接收Gogs/Gitea推送，校验签名后拉取代码并执行部署脚本，最终通过PM2管理后端进程。

章节来源
- [server/src/app.ts:91-98](file://server/src/app.ts#L91-L98)
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)
- [server/webhook-deploy.py:79-138](file://server/webhook-deploy.py#L79-L138)

## 架构总览
下图展示生产与开发两种部署形态的关键交互：

```mermaid
graph TB
subgraph "开发环境"
D_NGINX["Docker Nginx<br/>bookapi.conf -> host:3000"]
D_APP["后端容器<br/>dist/app.js"]
D_DB["MySQL 容器"]
D_REDIS["Redis 容器"]
end
subgraph "生产环境"
P_NGINX["宝塔 Nginx<br/>book.rrbrr.com -> /h5<br/>bookapi.rrbrr.com -> 3100"]
P_FE["前端构建产物<br/>/data/ai/audio/frontend/build/h5"]
P_APP["PM2 管理后端<br/>dist/app.js"]
P_DB["MySQL 容器/主机"]
P_REDIS["Redis 容器/主机"]
P_OSS["阿里云 OSS"]
end
subgraph "自动化"
WEBHOOK["webhook-deploy.py"]
DEPLOY["deploy-prod.sh / deploy.sh"]
end
D_NGINX --> D_APP
D_APP --> D_DB
D_APP --> D_REDIS
P_NGINX --> P_FE
P_NGINX --> P_APP
P_APP --> P_DB
P_APP --> P_REDIS
P_APP --> P_OSS
WEBHOOK --> DEPLOY
DEPLOY --> P_APP
DEPLOY --> P_NGINX
```

图表来源
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [DEPLOY_PROD.md:146-239](file://DEPLOY_PROD.md#L146-L239)
- [server/webhook-deploy.py:38-78](file://server/webhook-deploy.py#L38-L78)
- [deploy.sh:178-201](file://deploy.sh#L178-L201)

## 详细组件分析

### 组件A：后端应用启动与健康检查
- 启动流程要点
  - 初始化Sentry错误监控
  - 连接数据库（Prisma）
  - 测试Redis与存储连接
  - 初始化订阅套餐、WebSocket
  - 监听配置端口，输出启动日志
  - 注册优雅关闭钩子，释放资源
- 健康检查
  - /health 返回标准响应体，便于Nginx/PM2探活

```mermaid
sequenceDiagram
participant Proc as "PM2/进程"
participant App as "server/src/app.ts"
participant DB as "MySQL"
participant Cache as "Redis"
participant Store as "OSS/本地"
Proc->>App : 启动 dist/app.js
App->>App : initSentry()
App->>DB : connectDatabase()
DB-->>App : OK
App->>Cache : testConnection()
Cache-->>App : OK/失败
App->>Store : testConnection()
Store-->>App : OK/失败
App->>App : initWebSocket()/initQueues()
App->>Proc : 监听配置端口
Proc-->>Proc : /health 健康检查
```

图表来源
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)

章节来源
- [server/src/app.ts:91-98](file://server/src/app.ts#L91-L98)
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)

### 组件B：配置与环境变量
- 环境变量加载
  - 通过dotenv加载 .env；端口优先级：PORT > SERVER_PORT > 默认值
- 模型配置
  - models.json集中管理多厂商模型与默认参数，支持按类型筛选与自动切换
- 关键配置项
  - JWT密钥、DashScope/TTS参数、数据库URL、Redis连接、OSS凭据等

```mermaid
flowchart TD
Start(["启动"]) --> LoadEnv["加载 .env"]
LoadEnv --> PortCfg["解析端口配置"]
PortCfg --> ModelsLoad["加载 models.json"]
ModelsLoad --> SwitchCheck{"是否需要模型切换?"}
SwitchCheck --> |是| NextModel["选择下一个可用模型"]
SwitchCheck --> |否| Ready["进入运行阶段"]
NextModel --> Ready
Ready --> End(["完成"])
```

图表来源
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)

章节来源
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/config/models.json:1-186](file://server/src/config/models.json#L1-L186)

### 组件C：Nginx反向代理与SSL
- 生产环境（宝塔）
  - 前端：book.rrbrr.com -> /data/ai/audio/frontend/build/h5
  - 后端：bookapi.rrbrr.com -> 3100
  - HTTPS：证书路径与HSTS、HTTP/2、TLS策略配置
- 开发环境（Docker Compose）
  - Nginx容器映射80:80，代理到 host.docker.internal:3000

```mermaid
flowchart TD
CfgStart["Nginx 配置"] --> Prod{"生产环境?"}
Prod --> |是| BT["宝塔 vhost 配置<br/>ssl_certificate/key<br/>/api -> 3100"]
Prod --> |否| Dev["Docker Compose<br/>bookapi.conf -> 3000"]
BT --> Done["生效"]
Dev --> Done
```

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

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

### 组件D：自动化部署与回滚
- webhook服务
  - 接收Gogs/Gitea推送，校验签名，执行部署脚本
- 部署脚本
  - deploy.sh：本地构建后端与前端，同步至服务器，安装依赖，生成Prisma客户端，重启PM2
  - deploy-prod.sh：生产专用脚本，检查/安装Node.js，复制生产.env，生成Prisma客户端，PM2启动
- 回滚策略
  - 部署前自动创建备份目录，保留前后端目录，回滚时直接恢复对应备份

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Git as "Gogs/Gitea"
participant WH as "webhook-deploy.py"
participant Srv as "服务器"
participant Dep as "deploy-prod.sh"
participant PM2 as "PM2"
Dev->>Git : Push 代码
Git->>WH : POST webhook
WH->>WH : 校验签名
WH->>Dep : 执行部署脚本
Dep->>Srv : rsync/解压/安装依赖
Dep->>PM2 : pm2 restart server
PM2-->>Srv : 服务就绪
```

图表来源
- [server/webhook-deploy.py:79-138](file://server/webhook-deploy.py#L79-L138)
- [deploy-prod.sh:139-164](file://deploy-prod.sh#L139-L164)
- [deploy.sh:54-90](file://deploy.sh#L54-L90)

章节来源
- [AUTO_DEPLOY.md:1-77](file://AUTO_DEPLOY.md#L1-L77)
- [server/webhook-deploy.py:38-78](file://server/webhook-deploy.py#L38-L78)
- [deploy-prod.sh:139-164](file://deploy-prod.sh#L139-L164)
- [deploy.sh:54-90](file://deploy.sh#L54-L90)

## 依赖关系分析
- 后端依赖
  - Koa、路由、中间件、Prisma、Sentry、Redis、OSS、队列、WebSocket等
- 前端依赖
  - UniApp生态、Vue3、Pinia、vConsole等
- 部署与运维
  - PM2、Nginx、宝塔、Docker、rsync、ssh、systemd

```mermaid
graph LR
S_PKG["server/package.json"] --> S_DEPS["后端依赖"]
F_PKG["my-uniapp-vue3/package.json"] --> F_DEPS["前端依赖"]
S_DEPS --> APP_TS["server/src/app.ts"]
S_DEPS --> CFG_TS["server/src/config/index.ts"]
CFG_TS --> MODELS["server/src/config/models.json"]
APP_TS --> PM2["PM2"]
PM2 --> NGINX["Nginx/宝塔"]
```

图表来源
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [server/src/app.ts:1-56](file://server/src/app.ts#L1-L56)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)

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

## 性能考虑
- 连接池与并发
  - 数据库连接池大小与超时应结合负载评估；生产环境建议开启连接复用与超时控制
- 缓存策略
  - Redis作为缓存层，需关注命中率与过期策略；对热点数据进行预热
- 存储与CDN
  - 音频/视频文件走OSS，静态资源Nginx缓存；合理设置expires与压缩
- 监控与告警
  - 启用Sentry错误监控、性能中间件与日志采集，建立阈值告警

## 故障排查指南

### 容器启动失败
- 检查容器日志
  - Docker Compose：查看Nginx容器日志与启动状态
- 端口占用
  - 确认宿主机80端口未被占用；若冲突，修改映射或释放端口
- 权限问题
  - 确保挂载目录权限正确，避免容器内无法写入

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

### 端口冲突
- 本地开发
  - 将Nginx映射端口调整为非80或停止占用进程
- 生产环境
  - 确认防火墙与安全组放行端口；宝塔面板检查端口占用

章节来源
- [docker-nginx/bookapi.conf:2-13](file://docker-nginx/bookapi.conf#L2-L13)
- [DEPLOY_PROD.md:348-362](file://DEPLOY_PROD.md#L348-L362)

### 文件权限问题
- 前端静态目录
  - 确保Nginx可读；生产环境检查 /data/ai/audio/frontend/build/h5 权限
- 上传与视频目录
  - 后端 uploads/public/videos 目录属主与权限需允许Node进程写入

章节来源
- [DEPLOY.md:206-209](file://DEPLOY.md#L206-L209)
- [DEPLOY_PROD.md:310-316](file://DEPLOY_PROD.md#L310-L316)

### 网络连接异常
- 后端无法访问
  - 检查PM2状态与端口监听；直接curl 127.0.0.1:端口验证
- Nginx 502
  - 检查后端进程、端口监听、Nginx配置语法与重载

章节来源
- [DEPLOY.md:201-204](file://DEPLOY.md#L201-L204)
- [DEPLOY_PROD.md:348-362](file://DEPLOY_PROD.md#L348-L362)

### 数据库连接池问题
- 连接失败
  - 检查MySQL容器状态、密码、网络连通；执行SQL验证连接
- 迁移与初始化
  - 使用Prisma迁移命令确保schema一致

章节来源
- [DEPLOY_PROD.md:332-346](file://DEPLOY_PROD.md#L332-L346)
- [DEPLOY_PROD.md:291-294](file://DEPLOY_PROD.md#L291-L294)

### 自动化部署脚本调试
- webhook服务
  - 校验签名头字段（X-Hub-Signature-256/X-Gogs-Signature/X-Gitea-Signature）；确认secret一致
  - 查看日志文件与端口监听
- 部署脚本
  - 检查rsync排除规则、远程执行顺序、PM2启动参数与环境变量

章节来源
- [AUTO_DEPLOY.md:68-77](file://AUTO_DEPLOY.md#L68-L77)
- [server/webhook-deploy.py:94-106](file://server/webhook-deploy.py#L94-L106)
- [deploy-prod.sh:139-164](file://deploy-prod.sh#L139-L164)

### 环境一致性检查
- 环境变量
  - 对比 .env.production 与 .env；核对数据库URL、Redis、OSS、TTS密钥
- 依赖版本
  - server/package.json 与 my-uniapp-vue3/package.json 的关键依赖版本
- 构建产物
  - 前端构建目录与后端dist目录完整性

章节来源
- [deploy-prod.sh:117-121](file://deploy-prod.sh#L117-L121)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

### 服务健康检查与回滚策略
- 健康检查
  - /health 接口、PM2状态、Nginx状态、后端端口监听
- 回滚
  - 使用备份目录恢复；PM2回滚至上一个版本

章节来源
- [server/src/app.ts:91-98](file://server/src/app.ts#L91-L98)
- [DEPLOY.md:27-59](file://DEPLOY.md#L27-L59)
- [DEPLOY.md:220-250](file://DEPLOY.md#L220-L250)

### 生产环境与开发环境差异
- 端口与域名
  - 生产：bookapi.rrbrr.com:3100；开发：bookapi.rrbrr.com:80 -> host:3000
- Nginx管理
  - 生产：宝塔vhost；开发：Docker Compose
- 部署方式
  - 生产：deploy-prod.sh（含Node.js检查、复制生产.env）；开发：deploy.sh
- SSL与证书
  - 生产：宝塔证书路径；开发：本地或跳过

章节来源
- [DEPLOY_PROD.md:146-239](file://DEPLOY_PROD.md#L146-L239)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [deploy-prod.sh:139-164](file://deploy-prod.sh#L139-L164)
- [deploy.sh:178-201](file://deploy.sh#L178-L201)

## 结论
通过标准化的部署脚本、清晰的配置体系与完善的自动化流程，本项目可在生产与开发环境中稳定运行。建议持续完善监控与告警、定期演练回滚流程，并在变更前进行充分的环境一致性检查，以降低发布风险。

## 附录
- 常用命令与参考路径
  - 后端管理：PM2日志、重启、状态
  - Nginx管理：配置测试、重载、重启
  - 日志查看：Nginx访问/错误日志、PM2后端日志
- 参考文档
  - DEPLOY.md、DEPLOY_PROD.md、AUTO_DEPLOY.md