SQLite 分片方案实战：三种分片策略的深度对比

SQLite 分片方案实战：三种分片策略的深度对比

当单文件 SQLite 遇到并发瓶颈，我们该如何破局？本文分享 HagiCode 项目中三种不同场景下的 SQLite 分片方案，帮你理解如何选择合适的分片策略。

全民制作人们大家好，我是 HagiCode 制作人俞坤。

背景

在构建高性能应用时，单文件 SQLite 数据库会碰到很现实的问题。用户量和数据量一上来，这些状况就会排队找上门：

• 写入操作开始排队，响应时间肉眼可见地变长

• 查询性能随数据增长往下掉

• 多线程访问时频繁出现 “database is locked” 错误

很多人第一反应是：要不要直接迁移到 PostgreSQL 或者 MySQL？这波操作虽然能解决问题，但部署复杂度会直线上升。有没有更轻量的方案？

答案是：分片。说到底，工程问题还是要回到工程方法里解决，通过将数据分散到多个 SQLite 文件，可以显著提升并发能力和查询性能，同时保持 SQLite 的轻量级特性。

关于 HagiCode

本文分享的方案来自我们在 HagiCode (https://hagicode.com) 项目中的实践经验。作为一个 AI 代码助手项目，HagiCode 需要处理大量的对话消息、状态持久化和事件历史记录。正是在解决这些实际问题的过程中，我们总结出了三种不同场景下的分片方案。

工欲善其事，必先利其器，但这些"器"怎么用，还得看具体的"事"是什么。

我们的代码仓库在 github.com/HagiCode-org/site (https://github.com/HagiCode-org/site)，欢迎感兴趣的朋友深入了解。

三种分片方案概览

经过对 HagiCode 代码库的分析，我们发现了三种针对不同业务场景的 SQLite 分片方案：

1. Session Message 分片存储：AI 对话消息存储，特点是高频写入、基于 Session 的隔离查询

2. Orleans Grain 分片存储：分布式框架状态持久化，特点是跨节点访问、需要确定性路由

3. Hero History 分片存储：游戏化系统历史事件记录，特点是事件溯源、需要迁移兼容

虽然业务场景不同，但三者都遵循相同的核心设计原则：

• 确定性路由：直接从业务 ID 计算分片，无需元数据表

• 透明访问：上层通过统一接口操作，不感知分片存在

• 独立存储：每个分片是完全独立的 SQLite 文件

• 并发优化：WAL 模式 + busy_timeout 降低锁竞争

很多人会问：为什么不搞一套通用的分片方案？这个问题问得很实在，我们直接上结论：工程上没有万能方案，只有最贴合当前业务场景的方案。接下来我们深入对比这三种方案的具体实现。

分片策略对比

分片数量与命名规则

为什么分片数量差异这么大？这取决于业务特点。换句话说，模型会说，工具会变，工作流会升级，但工程上的基本盘一直都在那里：你得先搞清楚自己要解决什么问题。

• Session Message使用 256 个分片，因为对话消息的写入频率最高，需要更多的分片来分散负载

• Orleans Grain使用 100 个分片，平衡了并发性能和管理复杂度

• Hero History只用 10 个分片，因为历史事件写入频率较低，且需要考虑迁移成本

路由算法差异

路由算法是分片方案的核心，决定了数据如何分布到各个分片。三种方案使用了不同的路由策略：

csharp // 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 永远映射到同一分片。这是分布式系统中最基本的要求，否则会导致数据不一致。说到底，路由不稳定，一切努力都是零。

初始化策略差异

为什么 Orleans Grain 选择启动时全量初始化？

因为 Orleans 是分布式框架，Grain 可能被调度到任意节点。如果在运行时才发现分片文件不存在，会导致请求失败。启动时全量初始化虽然会延长启动时间，但能确保运行时的稳定性。能跑起来只是开始，能维护下去才算本事。

懒加载的优势：

对于 Session Message 和 Hero History，使用懒加载可以减少启动时间，只有在真正需要访问某个分片时才创建文件和初始化 Schema。使用Lazy<Task>可以防止并发初始化时的竞态条件。这个设计看着简单，但在真实项目里能省掉很多不必要的麻烦。

Schema 设计特点

三种方案的 Schema 设计反映了各自的业务特点：

Session Message：

• 支持 Event Sourcing 模式（事件表 + 快照表）

• 包含消息内容块子表（MessageContentBlocks）

• 具有压缩和压缩标记字段，支持后续优化

Orleans Grain：

• 最简设计：单表 GrainState

• JSON 序列化存储状态

• ETag 乐观并发控制

Hero History：

• 时间线查询优化索引

• DedupeKey 唯一约束防重复

• 支持多种事件类型和状态

从这些设计中可以看出，Schema 设计应该紧密贴合业务需求，而不是追求通用性。Orleans Grain 的简单设计正是因为它只需要存储序列化后的状态，不需要复杂的查询能力。这波不是玄学，是工程。别急着把名字起得太大，先看看这东西能不能在团队里活过两个迭代。

并发配置对比

三种方案都使用了相同的 SQLite 并发优化配置：

sql PRAGMA journal_mode=WAL; -- 写前日志模式 PRAGMA synchronous=NORMAL; -- 降低持久化开销 PRAGMA busy_timeout=5000; -- 5秒忙等待 PRAGMA foreign_keys=ON; -- 外键约束

WAL 模式的优势：

传统的回滚日志模式在写入时会产生锁竞争，而 WAL 模式允许读写并发进行。这在大数据量场景下可以显著提升性能。很多人不知道这个配置，其实它比你想的要重要得多。

synchronous=NORMAL 的权衡：

设置为 FULL 可以保证最高安全性，但会显著降低性能。NORMAL 模式在安全性和性能之间取得了平衡，对于大多数应用来说是合适的选择。这个配置不需要纠结太久，NORMAL 就够了。

如何选择分片策略

基于对 HagiCode 三种方案的分析，我们可以总结出以下决策矩阵：

Plain Text 高吞吐量场景 → 更多分片（如 Message 用 256） 简单维护性 → 较少分片（如 Hero History 用 10） 数字 ID 为主 → 取模算法（Orleans Grain） GUID 为主 → 16 进制后缀（Session Message） 字符串 ID → ASCII 取模（Hero History）

分片数量选择的经验值：

• 太少（< 10）：并发提升有限，分片意义不大

• 太多（> 1000）：文件管理复杂，连接池开销大

• 经验值：10-100 个分片适用于大多数场景

• 极高并发场景：可以考虑 256 个分片

这事你要是只看演示，确实容易上头；可一旦进了生产环境，账就得一笔一笔算清楚。很多问题不是不能做，只是没把代价算明白。

实践指南

实现标准化分片路由器

csharp public interfaceIShardResolver<TId> { string ResolveShardKey(TId id); } // 16 进制分片（适用于 GUID） publicclassHexSuffixShardResolver : IShardResolver<string> { privatereadonlyint _suffixLength; public HexSuffixShardResolver(int suffixLength = 2) { _suffixLength = suffixLength; } public string ResolveShardKey(string id) { var normalized = id.Replace("-", "").ToLowerInvariant(); return normalized[^_suffixLength..]; } } // 数字取模分片（适用于纯数字 ID） publicclassNumericModuloShardResolver : IShardResolver<long> { privatereadonlyint _shardCount; public NumericModuloShardResolver(int shardCount) { _shardCount = shardCount; } public string ResolveShardKey(long id) { return (id % _shardCount).ToString("D2"); } }

统一连接工厂模式

csharp public classShardedConnectionFactory<TOptions> { privatereadonly ConcurrentDictionary<string, Lazy<Task>> _initializationTasks = new(); privatereadonly TOptions _options; privatereadonly 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 初始化最佳实践

csharp public classSqliteShardInitializer : IShardSchemaInitializer { public async Task InitializeAsync(string connectionString, CancellationToken ct) { awaitusingvar 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); """); } }

关键注意事项

1. 路由稳定性

路由算法必须保证同一 ID 永远映射到同一分片。避免使用随机或时间相关的计算，也不要在算法中引入可变参数。

2. 分片数量选择

分片数量应该在设计阶段确定，后期修改非常困难。需要考虑：

• 当前和未来的并发量

• 单个分片的管理成本

• 数据迁移的复杂度

3. 迁移考虑

Hero History 方案展示了完整的迁移路径：

1. 新建分片存储基础设施

2. 实现迁移服务将主库数据复制到分片

3. 验证迁移后查询兼容性

4. 切换读写路径到分片

5. 清理主库旧表

设计分片方案时就需要考虑未来的迁移需求。Talk is cheap. Show me the code，但光有代码还不够，你还得有完整的迁移路径。一次成功不叫体系，持续成功才叫体系。

4. 监控与运维

• 监控各分片的大小分布，及时发现数据倾斜

• 设置告警检测分片热点，避免单个分片成为瓶颈

• 定期检查 WAL 文件大小，防止磁盘空间占用过多

• 建立分片健康检查机制

5. 测试覆盖

• 测试边界条件（空 ID、特殊字符、超长 ID）

• 验证路由确定性，确保同一 ID 总是映射到同一分片

• 并发写入压力测试，验证锁竞争得到有效缓解

• 迁移测试，确保数据完整性和一致性

总结

通过对比 HagiCode 项目中的三种 SQLite 分片方案，我们可以看到：

1. 没有万能的解决方案：不同业务场景需要不同的分片策略

2. 核心原则是通用的：确定性路由、透明访问、独立存储、并发优化

3. 设计要面向未来：考虑迁移路径和运维成本

如果你的项目正在使用 SQLite，并且开始遇到并发瓶颈，希望这篇文章能为你提供一些思路。不需要急着迁移到重量级数据库，有时候合适的分片方案就能解决问题。

当然，分片不是银弹。在选择分片方案之前，先确保：

• 你已经优化了单表查询性能

• 你已经使用了合适的索引

• 你已经启用了 WAL 模式

只有在这些优化都做完之后，仍然存在性能瓶颈时，才考虑引入分片。你能把简单的事情做好，这本身就是一种能力。

很多话讲一遍不如做一遍，接下来就让工程结果自己发声。

参考资料

• HagiCode 项目仓库：github.com/HagiCode-org/site (https://github.com/HagiCode-org/site)

• SQLite WAL 模式文档：sqlite.org/wal.html (https://www.sqlite.org/wal.html)

• Orleans 分布式框架：dotnet.github.io/orleans (https://dotnet.github.io/orleans/)

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。 本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524 (https://www.newbe.pro)

• 原文链接: https://docs.hagicode.com/go?platform=wechat&target=%2Fblog%2F2026-04-17-sqlite-sharding-strategies-comparison%2F (https://docs.hagicode.com/go?platform=wechat&target=%2Fblog%2F2026-04-17-sqlite-sharding-strategies-comparison%2F)

• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!