audio_codebuddy/.qoder/repowiki/zh/content/系统架构/部署架构/数据库部署.md

数据库部署

本文引用的文件

• schema.prisma
• migration_lock.toml
• 20260422105352_add_content_status/migration.sql
• migrate_publish.sql
• .env.example
• index.ts
• migrate-genstage.ts
• sync-genstage.ts
• DEPLOY.md
• audio_book.sql

目录

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

简介

本文件面向AI有声书生成平台的数据库部署与运维，聚焦于MySQL数据库的安装配置、初始化、Prisma ORM迁移机制、备份恢复策略、监控优化与安全配置。文档基于仓库中的Prisma配置、迁移脚本与示例环境变量，提供可操作的部署指导。

项目结构

• 数据库ORM与模型定义位于 server/prisma/schema.prisma，声明了MySQL数据源与完整的业务模型关系。
• 迁移文件位于 server/prisma/migrations，包含Prisma自动生成的SQL迁移与补充的发布模块迁移脚本。
• 数据库连接与Prisma客户端初始化位于 server/src/models/index.ts。
• 示例环境变量 server/.env.example 提供DATABASE_URL等关键配置项。

• 文档 docs/DEPLOY.md 包含部署与运维相关内容（MongoDB为主，可参考其运维思路）。

  graph TB
  subgraph "后端服务"
  APP["应用服务"]
  PRISMA["Prisma 客户端"]
  MODELS["模型定义<br/>schema.prisma"]
  MIGRATIONS["迁移文件<br/>migrations/*"]
  ENV[".env.example<br/>DATABASE_URL"]
  end
  subgraph "数据库"
  MYSQL["MySQL 服务器"]
  SCHEMA["数据库结构<br/>schema.prisma"]
  end
  APP --> PRISMA
  PRISMA --> MODELS
  PRISMA --> MIGRATIONS
  PRISMA --> MYSQL
  MODELS --> SCHEMA
  ENV --> MYSQL
  

图表来源

• schema.prisma
• index.ts
• .env.example

章节来源

• schema.prisma
• index.ts
• .env.example

核心组件

• 数据源与连接
  • 数据源配置指向MySQL，通过环境变量 DATABASE_URL 提供连接字符串。
  • Prisma客户端在应用启动时建立连接并提供类型化查询能力。
• 模型与索引
  • 用户、订单、播放记录、收藏、评论、订阅、书稿、章节、视频项目、音频记录、发布任务等核心实体。
  • 多处复合索引与唯一约束，覆盖高频查询维度（如用户+时间、订单号、章节唯一组合等）。
• 迁移与版本控制
  • Prisma迁移文件包含表结构、索引与外键定义。
  • 提供补充的发布模块迁移脚本，确保视频发布相关表结构就绪。
  • 迁移锁定文件保证并发一致性。

章节来源

• schema.prisma
• migration_lock.toml
• 20260422105352_add_content_status/migration.sql
• migrate_publish.sql

架构概览

下图展示了应用、ORM与数据库之间的交互关系，以及迁移与初始化的关键节点。

sequenceDiagram
participant Dev as "开发者"
participant App as "应用服务"
participant Prisma as "Prisma 客户端"
participant DB as "MySQL 数据库"
Dev->>App : 配置 DATABASE_URL
App->>Prisma : 初始化客户端
Prisma->>DB : 建立连接
Dev->>Prisma : 执行迁移
Prisma->>DB : 应用迁移SQL
App->>Prisma : 查询/写入数据
Prisma->>DB : 执行SQL
DB-->>Prisma : 返回结果
Prisma-->>App : 返回结果

图表来源

• index.ts
• schema.prisma
• 20260422105352_add_content_status/migration.sql

详细组件分析

MySQL安装与初始化

• 安装与配置
  • 在目标主机安装MySQL 8.0+，创建数据库与用户，授予必要权限。
  • 使用 .env.example 中的 DATABASE_URL 格式配置连接串（用户名、密码、主机、端口、数据库名）。
• 字符集与排序规则
  • Prisma迁移脚本与补充SQL均使用 utf8mb4 与 utf8mb4_unicode_ci，确保表情符号与多语言支持。
• 存储引擎
  • 迁移脚本指定 InnoDB 引擎，具备事务、外键与崩溃恢复能力，适合高并发写入场景。
• 性能参数调优（建议）
  • innodb_buffer_pool_size：建议占物理内存的 50%-70%
  • innodb_log_file_size：建议 256M-512M
  • innodb_flush_log_at_trx_commit：生产环境设为 1 或 2 平衡安全与性能
  • max_connections：根据应用实例数量与峰值并发合理设置
  • query_cache_size：MySQL 8.0 默认禁用，建议使用二级缓存（如Redis）替代
  • thread_cache_size：根据并发连接数调整
  • tmp_table_size 与 max_heap_table_size：避免磁盘临时表
  • open_files_limit：确保足够打开文件句柄
  • 注意：以上为通用建议，需结合实际硬件与负载压测确定最优值。

章节来源

• .env.example
• 20260422105352_add_content_status/migration.sql
• migrate_publish.sql

Prisma ORM迁移机制

• 迁移生成与执行
  • 通过 Prisma CLI 生成迁移文件，包含表结构、索引与外键定义。
  • 迁移锁定文件 migration_lock.toml 保障并发迁移安全。
• 回滚策略
  • Prisma支持向后迁移（down），可在测试环境快速回退到上一版本。
  • 生产环境建议谨慎使用，优先采用“向前修复”迁移（新增修正SQL）。
• 补充迁移
  • migrate_publish.sql 为视频发布模块的补充迁移，需在应用Prisma迁移后手动执行。

• 状态迁移脚本

  • migrate-genstage.ts：将旧字段映射到新的 genStage 字段。

  • sync-genstage.ts：基于安全函数同步genStage，处理并发与回退场景。

    flowchart TD
    Start(["开始"]) --> CheckLock["检查迁移锁定文件"]
    CheckLock --> |通过| ApplyPrisma["应用 Prisma 迁移"]
    CheckLock --> |冲突| WaitRetry["等待或重试"]
    ApplyPrisma --> ApplyExtra["执行补充迁移 SQL"]
    ApplyExtra --> GenStage["执行 genStage 迁移脚本"]
    GenStage --> Done(["完成"])
    WaitRetry --> CheckLock
    

图表来源

• migration_lock.toml
• 20260422105352_add_content_status/migration.sql
• migrate_publish.sql
• migrate-genstage.ts
• sync-genstage.ts

章节来源

• migration_lock.toml
• 20260422105352_add_content_status/migration.sql
• migrate_publish.sql
• migrate-genstage.ts
• sync-genstage.ts

数据库备份与恢复

• 备份策略
  • 全量备份：使用逻辑导出（如mysqldump）定期生成全库快照。
  • 增量备份：结合binlog或Percona XtraBackup实现增量备份与时间点恢复。
  • 对象级备份：针对大字段（如LongText）可单独导出或使用压缩归档。
• 恢复流程
  • 恢复顺序：先恢复结构（迁移），再恢复数据；若涉及genStage字段，最后执行状态迁移脚本。
  • 验证：恢复后执行基础查询与索引校验，确认业务关键查询可用。
• 灾难恢复
  • 制定RTO/RPO目标，定期演练恢复流程。
  • 将备份存储在异地或云端，确保不可篡改与可审计。

章节来源

• migrate-genstage.ts
• sync-genstage.ts

监控与性能优化

• 慢查询分析
  • 启用慢查询日志，定位执行时间长、扫描行数多的SQL。
  • 结合EXPLAIN分析执行计划，优化索引与查询条件。
• 索引优化
  • 针对高频过滤与连接字段建立复合索引（如用户+时间、订单号、章节唯一组合）。
  • 定期评估冗余索引，删除未使用或重复索引。
• 连接池配置
  • 在应用侧使用连接池（如Prisma默认连接池），合理设置最大连接数与超时时间。
  • 监控连接池命中率与等待时间，避免连接泄漏。
• 读写分离与分片
  • 高并发场景可考虑读写分离与按用户ID分片，降低单库压力。

章节来源

• schema.prisma

安全配置

• 用户权限管理
  • 为应用创建专用数据库用户，仅授予必要权限（SELECT、INSERT、UPDATE、DELETE、CREATE、INDEX等）。
  • 为备份任务创建只读用户，避免写入风险。
• 网络访问控制
  • 限制MySQL监听地址与访问白名单，仅允许应用服务器访问。
  • 使用跳板机或VPN访问数据库管理端口。
• 数据加密
  • 启用SSL/TLS加密连接，防止中间人攻击。
  • 敏感字段（如支付订单）在应用层做额外加密存储。
• 审计与合规
  • 启用审计日志，记录DDL与关键DML操作。
  • 定期审查权限与访问日志，满足合规要求。

章节来源

• .env.example

依赖关系分析

• 组件耦合
  • 应用通过 Prisma 客户端访问数据库，模型变更直接影响迁移与查询性能。
  • 迁移脚本与补充SQL共同构成最终数据库结构，需严格版本控制。

• 外部依赖

  • MySQL版本需与Prisma驱动兼容（建议8.0+）。

  • 环境变量 DATABASE_URL 必须正确配置，否则连接失败。

    graph LR
    ENV[".env.example"] --> DBURL["DATABASE_URL"]
    DBURL --> MYSQL["MySQL"]
    SCHEMA["schema.prisma"] --> MIG["迁移文件"]
    MIG --> MYSQL
    APP["应用服务"] --> PRISMA["Prisma 客户端"]
    PRISMA --> MYSQL
    

图表来源

• .env.example
• schema.prisma
• index.ts

章节来源

• schema.prisma
• index.ts
• .env.example

性能考虑

• 查询性能
  • 为高频查询字段建立合适索引，避免全表扫描。
  • 使用LIMIT与分页，避免一次性返回过多数据。
• 写入性能
  • 批量插入与事务提交，减少往返开销。
  • 控制并发写入，避免热点更新导致锁竞争。
• 缓存策略
  • 对热点读取（如用户偏好、热门搜索）引入Redis缓存，降低数据库压力。
• 监控指标
  • 关注慢查询、连接数、缓冲池命中率、锁等待与表扫描等关键指标。

[本节为通用指导，无需特定文件引用]

故障排查指南

• 连接失败
  • 检查 DATABASE_URL 格式与可达性，确认MySQL服务状态与防火墙策略。
  • 参考应用侧连接日志，定位认证与权限问题。
• 迁移异常
  • 检查 migration_lock.toml 是否被意外修改，必要时清理锁定后重试。
  • 若补充迁移失败，确认数据库用户具备DDL权限。
• 数据不一致
  • 执行 genStage 状态迁移脚本，确保章节与书稿状态一致。
  • 使用 sync-genstage.ts 进行安全同步，避免并发冲突导致的状态错乱。

章节来源

• migration_lock.toml
• migrate-genstage.ts
• sync-genstage.ts

结论

本部署文档基于仓库中的Prisma配置与迁移脚本，给出了MySQL安装、初始化、迁移、备份恢复、监控优化与安全配置的完整实践路径。建议在生产环境中结合压测与监控持续优化参数，并严格执行备份与演练流程，确保系统稳定与数据安全。

[本节为总结性内容，无需特定文件引用]

附录

• 参考文档
  • docs/DEPLOY.md 提供了部署与运维的通用流程（MongoDB为主），可借鉴其运维思路与最佳实践。

章节来源

• DEPLOY.md