Epic Stack项目中的多机部署与SQLite写入问题解析

问题背景

在Epic Stack项目中使用Fly.io进行多机部署时，开发者可能会遇到一个典型的数据库写入问题。当应用从单机扩展到多机环境后，某些数据库更新操作会突然失败，并出现"disk I/O error"或"read only replica"的错误提示。

问题现象

具体表现为：

1. 当应用运行在单机环境时一切正常
2. 扩展为多机后，某些数据库更新操作开始失败
3. 错误日志显示"disk I/O error"或"read only replica"信息
4. 问题特别容易发生在GET请求中进行数据写入的场景

技术原理分析

这个问题源于Epic Stack项目使用的LiteFS分布式SQLite架构设计：

1. 主从架构：LiteFS采用主从复制模式，只有主节点可以处理写入操作，从节点只能读取数据
2. 请求路由：系统配置了请求分发服务，会自动将非GET请求(如POST/PUT等)路由到主节点
3. GET请求限制：由于GET请求不会被自动路由，如果在GET请求中执行写入，就可能命中从节点导致失败

解决方案

针对这个问题，Epic Stack项目提供了两种解决方案：

1. 最佳实践方案（推荐）

遵循RESTful设计原则，避免在GET请求中进行数据修改操作。应该：

• 将数据更新逻辑迁移到POST/PUT等非GET请求中
• 保持GET请求的幂等性
• 这样既能解决多机写入问题，也符合Web安全最佳实践

2. 应急方案

如果确实需要在GET请求中写入数据，可以使用LiteFS提供的ensurePrimary()方法强制请求路由到主节点。但这种方法应该作为最后手段，因为它会破坏RESTful设计原则。

实际案例

项目中发现的几个典型问题场景：

1. 用户注册流程：在GET请求中创建Stripe客户ID并更新用户记录
2. OAuth回调处理：在认证回调的GET请求中创建数据库连接记录

这些问题都在项目后续更新中得到了修复，将写入操作迁移到了适当的非GET请求中。

总结

Epic Stack项目通过LiteFS实现了SQLite的多机部署能力，但也带来了写入限制。开发者需要：

1. 理解分布式SQLite的架构特点
2. 严格遵守RESTful设计原则
3. 避免在GET请求中进行数据修改
4. 必要时使用ensurePrimary()方法（但不推荐）

这种设计权衡了简单性和扩展性，开发者需要适应这种架构特点才能充分发挥Epic Stack在多机环境下的优势。