audio_codebuddy/.qoder/repowiki/zh/content/故障排除/部署与环境问题.md

部署与环境问题

本文引用的文件

• DEPLOY.md
• DEPLOY_PROD.md
• deploy.sh
• deploy-prod.sh
• deploy-server.sh
• docker-nginx/docker-compose.yml
• docker-nginx/bookapi.conf
• server/src/app.ts
• server/src/config/index.ts
• server/src/config/models.json
• server/package.json
• my-uniapp-vue3/package.json
• server/webhook-deploy.py
• AUTO_DEPLOY.md

目录

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

  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
• server/src/config/index.ts:69-117
• docker-nginx/docker-compose.yml:1-12
• server/webhook-deploy.py:38-78

章节来源

• DEPLOY.md:10-116
• DEPLOY_PROD.md:33-46
• docker-nginx/docker-compose.yml:1-12

核心组件

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

章节来源

• server/src/app.ts:91-98
• server/src/app.ts:133-192
• server/src/config/index.ts:1-117
• server/src/config/models.json:1-186
• server/webhook-deploy.py:79-138

架构总览

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

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
• docker-nginx/docker-compose.yml:1-12
• DEPLOY_PROD.md:146-239
• server/webhook-deploy.py:38-78
• deploy.sh:178-201

详细组件分析

组件A：后端应用启动与健康检查

• 启动流程要点
  • 初始化Sentry错误监控
  • 连接数据库（Prisma）
  • 测试Redis与存储连接
  • 初始化订阅套餐、WebSocket
  • 监听配置端口，输出启动日志
  • 注册优雅关闭钩子，释放资源

• 健康检查

  • /health 返回标准响应体，便于Nginx/PM2探活

    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

章节来源

• server/src/app.ts:91-98
• server/src/app.ts:133-192

组件B：配置与环境变量

• 环境变量加载
  • 通过dotenv加载 .env；端口优先级：PORT > SERVER_PORT > 默认值
• 模型配置
  • models.json集中管理多厂商模型与默认参数，支持按类型筛选与自动切换

• 关键配置项

  • JWT密钥、DashScope/TTS参数、数据库URL、Redis连接、OSS凭据等

    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
• server/src/config/models.json:1-186

章节来源

• server/src/config/index.ts:1-117
• server/src/config/models.json:1-186

组件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

    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
• docker-nginx/bookapi.conf:1-15
• docker-nginx/docker-compose.yml:1-12

章节来源

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

组件D：自动化部署与回滚

• webhook服务
  • 接收Gogs/Gitea推送，校验签名，执行部署脚本
• 部署脚本
  • deploy.sh：本地构建后端与前端，同步至服务器，安装依赖，生成Prisma客户端，重启PM2
  • deploy-prod.sh：生产专用脚本，检查/安装Node.js，复制生产.env，生成Prisma客户端，PM2启动

• 回滚策略

  • 部署前自动创建备份目录，保留前后端目录，回滚时直接恢复对应备份

    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
• deploy-prod.sh:139-164
• deploy.sh:54-90

章节来源

• AUTO_DEPLOY.md:1-77
• server/webhook-deploy.py:38-78
• deploy-prod.sh:139-164
• deploy.sh:54-90

依赖关系分析

• 后端依赖
  • Koa、路由、中间件、Prisma、Sentry、Redis、OSS、队列、WebSocket等
• 前端依赖
  • UniApp生态、Vue3、Pinia、vConsole等

• 部署与运维

  • PM2、Nginx、宝塔、Docker、rsync、ssh、systemd

    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
• my-uniapp-vue3/package.json:1-65
• server/src/app.ts:1-56
• server/src/config/index.ts:1-117

章节来源

• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65

性能考虑

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

故障排查指南

容器启动失败

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

章节来源

• docker-nginx/docker-compose.yml:1-12

端口冲突

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

章节来源

• docker-nginx/bookapi.conf:2-13
• DEPLOY_PROD.md:348-362

文件权限问题

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

章节来源

• DEPLOY.md:206-209
• DEPLOY_PROD.md:310-316

网络连接异常

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

章节来源

• DEPLOY.md:201-204
• DEPLOY_PROD.md:348-362

数据库连接池问题

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

章节来源

• DEPLOY_PROD.md:332-346
• DEPLOY_PROD.md:291-294

自动化部署脚本调试

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

章节来源

• AUTO_DEPLOY.md:68-77
• server/webhook-deploy.py:94-106
• deploy-prod.sh:139-164

环境一致性检查

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

章节来源

• deploy-prod.sh:117-121
• server/package.json:1-60
• my-uniapp-vue3/package.json:1-65

服务健康检查与回滚策略

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

章节来源

• server/src/app.ts:91-98
• DEPLOY.md:27-59
• DEPLOY.md:220-250

生产环境与开发环境差异

• 端口与域名
  • 生产：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
• docker-nginx/bookapi.conf:1-15
• deploy-prod.sh:139-164
• deploy.sh:178-201

结论

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

附录

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