audio_codebuddy/.qoder/repowiki/zh/content/部署运维/部署运维.md

部署运维

本文引用的文件

• DEPLOY.md
• DEPLOY_PROD.md
• deploy-prod.sh
• deploy.sh
• docker-nginx/docker-compose.yml
• docker-nginx/bookapi.conf
• server/src/app.ts
• server/src/config/index.ts
• server/src/middleware/security.ts
• server/src/services/sentry.service.ts
• server/prisma/schema.prisma
• server/package.json
• my-uniapp-vue3/package.json
• AUTO_DEPLOY.md
• server/webhook-deploy.py

目录

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反代

  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
• server/src/config/index.ts:70-117
• server/prisma/schema.prisma:1-472

章节来源

• DEPLOY.md:1-251
• DEPLOY_PROD.md:1-393

核心组件

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

章节来源

• server/src/app.ts:1-194
• server/src/config/index.ts:1-117
• server/prisma/schema.prisma:1-472

架构总览

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

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
• server/src/config/index.ts:70-117
• server/prisma/schema.prisma:1-472

详细组件分析

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

2) Docker容器化部署方案

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

章节来源

• docker-nginx/docker-compose.yml:1-12
• docker-nginx/bookapi.conf:1-15

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
• DEPLOY_PROD.md:146-246

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
• server/prisma/schema.prisma:1-472

5) Redis缓存配置

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

章节来源

• server/src/app.ts:142-151
• server/src/config/index.ts:129-134

6) 环境变量与依赖服务

• 后端环境变量（示例）：NODE_ENV、SERVER_PORT、JWTSECRET、DASHSCOPE*、DATABASE_URL、STORAGETYPE、REDIS*、OSS_*、MINIMAX_API_KEY
• 前端依赖：Vue3、Pinia、UniApp生态
• 后端依赖：Koa、Prisma、ioredis、bull、axios、langchain、mysql2、ali-oss、sentry等

章节来源

• DEPLOY_PROD.md:105-144
• my-uniapp-vue3/package.json:1-65
• server/package.json:1-60

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
• deploy.sh:1-209
• AUTO_DEPLOY.md:1-142

8) CI/CD流水线设计与自动化部署

• 方案一：Webhook（推荐）
  • 服务器端：Python HTTP服务监听端口，校验签名后执行部署脚本
  • Nginx：将/webhook转发至本地端口
  • Gogs：推送事件触发webhook

• 方案二：Git Hook（简化）

  • 服务器Git仓库post-receive钩子，拉取代码、构建后PM2重启

    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
• server/webhook-deploy.py:79-125

章节来源

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

9) 回滚策略

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

章节来源

• DEPLOY.md:27-59
• DEPLOY_PROD.md:377-393

10) 监控告警与日志

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

章节来源

• server/src/services/sentry.service.ts:1-113
• server/src/app.ts:92-98
• DEPLOY.md:187-197

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
• server/src/config/index.ts:77-81
• DEPLOY_PROD.md:173-186

依赖关系分析

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
• server/src/config/index.ts:1-117
• server/prisma/schema.prisma:1-472

章节来源

• server/src/app.ts:1-194
• server/src/config/index.ts:1-117
• server/prisma/schema.prisma:1-472

性能考虑

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

章节来源

• server/src/config/index.ts:45-67
• server/src/services/sentry.service.ts:15-43

故障排查指南

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

章节来源

• DEPLOY.md:199-214
• DEPLOY_PROD.md:318-375
• AUTO_DEPLOY.md:97-111

结论

本部署运维文档提供了从开发到生产的完整落地方案，涵盖容器化、反向代理、数据库与缓存、自动化部署与回滚、监控告警与安全加固。建议在生产环境中结合宝塔面板与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

B. 常用命令速查

• 后端管理：PM2状态、日志、重启、停止
• Nginx管理：配置测试、重载、重启
• 数据库：进入容器、查看数据库、执行SQL、备份、迁移

章节来源

• DEPLOY.md:161-197
• DEPLOY_PROD.md:276-294