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

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

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

背景

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

写入操作开始排队，响应时间肉眼可见地变长
查询性能随数据增长往下掉
多线程访问时频繁出现 "database is locked" 错误

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

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

关于 HagiCode

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

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

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

三种分片方案概览

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

Session Message 分片存储：AI 对话消息存储，特点是高频写入、基于 Session 的隔离查询
Orleans Grain 分片存储：分布式框架状态持久化，特点是跨节点访问、需要确定性路由
Hero History 分片存储：游戏化系统历史事件记录，特点是事件溯源、需要迁移兼容

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

确定性路由：直接从业务 ID 计算分片，无需元数据表
透明访问：上层通过统一接口操作，不感知分片存在
独立存储：每个分片是完全独立的 SQLite 文件
并发优化：WAL 模式 + busy_timeout 降低锁竞争

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

分片策略对比

分片数量与命名规则

方面	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 个分片，因为历史事件写入频率较低，且需要考虑迁移成本

路由算法差异

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

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

初始化策略差异

方面	Session Message	Orleans Grain	Hero History
初始化时机	按需懒加载	启动时全量并行初始化	按需懒加载
并发控制	Lazy 防重复初始化	Parallel.ForEachAsync	Lazy 防重复初始化

为什么 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 三种方案的分析，我们可以总结出以下决策矩阵：

复制代码

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

分片数量选择的经验值：

太少（< 10）：并发提升有限，分片意义不大
太多（> 1000）：文件管理复杂，连接池开销大
经验值：10-100 个分片适用于大多数场景
极高并发场景：可以考虑 256 个分片

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

实践指南

实现标准化分片路由器

csharp 复制代码

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");
    }
}

统一连接工厂模式

csharp 复制代码

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 初始化最佳实践

csharp 复制代码

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. 监控与运维

监控各分片的大小分布，及时发现数据倾斜
设置告警检测分片热点，避免单个分片成为瓶颈
定期检查 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/go?platform=cnblogs&target=%2Fblog%2F2026-04-17-sqlite-sharding-strategies-comparison%2F
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!