feat: add libsql

2025-12-29 18:05:34 +08:00
parent 4c7b3afc10
commit 953bb146ba
18 changed files with 1128 additions and 502 deletions
--- a/README.md
+++ b/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                       |
--- a/README.zh.md
+++ b/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                       |
--- a/builds/debian-dind/.env.example
+++ b/builds/debian-dind/.env.example
@@ -3,8 +3,8 @@
 # Timezone (default: UTC)
 TZ=UTC

-# Debian version (default: 13.2)
-DEBIAN_VERSION=13.2
+# Debian version (default: 13.2-slim)
+DEBIAN_VERSION=13.2-slim

 # Docker port override (default: 2375)
 DIND_PORT_OVERRIDE=2375
--- a/builds/debian-dind/Dockerfile
+++ b/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
--- a/builds/debian-dind/README.md
+++ b/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
@@ -36,14 +36,14 @@ 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`  |
-| `DIND_PORT_OVERRIDE`     | Host port for Docker daemon         | `2375`  |
-| `INSTALL_NVIDIA_TOOLKIT` | Install NVIDIA toolkit during build | `false` |
-| `TZ`                     | Timezone                            | `UTC`   |
-| `DIND_CPU_LIMIT`         | CPU limit                           | `2.0`   |
-| `DIND_MEMORY_LIMIT`      | Memory limit                        | `4G`    |
+| Variable                 | Description                         | Default     |
+| ------------------------ | ----------------------------------- | ----------- |
+| `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`       |
+| `DIND_CPU_LIMIT`         | CPU limit                           | `2.0`       |
+| `DIND_MEMORY_LIMIT`      | Memory limit                        | `4G`        |

 ## GPU Support

@@ -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
--- a/builds/debian-dind/README.zh.md
+++ b/builds/debian-dind/README.zh.md
@@ -4,7 +4,7 @@

 ## 特性

- 基于最新稳定版 Debian（13.2）
+- 基于最新稳定版 Debian（13.2-slim）
 - 开箱即用的 Docker 守护进程
 - 可选的 NVIDIA Container Toolkit，支持 GPU
 - 配置了资源限制
@@ -36,14 +36,14 @@

 主要环境变量（查看 `.env.example` 了解所有选项）：

-| 变量                     | 说明                      | 默认值  |
-| ------------------------ | ------------------------- | ------- |
-| `DEBIAN_VERSION`         | Debian 基础镜像版本       | `13.2`  |
-| `DIND_PORT_OVERRIDE`     | Docker 守护进程的主机端口 | `2375`  |
-| `INSTALL_NVIDIA_TOOLKIT` | 构建时安装 NVIDIA 工具包  | `false` |
-| `TZ`                     | 时区                      | `UTC`   |
-| `DIND_CPU_LIMIT`         | CPU 限制                  | `2.0`   |
-| `DIND_MEMORY_LIMIT`      | 内存限制                  | `4G`    |
+| 变量                     | 说明                      | 默认值      |
+| ------------------------ | ------------------------- | ----------- |
+| `DEBIAN_VERSION`         | Debian 基础镜像版本       | `13.2-slim` |
+| `DIND_PORT_OVERRIDE`     | Docker 守护进程的主机端口 | `2375`      |
+| `INSTALL_NVIDIA_TOOLKIT` | 构建时安装 NVIDIA 工具包  | `false`     |
+| `TZ`                     | 时区                      | `UTC`       |
+| `DIND_CPU_LIMIT`         | CPU 限制                  | `2.0`       |
+| `DIND_MEMORY_LIMIT`      | 内存限制                  | `4G`        |

 ## GPU 支持

@@ -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 .
 ```

 ## 许可证
--- a/builds/debian-dind/docker-compose.yaml
+++ b/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-gpu-data:
+  dind_data:
+  dind_gpu_data:
--- a/builds/debian-dind/dockerd-entrypoint.sh
+++ b/builds/debian-dind/dockerd-entrypoint.sh
@@ -5,46 +5,46 @@ set -e
 # https://github.com/docker-library/docker/blob/master/24/dind/dockerd-entrypoint.sh

 if [ -z "$DOCKER_HOST" ]; then
-	case "$1" in
-		dockerd*)
-			# If we're running dockerd, we need to make sure we have cgroups mounted
-			if [ ! -d /sys/fs/cgroup ]; then
-				mkdir -p /sys/fs/cgroup
-			fi
-			if ! mountpoint -q /sys/fs/cgroup; then
-				mount -t tmpfs -o uid=0,gid=0,mode=0755 cgroup /sys/fs/cgroup
-			fi
+  case "$1" in
+    dockerd*)
+      # If we're running dockerd, we need to make sure we have cgroups mounted
+      if [ ! -d /sys/fs/cgroup ]; then
+        mkdir -p /sys/fs/cgroup
+      fi
+      if ! mountpoint -q /sys/fs/cgroup; then
+        mount -t tmpfs -o uid=0,gid=0,mode=0755 cgroup /sys/fs/cgroup
+      fi

-			# Mount cgroup v2 if available and not mounted
-			if [ -e /sys/fs/cgroup/cgroup.controllers ] && ! mountpoint -q /sys/fs/cgroup; then
-				mount -t cgroup2 -o nsdelegate cgroup2 /sys/fs/cgroup
-			fi
+      # Mount cgroup v2 if available and not mounted
+      if [ -e /sys/fs/cgroup/cgroup.controllers ] && ! mountpoint -q /sys/fs/cgroup; then
+        mount -t cgroup2 -o nsdelegate cgroup2 /sys/fs/cgroup
+      fi

-			# If /sys/fs/cgroup is not a cgroup2 mount, we might need to mount cgroup v1 hierarchies
-			if ! mountpoint -q /sys/fs/cgroup || [ "$(stat -f -c %T /sys/fs/cgroup)" != "cgroup2fs" ]; then
-				if [ -d /sys/fs/cgroup/cgroup.controllers ]; then
-					# It is cgroup2 but maybe not mounted as such?
-					# Actually if it exists, it's likely v2.
-					:
-				else
-					# cgroup v1
-					for subsystem in $(awk '/^[^#]/ { print $1 }' /proc/cgroups); do
-						mkdir -p "/sys/fs/cgroup/$subsystem"
-						if ! mountpoint -q "/sys/fs/cgroup/$subsystem"; then
-							mount -t cgroup -o "$subsystem" cgroup "/sys/fs/cgroup/$subsystem"
-						fi
-					done
-				fi
-			fi
-			;;
-	esac
+      # If /sys/fs/cgroup is not a cgroup2 mount, we might need to mount cgroup v1 hierarchies
+      if ! mountpoint -q /sys/fs/cgroup || [ "$(stat -f -c %T /sys/fs/cgroup)" != "cgroup2fs" ]; then
+        if [ -d /sys/fs/cgroup/cgroup.controllers ]; then
+          # It is cgroup2 but maybe not mounted as such?
+          # Actually if it exists, it's likely v2.
+          :
+        else
+          # cgroup v1
+          for subsystem in $(awk '/^[^#]/ { print $1 }' /proc/cgroups); do
+            mkdir -p "/sys/fs/cgroup/$subsystem"
+            if ! mountpoint -q "/sys/fs/cgroup/$subsystem"; then
+              mount -t cgroup -o "$subsystem" cgroup "/sys/fs/cgroup/$subsystem"
+            fi
+          done
+        fi
+      fi
+      ;;
+  esac
 fi

 if [ "$1" = 'dockerd' ] || [ "${1#-}" != "$1" ]; then
-	# if the first argument is "dockerd" or a flag (starts with -)
-	if [ "${1#-}" != "$1" ]; then
-		set -- dockerd "$@"
-	fi
+  # if the first argument is "dockerd" or a flag (starts with -)
+  if [ "${1#-}" != "$1" ]; then
+    set -- dockerd "$@"
+  fi

    # Explicitly use iptables-legacy if available, as it is often more stable for DinD
    if command -v update-alternatives >/dev/null; then
--- a/builds/kata-inside-dind/.env.example
+++ b/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
--- a/builds/kata-inside-dind/Dockerfile
+++ b/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
--- a/builds/kata-inside-dind/README.md
+++ b/builds/kata-inside-dind/README.md
@@ -84,18 +84,18 @@ cat /sys/module/kvm_intel/parameters/nested

 ### Environment Variables

-| Variable                       | Default  | Description                                   |
-| ------------------------------ | -------- | --------------------------------------------- |
-| `DEBIAN_VERSION`               | `13.2`   | 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                       |
-| `TZ`                           | `UTC`    | Timezone for the container                    |
-| `KATA_LOGGING_LEVEL`           | `info`   | Kata logging level (debug, info, warn, error) |
-| `KATA_DIND_CPU_LIMIT`          | `2.00`   | CPU limit in cores                            |
-| `KATA_DIND_MEMORY_LIMIT`       | `4G`     | Memory limit                                  |
-| `KATA_DIND_CPU_RESERVATION`    | `0.50`   | CPU reservation in cores                      |
-| `KATA_DIND_MEMORY_RESERVATION` | `1G`     | Memory reservation                            |
+| Variable                       | Default     | Description                                   |
+| ------------------------------ | ----------- | --------------------------------------------- |
+| `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                       |
+| `TZ`                           | `UTC`       | Timezone for the container                    |
+| `KATA_LOGGING_LEVEL`           | `info`      | Kata logging level (debug, info, warn, error) |
+| `KATA_DIND_CPU_LIMIT`          | `2.00`      | CPU limit in cores                            |
+| `KATA_DIND_MEMORY_LIMIT`       | `4G`        | Memory limit                                  |
+| `KATA_DIND_CPU_RESERVATION`    | `0.50`      | CPU reservation in cores                      |
+| `KATA_DIND_MEMORY_RESERVATION` | `1G`        | Memory reservation                            |

 ## Usage Examples

--- a/builds/kata-inside-dind/README.zh.md
+++ b/builds/kata-inside-dind/README.zh.md
@@ -84,18 +84,18 @@ cat /sys/module/kvm_intel/parameters/nested

 ### 环境变量

-| 变量                           | 默认值   | 说明                                      |
-| ------------------------------ | -------- | ----------------------------------------- |
-| `DEBIAN_VERSION`               | `13.2`   | 基础 Debian 版本                          |
-| `KATA_VERSION`                 | `3.24.0` | Kata Containers 版本                      |
-| `FIRECRACKER_VERSION`          | `1.10.1` | 要安装的 Firecracker VMM 版本             |
-| `KATA_DIND_VERSION`            | `0.2.0`  | 构建的镜像版本标签                        |
-| `TZ`                           | `UTC`    | 容器的时区                                |
-| `KATA_LOGGING_LEVEL`           | `info`   | Kata 日志级别（debug、info、warn、error） |
-| `KATA_DIND_CPU_LIMIT`          | `2.00`   | CPU 限制（核心数）                        |
-| `KATA_DIND_MEMORY_LIMIT`       | `4G`     | 内存限制                                  |
-| `KATA_DIND_CPU_RESERVATION`    | `0.50`   | CPU 预留（核心数）                        |
-| `KATA_DIND_MEMORY_RESERVATION` | `1G`     | 内存预留                                  |
+| 变量                           | 默认值      | 说明                                      |
+| ------------------------------ | ----------- | ----------------------------------------- |
+| `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`     | 构建的镜像版本标签                        |
+| `TZ`                           | `UTC`       | 容器的时区                                |
+| `KATA_LOGGING_LEVEL`           | `info`      | Kata 日志级别（debug、info、warn、error） |
+| `KATA_DIND_CPU_LIMIT`          | `2.00`      | CPU 限制（核心数）                        |
+| `KATA_DIND_MEMORY_LIMIT`       | `4G`        | 内存限制                                  |
+| `KATA_DIND_CPU_RESERVATION`    | `0.50`      | CPU 预留（核心数）                        |
+| `KATA_DIND_MEMORY_RESERVATION` | `1G`        | 内存预留                                  |

 ## 使用示例

--- a/builds/kata-inside-dind/docker-compose.yaml
+++ b/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
--- a/builds/kata-inside-dind/dockerd-entrypoint.sh
+++ b/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
--- a/src/libsql/.env.example
+++ b/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
--- a/src/libsql/README.md
+++ b/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.
--- a/src/libsql/README.zh.md
+++ b/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)。
--- a/src/libsql/docker-compose.yaml
+++ b/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: