分片

1 post with the tag “分片”

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

Apr 17, 2026

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

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

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

背景

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

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

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

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

关于 HagiCode

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

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

我们的代码仓库在 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	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 个分片，因为历史事件写入频率较低，且需要考虑迁移成本

路由算法差异

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

// 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<Task> 防重复初始化	Parallel.ForEachAsync	Lazy<Task> 防重复初始化

为什么 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 并发优化配置：

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 个分片

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

实践指南

实现标准化分片路由器

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

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

关键注意事项

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
• 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 许可协议。转载请注明出处!

Tags:

• SQLite
• 分片
• 性能优化
• 架构设计
• HagiCode