SQLite 分片方案实战：三种分片策略的深度对比
SQLite 分片方案实战：三种分片策略的深度对比
Section titled “SQLite 分片方案实战：三种分片策略的深度对比”当单文件 SQLite 遇到并发瓶颈，我们该如何破局？本文分享 HagiCode 项目中三种不同场景下的 SQLite 分片方案，帮你理解如何选择合适的分片策略。
全民制作人们大家好，我是 HagiCode 制作人俞坤。
在构建高性能应用时，单文件 SQLite 数据库会碰到很现实的问题。用户量和数据量一上来，这些状况就会排队找上门：
- 写入操作开始排队，响应时间肉眼可见地变长
- 查询性能随数据增长往下掉
- 多线程访问时频繁出现 “database is locked” 错误
很多人第一反应是：要不要直接迁移到 PostgreSQL 或者 MySQL？这波操作虽然能解决问题，但部署复杂度会直线上升。有没有更轻量的方案？
答案是：分片。说到底，工程问题还是要回到工程方法里解决，通过将数据分散到多个 SQLite 文件，可以显著提升并发能力和查询性能，同时保持 SQLite 的轻量级特性。
关于 HagiCode
Section titled “关于 HagiCode”本文分享的方案来自我们在 HagiCode 项目中的实践经验。作为一个 AI 代码助手项目，HagiCode 需要处理大量的对话消息、状态持久化和事件历史记录。正是在解决这些实际问题的过程中，我们总结出了三种不同场景下的分片方案。
工欲善其事，必先利其器，但这些”器”怎么用，还得看具体的”事”是什么。
我们的代码仓库在 github.com/HagiCode-org/site，欢迎感兴趣的朋友深入了解。
三种分片方案概览
Section titled “三种分片方案概览”经过对 HagiCode 代码库的分析，我们发现了三种针对不同业务场景的 SQLite 分片方案：
- Session Message 分片存储：AI 对话消息存储，特点是高频写入、基于 Session 的隔离查询
- Orleans Grain 分片存储：分布式框架状态持久化，特点是跨节点访问、需要确定性路由
- Hero History 分片存储：游戏化系统历史事件记录，特点是事件溯源、需要迁移兼容
虽然业务场景不同，但三者都遵循相同的核心设计原则：
- 确定性路由：直接从业务 ID 计算分片，无需元数据表
- 透明访问：上层通过统一接口操作，不感知分片存在
- 独立存储：每个分片是完全独立的 SQLite 文件
- 并发优化：WAL 模式 + busy_timeout 降低锁竞争
很多人会问：为什么不搞一套通用的分片方案？这个问题问得很实在，我们直接上结论：工程上没有万能方案，只有最贴合当前业务场景的方案。接下来我们深入对比这三种方案的具体实现。
分片策略对比
Section titled “分片策略对比”分片数量与命名规则
Section titled “分片数量与命名规则”| 方面 | Session Message | Orleans Grain | Hero History |
|---|---|---|---|
| 分片数量 | 256 (16²) | 100 | 10 |
| 命名规则 | 16 进制 (00-ff) | 10 进制 (00-99) | 10 进制 (0-9) |
| 存储目录 | DataDir/messages/ | DataDir/orleans/grains/ | DataDir/hero-history/ |
| 文件名模式 | {shard}.db | grains-{shard}.db | {shard}.db |
为什么分片数量差异这么大？这取决于业务特点。换句话说，模型会说，工具会变，工作流会升级，但工程上的基本盘一直都在那里：你得先搞清楚自己要解决什么问题。
- Session Message 使用 256 个分片，因为对话消息的写入频率最高，需要更多的分片来分散负载
- Orleans Grain 使用 100 个分片，平衡了并发性能和管理复杂度
- Hero History 只用 10 个分片，因为历史事件写入频率较低，且需要考虑迁移成本
路由算法差异
Section titled “路由算法差异”路由算法是分片方案的核心，决定了数据如何分布到各个分片。三种方案使用了不同的路由策略：
// Session Message: GUID 后两位 16 进制var normalized = Guid.Parse(sessionId.Value).ToString("N").ToLowerInvariant();return normalized[^2..]; // 取末两位 16 进制字符
// Orleans Grain: 提取数字后两位取模var digits = ExtractDigits(grainId); // 提取所有数字var lastTwoDigits = (digits[^2] * 10) + digits[^1];return lastTwoDigits % shardCount;
// Hero History: 末位字符 ASCII 值取模return heroId[^1] % 10;设计思路解析：
- Session Message 的 ID 是 GUID，转换为 16 进制后取末两位，可以得到均匀分布的 256 个分片
- Orleans Grain 的 ID 格式不统一，可能包含字母和数字，所以提取所有数字后取模
- Hero History 的 ID 是字符串，直接用末位字符的 ASCII 值取模，简单但分布可能不够均匀
关键点：无论使用哪种算法，都必须保证同一 ID 永远映射到同一分片。这是分布式系统中最基本的要求，否则会导致数据不一致。说到底，路由不稳定，一切努力都是零。
初始化策略差异
Section titled “初始化策略差异”| 方面 | Session Message | Orleans Grain | Hero History |
|---|---|---|---|
| 初始化时机 | 按需懒加载 | 启动时全量并行初始化 | 按需懒加载 |
| 并发控制 | Lazy<Task> 防重复初始化 | Parallel.ForEachAsync | Lazy<Task> 防重复初始化 |
为什么 Orleans Grain 选择启动时全量初始化？
因为 Orleans 是分布式框架，Grain 可能被调度到任意节点。如果在运行时才发现分片文件不存在，会导致请求失败。启动时全量初始化虽然会延长启动时间，但能确保运行时的稳定性。能跑起来只是开始，能维护下去才算本事。
懒加载的优势：
对于 Session Message 和 Hero History，使用懒加载可以减少启动时间，只有在真正需要访问某个分片时才创建文件和初始化 Schema。使用 Lazy<Task> 可以防止并发初始化时的竞态条件。这个设计看着简单，但在真实项目里能省掉很多不必要的麻烦。
Schema 设计特点
Section titled “Schema 设计特点”三种方案的 Schema 设计反映了各自的业务特点：
Session Message：
- 支持 Event Sourcing 模式（事件表 + 快照表）
- 包含消息内容块子表（MessageContentBlocks）
- 具有压缩和压缩标记字段，支持后续优化
Orleans Grain：
- 最简设计：单表 GrainState
- JSON 序列化存储状态
- ETag 乐观并发控制
Hero History：
- 时间线查询优化索引
- DedupeKey 唯一约束防重复
- 支持多种事件类型和状态
从这些设计中可以看出，Schema 设计应该紧密贴合业务需求，而不是追求通用性。Orleans Grain 的简单设计正是因为它只需要存储序列化后的状态，不需要复杂的查询能力。这波不是玄学，是工程。别急着把名字起得太大，先看看这东西能不能在团队里活过两个迭代。
并发配置对比
Section titled “并发配置对比”三种方案都使用了相同的 SQLite 并发优化配置：
PRAGMA journal_mode=WAL; -- 写前日志模式PRAGMA synchronous=NORMAL; -- 降低持久化开销PRAGMA busy_timeout=5000; -- 5秒忙等待PRAGMA foreign_keys=ON; -- 外键约束WAL 模式的优势：
传统的回滚日志模式在写入时会产生锁竞争，而 WAL 模式允许读写并发进行。这在大数据量场景下可以显著提升性能。很多人不知道这个配置，其实它比你想的要重要得多。
synchronous=NORMAL 的权衡：
设置为 FULL 可以保证最高安全性，但会显著降低性能。NORMAL 模式在安全性和性能之间取得了平衡，对于大多数应用来说是合适的选择。这个配置不需要纠结太久，NORMAL 就够了。
如何选择分片策略
Section titled “如何选择分片策略”基于对 HagiCode 三种方案的分析，我们可以总结出以下决策矩阵：
高吞吐量场景 → 更多分片（如 Message 用 256）简单维护性 → 较少分片（如 Hero History 用 10）数字 ID 为主 → 取模算法（Orleans Grain）GUID 为主 → 16 进制后缀（Session Message）字符串 ID → ASCII 取模（Hero History）分片数量选择的经验值：
- 太少（< 10）：并发提升有限，分片意义不大
- 太多（> 1000）：文件管理复杂，连接池开销大
- 经验值：10-100 个分片适用于大多数场景
- 极高并发场景：可以考虑 256 个分片
这事你要是只看演示，确实容易上头；可一旦进了生产环境，账就得一笔一笔算清楚。很多问题不是不能做，只是没把代价算明白。
实现标准化分片路由器
Section titled “实现标准化分片路由器”public interface IShardResolver<TId>{ string ResolveShardKey(TId id);}
// 16 进制分片（适用于 GUID）public class HexSuffixShardResolver : IShardResolver<string>{ private readonly int _suffixLength;
public HexSuffixShardResolver(int suffixLength = 2) { _suffixLength = suffixLength; }
public string ResolveShardKey(string id) { var normalized = id.Replace("-", "").ToLowerInvariant(); return normalized[^_suffixLength..]; }}
// 数字取模分片（适用于纯数字 ID）public class NumericModuloShardResolver : IShardResolver<long>{ private readonly int _shardCount;
public NumericModuloShardResolver(int shardCount) { _shardCount = shardCount; }
public string ResolveShardKey(long id) { return (id % _shardCount).ToString("D2"); }}统一连接工厂模式
Section titled “统一连接工厂模式”public class ShardedConnectionFactory<TOptions>{ private readonly ConcurrentDictionary<string, Lazy<Task>> _initializationTasks = new(); private readonly TOptions _options; private readonly IShardSchemaInitializer _initializer;
public ShardedConnectionFactory( TOptions options, IShardSchemaInitializer initializer) { _options = options; _initializer = initializer; }
public async Task<TDbContext> CreateAsync(string shardKey, CancellationToken ct) { var connectionString = BuildConnectionString(shardKey);
// 使用 Lazy<Task> 防止并发初始化 var initTask = _initializationTasks.GetOrAdd( connectionString, _ => new Lazy<Task>(() => InitializeShardAsync(connectionString, ct)) );
await initTask.Value; return CreateDbContext(connectionString); }
private async Task InitializeShardAsync(string connectionString, CancellationToken ct) { await _initializer.InitializeAsync(connectionString, ct); }
private string BuildConnectionString(string shardKey) { var shardPath = Path.Combine(_options.BaseDirectory, $"{shardKey}.db"); return $"Data Source={shardPath}"; }
private TDbContext CreateDbContext(string connectionString) { // 根据具体的 ORM 创建 DbContext return Activator.CreateInstance(typeof(TDbContext), connectionString) as TDbContext; }}Schema 初始化最佳实践
Section titled “Schema 初始化最佳实践”public class SqliteShardInitializer : IShardSchemaInitializer{ public async Task InitializeAsync(string connectionString, CancellationToken ct) { await using var connection = new SqliteConnection(connectionString); await connection.OpenAsync(ct);
// 并发优化配置 await connection.ExecuteAsync(""" PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON; """);
// 创建表结构 await connection.ExecuteAsync(""" CREATE TABLE IF NOT EXISTS Entities ( Id TEXT PRIMARY KEY, CreatedAt TEXT NOT NULL, UpdatedAt TEXT NOT NULL, Data TEXT NOT NULL, ETag TEXT ); """);
// 创建索引 await connection.ExecuteAsync(""" CREATE INDEX IF NOT EXISTS IX_Entities_CreatedAt ON Entities(CreatedAt DESC);
CREATE INDEX IF NOT EXISTS IX_Entities_UpdatedAt ON Entities(UpdatedAt DESC); """); }}关键注意事项
Section titled “关键注意事项”1. 路由稳定性
路由算法必须保证同一 ID 永远映射到同一分片。避免使用随机或时间相关的计算，也不要在算法中引入可变参数。
2. 分片数量选择
分片数量应该在设计阶段确定，后期修改非常困难。需要考虑：
- 当前和未来的并发量
- 单个分片的管理成本
- 数据迁移的复杂度
3. 迁移考虑
Hero History 方案展示了完整的迁移路径：
- 新建分片存储基础设施
- 实现迁移服务将主库数据复制到分片
- 验证迁移后查询兼容性
- 切换读写路径到分片
- 清理主库旧表
设计分片方案时就需要考虑未来的迁移需求。Talk is cheap. Show me the code，但光有代码还不够，你还得有完整的迁移路径。一次成功不叫体系，持续成功才叫体系。
4. 监控与运维
- 监控各分片的大小分布，及时发现数据倾斜
- 设置告警检测分片热点，避免单个分片成为瓶颈
- 定期检查 WAL 文件大小，防止磁盘空间占用过多
- 建立分片健康检查机制
5. 测试覆盖
- 测试边界条件（空 ID、特殊字符、超长 ID）
- 验证路由确定性，确保同一 ID 总是映射到同一分片
- 并发写入压力测试，验证锁竞争得到有效缓解
- 迁移测试，确保数据完整性和一致性
通过对比 HagiCode 项目中的三种 SQLite 分片方案，我们可以看到：
- 没有万能的解决方案：不同业务场景需要不同的分片策略
- 核心原则是通用的：确定性路由、透明访问、独立存储、并发优化
- 设计要面向未来：考虑迁移路径和运维成本
如果你的项目正在使用 SQLite，并且开始遇到并发瓶颈，希望这篇文章能为你提供一些思路。不需要急着迁移到重量级数据库，有时候合适的分片方案就能解决问题。
当然，分片不是银弹。在选择分片方案之前，先确保：
- 你已经优化了单表查询性能
- 你已经使用了合适的索引
- 你已经启用了 WAL 模式
只有在这些优化都做完之后，仍然存在性能瓶颈时，才考虑引入分片。你能把简单的事情做好，这本身就是一种能力。
很多话讲一遍不如做一遍，接下来就让工程结果自己发声。
- HagiCode 项目仓库：github.com/HagiCode-org/site
- SQLite WAL 模式文档：sqlite.org/wal.html
- Orleans 分布式框架：dotnet.github.io/orleans
感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: newbe36524
- 原文链接: https://docs.hagicode.com/blog/2026-04-17-sqlite-sharding-strategies-comparison/
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!