Epic Stack项目数据库管理全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00598/article/details/148505635

Epic Stack项目数据库管理全指南

epic-stack This is a Full Stack app starter with the foundational things setup and configured for you to hit the ground running on your next EPIC idea. 项目地址: https://gitcode.com/gh_mirrors/ep/epic-stack

数据库架构概述

Epic Stack项目采用了一种创新的分布式数据库架构，基于LiteFS实现SQLite数据库的分布式部署。这种架构包含一个主实例(Primary Instance)和多个副本实例(Replica Instance)，其中主实例是唯一可以写入数据库的节点，而副本实例只能读取数据。这种主从架构模式在数据库系统中非常常见，能够有效保证数据一致性。

主实例配置与管理

主实例选举机制

主实例的选举由Consul服务完成，系统默认允许所有实例成为主实例。但在实际部署中，Epic Stack项目做了优化配置：

通过litefs.yml文件限制只有主区域(PRIMARY_REGION)的实例才能成为主实例
主区域信息从fly.toml文件的primary_region属性获取
建议选择靠近大多数用户的区域作为主区域，以优化写入性能

部署建议

初始化应用时会提示选择部署区域
建议在主区域部署至少两个实例，确保零停机部署
可通过命令查看当前主实例状态：
```
fly status --app [YOUR_APP_NAME]
```

多区域扩展

通过以下命令可实现多区域部署：

fly scale count 2 --region sjc  # 在主区域部署2个实例
fly scale count 1 --region ams  # 在副区域部署1个实例

生产环境数据库连接

数据库文件位置

Epic Stack项目中数据库文件的实际位置与访问路径有所不同：

实际位置：/data/litefs/dbs/sqlite.db
访问路径：/litefs/data/sqlite.db（通过LiteFS虚拟文件系统访问）

连接方式

命令行连接：
```
fly ssh console -C database-cli
```
Prisma Studio连接：
- 终端1启动Prisma Studio：
```
fly ssh console -C "npx prisma studio" --app [YOUR_APP_NAME]
```
- 终端2建立端口转发：
```
fly proxy 5556:5555 --app [YOUR_APP_NAME]
```
- 浏览器访问：http://localhost:5556

注意：在多实例环境中，确保连接到主实例进行数据库修改操作。

数据库迁移策略

Epic Stack项目采用Prisma进行数据库迁移管理，遵循以下最佳实践：

迁移执行机制

迁移脚本作为部署流程的一部分自动执行
仅主实例会执行迁移操作
支持多版本应用同时运行，确保零停机部署

迁移策略示例：字段拆分

假设需要将name字段拆分为firstName和lastName：

拓宽阶段：
- 应用支持读取name或firstName+lastName
- 数据库添加新字段，迁移脚本将name值复制到firstName
收窄阶段：
- 应用仅使用新字段
- 从数据库中移除旧字段

这种"先拓宽后收窄"的策略确保了平滑迁移。

生产环境数据种子

Epic Stack项目内置了基于角色的访问控制(RBAC)系统，初始化时自动创建admin和user角色。如需自定义种子数据：

创建种子脚本：
```
cp prisma/seed.ts ./prod-seed.local.ts
```

创建临时数据库并执行种子：

DATABASE_URL=file:./seed.local.db npx prisma migrate reset --skip-seed --force
DATABASE_URL=file:./seed.local.db npx tsx ./prod-seed.local.ts

导出SQL并整合到迁移文件：

sqlite3 ./prisma/seed.local.db .dump > seed.local.sql

部署后执行迁移：

fly ssh console -C "npx prisma migrate reset --skip-seed --force"

数据库备份与恢复

手动备份流程

创建备份目录：

fly ssh console --app [YOUR_APP_NAME]
mkdir /backups

执行备份：

litefs export -name sqlite.db /backups/backup-$(date +%F).db

下载备份文件：

fly ssh sftp get /backups/backup-2023-10-10.db

恢复注意事项

警告：恢复操作会覆盖现有数据库！

上传备份文件：

fly ssh sftp shell --app [YOUR_APP_NAME]
put backup-2023-10-10.db

执行恢复：

litefs import -name sqlite.db /backup-2023-10-10.db

故障排查指南

迁移失败处理

当出现迁移失败时：

无数据保留需求：删除应用后重新部署
有备份：恢复备份后修复迁移脚本
无备份：
- 临时禁用自动迁移
- 手动备份数据库
- 修复迁移脚本
- 重新启用自动迁移

关键SQL操作：

DELETE FROM _prisma_migrations WHERE name = 'migration_name';

通过以上全面的数据库管理方案，Epic Stack项目为用户提供了稳定、可靠且易于维护的数据库架构，支持应用的平滑运行和持续演进。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考