danieldeer/seriousdb · 上手攻略

仓库：danieldeer/seriousdb
链接：https://github.com/danieldeer/seriousdb
分类：基础设施 · 键值存储
作者：Tom
更新：2026-09-16

是什么

seriousdb 是一个极简的持久化键值存储（Persistent Key-Value Store），通过 HTTP API 暴露读写接口，数据以 JSON 格式保存在本地 .sdb 文件中。项目使用 Python + FastAPI 实现，代码量极小，架构刻意保持简单——没有独立数据库进程、没有客户端 SDK、没有复杂依赖，适合作为嵌入式配置存储、轻量状态持久化或原型阶段的数据管理方案。

⚠️ 重要约束：当前版本不协调并发写入，多进程并发访问存在数据竞争风险，不适合生产高并发场景。

解决什么问题

在小型工具或脚本中，需要一个持久化存储，但又不想引入 Redis、SQLite 等独立服务。seriousdb 的价值在于：

零运维：直接 pip install 或 uv sync 后 uv run run.py 起服务
HTTP 接口：任何语言均可通过 REST 调用，无需专用客户端
文件即存储：.sdb 是普通 JSON 文件，可用文本编辑器直接查看或修改
无守护进程：随用随启，不需要单独的后台进程

快速安装

git clone https://github.com/danieldeer/seriousdb.git
cd seriousdb
uv sync          # 安装依赖（需要 uv，https://github.com/astral-sh/uv）
uv run run.py    # 启动服务

服务启动后监听 http://0.0.0.0:8000，自动在运行目录创建空的 .sdb 文件（初始内容为 {"default": "default"}）。

也可用标准 pip：

pip install fastapi uvicorn
python -c "from seriousdb import app; import uvicorn; uvicorn.run(app, host='0.0.0.0', port=8000)"

⚠️ pip 安装方式未在官方文档明确说明，推荐使用上面的 uv sync 或直接参考 PyPI 页面（若已发布）。

核心用法

API 端点一览

方法	路径	说明
`PUT`	`/db?key=xxx&value=yyy`	存入或更新键值对
`GET`	`/db?key=xxx`	读取指定 key 的值
`HEAD`	`/db?key=xxx`	检查 key 是否存在（只返回 HTTP 头）
`GET`	`/db/all`	读取所有键值对
`DELETE`	`/db?key=xxx`	删除指定 key
`GET`	`/health`	服务就绪状态（`200`=就绪，`503`=未就绪）

所有端点详细文档见 docs/api.md。

常用命令示例

# 存数据
curl -X PUT "http://localhost:8000/db?key=name&value=Alice"

# 取数据
curl "http://localhost:8000/db?key=name"
# 返回: Alice

# 检查存在性
curl -I "http://localhost:8000/db?key=name"
# 存在返回 200，不存在返回 404

# 查看所有数据
curl "http://localhost:8000/db/all"
# 返回: {"default":"default","name":"Alice"}

# 删除
curl -X DELETE "http://localhost:8000/db?key=name"

# 健康检查
curl "http://localhost:8000/health"
# 返回: {"status":"ok"}

Python 调用示例

import requests

BASE = "http://localhost:8000"

# 写入
requests.put(f"{BASE}/db", params={"key": "name", "value": "Alice"})

# 读取
r = requests.get(f"{BASE}/db", params={"key": "name"})
print(r.text)  # Alice

# 全量读取
r = requests.get(f"{BASE}/db/all")
print(r.json())  # {"default": "default", "name": "Alice"}

交互式 API 文档

启动服务后，浏览器访问： - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc - OpenAPI Schema: http://localhost:8000/openapi.json

典型适用场景

本地工具配置存储：脚本或 CLI 工具需要持久化少量配置（API Key、用户偏好、计数器等）
轻量原型/概念验证：快速搭建物联网数据采集、小型监控系统，无需部署数据库服务
多语言环境共享状态：不同语言的项目通过 HTTP 读写同一份数据，无需为每种语言实现客户端库
小型静态网站数据管理：配合一个简单后台管理界面管理站点配置

坑与注意

⚠️ 并发写入不安全：每个 PUT 操作会完整读取 .sdb、修改一个 key、再完整写回。在多进程或多容器并发写入时存在数据竞争，可能导致数据丢失。不要在生产环境高并发场景使用。

⚠️ 文件路径绑定：.sdb 文件位于服务进程的工作目录，不同路径启动服务会读写不同的数据文件，导致数据隔离或丢失。部署时注意固定工作目录。

⚠️ 无访问控制：默认无认证机制，直接暴露在公网非常危险。若需安全访问，应在服务前加一层 Nginx/APISIX 认证或使用网络隔离。

⚠️ 不支持集群/分布式：数据存储在单机本地文件，无主从复制、无分片，不适合需要横向扩展的场景。

⚠️ 单次操作原子性但非事务性：每次 PUT 是原子的（要么全写要么全不写），但不支持批量操作或事务。

与同类对比

特性	seriousdb	Redis	SQLite	Dolt
部署复杂度	极低（单文件）	中（需守护进程）	低（嵌入式）	中（需进程）
数据格式	JSON	多协议	SQL	SQL + Git
并发安全	❌ 无协调	✅ 支持	✅ 支持	✅ 支持
持久化	文件级 JSON	RDB/AOF	磁盘文件	Git 版本化
访问方式	HTTP REST	Redis 协议	SQL	SQL + CLI
适用规模	单机少量数据	中等规模	中小规模	团队协作
无外部依赖	✅	❌	✅	❌

seriousdb 的核心竞争力是极简和零依赖。当数据量小、无并发需求、只需要一个 HTTP 接口时，它比 Redis 更轻；当需要 SQL 查询或数据库工具时，SQLite 更合适。

一句话推荐结论

极简嵌入式 KV 存储，适合单机少量数据、无并发需求的工具类场景；生产环境高并发请用 Redis 或 SQLite。