当单文件 SQLite 遇到并发瓶颈，我们该如何破局？本文分享 HagiCode 项目中三种不同场景下的 SQLite 分片方案，帮你理解如何选择合适的分片策略。
全民制作人们大家好，我是 HagiCode 制作人俞坤。
在构建高性能应用时，单文件 SQLite 数据库会碰到很现实的问题。用户量和数据量一上来，这些状况就会排队找上门：
很多人第一反应是：要不要直接迁移到 PostgreSQL 或者 MySQL？这波操作虽然能解决问题，但部署复杂度会直线上升。有没有更轻量的方案？
答案是：分片。说到底，工程问题还是要回到工程方法里解决，通过将数据分散到多个 SQLite 文件，可以显著提升并发能力和查询性能，同时保持 SQLite 的轻量级特性。
本文分享的方案来自我们在 HagiCode 项目中的实践经验。作为一个 AI 代码助手项目，HagiCode 需要处理大量的对话消息、状态持久化和事件历史记录。正是在解决这些实际问题的过程中，我们总结出了三种不同场景下的分片方案。
工欲善其事，必先利其器，但这些"器"怎么用，还得看具体的"事"是什么。
我们的代码仓库在 github.com/HagiCode-org/site，欢迎感兴趣的朋友深入了解。
经过对 HagiCode 代码库的分析，我们发现了三种针对不同业务场景的 SQLite 分片方案：
虽然业务场景不同，但三者都遵循相同的核心设计原则：
很多人会问：为什么不搞一套通用的分片方案？这个问题问得很实在，我们直接上结论：工程上没有万能方案，只有最贴合当前业务场景的方案。接下来我们深入对比这三种方案的具体实现。
| 方面 | 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: 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;
设计思路解析：
关键点：无论使用哪种算法，都必须保证同一 ID 永远映射到同一分片。这是分布式系统中最基本的要求，否则会导致数据不一致。说到底，路由不稳定，一切努力都是零。
| 方面 | Session Message | Orleans Grain | Hero History |
|---|---|---|---|
| 初始化时机 | 按需懒加载 | 启动时全量并行初始化 | 按需懒加载 |
| 并发控制 | Lazy 防重复初始化 | Parallel.ForEachAsync | Lazy 防重复初始化 |
为什么 Orleans Grain 选择启动时全量初始化？
因为 Orleans 是分布式框架，Grain 可能被调度到任意节点。如果在运行时才发现分片文件不存在，会导致请求失败。启动时全量初始化虽然会延长启动时间，但能确保运行时的稳定性。能跑起来只是开始，能维护下去才算本事。
懒加载的优势：
对于 Session Message 和 Hero History，使用懒加载可以减少启动时间，只有在真正需要访问某个分片时才创建文件和初始化 Schema。使用 Lazy<Task> 可以防止并发初始化时的竞态条件。这个设计看着简单，但在真实项目里能省掉很多不必要的麻烦。
三种方案的 Schema 设计反映了各自的业务特点：
Session Message：
Orleans Grain：
Hero History：
从这些设计中可以看出，Schema 设计应该紧密贴合业务需求，而不是追求通用性。Orleans Grain 的简单设计正是因为它只需要存储序列化后的状态，不需要复杂的查询能力。这波不是玄学，是工程。别急着把名字起得太大，先看看这东西能不能在团队里活过两个迭代。
三种方案都使用了相同的 SQLite 并发优化配置：
PRAGMA journal_mode=WAL; -- 写前日志模式
PRAGMA synchronous=NORMAL; -- 降低持久化开销
PRAGMA busy_timeout=5000; -- 5秒忙等待
PRAGMA foreign_keys=ON; -- 外键约束
WAL 模式的优势：
传统的回滚日志模式在写入时会产生锁竞争，而 WAL 模式允许读写并发进行。这在大数据量场景下可以显著提升性能。很多人不知道这个配置，其实它比你想的要重要得多。
synchronous=NORMAL 的权衡：
设置为 FULL 可以保证最高安全性，但会显著降低性能。NORMAL 模式在安全性和性能之间取得了平衡，对于大多数应用来说是合适的选择。这个配置不需要纠结太久，NORMAL 就够了。
基于对 HagiCode 三种方案的分析，我们可以总结出以下决策矩阵：
高吞吐量场景 → 更多分片（如 Message 用 256）
简单维护性 → 较少分片（如 Hero History 用 10）
数字 ID 为主 → 取模算法（Orleans Grain）
GUID 为主 → 16 进制后缀（Session Message）
字符串 ID → ASCII 取模（Hero History）
分片数量选择的经验值：
这事你要是只看演示，确实容易上头；可一旦进了生产环境，账就得一笔一笔算清楚。很多问题不是不能做，只是没把代价算明白。
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");
}
}
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;
}
}
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);
""");
}
}
1. 路由稳定性
路由算法必须保证同一 ID 永远映射到同一分片。避免使用随机或时间相关的计算，也不要在算法中引入可变参数。
2. 分片数量选择
分片数量应该在设计阶段确定，后期修改非常困难。需要考虑：
3. 迁移考虑
Hero History 方案展示了完整的迁移路径：
设计分片方案时就需要考虑未来的迁移需求。Talk is cheap. Show me the code，但光有代码还不够，你还得有完整的迁移路径。一次成功不叫体系，持续成功才叫体系。
4. 监控与运维
5. 测试覆盖
通过对比 HagiCode 项目中的三种 SQLite 分片方案，我们可以看到：
如果你的项目正在使用 SQLite，并且开始遇到并发瓶颈，希望这篇文章能为你提供一些思路。不需要急着迁移到重量级数据库，有时候合适的分片方案就能解决问题。
当然，分片不是银弹。在选择分片方案之前，先确保：
只有在这些优化都做完之后，仍然存在性能瓶颈时，才考虑引入分片。你能把简单的事情做好，这本身就是一种能力。
很多话讲一遍不如做一遍，接下来就让工程结果自己发声。
感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。