尧图网站建设 
libSQL sqld 构建与运行完全指南五种部署方式与源码级配置解析【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql本指南围绕 libSQL 仓库中sqldSQL daemonlibSQL 的服务端形态的构建与运行展开覆盖预编译二进制、Homebrew、预构建 Docker 镜像、Docker/Podman 源码构建、Rust 源码构建五种路径并结合 libsql-server/src/main.rs 的 CLI 实现与 Dockerfile、docker-entrypoint.sh 等仓库源码深度解析默认配置、环境变量、primary/replica/standalone 三种运行模式及测试方法。读完本文你将能够独立完成 sqld 的本地开发部署、容器化发布和读写分离集群搭建。sqld 是什么sqld是 libSQL 的“服务端模式”它把 SQLite 兼容的数据库引擎封装成可通过 HTTP / WebSocketHrana 协议访问的数据库服务适合服务端无状态应用、边缘计算等不适合内嵌数据库引擎的场景。其二进制由 libsql-server/Cargo.toml 定义包名为libsql-server、二进制名为sqld当前仓库版本为 0.24.33。构建与运行 sqld 共有五种方式下载预编译二进制使用 Homebrew 构建安装使用预构建 Docker 镜像用 Docker / Podman 从源码构建用 Rust 工具链从源码构建。下文按“先直接体验、再逐种部署”的顺序展开。快速开始直接运行 sqld在获得sqld二进制任意一种方式构建/安装之后不带任何命令行参数直接启动即可运行一个实例sqld默认行为如下数据库数据持久化在目录./data.sqldHTTP 服务监听127.0.0.1:8080。这两个默认值并非约定俗成而是直接定义在 libsql-server/src/main.rs 中--db-path参数默认值为data.sqld--http-listen-addr参数默认值为127.0.0.1:8080。运行时可以通过--help查看全部可用的命令行参数、默认值以及对应的环境变量帮助输出中标注为env:的部分sqld --help启动成功后sqld 会打印欢迎信息其中包含版本号、commit SHA、构建日期以及本次启动的运行模式与监听地址见 print_welcome_message。查询 sqldsqld 启动后可以使用仓库提供的各类客户端库TypeScript/JavaScript、Rust、Go、Python 等连接http://127.0.0.1:8080或ws://127.0.0.1:8080进行查询。也可以使用 turso CLI 直接以 shell 方式连接本地实例turso db shell http://127.0.0.1:8080方式一下载预编译二进制libsql-server 的 Releases 页面会随版本发布列出 macOS 与 Linux 的预编译产物。选择对应平台Linux 亦适用于 WSL的压缩包下载、解压后即可直接使用无需安装任何依赖。方式二使用 Homebrew 构建安装sqld 的 Homebrew formulae 支持 macOS 和 Linux含 WSL。1. 添加 tap 仓库libsql/sqldbrew tap libsql/sqld2. 安装 formulaesqldbrew install sqld该命令会从源码构建并安装二进制sqld到$HOMEBREW_PREFIX/bin/sqld该目录通常已在 PATH 中。3. 验证安装sqld --help能正常打印帮助信息即安装成功。方式三使用预构建 Docker 镜像sqld 的发布流程会把镜像推送到 GitHub Container RegistryGHCR镜像名为ghcr.io/tursodatabase/libsql-server。在本地 8080 端口运行最新版docker run -p 8080:8080 -d ghcr.io/tursodatabase/libsql-server:latest也可以按版本号vX.Y.Z的形式拉取特定版本的容器镜像标签docker run -p 8080:8080 -d ghcr.io/tursodatabase/libsql-server:vX.Y.Z注意与本地直接运行不同容器镜像默认将数据库文件存放在容器内/var/lib/sqld见 Dockerfile 的VOLUME声明并用独立的sqld系统用户UID/GID 666运行服务因此生产环境务必挂载持久化卷详见下一节。方式四使用 Docker / Podman 从源码构建这种方式适合需要定制构建参数如启用encryption、bottomless等功能特性或无法访问预构建镜像的场景。前提是机器上已安装并启动 Docker或兼容的 Podman且 CLI 已在 PATH 中。1. 克隆仓库使用 git 克隆本仓库到本地。若希望构建特定版本可检出对应的 release tag。2. 构建 Docker 镜像在仓库根目录执行docker build -t libsql/sqld:latest .仓库根目录的 Dockerfile 采用多阶段构建chef 阶段基于rust:slim-bullseye安装构建所需系统依赖libclang-dev、clang、build-essential、tcl、protobuf-compiler、file、libssl-dev、pkg-config、git、cmake并按 rust-toolchain.toml 指定的通道当前为 1.85.0固定工具链同时安装cargo-chef以利用依赖层缓存planner / builder 阶段执行cargo chef cook --release缓存依赖后正式执行cargo build -p libsql-server --release --locked构建时可传入ENABLE_FEATURES构建参数如ENABLE_FEATURESencryption启用附加特性同时还会构建bottomless-cliruntime 阶段基于debian:bullseye-slimEXPOSE 5001 8080声明VOLUME /var/lib/sqld创建sqld用户并以docker-wrapper.sh为入口、/bin/sqld为默认命令。3. 验证构建产物docker container run \ --rm \ -i \ libsql/sqld \ /bin/sqld --help能打印帮助信息即构建成功。4. 创建数据卷sqld 使用数据卷持久化数据库文件创建一个名为sqld-data的卷docker volume create sqld-data5. 运行 sqld 容器使用刚构建的镜像创建并后台运行名为sqld的容器挂载数据卷并把 8080 端口映射到本机docker container run \ -d \ --name sqld \ -v sqld-data:/var/lib/sqld \ -p 127.0.0.1:8080:8080 \ libsql/sqld:latest8080 是 sqld HTTP 服务的默认端口负责处理客户端查询。容器运行后即可用http://127.0.0.1:8080或ws://127.0.0.1:8080配置任意一种 libSQL 客户端 SDK 进行本地开发。6. 用环境变量配置 sqld在第 3 步--help的输出中除了命令行参数名还会看到每个参数对应的环境变量名标注env:。例如--http-listen-addr对应SQLD_HTTP_LISTEN_ADDR--db-path对应SQLD_DB_PATH。容器场景下通过-e传递环境变量即可覆盖默认行为docker container run \ -d \ --name sqld \ -v sqld-data:/var/lib/sqld \ -p 8080:8080 \ -e SQLD_DB_PATH/var/lib/sqld \ -e SQLD_HTTP_LISTEN_ADDR0.0.0.0:8080 \ libsql/sqld:latest方式五使用 Rust 工具链从源码构建这是最灵活的构建方式适合二次开发与调试。需要本机已安装 Rust 开发环境并位于 PATH 中。当前仅支持 macOS 和 Linux含 WSLWindows 原生构建仍在完善中。1. 克隆仓库并进入 libsql-server 目录git clone 本仓库地址 cd libsql-server构建时请注意 rust-toolchain.toml 指定的工具链版本当前为1.85.0rustup 会自动按该文件切换对应工具链。2. 使用 cargo 构建cargo build构建产物为./target/debug/sqld。如需发布版可执行cargo build --release产物位于./target/release/sqld。仓库中的 Dockerfile 也是以cargo build -p libsql-server --release --locked作为正式构建命令。3. 验证构建./target/debug/sqld --help4. 以全部默认配置运行./target/debug/sqld该命令使用以下默认配置启动本地数据文件存储在目录./data.sqld客户端 HTTP 请求监听127.0.0.1:8080。同样地8080 是 sqld HTTP 服务的默认端口启动后即可用http://127.0.0.1:8080或ws://127.0.0.1:8080连接任意 libSQL 客户端 SDK 进行开发。需要改变运行时行为时通过--help发现参数或直接参考下文的参数速查表。5. 运行测试可选cargo xtask test该命令会调用仓库 xtask/src/main.rs 中定义的test任务先安装固定版本0.9.98的cargo-nextest再以cargo nextest run运行整个 libsql 测试套件。除test外cargo xtask还支持test-encryption嵌入式副本加密测试、sim-tests test name模拟测试、build、build-bundled、build-wasm等任务可用cargo xtask查看全部任务说明。sqld 核心启动参数与运行模式从 libsql-server/src/main.rs 的 CLI 定义可以看出sqld 的配置全部通过 clap 声明每个参数都绑定了环境变量。下表列出最常用的参数均可用--flag传入或用对应env:环境变量覆盖命令行参数环境变量默认值说明--db-pathSQLD_DB_PATHdata.sqld数据库文件存储目录--http-listen-addrSQLD_HTTP_LISTEN_ADDR127.0.0.1:8080HTTP API 监听地址与端口--hrana-list-en-addr-lSQLD_HRANA_LISTEN_ADDR无旧版纯 WebSocket Hrana 服务监听地址--admin-listen-addrSQLD_ADMIN_LISTEN_ADDR无管理 HTTP API 监听地址需配合LIBSQL_ADMIN_AUTH_KEY--grpc-listen-addrSQLD_GRPC_LISTEN_ADDR无节点间 RPCgRPC监听地址启用后为 primary 模式--primary-grpc-urlSQLD_PRIMARY_GRPC_URL无primary 节点的 gRPC URL设置后为 replica 模式与--grpc-listen-addr互斥--auth-jwt-key-fileSQLD_AUTH_JWT_KEY_FILE无JWT 解码密钥文件PKCS#8 PEM 或 URL-safe base64可直接用SQLD_AUTH_JWT_KEY传值--http-authSQLD_HTTP_AUTH无旧版 HTTP Basic 认证格式basic:$PARAM$PARAM为用户名:密码的 base64--extensions-path无无受信扩展目录须含trusted.lst否则扩展加载被禁用--max-log-sizeSQLD_MAX_LOG_SIZE200复制日志最大体积MB--max-response-sizeSQLD_MAX_RESPONSE_SIZE10MB单次响应最大体积--max-total-response-sizeSQLD_MAX_TOTAL_RESPONSE_SIZE32MB全部响应累计最大体积--checkpoint-interval-sSQLD_CHECKPOINT_INTERVAL_S无默认 1 小时WAL checkpoint 调用间隔秒--enable-namespaces无关闭启用命名空间默认全部请求落默认命名空间default--encryption-keySQLD_ENCRYPTION_KEY无静态数据加密密钥需encryption特性--max-concurrent-connectionsSQLD_MAX_CONCURRENT_CONNECTIONS128最大并发连接数--max-concurrent-requestsSQLD_MAX_CONCURRENT_REQUESTS128最大并发请求数--idle-shutdown-timeout-sSQLD_IDLE_SHUTDOWN_TIMEOUT_S无空闲多少秒后自动关闭默认不自动关闭--heartbeat-urlSQLD_HEARTBEAT_URL无心跳 POST 上报地址默认不发心跳--enable-bottomless-replicationSQLD_ENABLE_BOTTOMLESS_REPLICATION关闭启用 bottomless S3 复制备份--no-welcome无关闭关闭欢迎信息--disable-metricsLIBSQL_DISABLE_METRICS关闭关闭 Prometheus 指标采集注上表为当前仓库 libsql-server/src/main.rs 中定义参数的非完全列举完整列表以sqld --help输出为准。三种运行模式从 print_welcome_message 的实现可以看到 sqld 根据两个关键参数组合出三种运行模式standalone单机模式--grpc-listen-addr与--primary-grpc-url均未设置——默认行为独立服务primary主节点仅设置--grpc-listen-addr——开放节点间 gRPC 端口接收副本写入/同步replica副本节点仅设置--primary-grpc-url——连接 primary 进行复制本地只读。优雅停机sqld 在收到 SIGINT 或 SIGTERM 信号后会触发优雅停机见 shutdown_signal 与build_server中的信号处理逻辑默认停机超时 30 秒可通过--shutdown-timeout调整。容器内的角色编排SQLD_NODE容器镜像默认命令为/bin/sqld实际入口是 docker-wrapper.sh docker-entrypoint.sh 的组合前者确保数据目录存在并切换为sqld用户执行后者根据环境变量把容器“翻译”成 sqld 的 CLI 参数SQLD_NODE取值primary默认、replica、standaloneSQLD_DB_PATH容器内数据库路径默认iku.dbSQLD_HTTP_LISTEN_ADDR容器内 HTTP 监听地址默认0.0.0.0:8080SQLD_GRPC_LISTEN_ADDR仅 primary 模式生效默认0.0.0.0:5001SQLD_PRIMARY_URL仅 replica 模式生效指向 primary 的 gRPC 地址。因此在容器环境下无需手写 CLI 参数只需设置SQLD_NODE及对应变量即可声明节点角色。读写分离编排示例仓库提供了开箱即用的读写分离编排docker-compose/docker-compose.yml 定义了三个服务writer以SQLD_NODEprimary运行开放 5001 端口用于副本同步reader以SQLD_NODEreplica运行通过SQLD_PRIMARY_URLhttp://writer:5001指向主节点监听0.0.0.0:8080nginx作为反向代理对外暴露 8080HTTP 查询入口与 6001 端口按 nginx.conf 规则在读写节点间分发流量。使用docker compose up即可拉起一整套读写分离环境适合作为理解 sqld 复制能力的起点复制协议细节可参考 libsql-replication 与 docs/DESIGN.md。故障排查与注意事项构建依赖缺失源码/Docker 构建需要libclang-dev、clang、protobuf-compiler、libssl-dev、pkg-config、cmake、tcl等系统包参考 Dockerfile。本地 Rust 构建失败时优先确认这些依赖已安装。工具链版本请确保 rustup 按 rust-toolchain.toml 自动切换到1.85.0通道否则可能出现依赖编译失败。端口冲突默认 8080 被占用时用--http-listen-addr或SQLD_HTTP_LISTEN_ADDR更换端口。数据持久化Docker 方式运行务必挂载卷到/var/lib/sqld否则容器删除后数据丢失本地二进制方式默认数据在./data.sqld。扩展加载如需加载 SQLite 扩展须使用--extensions-path指向包含trusted.lst每行sha256 文件名的目录sqld 启动时会逐一校验 SHA256 后才加载校验逻辑见 config.rs 的 validate_extensions。S3 备份bottomless以--enable-bottomless-replication启动后可把数据库持续备份到 S3 兼容存储相关配置见 libsql-server/README.md 与 bottomless/ 子项目。小结从直接运行到容器编排sqld 提供了从开发到生产的完整部署路径本地开发可用预编译二进制或cargo build标准化交付可用 Homebrew 或 Docker规模化部署可借助SQLD_NODE角色声明与 docker-compose 快速搭建读写分离。所有运行行为都收敛在 libsql-server/src/main.rs 的单一 CLI 定义中--help即是最好的配置手册。【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 libSQL sqld 构建与运行完全指南：五种部署方式与源码级配置解析
libSQL sqld 构建与运行完全指南五种部署方式与源码级配置解析【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql本指南围绕 libSQL 仓库中sqldSQL daemonlibSQL 的服务端形态的构建与运行展开覆盖预编译二进制、Homebrew、预构建 Docker 镜像、Docker/Podman 源码构建、Rust 源码构建五种路径并结合 libsql-server/src/main.rs 的 CLI 实现与 Dockerfile、docker-entrypoint.sh 等仓库源码深度解析默认配置、环境变量、primary/replica/standalone 三种运行模式及测试方法。读完本文你将能够独立完成 sqld 的本地开发部署、容器化发布和读写分离集群搭建。sqld 是什么sqld是 libSQL 的“服务端模式”它把 SQLite 兼容的数据库引擎封装成可通过 HTTP / WebSocketHrana 协议访问的数据库服务适合服务端无状态应用、边缘计算等不适合内嵌数据库引擎的场景。其二进制由 libsql-server/Cargo.toml 定义包名为libsql-server、二进制名为sqld当前仓库版本为 0.24.33。构建与运行 sqld 共有五种方式下载预编译二进制使用 Homebrew 构建安装使用预构建 Docker 镜像用 Docker / Podman 从源码构建用 Rust 工具链从源码构建。下文按“先直接体验、再逐种部署”的顺序展开。快速开始直接运行 sqld在获得sqld二进制任意一种方式构建/安装之后不带任何命令行参数直接启动即可运行一个实例sqld默认行为如下数据库数据持久化在目录./data.sqldHTTP 服务监听127.0.0.1:8080。这两个默认值并非约定俗成而是直接定义在 libsql-server/src/main.rs 中--db-path参数默认值为data.sqld--http-listen-addr参数默认值为127.0.0.1:8080。运行时可以通过--help查看全部可用的命令行参数、默认值以及对应的环境变量帮助输出中标注为env:的部分sqld --help启动成功后sqld 会打印欢迎信息其中包含版本号、commit SHA、构建日期以及本次启动的运行模式与监听地址见 print_welcome_message。查询 sqldsqld 启动后可以使用仓库提供的各类客户端库TypeScript/JavaScript、Rust、Go、Python 等连接http://127.0.0.1:8080或ws://127.0.0.1:8080进行查询。也可以使用 turso CLI 直接以 shell 方式连接本地实例turso db shell http://127.0.0.1:8080方式一下载预编译二进制libsql-server 的 Releases 页面会随版本发布列出 macOS 与 Linux 的预编译产物。选择对应平台Linux 亦适用于 WSL的压缩包下载、解压后即可直接使用无需安装任何依赖。方式二使用 Homebrew 构建安装sqld 的 Homebrew formulae 支持 macOS 和 Linux含 WSL。1. 添加 tap 仓库libsql/sqldbrew tap libsql/sqld2. 安装 formulaesqldbrew install sqld该命令会从源码构建并安装二进制sqld到$HOMEBREW_PREFIX/bin/sqld该目录通常已在 PATH 中。3. 验证安装sqld --help能正常打印帮助信息即安装成功。方式三使用预构建 Docker 镜像sqld 的发布流程会把镜像推送到 GitHub Container RegistryGHCR镜像名为ghcr.io/tursodatabase/libsql-server。在本地 8080 端口运行最新版docker run -p 8080:8080 -d ghcr.io/tursodatabase/libsql-server:latest也可以按版本号vX.Y.Z的形式拉取特定版本的容器镜像标签docker run -p 8080:8080 -d ghcr.io/tursodatabase/libsql-server:vX.Y.Z注意与本地直接运行不同容器镜像默认将数据库文件存放在容器内/var/lib/sqld见 Dockerfile 的VOLUME声明并用独立的sqld系统用户UID/GID 666运行服务因此生产环境务必挂载持久化卷详见下一节。方式四使用 Docker / Podman 从源码构建这种方式适合需要定制构建参数如启用encryption、bottomless等功能特性或无法访问预构建镜像的场景。前提是机器上已安装并启动 Docker或兼容的 Podman且 CLI 已在 PATH 中。1. 克隆仓库使用 git 克隆本仓库到本地。若希望构建特定版本可检出对应的 release tag。2. 构建 Docker 镜像在仓库根目录执行docker build -t libsql/sqld:latest .仓库根目录的 Dockerfile 采用多阶段构建chef 阶段基于rust:slim-bullseye安装构建所需系统依赖libclang-dev、clang、build-essential、tcl、protobuf-compiler、file、libssl-dev、pkg-config、git、cmake并按 rust-toolchain.toml 指定的通道当前为 1.85.0固定工具链同时安装cargo-chef以利用依赖层缓存planner / builder 阶段执行cargo chef cook --release缓存依赖后正式执行cargo build -p libsql-server --release --locked构建时可传入ENABLE_FEATURES构建参数如ENABLE_FEATURESencryption启用附加特性同时还会构建bottomless-cliruntime 阶段基于debian:bullseye-slimEXPOSE 5001 8080声明VOLUME /var/lib/sqld创建sqld用户并以docker-wrapper.sh为入口、/bin/sqld为默认命令。3. 验证构建产物docker container run \ --rm \ -i \ libsql/sqld \ /bin/sqld --help能打印帮助信息即构建成功。4. 创建数据卷sqld 使用数据卷持久化数据库文件创建一个名为sqld-data的卷docker volume create sqld-data5. 运行 sqld 容器使用刚构建的镜像创建并后台运行名为sqld的容器挂载数据卷并把 8080 端口映射到本机docker container run \ -d \ --name sqld \ -v sqld-data:/var/lib/sqld \ -p 127.0.0.1:8080:8080 \ libsql/sqld:latest8080 是 sqld HTTP 服务的默认端口负责处理客户端查询。容器运行后即可用http://127.0.0.1:8080或ws://127.0.0.1:8080配置任意一种 libSQL 客户端 SDK 进行本地开发。6. 用环境变量配置 sqld在第 3 步--help的输出中除了命令行参数名还会看到每个参数对应的环境变量名标注env:。例如--http-listen-addr对应SQLD_HTTP_LISTEN_ADDR--db-path对应SQLD_DB_PATH。容器场景下通过-e传递环境变量即可覆盖默认行为docker container run \ -d \ --name sqld \ -v sqld-data:/var/lib/sqld \ -p 8080:8080 \ -e SQLD_DB_PATH/var/lib/sqld \ -e SQLD_HTTP_LISTEN_ADDR0.0.0.0:8080 \ libsql/sqld:latest方式五使用 Rust 工具链从源码构建这是最灵活的构建方式适合二次开发与调试。需要本机已安装 Rust 开发环境并位于 PATH 中。当前仅支持 macOS 和 Linux含 WSLWindows 原生构建仍在完善中。1. 克隆仓库并进入 libsql-server 目录git clone 本仓库地址 cd libsql-server构建时请注意 rust-toolchain.toml 指定的工具链版本当前为1.85.0rustup 会自动按该文件切换对应工具链。2. 使用 cargo 构建cargo build构建产物为./target/debug/sqld。如需发布版可执行cargo build --release产物位于./target/release/sqld。仓库中的 Dockerfile 也是以cargo build -p libsql-server --release --locked作为正式构建命令。3. 验证构建./target/debug/sqld --help4. 以全部默认配置运行./target/debug/sqld该命令使用以下默认配置启动本地数据文件存储在目录./data.sqld客户端 HTTP 请求监听127.0.0.1:8080。同样地8080 是 sqld HTTP 服务的默认端口启动后即可用http://127.0.0.1:8080或ws://127.0.0.1:8080连接任意 libSQL 客户端 SDK 进行开发。需要改变运行时行为时通过--help发现参数或直接参考下文的参数速查表。5. 运行测试可选cargo xtask test该命令会调用仓库 xtask/src/main.rs 中定义的test任务先安装固定版本0.9.98的cargo-nextest再以cargo nextest run运行整个 libsql 测试套件。除test外cargo xtask还支持test-encryption嵌入式副本加密测试、sim-tests test name模拟测试、build、build-bundled、build-wasm等任务可用cargo xtask查看全部任务说明。sqld 核心启动参数与运行模式从 libsql-server/src/main.rs 的 CLI 定义可以看出sqld 的配置全部通过 clap 声明每个参数都绑定了环境变量。下表列出最常用的参数均可用--flag传入或用对应env:环境变量覆盖命令行参数环境变量默认值说明--db-pathSQLD_DB_PATHdata.sqld数据库文件存储目录--http-listen-addrSQLD_HTTP_LISTEN_ADDR127.0.0.1:8080HTTP API 监听地址与端口--hrana-list-en-addr-lSQLD_HRANA_LISTEN_ADDR无旧版纯 WebSocket Hrana 服务监听地址--admin-listen-addrSQLD_ADMIN_LISTEN_ADDR无管理 HTTP API 监听地址需配合LIBSQL_ADMIN_AUTH_KEY--grpc-listen-addrSQLD_GRPC_LISTEN_ADDR无节点间 RPCgRPC监听地址启用后为 primary 模式--primary-grpc-urlSQLD_PRIMARY_GRPC_URL无primary 节点的 gRPC URL设置后为 replica 模式与--grpc-listen-addr互斥--auth-jwt-key-fileSQLD_AUTH_JWT_KEY_FILE无JWT 解码密钥文件PKCS#8 PEM 或 URL-safe base64可直接用SQLD_AUTH_JWT_KEY传值--http-authSQLD_HTTP_AUTH无旧版 HTTP Basic 认证格式basic:$PARAM$PARAM为用户名:密码的 base64--extensions-path无无受信扩展目录须含trusted.lst否则扩展加载被禁用--max-log-sizeSQLD_MAX_LOG_SIZE200复制日志最大体积MB--max-response-sizeSQLD_MAX_RESPONSE_SIZE10MB单次响应最大体积--max-total-response-sizeSQLD_MAX_TOTAL_RESPONSE_SIZE32MB全部响应累计最大体积--checkpoint-interval-sSQLD_CHECKPOINT_INTERVAL_S无默认 1 小时WAL checkpoint 调用间隔秒--enable-namespaces无关闭启用命名空间默认全部请求落默认命名空间default--encryption-keySQLD_ENCRYPTION_KEY无静态数据加密密钥需encryption特性--max-concurrent-connectionsSQLD_MAX_CONCURRENT_CONNECTIONS128最大并发连接数--max-concurrent-requestsSQLD_MAX_CONCURRENT_REQUESTS128最大并发请求数--idle-shutdown-timeout-sSQLD_IDLE_SHUTDOWN_TIMEOUT_S无空闲多少秒后自动关闭默认不自动关闭--heartbeat-urlSQLD_HEARTBEAT_URL无心跳 POST 上报地址默认不发心跳--enable-bottomless-replicationSQLD_ENABLE_BOTTOMLESS_REPLICATION关闭启用 bottomless S3 复制备份--no-welcome无关闭关闭欢迎信息--disable-metricsLIBSQL_DISABLE_METRICS关闭关闭 Prometheus 指标采集注上表为当前仓库 libsql-server/src/main.rs 中定义参数的非完全列举完整列表以sqld --help输出为准。三种运行模式从 print_welcome_message 的实现可以看到 sqld 根据两个关键参数组合出三种运行模式standalone单机模式--grpc-listen-addr与--primary-grpc-url均未设置——默认行为独立服务primary主节点仅设置--grpc-listen-addr——开放节点间 gRPC 端口接收副本写入/同步replica副本节点仅设置--primary-grpc-url——连接 primary 进行复制本地只读。优雅停机sqld 在收到 SIGINT 或 SIGTERM 信号后会触发优雅停机见 shutdown_signal 与build_server中的信号处理逻辑默认停机超时 30 秒可通过--shutdown-timeout调整。容器内的角色编排SQLD_NODE容器镜像默认命令为/bin/sqld实际入口是 docker-wrapper.sh docker-entrypoint.sh 的组合前者确保数据目录存在并切换为sqld用户执行后者根据环境变量把容器“翻译”成 sqld 的 CLI 参数SQLD_NODE取值primary默认、replica、standaloneSQLD_DB_PATH容器内数据库路径默认iku.dbSQLD_HTTP_LISTEN_ADDR容器内 HTTP 监听地址默认0.0.0.0:8080SQLD_GRPC_LISTEN_ADDR仅 primary 模式生效默认0.0.0.0:5001SQLD_PRIMARY_URL仅 replica 模式生效指向 primary 的 gRPC 地址。因此在容器环境下无需手写 CLI 参数只需设置SQLD_NODE及对应变量即可声明节点角色。读写分离编排示例仓库提供了开箱即用的读写分离编排docker-compose/docker-compose.yml 定义了三个服务writer以SQLD_NODEprimary运行开放 5001 端口用于副本同步reader以SQLD_NODEreplica运行通过SQLD_PRIMARY_URLhttp://writer:5001指向主节点监听0.0.0.0:8080nginx作为反向代理对外暴露 8080HTTP 查询入口与 6001 端口按 nginx.conf 规则在读写节点间分发流量。使用docker compose up即可拉起一整套读写分离环境适合作为理解 sqld 复制能力的起点复制协议细节可参考 libsql-replication 与 docs/DESIGN.md。故障排查与注意事项构建依赖缺失源码/Docker 构建需要libclang-dev、clang、protobuf-compiler、libssl-dev、pkg-config、cmake、tcl等系统包参考 Dockerfile。本地 Rust 构建失败时优先确认这些依赖已安装。工具链版本请确保 rustup 按 rust-toolchain.toml 自动切换到1.85.0通道否则可能出现依赖编译失败。端口冲突默认 8080 被占用时用--http-listen-addr或SQLD_HTTP_LISTEN_ADDR更换端口。数据持久化Docker 方式运行务必挂载卷到/var/lib/sqld否则容器删除后数据丢失本地二进制方式默认数据在./data.sqld。扩展加载如需加载 SQLite 扩展须使用--extensions-path指向包含trusted.lst每行sha256 文件名的目录sqld 启动时会逐一校验 SHA256 后才加载校验逻辑见 config.rs 的 validate_extensions。S3 备份bottomless以--enable-bottomless-replication启动后可把数据库持续备份到 S3 兼容存储相关配置见 libsql-server/README.md 与 bottomless/ 子项目。小结从直接运行到容器编排sqld 提供了从开发到生产的完整部署路径本地开发可用预编译二进制或cargo build标准化交付可用 Homebrew 或 Docker规模化部署可借助SQLD_NODE角色声明与 docker-compose 快速搭建读写分离。所有运行行为都收敛在 libsql-server/src/main.rs 的单一 CLI 定义中--help即是最好的配置手册。【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考