feat: add libsql

README.md

@@ -51,6 +51,7 @@ Compose Anything helps users quickly deploy various services by providing a set
 | [Langflow](./apps/langflow)                                   | latest                       |
 | [Langfuse](./apps/langfuse)                                   | 3.115.0                      |
 | [LibreOffice](./src/libreoffice)                              | latest                       |
+| [libSQL Server](./src/libsql)                                 | latest                       |
 | [LiteLLM](./src/litellm)                                      | main-stable                  |
 | [Logstash](./src/logstash)                                    | 8.16.1                       |
 | [MariaDB Galera Cluster](./src/mariadb-galera)                | 11.7.2                       |

README.zh.md

@@ -51,6 +51,7 @@ Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，
 | [Langflow](./apps/langflow)                                   | latest                       |
 | [Langfuse](./apps/langfuse)                                   | 3.115.0                      |
 | [LibreOffice](./src/libreoffice)                              | latest                       |
+| [libSQL Server](./src/libsql)                                 | latest                       |
 | [LiteLLM](./src/litellm)                                      | main-stable                  |
 | [Logstash](./src/logstash)                                    | 8.16.1                       |
 | [MariaDB Galera 集群](./src/mariadb-galera)                   | 11.7.2                       |

builds/debian-dind/.env.example

@@ -3,8 +3,8 @@
 # Timezone (default: UTC)
 TZ=UTC
 
-# Debian version (default: 13.2)
+# Debian version (default: 13.2-slim)
-DEBIAN_VERSION=13.2
+DEBIAN_VERSION=13.2-slim
 
 # Docker port override (default: 2375)
 DIND_PORT_OVERRIDE=2375

builds/debian-dind/Dockerfile

@@ -1,4 +1,4 @@
-ARG DEBIAN_VERSION=13.2
+ARG DEBIAN_VERSION=13.2-slim
 FROM debian:${DEBIAN_VERSION}
 
 # Install dependencies

builds/debian-dind/README.md

@@ -4,7 +4,7 @@ A Docker-in-Docker (DinD) service based on Debian, allowing you to run Docker in
 
 ## Features
 
-- Based on latest stable Debian (13.2)
+- Based on latest stable Debian (13.2-slim)
 - Out-of-the-box Docker daemon
 - Optional NVIDIA Container Toolkit for GPU support
 - Resource limits configured
@@ -37,8 +37,8 @@ A Docker-in-Docker (DinD) service based on Debian, allowing you to run Docker in
 Key environment variables (see `.env.example` for all options):
 
 | Variable                 | Description                         | Default     |
-| ------------------------ | ----------------------------------- | ------- |
+| ------------------------ | ----------------------------------- | ----------- |
-| `DEBIAN_VERSION`         | Debian base image version           | `13.2`  |
+| `DEBIAN_VERSION`         | Debian base image version           | `13.2-slim` |
 | `DIND_PORT_OVERRIDE`     | Host port for Docker daemon         | `2375`      |
 | `INSTALL_NVIDIA_TOOLKIT` | Install NVIDIA toolkit during build | `false`     |
 | `TZ`                     | Timezone                            | `UTC`       |
@@ -112,13 +112,13 @@ variables:
 
 When building the image manually:
 
-- `DEBIAN_VERSION`: Debian base version (default: `13.2`)
+- `DEBIAN_VERSION`: Debian base version (default: `13.2-slim`)
 - `INSTALL_NVIDIA_TOOLKIT`: Install NVIDIA toolkit (default: `false`)
 
 Example:
 
 ```bash
-docker build --build-arg DEBIAN_VERSION=13.2 --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu .
+docker build --build-arg DEBIAN_VERSION=13.2-slim --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu .
 ```
 
 ## License

builds/debian-dind/README.zh.md

@@ -4,7 +4,7 @@
 
 ## 特性
 
-- 基于最新稳定版 Debian（13.2）
+- 基于最新稳定版 Debian（13.2-slim）
 - 开箱即用的 Docker 守护进程
 - 可选的 NVIDIA Container Toolkit，支持 GPU
 - 配置了资源限制
@@ -37,8 +37,8 @@
 主要环境变量（查看 `.env.example` 了解所有选项）：
 
 | 变量                     | 说明                      | 默认值      |
-| ------------------------ | ------------------------- | ------- |
+| ------------------------ | ------------------------- | ----------- |
-| `DEBIAN_VERSION`         | Debian 基础镜像版本       | `13.2`  |
+| `DEBIAN_VERSION`         | Debian 基础镜像版本       | `13.2-slim` |
 | `DIND_PORT_OVERRIDE`     | Docker 守护进程的主机端口 | `2375`      |
 | `INSTALL_NVIDIA_TOOLKIT` | 构建时安装 NVIDIA 工具包  | `false`     |
 | `TZ`                     | 时区                      | `UTC`       |
@@ -112,13 +112,13 @@ variables:
 
 手动构建镜像时：
 
-- `DEBIAN_VERSION`：Debian 基础版本（默认：`13.2`）
+- `DEBIAN_VERSION`：Debian 基础版本（默认：`13.2-slim`）
 - `INSTALL_NVIDIA_TOOLKIT`：安装 NVIDIA 工具包（默认：`false`）
 
 示例：
 
 ```bash
-docker build --build-arg DEBIAN_VERSION=13.2 --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu .
+docker build --build-arg DEBIAN_VERSION=13.2-slim --build-arg INSTALL_NVIDIA_TOOLKIT=true -t debian-dind-gpu .
 ```
 
 ## 许可证

builds/debian-dind/docker-compose.yaml

@@ -17,13 +17,13 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2}
+        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim}
         - INSTALL_NVIDIA_TOOLKIT=${INSTALL_NVIDIA_TOOLKIT:-false}
     privileged: true
     ports:
       - "${DIND_PORT_OVERRIDE:-2375}:2375"
     volumes:
-      - dind-data:/var/lib/docker
+      - dind_data:/var/lib/docker
     environment:
       - TZ=${TZ:-UTC}
       - DOCKER_TLS_CERTDIR=${DOCKER_TLS_CERTDIR:-}
@@ -52,13 +52,13 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2}
+        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim}
         - INSTALL_NVIDIA_TOOLKIT=true
     privileged: true
     ports:
       - "${DIND_PORT_OVERRIDE:-2375}:2375"
     volumes:
-      - dind-gpu-data:/var/lib/docker
+      - dind_gpu_data:/var/lib/docker
     environment:
       - TZ=${TZ:-UTC}
       - DOCKER_TLS_CERTDIR=${DOCKER_TLS_CERTDIR:-}
@@ -86,5 +86,5 @@ services:
       - gpu
 
 volumes:
-  dind-data:
+  dind_data:
-  dind-gpu-data:
+  dind_gpu_data:

builds/kata-inside-dind/.env.example

@@ -2,7 +2,7 @@
 # GLOBAL_REGISTRY=registry.example.com/
 
 # Debian Version
-DEBIAN_VERSION=13.2
+DEBIAN_VERSION=13.2-slim
 
 # Kata Containers Version
 KATA_VERSION=3.24.0

builds/kata-inside-dind/Dockerfile

@@ -1,4 +1,4 @@
-ARG DEBIAN_VERSION=13.2
+ARG DEBIAN_VERSION=13.2-slim
 FROM debian:${DEBIAN_VERSION}
 
 # Install dependencies
@@ -57,7 +57,8 @@ RUN if [ "${ARCH}" = "amd64" ]; then ARCH="x86_64"; fi \
     && curl -fsSL https://github.com/firecracker-microvm/firecracker/releases/download/v${FIRECRACKER_VERSION}/firecracker-v${FIRECRACKER_VERSION}-${ARCH}.tgz -o firecracker.tgz \
     && tar -xzf firecracker.tgz \
     && mv release-v${FIRECRACKER_VERSION}-${ARCH}/firecracker-v${FIRECRACKER_VERSION}-${ARCH} /usr/local/bin/firecracker \
-    && chmod +x /usr/local/bin/firecracker \
+    && mv release-v${FIRECRACKER_VERSION}-${ARCH}/jailer-v${FIRECRACKER_VERSION}-${ARCH} /usr/local/bin/jailer \
+    && chmod +x /usr/local/bin/firecracker /usr/local/bin/jailer \
     && rm -rf release-v${FIRECRACKER_VERSION}-${ARCH} firecracker.tgz
 
 # Set up dind

builds/kata-inside-dind/README.md

@@ -85,8 +85,8 @@ cat /sys/module/kvm_intel/parameters/nested
 ### Environment Variables
 
 | Variable                       | Default     | Description                                   |
-| ------------------------------ | -------- | --------------------------------------------- |
+| ------------------------------ | ----------- | --------------------------------------------- |
-| `DEBIAN_VERSION`               | `13.2`   | Base Debian version                           |
+| `DEBIAN_VERSION`               | `13.2-slim` | Base Debian version                           |
 | `KATA_VERSION`                 | `3.24.0`    | Kata Containers version                       |
 | `FIRECRACKER_VERSION`          | `1.10.1`    | Version of Firecracker VMM to install         |
 | `KATA_DIND_VERSION`            | `0.2.0`     | Built image version tag                       |

builds/kata-inside-dind/README.zh.md

@@ -85,8 +85,8 @@ cat /sys/module/kvm_intel/parameters/nested
 ### 环境变量
 
 | 变量                           | 默认值      | 说明                                      |
-| ------------------------------ | -------- | ----------------------------------------- |
+| ------------------------------ | ----------- | ----------------------------------------- |
-| `DEBIAN_VERSION`               | `13.2`   | 基础 Debian 版本                          |
+| `DEBIAN_VERSION`               | `13.2-slim` | 基础 Debian 版本                          |
 | `KATA_VERSION`                 | `3.24.0`    | Kata Containers 版本                      |
 | `FIRECRACKER_VERSION`          | `1.10.1`    | 要安装的 Firecracker VMM 版本             |
 | `KATA_DIND_VERSION`            | `0.2.0`     | 构建的镜像版本标签                        |

builds/kata-inside-dind/docker-compose.yaml

@@ -18,7 +18,7 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
-        DEBIAN_VERSION: ${DEBIAN_VERSION:-13.2}
+        DEBIAN_VERSION: ${DEBIAN_VERSION:-13.2-slim}
         KATA_VERSION: ${KATA_VERSION:-3.24.0}
         FIRECRACKER_VERSION: ${FIRECRACKER_VERSION:-1.14.0}
     privileged: true

builds/kata-inside-dind/dockerd-entrypoint.sh

@@ -78,6 +78,15 @@ if [ -f /etc/kata-containers/configuration-fc.toml ] && [ -x /usr/local/bin/fire
             sed -i 's|path = ".*firecracker"|path = "/usr/local/bin/firecracker"|g' /etc/kata-containers/configuration-fc.toml || true
         fi
     fi
+
+    # Update jailer path if available
+    if [ -x /usr/local/bin/jailer ]; then
+        if ! grep -q "jailer_path = \"/usr/local/bin/jailer\"" /etc/kata-containers/configuration-fc.toml 2>/dev/null; then
+             if [ -w /etc/kata-containers/configuration-fc.toml ]; then
+                sed -i 's|jailer_path = ".*jailer"|jailer_path = "/usr/local/bin/jailer"|g' /etc/kata-containers/configuration-fc.toml || true
+             fi
+        fi
+    fi
 fi
 
 # Enable debug logging if requested

src/libsql/.env.example

@@ -0,0 +1,71 @@
+# Global registry prefix (optional, for custom registry mirrors)
+# GLOBAL_REGISTRY=
+
+# libSQL Server version
+LIBSQL_VERSION=latest
+
+# Platform architecture (linux/amd64 or linux/arm64)
+# Note: For ARM64 (Apple Silicon), use latest-arm tag or run via Rosetta with linux/amd64
+LIBSQL_PLATFORM=linux/amd64
+
+# Timezone
+TZ=UTC
+
+# ==================== Port Configuration ====================
+# HTTP/Hrana API port (client connections)
+LIBSQL_HTTP_PORT_OVERRIDE=8080
+
+# gRPC port (for replication between primary and replicas)
+LIBSQL_GRPC_PORT_OVERRIDE=5001
+
+# Replica HTTP port (only used when replica profile is enabled)
+LIBSQL_REPLICA_HTTP_PORT_OVERRIDE=8081
+
+# Replica gRPC port (only used when replica profile is enabled)
+LIBSQL_REPLICA_GRPC_PORT_OVERRIDE=5002
+
+# ==================== Node Configuration ====================
+# Node type: primary, replica, or standalone
+# - primary: Main database instance, accepts writes
+# - replica: Read-only replica, replicates from primary
+# - standalone: Single instance without replication
+LIBSQL_NODE=primary
+
+# Database file name (stored in /var/lib/sqld by default)
+LIBSQL_DB_PATH=iku.db
+
+# HTTP listen address (internal, usually no need to change)
+LIBSQL_HTTP_LISTEN_ADDR=0.0.0.0:8080
+
+# gRPC listen address (internal, usually no need to change)
+LIBSQL_GRPC_LISTEN_ADDR=0.0.0.0:5001
+
+# ==================== Replication Configuration ====================
+# Primary URL for replica instances (format: http://host:port or https://host:port)
+# Only required when LIBSQL_NODE=replica
+# Example for Docker Compose: http://libsql:5001
+LIBSQL_PRIMARY_URL=http://libsql:5001
+
+# ==================== Authentication (Optional) ====================
+# HTTP basic authentication (format: basic:base64(username:password))
+# Example: basic:dXNlcjpwYXNz (for user:pass)
+# LIBSQL_HTTP_AUTH=
+
+# Path to JWT key file for authentication (mounted into container)
+# LIBSQL_AUTH_JWT_KEY_FILE=
+
+# JWT key directly as environment variable (alternative to file)
+# LIBSQL_AUTH_JWT_KEY=
+
+# ==================== Resource Limits ====================
+# Primary instance resource limits
+LIBSQL_CPU_LIMIT=1.0
+LIBSQL_MEMORY_LIMIT=512M
+LIBSQL_CPU_RESERVATION=0.5
+LIBSQL_MEMORY_RESERVATION=256M
+
+# Replica instance resource limits (when replica profile is enabled)
+LIBSQL_REPLICA_CPU_LIMIT=1.0
+LIBSQL_REPLICA_MEMORY_LIMIT=512M
+LIBSQL_REPLICA_CPU_RESERVATION=0.5
+LIBSQL_REPLICA_MEMORY_RESERVATION=256M

src/libsql/README.md

@@ -0,0 +1,228 @@
+# libSQL Server
+
+[中文说明](README.zh.md)
+
+## Introduction
+
+libSQL is an open-source fork of SQLite optimized for edge deployments and serverless architectures. It offers SQLite compatibility with additional features like primary-replica replication, built-in HTTP/WebSocket API (Hrana protocol), and is designed for distributed database scenarios.
+
+**Key Features:**
+
+- 100% SQLite compatible
+- Primary-replica replication support
+- Built-in HTTP and WebSocket APIs
+- Edge-optimized for low latency
+- Open-source and extensible
+
+**Official Resources:**
+
+- GitHub: <https://github.com/tursodatabase/libsql>
+- Documentation: <https://github.com/tursodatabase/libsql/tree/main/docs>
+- Docker Hub: <https://github.com/tursodatabase/libsql/pkgs/container/libsql-server>
+
+## Quick Start
+
+### 1. Basic Usage (Primary Instance)
+
+```bash
+cd src/libsql
+docker compose up -d
+```
+
+The database will be available at:
+
+- HTTP/Hrana API: <http://localhost:8080>
+- gRPC (for replication): localhost:5001
+
+### 2. With Replica Instance
+
+To enable replication, start with the `replica` profile:
+
+```bash
+docker compose --profile replica up -d
+```
+
+This will start:
+
+- Primary instance on ports 8080 (HTTP) and 5001 (gRPC)
+- Replica instance on ports 8081 (HTTP) and 5002 (gRPC)
+
+### 3. Accessing the Database
+
+You can connect to libSQL using:
+
+**Via HTTP API:**
+
+```bash
+# Create a table
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}'
+
+# Insert data
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}'
+
+# Query data
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["SELECT * FROM users"]}'
+```
+
+**Via libSQL CLI (if installed):**
+
+```bash
+libsql client http://localhost:8080
+```
+
+## Configuration
+
+### Environment Variables
+
+Key environment variables (see `.env.example` for full list):
+
+| Variable                    | Default              | Description                                      |
+| --------------------------- | -------------------- | ------------------------------------------------ |
+| `LIBSQL_VERSION`            | `latest`             | libSQL server version                            |
+| `LIBSQL_HTTP_PORT_OVERRIDE` | `8080`               | HTTP API port                                    |
+| `LIBSQL_GRPC_PORT_OVERRIDE` | `5001`               | gRPC port for replication                        |
+| `LIBSQL_NODE`               | `primary`            | Node type: `primary`, `replica`, or `standalone` |
+| `LIBSQL_DB_PATH`            | `iku.db`             | Database file name                               |
+| `LIBSQL_PRIMARY_URL`        | `http://libsql:5001` | Primary URL for replica nodes                    |
+| `TZ`                        | `UTC`                | Timezone                                         |
+
+### Authentication (Optional)
+
+To enable authentication, uncomment and configure these variables:
+
+**HTTP Basic Auth:**
+
+```bash
+# Generate base64 encoded credentials
+echo -n "username:password" | base64
+# Result: dXNlcm5hbWU6cGFzc3dvcmQ=
+
+# Set in .env
+LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ=
+```
+
+**JWT Authentication:**
+
+```bash
+# Option 1: Using key file
+LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem
+
+# Option 2: Using key directly
+LIBSQL_AUTH_JWT_KEY=your-jwt-key-here
+```
+
+### Platform Support
+
+- **x86-64:** Use `LIBSQL_PLATFORM=linux/amd64` (default)
+- **ARM64 (Apple Silicon):**
+  - Use `LIBSQL_VERSION=latest-arm` for native ARM images
+  - Or use `LIBSQL_PLATFORM=linux/amd64` to run via Rosetta
+
+## Data Persistence
+
+Database files are stored in a Docker named volume:
+
+- Volume: `libsql_data`
+- Container path: `/var/lib/sqld`
+
+To backup your database:
+
+```bash
+# Copy database file from container
+docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db
+```
+
+## Resource Limits
+
+Default resource allocations per instance:
+
+- CPU: 0.5-1.0 cores
+- Memory: 256M-512M
+
+Adjust in `.env` file:
+
+```bash
+LIBSQL_CPU_LIMIT=2.0
+LIBSQL_MEMORY_LIMIT=1G
+```
+
+## Replication Architecture
+
+libSQL supports primary-replica replication:
+
+1. **Primary Instance:** Accepts reads and writes
+2. **Replica Instance(s):** Read-only, replicates from primary via gRPC
+
+To add a replica:
+
+```bash
+# Start with replica profile
+docker compose --profile replica up -d
+```
+
+Replicas connect to the primary using `LIBSQL_PRIMARY_URL` and stay synchronized automatically.
+
+## Common Operations
+
+### Check Server Health
+
+```bash
+curl http://localhost:8080/health
+```
+
+### View Logs
+
+```bash
+docker compose logs -f libsql
+```
+
+### Restart Service
+
+```bash
+docker compose restart libsql
+```
+
+### Stop and Remove
+
+```bash
+docker compose down
+# To remove volumes as well
+docker compose down -v
+```
+
+## Troubleshooting
+
+### Connection Refused
+
+- Verify the service is running: `docker compose ps`
+- Check logs: `docker compose logs libsql`
+- Ensure ports are not in use: `netstat -an | grep 8080`
+
+### Replica Not Syncing
+
+- Verify `LIBSQL_PRIMARY_URL` is correct
+- Check primary instance is healthy and accessible
+- Review replica logs for connection errors
+
+### Performance Issues
+
+- Increase resource limits in `.env`
+- Consider using SSD for volume storage
+- Enable query logging for optimization
+
+## Security Notes
+
+- **Default Setup:** No authentication enabled - suitable for development only
+- **Production:** Always enable authentication (HTTP Basic or JWT)
+- **Network:** Consider using Docker networks or reverse proxy for external access
+- **Secrets:** Never commit `.env` with credentials to version control
+
+## License
+
+libSQL is licensed under the MIT License. See the [official repository](https://github.com/tursodatabase/libsql) for details.

src/libsql/README.zh.md

@@ -0,0 +1,228 @@
+# libSQL Server
+
+[English Documentation](README.md)
+
+## 简介
+
+libSQL 是 SQLite 的开源分支，针对边缘部署和无服务器架构进行了优化。它提供与 SQLite 的完全兼容性，同时增加了主从复制、内置 HTTP/WebSocket API（Hrana 协议）等功能，专为分布式数据库场景设计。
+
+**核心特性：**
+
+- 100% SQLite 兼容
+- 支持主从复制
+- 内置 HTTP 和 WebSocket API
+- 边缘优化，低延迟
+- 开源可扩展
+
+**官方资源：**
+
+- GitHub：<https://github.com/tursodatabase/libsql>
+- 文档：<https://github.com/tursodatabase/libsql/tree/main/docs>
+- Docker Hub：<https://github.com/tursodatabase/libsql/pkgs/container/libsql-server>
+
+## 快速开始
+
+### 1. 基本用法（主实例）
+
+```bash
+cd src/libsql
+docker compose up -d
+```
+
+数据库将在以下端口可用：
+
+- HTTP/Hrana API：<http://localhost:8080>
+- gRPC（用于复制）：localhost:5001
+
+### 2. 启用副本实例
+
+要启用复制，使用 `replica` profile 启动：
+
+```bash
+docker compose --profile replica up -d
+```
+
+这将启动：
+
+- 主实例，端口 8080（HTTP）和 5001（gRPC）
+- 副本实例，端口 8081（HTTP）和 5002（gRPC）
+
+### 3. 访问数据库
+
+可以通过以下方式连接到 libSQL：
+
+**通过 HTTP API：**
+
+```bash
+# 创建表
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"]}'
+
+# 插入数据
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["INSERT INTO users (name) VALUES ('\''Alice'\'')"]}'
+
+# 查询数据
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"statements": ["SELECT * FROM users"]}'
+```
+
+**通过 libSQL CLI（如已安装）：**
+
+```bash
+libsql client http://localhost:8080
+```
+
+## 配置说明
+
+### 环境变量
+
+主要环境变量（完整列表请参见 `.env.example`）：
+
+| 变量名                      | 默认值               | 说明                                           |
+| --------------------------- | -------------------- | ---------------------------------------------- |
+| `LIBSQL_VERSION`            | `latest`             | libSQL 服务器版本                              |
+| `LIBSQL_HTTP_PORT_OVERRIDE` | `8080`               | HTTP API 端口                                  |
+| `LIBSQL_GRPC_PORT_OVERRIDE` | `5001`               | gRPC 复制端口                                  |
+| `LIBSQL_NODE`               | `primary`            | 节点类型：`primary`、`replica` 或 `standalone` |
+| `LIBSQL_DB_PATH`            | `iku.db`             | 数据库文件名                                   |
+| `LIBSQL_PRIMARY_URL`        | `http://libsql:5001` | 副本节点的主节点 URL                           |
+| `TZ`                        | `UTC`                | 时区                                           |
+
+### 身份验证（可选）
+
+要启用身份验证，请取消注释并配置以下变量：
+
+**HTTP 基本认证：**
+
+```bash
+# 生成 base64 编码的凭据
+echo -n "username:password" | base64
+# 结果：dXNlcm5hbWU6cGFzc3dvcmQ=
+
+# 在 .env 中设置
+LIBSQL_HTTP_AUTH=basic:dXNlcm5hbWU6cGFzc3dvcmQ=
+```
+
+**JWT 认证：**
+
+```bash
+# 方式 1：使用密钥文件
+LIBSQL_AUTH_JWT_KEY_FILE=/path/to/jwt-key.pem
+
+# 方式 2：直接使用密钥
+LIBSQL_AUTH_JWT_KEY=your-jwt-key-here
+```
+
+### 平台支持
+
+- **x86-64：** 使用 `LIBSQL_PLATFORM=linux/amd64`（默认）
+- **ARM64（Apple Silicon）：**
+  - 使用 `LIBSQL_VERSION=latest-arm` 获取原生 ARM 镜像
+  - 或使用 `LIBSQL_PLATFORM=linux/amd64` 通过 Rosetta 运行
+
+## 数据持久化
+
+数据库文件存储在 Docker 命名卷中：
+
+- 卷名：`libsql_data`
+- 容器路径：`/var/lib/sqld`
+
+备份数据库：
+
+```bash
+# 从容器复制数据库文件
+docker compose cp libsql:/var/lib/sqld/iku.db ./backup.db
+```
+
+## 资源限制
+
+每个实例的默认资源分配：
+
+- CPU：0.5-1.0 核心
+- 内存：256M-512M
+
+在 `.env` 文件中调整：
+
+```bash
+LIBSQL_CPU_LIMIT=2.0
+LIBSQL_MEMORY_LIMIT=1G
+```
+
+## 复制架构
+
+libSQL 支持主从复制：
+
+1. **主实例：** 接受读写操作
+2. **副本实例：** 只读，通过 gRPC 从主实例复制
+
+添加副本：
+
+```bash
+# 使用 replica profile 启动
+docker compose --profile replica up -d
+```
+
+副本使用 `LIBSQL_PRIMARY_URL` 连接到主实例，并自动保持同步。
+
+## 常用操作
+
+### 检查服务器健康状态
+
+```bash
+curl http://localhost:8080/health
+```
+
+### 查看日志
+
+```bash
+docker compose logs -f libsql
+```
+
+### 重启服务
+
+```bash
+docker compose restart libsql
+```
+
+### 停止并删除
+
+```bash
+docker compose down
+# 同时删除卷
+docker compose down -v
+```
+
+## 故障排查
+
+### 连接被拒绝
+
+- 验证服务正在运行：`docker compose ps`
+- 检查日志：`docker compose logs libsql`
+- 确保端口未被占用：`netstat -an | grep 8080`
+
+### 副本未同步
+
+- 验证 `LIBSQL_PRIMARY_URL` 是否正确
+- 检查主实例是否健康且可访问
+- 查看副本日志以查找连接错误
+
+### 性能问题
+
+- 在 `.env` 中增加资源限制
+- 考虑为卷存储使用 SSD
+- 启用查询日志以进行优化
+
+## 安全注意事项
+
+- **默认设置：** 未启用身份验证 - 仅适用于开发环境
+- **生产环境：** 始终启用身份验证（HTTP Basic 或 JWT）
+- **网络：** 考虑使用 Docker 网络或反向代理进行外部访问
+- **密钥：** 切勿将包含凭据的 `.env` 提交到版本控制
+
+## 许可证
+
+libSQL 采用 MIT 许可证。详情请参见[官方仓库](https://github.com/tursodatabase/libsql)。

src/libsql/docker-compose.yaml

@@ -0,0 +1,87 @@
+# Docker Compose configuration for libSQL Server
+# libSQL is an open-source fork of SQLite optimized for edge deployments
+# Supports primary-replica replication and serverless architectures
+
+x-defaults: &defaults
+  restart: unless-stopped
+  logging:
+    driver: json-file
+    options:
+      max-size: 100m
+      max-file: "3"
+
+services:
+  libsql:
+    <<: *defaults
+    image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest}
+    platform: ${LIBSQL_PLATFORM:-linux/amd64}
+    ports:
+      - "${LIBSQL_HTTP_PORT_OVERRIDE:-8080}:8080"  # HTTP/Hrana API port
+      - "${LIBSQL_GRPC_PORT_OVERRIDE:-5001}:5001"  # gRPC port for replication
+    volumes:
+      - libsql_data:/var/lib/sqld
+    environment:
+      - TZ=${TZ:-UTC}
+      - SQLD_NODE=${LIBSQL_NODE:-primary}
+      - SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db}
+      - SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080}
+      - SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001}
+      # Authentication (optional, uncomment to enable)
+      # - SQLD_HTTP_AUTH=${LIBSQL_HTTP_AUTH:-}
+      # - SQLD_AUTH_JWT_KEY_FILE=${LIBSQL_AUTH_JWT_KEY_FILE:-}
+      # - SQLD_AUTH_JWT_KEY=${LIBSQL_AUTH_JWT_KEY:-}
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    deploy:
+      resources:
+        limits:
+          cpus: ${LIBSQL_CPU_LIMIT:-1.0}
+          memory: ${LIBSQL_MEMORY_LIMIT:-512M}
+        reservations:
+          cpus: ${LIBSQL_CPU_RESERVATION:-0.5}
+          memory: ${LIBSQL_MEMORY_RESERVATION:-256M}
+
+  # Replica instance (optional, use with profile)
+  libsql-replica:
+    <<: *defaults
+    image: ${GHCR_IO_REGISTRY:-ghcr.io}/tursodatabase/libsql-server:${LIBSQL_VERSION:-latest}
+    platform: ${LIBSQL_PLATFORM:-linux/amd64}
+    profiles:
+      - replica
+    ports:
+      - "${LIBSQL_REPLICA_HTTP_PORT_OVERRIDE:-8081}:8080"
+      - "${LIBSQL_REPLICA_GRPC_PORT_OVERRIDE:-5002}:5001"
+    volumes:
+      - libsql_replica_data:/var/lib/sqld
+    environment:
+      - TZ=${TZ:-UTC}
+      - SQLD_NODE=replica
+      - SQLD_PRIMARY_URL=${LIBSQL_PRIMARY_URL:-http://libsql:5001}
+      - SQLD_DB_PATH=${LIBSQL_DB_PATH:-iku.db}
+      - SQLD_HTTP_LISTEN_ADDR=${LIBSQL_HTTP_LISTEN_ADDR:-0.0.0.0:8080}
+      - SQLD_GRPC_LISTEN_ADDR=${LIBSQL_GRPC_LISTEN_ADDR:-0.0.0.0:5001}
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    depends_on:
+      libsql:
+        condition: service_healthy
+    deploy:
+      resources:
+        limits:
+          cpus: ${LIBSQL_REPLICA_CPU_LIMIT:-1.0}
+          memory: ${LIBSQL_REPLICA_MEMORY_LIMIT:-512M}
+        reservations:
+          cpus: ${LIBSQL_REPLICA_CPU_RESERVATION:-0.5}
+          memory: ${LIBSQL_REPLICA_MEMORY_RESERVATION:-256M}
+
+volumes:
+  libsql_data:
+  libsql_replica_data: