Startsida Utforska Hjälp
Logga in
caojunfei
/
audio_codebuddy
1
0
Fork 0
Filer Ärenden 0 Pull-förfrågningar 0 Wiki
Träd: b76f56a46b
Grenar Taggar
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
系统架构
/
模块架构
/
通信模式.md

通信模式.md 19 KB
Historik Rå

通信模式

本文引用的文件

  • server/src/app.ts
  • server/src/services/websocket.service.ts
  • server/src/modules/tts/tts.controller.ts
  • server/src/modules/auth/auth.controller.ts
  • server/src/middleware/auth.ts
  • server/src/middleware/security.ts
  • server/src/middleware/rate-limiter.ts
  • server/src/services/queue.service.ts
  • server/src/modules/book-generator/book-queue.processor.ts
  • server/src/services/memory-queue.ts
  • my-uniapp-vue3/src/utils/websocket.ts

目录

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

引言

本文件面向“AI有声书生成平台”的通信模式，系统化梳理平台内部的三类通信机制：同步通信（RESTful API）、异步通信（消息队列/Bull）与实时通信（WebSocket），并结合中间件管道（请求预处理、身份验证、权限检查、响应后处理）与事件驱动架构（事件发布订阅、消息路由、错误重试），给出架构图、流程图与最佳实践，帮助开发者与运维人员快速理解与优化系统通信。

项目结构

后端基于 Koa 应用，统一注册路由与中间件；前端采用 uni-app，内置 WebSocket 管理器，支持 H5 与小程序环境。平台围绕“异步任务 + 实时推送 + REST API”构建，形成高吞吐、低耦合的通信体系。

graph TB
subgraph "前端"
FE["uni-app 应用<br/>WebSocket 管理器"]
end
subgraph "后端"
APP["Koa 应用<br/>路由与中间件"]
WS["WebSocket 服务<br/>/ws 路径"]
Q["队列服务(Bull)<br/>Redis/内存回退"]
BKQ["书籍生成队列处理器"]
end
FE -- "HTTP REST API" --> APP
FE -- "WebSocket" --> WS
APP -- "异步任务入队" --> Q
Q -- "并发执行" --> BKQ
BKQ -- "事件广播" --> WS
WS -- "实时推送" --> FE

图表来源

  • server/src/app.ts:57-130
  • server/src/services/websocket.service.ts:102-133
  • server/src/services/queue.service.ts:48-122
  • server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

  • server/src/app.ts:57-130

核心组件

  • REST API 层：以 Koa Router 注册各模块路由，统一处理 CORS、BodyParser、静态资源、健康检查与指标暴露。
  • 中间件管道：错误处理、性能监控、日志、安全（XSS/SQL 注入）、速率限制、认证与可选认证。
  • 异步队列：Bull 队列承载音频/视频/书籍生成等长耗时任务，具备 Redis 回退与并发控制。
  • 实时通信：WebSocket 服务在 /ws 路径上建立连接，向客户端推送生成完成与进度事件。
  • 前端 WebSocket 管理器：封装连接、订阅、重连与事件派发，适配 H5/小程序。

章节来源

  • server/src/app.ts:63-130
  • server/src/middleware/security.ts:6-27
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/auth.ts:7-49
  • server/src/services/queue.service.ts:48-122
  • server/src/services/websocket.service.ts:102-133
  • my-uniapp-vue3/src/utils/websocket.ts:15-196

架构总览

下图展示三类通信模式在系统中的应用位置与数据流向：

graph TB
C["客户端/浏览器"] --> |REST API| R["Koa 路由"]
R --> M1["安全中间件<br/>XSS/SQL注入"]
R --> M2["速率限制中间件"]
R --> M3["认证中间件"]
R --> S["业务控制器<br/>如 tts.auth.book-generator"]
S --> |异步任务| Q["队列服务(Bull)"]
Q --> P["队列处理器<br/>并发执行"]
P --> E["领域服务/LLM"]
P --> W["WebSocket 服务"]
W --> |事件推送| C
subgraph "实时通道"
W
end
subgraph "异步通道"
Q
P
end
subgraph "同步通道"
R
M1
M2
M3
end

图表来源

  • server/src/app.ts:63-130
  • server/src/middleware/security.ts:6-27
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/auth.ts:7-49
  • server/src/services/queue.service.ts:48-122
  • server/src/services/websocket.service.ts:102-133

详细组件分析

同步通信（RESTful API）

  • 设计要点
    • 统一使用 Koa Router 注册模块路由，集中处理 CORS、BodyParser、静态资源与健康检查。
    • 控制器内进行参数校验、权限检查与配额校验，必要时调用订阅服务与数据库。
    • 对外返回统一结构，便于前端消费。
  • 典型流程（TTS 生成）
    • 客户端发起 POST /api/tts/generate，携带文本、音色、可选书籍章节信息。
    • 控制器执行 optionalAuth（可选认证）、参数校验、配额检查、调用服务生成异步任务。
    • 立即返回任务创建结果，后续通过 WebSocket 推送状态。

  • 安全与限流

    • 安全中间件对请求体与查询参数进行 XSS/SQL 注入清洗，并设置安全响应头。
    • 速率限制中间件按接口维度（API、登录、短信、TTS、上传）配置不同阈值。

    • 认证中间件支持强制认证与可选认证两种模式，开发环境可跳过。

      sequenceDiagram
participant Client as "客户端"
participant Router as "Koa 路由(tts)"
participant MW_Auth as "认证中间件"
participant MW_Rate as "限流中间件"
participant MW_Sec as "安全中间件"
participant Ctrl as "TTS 控制器"
participant Queue as "队列服务"
participant WS as "WebSocket 服务"
Client->>Router : "POST /api/tts/generate"
Router->>MW_Sec : "XSS/SQL 注入清洗"
Router->>MW_Rate : "速率限制检查"
Router->>MW_Auth : "optionalAuth/强制认证"
Router->>Ctrl : "进入控制器"
Ctrl->>Ctrl : "参数校验/配额检查"
Ctrl->>Queue : "异步生成任务"
Ctrl-->>Client : "返回任务创建结果"
Queue-->>WS : "完成后推送事件"
WS-->>Client : "实时推送生成完成"

图表来源

  • server/src/modules/tts/tts.controller.ts:52-127
  • server/src/middleware/auth.ts:7-49
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/security.ts:6-27
  • server/src/services/queue.service.ts:131-160
  • server/src/services/websocket.service.ts:66-86

章节来源

  • server/src/modules/tts/tts.controller.ts:52-127
  • server/src/middleware/auth.ts:7-49
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/security.ts:6-27

异步通信（消息队列/Bull）

  • 设计原则
    • 队列仅负责排队与并发控制，失败重试、超时管理与业务逻辑分别由容错层、AI 服务层与领域层承担。
    • 优先使用 Redis 队列，若不可用则回退至内存队列，保证系统可用性。
  • 关键能力
    • 任务类型：音频生成、视频生成、书籍生成、邮件发送等。
    • 任务状态：waiting/active/completed/failed/delayed。
    • 进度回调：支持任务进度上报与回调触发。
    • 统计与运维：提供队列统计、暂停/恢复、清空、优雅关闭等操作。

  • 书籍生成处理器

    • 初始化时优先使用 Redis 队列，最大并发 3；若 Redis 不可用则使用内存队列。

    • 启动时扫描数据库中处于生成中的书籍，恢复中断任务并重新入队。

      flowchart TD
Start(["提交任务"]) --> Add["入队(Redis/内存)"]
Add --> Consume{"Redis可用?"}
Consume --> |是| RedisProc["Redis队列处理器<br/>并发执行"]
Consume --> |否| MemProc["内存队列处理器<br/>并发执行"]
RedisProc --> Domain["领域服务/LLM生成"]
MemProc --> Domain
Domain --> Done{"完成?"}
Done --> |是| Push["推送完成事件"]
Done --> |否| Fail["标记失败/记录错误"]
Push --> End(["结束"])
Fail --> End

图表来源

  • server/src/services/queue.service.ts:48-122
  • server/src/services/memory-queue.ts:17-99
  • server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

  • server/src/services/queue.service.ts:48-122
  • server/src/services/memory-queue.ts:17-99
  • server/src/modules/book-generator/book-queue.processor.ts:48-83

实时通信（WebSocket 双向通信）

  • 服务端
    • 在 HTTP 服务器上监听 upgrade，仅接受 /ws 路径，从查询参数提取 clientId 并维护连接映射。
    • 提供客户端管理（添加/移除）、广播与定向推送，支持音频/视频生成完成与批量进度事件。
  • 前端
    • WebSocketManager 封装连接、订阅、重连与事件派发；支持 H5 与小程序。
    • 自动重连（最多 3 次，间隔 3s），重连成功后自动重新订阅事件。

  • 典型流程

    • 客户端连接 /ws，接收 connected 事件。

    • 服务端在书籍/音频/视频生成完成后，广播对应事件，前端按 bookId 过滤并更新 UI。

      sequenceDiagram
participant FE as "前端 WebSocketManager"
participant HTTP as "HTTP 服务器"
participant WS as "WebSocket 服务"
participant BKQ as "书籍生成处理器"
FE->>HTTP : "发起 upgrade /ws?clientId=..."
HTTP->>WS : "交由 WebSocket 服务处理"
WS-->>FE : "发送 connected 事件"
BKQ-->>WS : "生成完成事件"
WS-->>FE : "广播事件(音频/视频/书籍完成)"
FE->>FE : "根据 bookId 过滤并更新 UI"

图表来源

  • server/src/services/websocket.service.ts:102-133
  • my-uniapp-vue3/src/utils/websocket.ts:25-82
  • server/src/services/websocket.service.ts:66-86

章节来源

  • server/src/services/websocket.service.ts:102-133
  • my-uniapp-vue3/src/utils/websocket.ts:25-82

中间件管道设计模式

  • 请求预处理
    • CORS、BodyParser、静态资源、健康检查与指标暴露。
  • 身份验证
    • 强制认证：要求 Bearer Token，开发环境可通过开关跳过。
    • 可选认证：无 Token 时自动降级为测试用户，便于调试。
  • 权限检查
    • 控制器内结合用户上下文与订阅配额进行权限判断。
  • 响应后处理
    • 敏感数据脱敏（密码、token 等）与统一响应结构。
  • 安全加固
    • XSS/SQL 注入检测与清洗，设置安全响应头。

  • 速率限制

    • 多维度限流策略，避免滥用与攻击。

      flowchart TD
Req["请求到达"] --> CORS["CORS/BodyParser/静态资源"]
CORS --> SEC["安全中间件(XSS/SQL)"]
SEC --> RL["速率限制"]
RL --> AUTH["认证(强制/可选)"]
AUTH --> CTRL["控制器处理"]
CTRL --> RESP["统一响应/脱敏"]
RESP --> End["返回客户端"]

图表来源

  • server/src/app.ts:63-83
  • server/src/middleware/security.ts:6-27
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/auth.ts:7-49

章节来源

  • server/src/app.ts:63-83
  • server/src/middleware/security.ts:6-27
  • server/src/middleware/rate-limiter.ts:49-72
  • server/src/middleware/auth.ts:7-49

事件驱动架构与错误重试

  • 事件发布订阅
    • 书籍生成完成后，通过 WebSocket 广播事件；前端按需订阅。
  • 消息路由
    • 队列服务负责任务路由与并发调度；处理器根据任务类型路由到相应领域服务。

  • 错误重试与恢复

    • 队列层不负责失败重试，重试策略由容错层承担；超时与业务异常由 LLM/领域服务处理。

    • 服务器启动时扫描数据库中处于生成中的书籍，自动恢复中断任务并重新入队。

      flowchart TD
Scan["启动时扫描中断任务"] --> ReEnq["重新入队"]
ReEnq --> Proc["队列处理器执行"]
Proc --> OK{"成功?"}
OK --> |是| Notify["推送完成事件"]
OK --> |否| FT["容错层重试/告警"]
Notify --> End["结束"]
FT --> End

图表来源

  • server/src/modules/book-generator/book-queue.processor.ts:88-124
  • server/src/services/queue.service.ts:131-160

章节来源

  • server/src/modules/book-generator/book-queue.processor.ts:88-124
  • server/src/services/queue.service.ts:131-160

依赖关系分析

  • 应用层依赖
    • app.ts 统一注册路由与中间件，启动时初始化 Sentry、数据库、Redis、存储、WebSocket、书籍生成队列与中断任务恢复。
  • 控制器依赖
    • tts.controller.ts 依赖订阅服务与数据库进行配额与存在性校验。
    • auth.controller.ts 依赖认证服务与数据库进行用户信息读取与更新。
  • 服务层依赖
    • queue.service.ts 依赖 redis.service 与 memory-queue；book-queue.processor.ts 依赖 langGraphGenerator、bookStore、prisma。

  • 实时通信依赖

    • websocket.service.ts 依赖 ws；前端 websocket.ts 依赖 uni.connectSocket 与配置。

      graph LR
APP["app.ts"] --> WS["websocket.service.ts"]
APP --> Q["queue.service.ts"]
APP --> BKQ["book-queue.processor.ts"]
BKQ --> LG["langGraphGenerator"]
BKQ --> BS["book-store"]
BKQ --> PRISMA["prisma"]
TTS["tts.controller.ts"] --> SUB["subscription.service.ts"]
AUTHC["auth.controller.ts"] --> AUTHS["auth.service.ts"]

图表来源

  • server/src/app.ts:133-172
  • server/src/services/websocket.service.ts:102-133
  • server/src/services/queue.service.ts:48-122
  • server/src/modules/book-generator/book-queue.processor.ts:48-83

章节来源

  • server/src/app.ts:133-172
  • server/src/modules/book-generator/book-queue.processor.ts:48-83

性能考量

  • 队列并发与超时
    • 书籍生成任务最大并发 3，超时 2 小时；音频 5 分钟、视频 10 分钟，避免长时间占用资源。
  • 限流策略
    • 全局限流、登录限流、短信限流、TTS 限流、上传限流，按接口与用户维度精细化控制。
  • 缓存与存储
    • Redis 可用时优先使用；存储类型可切换（OSS/本地），启动时进行连通性检测。
  • 前端重连与订阅
    • WebSocketManager 自动重连与事件重订阅，降低弱网与断线影响。

章节来源

  • server/src/services/queue.service.ts:166-190
  • server/src/middleware/rate-limiter.ts:77-120
  • server/src/app.ts:142-151
  • my-uniapp-vue3/src/utils/websocket.ts:162-190

故障排查指南

  • WebSocket 连接问题
    • 检查 /ws 路径与 clientId 参数；确认服务端升级处理逻辑与客户端重连策略。
    • 查看服务端日志与客户端 onOpen/onError/onClose 回调。
  • 队列不可用
    • Redis 不可用时会回退到内存队列；检查 Redis 连接与队列可用性标志。
    • 关注队列错误事件与处理器的 completed/failed 回调。
  • 认证与限流
    • 确认 Authorization 头格式与 Token 有效性；检查限流中间件返回的 Retry-After。
  • 安全拦截
    • 若出现 400 非法字符提示，检查请求体与查询参数是否包含 SQL 注入特征。
  • 优雅关闭
    • 服务端监听 SIGTERM/SIGINT，确保队列与 Redis 正常关闭。

章节来源

  • server/src/services/websocket.service.ts:102-133
  • server/src/services/queue.service.ts:53-59
  • server/src/middleware/rate-limiter.ts:52-71
  • server/src/middleware/security.ts:69-83
  • server/src/app.ts:174-187

结论

该平台通过“REST API + 队列 + WebSocket”的组合实现了高可用、可扩展的通信体系：同步 API 提供即时交互体验，异步队列承载长耗时任务并具备回退与恢复能力，实时 WebSocket 保障事件推送的及时性。配合完善的中间件管道（安全、限流、认证）与事件驱动架构，系统在安全性、性能与可靠性方面均具备良好基础。建议在生产环境中启用全局限流与认证开关，并持续监控队列与 WebSocket 的运行状态，以进一步提升稳定性与用户体验。