Startsida Utforska Hjälp
Logga in
caojunfei
/
audio_codebuddy
1
0
Fork 0
Filer Ärenden 0 Pull-förfrågningar 0 Wiki
Träd: 3add33f930
Grenar Taggar
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
系统架构
/
部署架构
/
多环境部署.md

多环境部署.md 13 KB
Historik Rå

多环境部署

本文引用的文件

  • server/src/config/index.ts
  • deploy-package/server/config/index.js
  • DEPLOY.md
  • DEPLOY_PROD.md
  • AUTO_DEPLOY.md
  • server/webhook-deploy.py
  • deploy-prod.sh
  • deploy.sh
  • docker-nginx/docker-compose.yml

目录

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

简介

本文件面向AI有声书生成平台，提供覆盖开发、测试、生产的多环境部署策略与实施指南。内容涵盖：

  • 环境差异化配置（数据库、API端点、第三方服务密钥）
  • 环境变量使用模式与配置文件加载优先级
  • CI/CD流水线（自动化测试、构建、打包、部署触发）
  • 环境切换最佳实践（配置热更新、蓝绿/灰度发布）
  • 监控与告警（性能指标、错误日志、容量规划）

项目结构

该仓库包含后端服务、前端应用、部署脚本与Nginx/Docker配置。关键部署相关目录与文件如下：

  • server/src/config：运行时配置加载与模型管理
  • deploy-package/server/config：打包后配置（兼容JS）
  • docker-nginx：本地开发反向代理示例
  • 自动化部署脚本：deploy-prod.sh、deploy.sh、webhook-deploy.py

  • 文档：DEPLOY.md、DEPLOY_PROD.md、AUTO_DEPLOY.md

    graph TB
A["开发环境<br/>本地/容器"] --> B["测试环境<br/>测试服务器"]
B --> C["生产环境<br/>线上服务器"]
A --> D["构建产物<br/>server/dist, frontend/build/h5"]
D --> E["部署脚本<br/>deploy.sh / deploy-prod.sh"]
E --> F["PM2 进程管理<br/>server"]
F --> G["Nginx 反向代理<br/>book.rrbrr.com / bookapi.rrbrr.com"]
G --> H["后端服务<br/>监听端口"]
G --> I["静态资源<br/>前端H5"]

图表来源

  • DEPLOY.md:1-251
  • DEPLOY_PROD.md:1-393
  • deploy.sh:1-209
  • deploy-prod.sh:1-171

章节来源

  • DEPLOY.md:1-251
  • DEPLOY_PROD.md:1-393
  • docker-nginx/docker-compose.yml:1-12

核心组件

  • 配置加载与模型管理
    • 通过dotenv加载根目录环境变量，结合models.json统一管理模型清单与默认值
    • 提供模型切换逻辑（基于错误类型判断是否切换）
  • 自动化部署链路
    • 一键部署脚本负责构建、打包、同步、安装依赖、生成Prisma客户端、PM2启动
    • Webhook服务接收Gogs/GitHub推送，执行部署脚本
  • 反向代理与域名
    • Nginx配置后端API与前端静态资源分发；生产环境由宝塔面板管理

章节来源

  • server/src/config/index.ts:1-117
  • deploy-package/server/config/index.js:1-111
  • AUTO_DEPLOY.md:1-142
  • DEPLOY.md:61-116

架构总览

多环境部署采用“脚本驱动 + 反向代理 + 进程管理”的组合模式，支持一键部署与Webhook触发部署。

graph TB
Dev["开发者"] --> SCM["代码仓库(Gogs/GitHub)"]
SCM --> WH["Webhook 接收器<br/>webhook-deploy.py"]
WH --> Deploy["部署脚本<br/>deploy.sh / deploy-prod.sh"]
Deploy --> Build["构建产物<br/>server/dist, frontend/build/h5"]
Build --> PM2["PM2 进程管理"]
PM2 --> Nginx["Nginx 反向代理"]
Nginx --> API["后端API"]
Nginx --> FE["前端静态资源"]

图表来源

  • AUTO_DEPLOY.md:3-85
  • server/webhook-deploy.py:1-139
  • deploy.sh:1-209
  • deploy-prod.sh:1-171

详细组件分析

环境变量与配置加载

  • 加载顺序与优先级
    • 项目根目录加载 .env（dotenv）
    • 读取 models.json 作为模型配置源
    • 运行时通过 process.env 覆盖默认值（端口、数据库、JWT、TTS等）
  • 关键配置项
    • 服务端口与环境：NODE_ENV、SERVER_PORT
    • 数据库连接：MONGODB_URI（开发）/ DATABASE_URL（生产）
    • JWT：JWT_SECRET、JWT_EXPIRES_IN
    • 第三方服务：DASHSCOPE_API_KEY、DASHSCOPE_MODEL、DASHSCOPE_TTS_MODELS、DASHSCOPE_USE_REALTIME、DASHSCOPE_REALTIME_MODEL
    • 存储与缓存：STORAGETYPE、REDIS*、OSS_*（生产）

  • 模型管理

    • 统一列出vendors/models，按类型过滤启用模型，支持自动切换

      flowchart TD
Start(["启动"]) --> LoadEnv["加载 .env"]
LoadEnv --> ReadModels["读取 models.json"]
ReadModels --> MergeCfg["合并默认配置与环境变量"]
MergeCfg --> Export["导出 config 对象"]
Export --> End(["运行"])

图表来源

  • server/src/config/index.ts:1-117
  • deploy-package/server/config/index.js:1-111

章节来源

  • server/src/config/index.ts:69-117
  • DEPLOY_PROD.md:105-144

开发环境

  • 本地开发
    • 使用 docker-nginx 本地反向代理，映射80端口，便于联调
    • 通过 .env 注入开发数据库与第三方服务密钥
  • 前后端联调
    • 前端H5直连后端API（通过Nginx转发），便于调试

章节来源

  • docker-nginx/docker-compose.yml:1-12
  • server/src/config/index.ts:73-75

测试环境

  • 配置要点
    • 使用独立数据库（MySQL 8.0 Docker容器）
    • 通过 .env 设置 DATABASE_URL、Redis、OSS等
    • Nginx配置与生产类似，但指向测试后端端口
  • 部署流程
    • rsync同步前后端产物至测试服务器
    • 安装依赖、生成Prisma客户端、PM2启动
    • 验证健康检查与API连通性

章节来源

  • DEPLOY_PROD.md:264-294
  • DEPLOY.md:105-116

生产环境

  • 服务器与端口
    • 服务器IP：8.159.134.106
    • 前端路径：/data/ai/audio/frontend/build/h5
    • 后端端口：3100（PM2启动时指定）
    • SSH端口：22622
  • 配置要点
    • .env中设置 NODE_ENV=production、SERVER_PORT=3100、JWTSECRET、DASHSCOPE*、DATABASEURL、REDIS、OSS_
    • Nginx由宝塔面板管理，配置文件位于 /www/server/panel/vhost/nginx/
    • 健康检查：/api/health
  • 部署流程
    • 一键脚本 deploy-prod.sh 完成构建、打包、同步、安装依赖、复制生产配置、生成Prisma客户端、PM2启动
    • 手动部署步骤与一键脚本等价，便于理解与排障

章节来源

  • DEPLOY_PROD.md:3-65
  • DEPLOY_PROD.md:105-144
  • deploy-prod.sh:1-171

CI/CD流水线

  • 触发机制
    • Git Push → Gogs Webhook → 服务器 webhook-deploy.py → 自动部署脚本 → PM2重启
  • 服务配置
    • systemd服务：webhook.service，监听本地端口（默认8080），读取WEBHOOK_SECRET与WEBHOOK_PORT
    • Nginx转发：/webhook → 127.0.0.1:8080
  • 安全建议
    • 使用HTTPS与强Secret
    • 可限制IP仅允许Gogs服务器访问 /webhook

  • 替代方案

    • 无Python环境时，可用Git post-receive hook + Nginx + Bash脚本实现

      sequenceDiagram
participant Dev as "开发者"
participant Gogs as "Gogs 仓库"
participant Nginx as "Nginx"
participant WH as "webhook-deploy.py"
participant Script as "deploy.sh"
participant PM2 as "PM2"
participant Srv as "后端服务"
Dev->>Gogs : 推送代码
Gogs->>Nginx : 触发 /webhook
Nginx->>WH : 转发请求
WH->>Script : 执行部署脚本
Script->>PM2 : 重启 server
PM2->>Srv : 启动/重启进程
Dev-->>Gogs : 部署完成

图表来源

  • AUTO_DEPLOY.md:3-85
  • server/webhook-deploy.py:1-139
  • deploy.sh:178-201

章节来源

  • AUTO_DEPLOY.md:1-142
  • server/webhook-deploy.py:1-139
  • deploy.sh:178-201

环境切换最佳实践

  • 配置热更新
    • 通过 .env 分环境管理，生产环境使用 .env.production 并在部署时复制为 .env
    • 第三方服务密钥与数据库连接字符串按环境隔离
  • 蓝绿/灰度发布
    • 建议：使用多实例+负载均衡（Nginx upstream）进行蓝绿切换；灰度发布可通过Nginx基于Header/Cookie分流
    • 当前脚本未内置蓝绿/灰度逻辑，可在Nginx层扩展
  • 模型自动切换
    • 基于错误类型判断（限流、配额、服务不可用等）自动切换可用模型，提升稳定性

章节来源

  • server/src/config/index.ts:45-67
  • DEPLOY_PROD.md:115-144

监控与告警

  • 性能指标
    • Nginx访问/错误日志：/var/log/nginx/ 与宝塔日志目录
    • PM2进程状态与日志：pm2 status / pm2 logs server
  • 错误日志监控
    • 后端：pm2 logs server --lines 50
    • Nginx：tail -f /var/log/nginx/access.log / error.log
  • 容量规划建议
    • CPU/内存：根据并发请求与TTS生成任务峰值评估
    • 存储：上传文件与生成视频目录容量监控
    • 数据库：MySQL 8.0容器资源与备份策略

章节来源

  • DEPLOY.md:187-197
  • DEPLOY_PROD.md:318-375

依赖关系分析

  • 配置模块
    • server/src/config/index.ts 读取 .env 与 models.json，导出统一配置对象
    • deploy-package/server/config/index.js 为打包后JS版本，行为一致
  • 部署脚本
    • deploy.sh：通用部署脚本（本地Windows路径示例）
    • deploy-prod.sh：生产一键脚本（含Node.js检测、复制生产配置、PM2启动）

  • 自动化

    • webhook-deploy.py：HTTP服务，校验签名后执行部署脚本

    • systemd服务：webhook.service，随系统启动

      graph LR
Env[".env"] --> Cfg["server/src/config/index.ts"]
Models["models.json"] --> Cfg
Cfg --> App["后端应用"]
Deploy["deploy.sh"] --> PM2["PM2"]
Prod["deploy-prod.sh"] --> PM2
WH["webhook-deploy.py"] --> Deploy
SVC["webhook.service"] --> WH

图表来源

  • server/src/config/index.ts:1-117
  • deploy.sh:1-209
  • deploy-prod.sh:1-171
  • server/webhook-deploy.py:1-139

章节来源

  • server/src/config/index.ts:1-117
  • deploy.sh:1-209
  • deploy-prod.sh:1-171
  • server/webhook-deploy.py:1-139

性能考量

  • 反向代理
    • Nginx开启HTTP/2、缓存静态资源、压缩与安全头，降低后端压力
  • 进程管理
    • PM2自动重启与开机自启，保障高可用
  • 数据库
    • 生产使用Docker MySQL 8.0，建议开启慢查询日志与连接池参数优化
  • 存储
    • OSS对象存储与Redis缓存配合，减少IO压力

故障排查指南

  • 后端无法启动
    • 检查端口占用与 .env 配置，查看PM2日志
  • 前端无法访问
    • 检查Nginx配置与静态资源路径
  • 数据库连接失败
    • 检查MySQL容器状态与 .env 中 DATABASE_URL
  • Nginx 502
    • 检查后端进程监听端口与PM2状态
  • Webhook部署失败
    • 检查签名、日志与系统服务状态

章节来源

  • DEPLOY.md:199-251
  • DEPLOY_PROD.md:318-375
  • AUTO_DEPLOY.md:97-142

结论

本部署文档提供了从开发到生产的完整配置与流程说明，并给出了CI/CD自动化与监控告警建议。建议在现有脚本基础上扩展蓝绿/灰度发布能力，并完善测试环境的自动化回归与性能压测流程，以进一步提升交付质量与稳定性。

附录

  • 常用命令
    • PM2：status、logs、restart、save、startup
    • Nginx：-t、reload、restart
    • MySQL（Docker）：进入容器、备份、迁移
  • 安全加固
    • 强制HTTPS、强Secret、IP白名单、定期审计日志