自托管 libSQL 服务器

sqld（SQL 守护进程）是由 Turso 开发的 libSQL 服务器模式。本指南将介绍如何通过 Docker 容器设置和配置 sqld 以用于 StudioCMS 项目。

通过官方文档^了解更多关于 sqld 的信息

先决条件

• Docker 和 Docker Compose^（可在服务器或本地运行）
• 已安装 OpenSSL^
• StudioCMS CLI（位于 StudioCMS 项目根目录）

本地测试时的最终文件结构示例：

• docker-compose.yml
• 文件夹data/

  • …
• 文件夹keys/

  • …
• 文件夹my-studiocms-project/

  • astro.config.mjs
  • studiocms.config.mjs
  • package.json
  • 文件夹src/

    • …

生成公私钥对

在 keys 目录中执行以下命令创建 PKCS#8 编码的 Ed25519 密钥对：

openssl genpkey -algorithm Ed25519 -out ./libsql.pem

提取公钥：

openssl pkey -in ./libsql.pem -pubout -out ./libsql.pub

这将生成用于 sqld 服务器的 PKCS#8 密钥对。

生成 JWT 令牌

进入 StudioCMS 项目目录并执行：

npm

npm run studiocms crypto gen-jwt "../keys/libsql.pem" -e 31556926

pnpm

pnpm run studiocms crypto gen-jwt "../keys/libsql.pem" -e 31556926

yarn

yarn run studiocms crypto gen-jwt "../keys/libsql.pem" -e 31556926

输出包含标准格式和 Base64URL 编码的 JWT 认证令牌，用于 libSQL 身份验证。该令牌有效期为 1 年！

更新 StudioCMS 的 .env 文件

ASTRO_DB_REMOTE_URL=http://localhost:8080 # 指向 Docker 服务器/本地系统
ASTRO_DB_APP_TOKEN= # 粘贴您的标准 JWT 认证令牌

配置 Docker 容器

在 StudioCMS 项目目录外创建 docker-compose.yml 文件。您有两种配置 libSQL 认证的方式：

公钥文件方式

services:
  libsql:
    image: ghcr.io/tursodatabase/libsql-server:latest
    platform: linux/amd64
    ports:
      - "8080:8080" # HTTP API 端口
      - "5001:5001" # gRPC 端口
    environment:
      - SQLD_NODE=primary # 主节点模式
      - SQLD_AUTH_JWT_KEY_FILE=/home/.ssh/libsql.pub # 公钥路径
    volumes:
      - ./data/libsql:/var/lib/sqld # 数据持久化
      - ./keys/libsql.pub:/home/.ssh/libsql.pub # 挂载公钥

JWT 令牌方式

services:
  libsql:
    image: ghcr.io/tursodatabase/libsql-server:latest
    platform: linux/amd64
    ports:
      - "8080:8080"
      - "5001:5001"
    environment:
      - SQLD_NODE=primary
      - SQLD_AUTH_JWT_KEY=粘贴您的Base64URL编码JWT令牌
    volumes:
      - ./data/libsql:/var/lib/sqld # 数据持久化

部署到 Coolify？

Coolify^ 用户：使用我们的 GitHub Gist^ 获取兼容 Coolify 的 Docker Compose 配置，可直接通过域名访问 libSQL 而无需 :8080 端口后缀。

启动服务

1. 启动 Docker 容器： 在基础目录（或服务器目录）执行：

   docker compose up -d

2. 同步数据库架构： 进入 StudioCMS 项目目录执行：

   npm

   npx astro db push --remote

   pnpm

   pnpm astro db push --remote

   yarn

   yarn astro db push --remote

3. 完成首次设置： 遵循新数据库的首次设置流程：

   • 参考入门指南

   :::note 注意 若非首次设置 StudioCMS 项目，需在 studiocms.config.mjs 中启用 dbStartPage 选项 :::

总结

如果你想为 StudioCMS 自托管 libSQL 数据库，sqld 是一个可行的选择。只要采用正确方法，部署和运行过程并不复杂。遵循本指南操作，你将为 StudioCMS 项目获得一个安全的 libSQL 服务器。