强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

dqlite 分布式 SQLite 教程

dqlite 分布式 SQLite 教程

dqlite — 使用 C 语言实现的分布式 SQLite 引擎,基于 Raft 共识协议,为嵌入式和边缘场景提供高可用关系型存储。


为什么写这份教程?

dqlite(distributed SQLite)是 Canonical(Ubuntu 母公司)主导开发的开源项目,核心目标是把 SQLite 变成一个可容错的分布式数据库。与 rqlite 等同类方案不同,dqlite 以 C 语言库 的形式提供,不依赖外部进程或 HTTP API,而是通过自定义二进制协议直接嵌入应用程序。

dqlite 已在多个高影响力项目中经受验证:

使用项目说明
LXDCanonical 的容器/虚拟机管理器,使用 dqlite 存储集群状态
MicroK8s轻量级 Kubernetes 发行版,使用 dqlite 替代 etcd
charmed-k8sCanonical 生产级 Kubernetes,可选 dqlite 作为数据存储

本教程从零开始,覆盖 dqlite 的核心概念、安装编译、架构原理、API 使用、集群管理、性能优化、安全配置、容器化部署与生产最佳实践,适合以下读者:

读者类型适用章节
初学者,想了解 dqlite 是什么第 1-3 章
C/Go 开发者,需要在项目中集成 dqlite第 4、5 章
运维工程师,负责集群部署与管理第 6、8、9 章
架构师,评估技术选型第 1、3、10 章

章节目录

章节标题关键词
第 1 章dqlite 概述与适用场景Raft、SQLite、分布式、rqlite 对比
第 2 章安装与编译C 库、Go 绑定、Docker
第 3 章架构深度解析Raft 共识、日志复制、快照、成员变更
第 4 章基本操作创建数据库、SQL 操作、连接管理
第 5 章C API 与 Go 绑定详解事务、参数绑定、回调、错误处理
第 6 章集群搭建与管理节点管理、Leader 选举、故障转移
第 7 章性能优化批量写入、读优化、同步策略、日志压缩
第 8 章安全配置TLS、认证、访问控制、加密通信
第 9 章Docker 与 Kubernetes 部署Compose、K8s、数据持久化
第 10 章生产最佳实践何时使用、容量规划、监控、运维 SOP

快速体验

如果你想先体验再深入学习,可以用 Docker 快速启动一个三节点集群:

# 启动三个 dqlite 节点
docker run -d --name dqlite-1 -p 9001:9001 \
  -e DQLITE_NODE_ID=1 \
  -e DQLITE_BOOTSTRAP=1 \
  canonical/dqlite-demo

docker run -d --name dqlite-2 -p 9002:9001 \
  -e DQLITE_NODE_ID=2 \
  canonical/dqlite-demo

docker run -d --name dqlite-3 -p 9003:9001 \
  -e DQLITE_NODE_ID=3 \
  canonical/dqlite-demo

或者用 C 语言快速集成:

#include <dqlite.h>
#include <stdio.h>

int main() {
    dqlite_node *node;
    int rc;

    rc = dqlite_node_create(1, "/tmp/dqlite-data", "127.0.0.1:9001", &node);
    if (rc != 0) {
        fprintf(stderr, "Failed to create node\n");
        return 1;
    }

    rc = dqlite_node_start(node);
    if (rc != 0) {
        fprintf(stderr, "Failed to start node\n");
        return 1;
    }

    printf("dqlite node running on 127.0.0.1:9001\n");

    dqlite_node_stop(node);
    dqlite_node_destroy(node);
    return 0;
}

更多细节请从 第 1 章:dqlite 概述与适用场景 开始阅读。


环境说明

本教程中的示例基于以下环境编写和测试:

项目版本
dqlitev1.16+
libdqlitev1.16+
go-dqlitev1.7+
Docker24.x+
Go1.21+
GCC12.x+
Ubuntu22.04 / 24.04

注意: dqlite 仅在 Linux 上运行,不支持 macOS 和 Windows。开发环境建议使用 Docker 或 WSL2。


dqlite vs rqlite 快速对比

如果你是从 rqlite 完全指南 过来的,以下对比可以帮助你快速理解两者差异:

维度dqliterqlite
实现语言CGo
嵌入方式作为库嵌入进程独立服务进程
通信协议自定义二进制协议HTTP REST API
查询方式本地 C API / Go 绑定HTTP 请求
性能更低延迟(进程内调用)稍高延迟(网络 + HTTP)
复杂度更高(需自行管理生命周期)更低(开箱即用)
适用场景嵌入式系统、容器运行时微服务、HTTP 后端

参考资源