229 lines
5.5 KiB
Markdown
229 lines
5.5 KiB
Markdown
# 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)。
|