SurrealDB 介绍与选型指南

面向在 Ubuntu 22.04 上评估多模型数据库的工程师,介绍 SurrealDB 3.3.0 的定位、架构、功能边界与 MongoDB/PostgreSQL+pgvector/Fauna 的选型对比,全部命令与回显实测通过。

SurrealDBSurrealDB2026/10/17

SurrealDB 介绍与选型指南

‍‍​​‌​> 目标:面向需要在 Ubuntu 22.04 服务器上评估多模型数据库的工程师,系统介绍 SurrealDB 的定位、架构、功能、适用边界,并与 MongoDB、PostgreSQL+pgvector、Fauna 等同类产品做选型对比;全文命令与回显均在 SurrealDB 3.3.0(Ubuntu 22.04.4 LTS,x86_64,监听 0.0.0.0:8000,数据目录 /opt/data/surrealdb)实测通过。

一、环境信息

本文所有示例所依赖的实测环境如下,读者在对照命令回显时应保证关键项一致:

  • 操作系统:Ubuntu 22.04.4 LTS(内核 x86_64)
  • 数据库:SurrealDB 3.3.0 stable(2026-09-28 发布,官方 GitHub Releases 二进制安装于 /usr/local/bin/surreal)
  • 对比参考版本:SurrealDB 2.7.0 stable(2.x 维护分支最新,已实测 2.7.0 for linux on x86_64)
  • 服务监听:0.0.0.0:8000(SurrealDB 默认端口 8000,HTTP 与 WebSocket 同端口复用)
  • 数据目录:/opt/data/surrealdb(rocksdb 文件后端,落盘对象为 /opt/data/surrealdb/database.db 目录,实测约 145 MB)
  • 管理账号:root / q1w2e3r4(演示口令,生产环境请替换为强口令)
  • 接入通道:surreal sql 命令行(默认端点 ws://localhost:8000)与 HTTP 接口 POST /sql 双通道均已实测

💡 技术拓展:SurrealDB 属于「多模型数据库(Multi-model Database)」家族。同类主要选项对比——

产品数据模型组合许可语言/生态
SurrealDB文档 + 图 + 向量 + 时序(changefeed)BSL 1.1(源码可用)Rust
MongoDB纯文档(图查询需 $graphLookup)SSPLC++
PostgreSQL+pgvector关系 + 向量扩展(图需递归 CTE)PostgreSQL LicenseC
ArangoDB文档 + 图(向量能力弱)自有 BUSL 变体C++
Fauna文档 + 关系(托管服务,不可自托管)商业 SaaS闭源
OrientDB文档 + 图(已停止积极维护)Apache 2.0Java

本系列文章选型对象为 SurrealDB,理由:单一进程同时提供文档、图、全文检索与向量能力,且可在单台 Ubuntu 服务器上以单个二进制完成 0→1 部署。

二、软件概述

SurrealDB 是用 Rust 编写的多模型数据库,于 2021 年由 SurrealDB Ltd. 发布,设计目标是把应用后端常见的「文档库 + 图库 + 搜索引擎 + 向量库」四件套收敛到一个存储引擎里。它有一个非常鲜明的产品决策:数据库本身支持直接运行业务逻辑(SurrealQL 内置函数、事件、访问控制),因此官方称其为「端到端云原生数据库(edge-to-cloud)」,既可单机跑,也可对接 TiKV 等分布式 KV 做横向扩展。

版本与许可现状(2026-10-17 实查 GitHub Releases 与 LICENSE 文件):

  • 最新稳定版:v3.3.0(2026-09-28 发布);3.x 上一分支补丁 v3.2.5(2026-10-06 发布);2.x 维护分支最新 v2.7.0(2026-09-28 发布)。
  • 许可:Business Source License 1.1(BSL 1.1)。LICENSE 文件实测关键条款——Licensor 为 SurrealDB Ltd.,Licensed Work 为 SurrealDB 3.0(© 2025 SurrealDB Limited),Additional Use Grant 允许自由使用但不得将其作为 Database Service(数据库服务)对外提供;Change Date 为 2030-01-01,Change License 为 Apache License 2.0(且每个版本在其首次公开发布满四周年时也自动转为 Apache 2.0)。
  • 官方发布件:GitHub Releases 提供 linux-amd64 / linux-arm64、darwin-amd64 / darwin-arm64 / darwin-universal 的 .tgz 与 windows-amd64.exe,linux-amd64 压缩包实测 104,520,734 字节,解压后单个 surreal 二进制约 348 MB。

一句话概括定位:如果你想要「一个二进制、一条连接、一套查询语言」同时覆盖文档、关系图、全文与向量检索,并且能接受 BSL 1.1 的非 DBaaS 使用限制,SurrealDB 是当前完成度较高的一站式选项。

三、核心架构

理解 SurrealDB 的架构要抓住三层:数据寻址层级、存储引擎抽象、访问协议层。本节每一层都给出实测依据。

3.1 数据寻址层级:Root → Namespace → Database → Table → Record

SurrealDB 的寻址层级自上而下为根(Root)、命名空间(NS)、数据库(DB)、表(TB)、记录(Record)。所有 SQL 语句都作用在当前会话选定的 NS/DB 上。实测(surreal sql 命令行,root 身份):

surreal sql -u root -p q1w2e3r4
USE NS shop DB demo;
INFO FOR NS;
DEFINE TABLE user SCHEMALESS;
DEFINE TABLE post SCHEMAFUL;
INFO FOR DB;

实测回显(REPL 横幅节选,实测首尾):

#
#  Welcome to the SurrealDB SQL shell
#
#  How to use this shell:
#    - Different statements within a query should be separated by a (;) semicolon.
#    - To create a multi-line query, end your lines with a (\) backslash, and press enter.
#    - To exit, send a SIGTERM or press CTRL+C
#
#  SurrealDB version: 3.3.0
#

[{ database: 'demo', namespace: 'shop' }]

[{ accesses: {  }, databases: { demo: 'DEFINE DATABASE demo' }, users: {  } }]

[NONE]

[NONE]

[{ accesses: {  }, analyzers: {  }, apis: {  }, buckets: {  }, configs: {  }, functions: {  }, models: {  }, modules: {  }, params: {  }, sequences: {  }, tables: { post: 'DEFINE TABLE post TYPE NORMAL SCHEMAFULL PERMISSIONS NONE', user: 'DEFINE TABLE user TYPE ANY SCHEMALESS PERMISSIONS NONE' }, users: {  } }]

要点:INFO FOR NS 返回命名空间下的数据库清单;INFO FOR DB 返回表、分析器、访问方法(accesses)、用户(users)等九类定义;SCHEMALESS 表回显为 TYPE ANY SCHEMALESS,SCHEMAFUL 表为 TYPE NORMAL SCHEMAFULL。记录 ID 是全库寻址的基本单位,形如 user:alex,图关系的边也是一张表(如 wrote),边记录自带 in/out 字段。

3.2 存储引擎抽象:rocksdb / surrealkv / tikv / memory

SurrealDB 的 surreal start 以一个路径前缀决定底层 KV 存储引擎。引擎层是统一 KV 抽象,上层(文档/图/全文索引)构建在其上。

💡 技术拓展:同为嵌入式 KV 引擎,选型差异对比——

引擎启动参数特点适用场景
RocksDBrocksdb:<path>成熟 LSM 引擎,写入吞吐高单机生产默认选型
SurrealKVsurrealkv:<path>SurrealDB 自研,面向版本化存储新引擎,单机尝鲜
TiKVtikv://<pd-address>分布式 KV,PD 调度多节点水平扩展
Memorymemory(默认)纯内存,重启即失测试、临时计算

本文单机场景采用 rocksdb 后端,理由:最成熟稳定、社区验证最充分。

本环境实测启动命令(前台运行,控制台回显实测首尾):

surreal start --user root --pass q1w2e3r4 --bind 0.0.0.0:8000 rocksdb:/opt/data/surrealdb/database.db
 .d8888b.                                             888 8888888b.  888 8888888b.  888888b.  888888b.
d88P  Y88b                                            888 888   'Y88b  888 888  'Y88b. 888  'Y88b.  'Y888b.   '8888888P'
Y88b.                                                 888 888    888  888 888    888 888    888 888   'Y88b.  'Y8888b.
 'Y8888P'   'Y88888 888     888     888  'Y8888  'Y888888 888 8888888P'  888 888    888 8888888P'  8888888P'  '8888888P'


2026-10-17T10:16:48.551160Z  INFO surrealdb_server::cli::start: Memory threshold is disabled; queries will not be refused on memory pressure
2026-10-17T10:16:48.551188Z  INFO surrealdb_server::env: Running 3.3.0 for linux on x86_64
2026-10-17T10:16:48.552199Z  INFO surrealdb::core::kvs::ds: Starting kvs store at absolute path rocksdb:/opt/data/surrealdb/database.db
2026-10-17T10:16:48.555095Z  INFO surrealdb::core::kvs::rocksdb: Setting storage engine log level: warn
(中略:rocksdb 各项初始化参数日志,实测共 40 余行)
2026-10-17T10:16:48.765748Z  INFO surrealdb::net: Started web server on 0.0.0.0:8000
2026-10-17T10:16:48.994807Z  INFO surrealdb::net: Listening for a system shutdown signal.
2026-10-17T10:16:48.995Z  INFO surrealdb_server::cli::start: Startup complete; instance is now ready to serve

要点:日志首行确认版本与架构;Starting kvs store at absolute path rocksdb:/opt/data/surrealdb/database.db 确认数据落盘路径;Started web server on 0.0.0.0:8000 确认 HTTP/WS 监听端口。数据目录落盘产物实测:

ls -la /opt/data/surrealdb/
total 12
drwxr-xr-x 3 65532 65532 4096 Oct 17 17:54 .
drwxr-xr-x 23 root  root  4096 Oct 17 17:54 ..
drwxr-xr-x 2 65532 65532 4096 Oct 17 18:12 database.db

database.db 本身是一个目录(RocksDB 的 SST/WAL 文件都在其中),这是文件后端的典型形态,备份时按目录整体处理。

3.3 访问协议层:HTTP、WebSocket、RPC 与 CLI

SurrealDB 在 8000 端口同时提供多套协议,均实测可用:

  • HTTP:POST /sql(原生 SurrealQL 批量执行)、/signin、/signup、/key/:table(REST 风格)、/rpc(JSON-RPC)。
  • WebSocket:/rpc 上的 WS 通道,SDK 与 LIVE SELECT 实时推送走这条通道。
  • CLI:surreal sql REPL(默认端点 ws://localhost:8000),本质是 WebSocket 客户端。

HTTP 双认证实测(Basic 与 Bearer):

curl -s http://127.0.0.1:8000/sql -u root:q1w2e3r4 \
  -H 'surreal-ns: shop' -H 'surreal-db: demo' \
  -H 'Accept: application/json' \
  -d 'SELECT id, name, score FROM user ORDER BY score DESC LIMIT 3;'
[{"result":[{"id":"user:alex","name":"Alex Zhang","score":97},{"id":"user:jamie","name":"Jamie Li","score":92},{"id":"user:wangwu","name":"王五","score":81}],"status":"OK","time":"432.16µs","type":null}]
TOKEN=$(curl -s http://127.0.0.1:8000/signin -H 'surreal-ns: shop' -H 'surreal-db: demo' \
  -d '{"user":"root","pass":"q1w2e3r4"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')
curl -s http://127.0.0.1:8000/sql -H "Authorization: Bearer $TOKEN" \
  -H 'surreal-ns: shop' -H 'surreal-db: demo' \
  -d 'SELECT id, name FROM user:alex;'
[{"result":[{"id":"user:alex","name":"Alex Zhang"}],"status":"OK","time":"195.997µs","type":null}]

要点:/signin 返回 HS512 签名的 JWT(载荷含 ID: root),之后可用 Authorization: Bearer 免密调用;HTTP 响应是数组,每个语句一个元素,含 result/status/time 三字段,天然支持一次批量多条语句。

四、功能特性

以下特性均在本环境逐项实测(命令与完整回显见《SurrealDB SurrealQL 查询语言详解》一篇的对应章节,此处给结论与代表性回显)。

4.1 双模式表:SCHEMALESS 与 SCHEMAFUL 可并存

同一个库中,user 表 SCHEMALESS(任意字段)、post 表 SCHEMAFUL(字段强约束)实测并存。SCHEMAFUL 表写入未定义字段会被直接拒绝,实测回显:

["Found field 'created_at', but no such field exists for table 'post'"]

4.2 图关系:RELATE 建边与双向遍历

RELATE user:alex->wrote->post:set_up_db SET role = 'lead', at = time::now(); 实测回显:

[[{ at: d'2026-10-17T09:58:06.818700886Z', id: wrote:tn91oj6bzxzxpg9f5lt4, in: user:alex, out: post:set_up_db, role: 'lead' }]]

边记录自动生成随机 ID 并带 in/out;图方向查询 -> 与 <- 实测:

SELECT ->wrote->post.title AS titles FROM user:alex;
[[{ titles: ['SurrealQL 查询语言语法速查', 'SurrealDB 数据库安装与初始化实战'] }]]
SELECT <-wrote<-user.name AS writers FROM post:graph_model;
[[{ writers: ['Jamie Li'] }]]

多跳遍历(两跳:用户→文章→引用的文章)实测:

SELECT ->wrote->post->references->post.title AS chain FROM user:alex;
[[{ chain: ['SurrealDB 数据库安装与初始化实战'] }]]

4.3 全文检索:ANALYZER 分词 + BM25 打分 + 高亮

内置 FULLTEXT 索引,支持自定义分词器。中文场景实测结论:class 分词器不切分连续中文,需配合 NGRAM/EDGENGRAM 过滤器。实测分词回显:

RETURN search::analyze('zh_class', '数据库系统原理实战指南');
[['数据库系统原理实战指南']]
RETURN search::analyze('zh_ngram', '数据库系统原理实战指南');
[['数据', '数据库', '数据库系', '数据库系统', '据库', '据库系', '据库系统', '据库系统原', '库系', '库系统', '库系统原', '库系统原理', '系统', '系统原', '系统原理', '系统原理实', '统原', '统原理', '统原理实', '统原理实战', '原理', '原理实', '原理实战', '原理实战指', '理实', '理实战', '理实战指', '理实战指南', '实战', '实战指', '实战指南', '战指', '战指南', '指南']]

BM25 打分与高亮实测:

SELECT id, title, search::score(1.0) AS score FROM post WHERE title @@ '数据库安装' ORDER BY score DESC;
[[{ id: post:set_up_db, score: 0.4721917510032654f, title: 'SurrealDB 数据库安装与初始化实战' }]]
SELECT id, title, search::highlight('<b>', '</b>', 1.0) AS marked, search::offsets(1.0) AS offsets FROM post WHERE title @@ '数据库安装';
[[{ id: post:set_up_db, marked: 'SurrealDB <b>数据库安装与初始化实战</b>', offsets: { "0": [{ e: 21, s: 10 }] }, title: 'SurrealDB 数据库安装与初始化实战' }]]

4.4 实时订阅:LIVE SELECT

一个连接发起 LIVE SELECT * FROM user; 后返回订阅 UUID u'adb75583-e2ec-49ff-bbf1-c4e5644cfd52';另一连接执行 CREATE user:live_probe ... 时,第一个连接立即收到推送(实测回显):

{ action: 'CREATE', id: u'adb75583-e2ec-49ff-bbf1-c4e5644cfd52', result: { age: 18, created_at: d'2026-10-17T10:00:26.478788350Z', email: 'live@example.com', id: user:live_probe, name: 'LiveProbe', score: 1 } }

KILL u'adb75583-...'; 可注销订阅(实测执行后无报错、不再推送)。

4.5 事务与内置函数

单条查询内 BEGIN TRANSACTION; ... ; COMMIT/CANCEL TRANSACTION; 原子执行。实测 CANCEL 回滚:

BEGIN TRANSACTION; CREATE user:tx_test4 SET name = 'T4', email = 't4@example.com', age = 20, score = 50; UPDATE user:tx_test4 SET score = 66; CANCEL TRANSACTION;
[NONE, 'The query was not executed due to a cancelled transaction', 'The query was not executed due to a cancelled transaction', NONE]
SELECT * FROM user:tx_test4;
[]

内置函数抽样实测:math::sum([1,2,3,4]) → 10,math::pow(2,10) → 1024,time::year(time::now()) → 2026,time::floor(time::now(), 1h) → 2026-10-17T10:00:00Z,string::len('数据库') → 3,array::distinct([1,2,2,3]) → [1,2,3]。

4.6 访问控制:系统用户 + 记录用户双层模型

系统用户(root/ns/db 级,ROLES OWNER/EDITOR/VIEWER)与记录用户(RECORD 访问方法 + SIGNUP/SIGNIN 表达式)双层并存。实测 VIEWER 角色执行 DEFINE 被拒:

{"details":{"details":{"details":{"action":"Edit","actor":"/ns:shop/db:demo/Actor::viewer_user(Viewer)","resource":"/ns:shop/db:demo/Table:\"\""},"kind":"NotAllowed"},"kind":"Auth"},"kind":"NotAllowed","result":"IAM error: Not enough permissions to perform this action","status":"ERR","time":"42.551µs","type":null]}

记录用户登录后 $auth 即本人记录 ID,实测 RETURN $auth; → person:d4sdynsd70o0izqpily3。

五、快速开始

本节给出从零到第一条查询的最小闭环,全部命令实测。前置:Ubuntu 22.04 已安装 surreal 二进制(安装过程见《SurrealDB 安装指南》)。

5.1 启动服务并验证

surreal start --user root --pass q1w2e3r4 --bind 0.0.0.0:8000 rocksdb:/opt/data/surrealdb/database.db

启动后验证健康检查与版本(/health 正常时返回空响应体、仅以 HTTP 200 表达健康状态,直接 curl -s 会「没有输出」,因此用 -w 打印状态码观察):

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health
200
surreal version
3.3.0 for linux on x86_64

5.2 建模型、写数据、查数据

surreal sql -u root -p q1w2e3r4 --ns shop --db demo
DEFINE TABLE user SCHEMALESS;
CREATE user:alex SET name = 'Alex Zhang', email = 'alex@example.com', age = 30, score = 88, tags = ['admin', 'dev'], created_at = time::now();
SELECT name, score FROM user WHERE score > 80 ORDER BY score DESC;

实测回显:

[NONE]
[[{ age: 30, created_at: d'2026-10-17T10:45:31.237112182Z', email: 'alex@example.com', id: user:alex, name: 'Alex Zhang', score: 88, tags: ['admin', 'dev'] }]]
[[{ name: 'Alex Zhang', score: 88 }]]

5.3 一条语句体验多模型

先建一篇带作者引用的文章记录,再建图边,最后在一条 SELECT 里同时体验图遍历与文档展开:

CREATE post:set_up_db SET title = 'SurrealDB 数据库安装与初始化实战', author = user:alex;
RELATE user:alex->wrote->post:set_up_db SET role = 'lead';
SELECT id, title, author.name AS author_name, author.email AS author_email FROM post FETCH author;
SELECT ->wrote->post.title AS titles FROM user:alex;

实测回显:

[[{ author: user:alex, id: post:set_up_db, title: 'SurrealDB 数据库安装与初始化实战' }]]
[[{ id: wrote:ioj7z645kjhrqg61dxni, in: user:alex, out: post:set_up_db, role: 'lead' }]]
[[{ author_email: 'alex@example.com', author_name: 'Alex Zhang', id: post:set_up_db, title: 'SurrealDB 数据库安装与初始化实战' }]]
[[{ titles: ['SurrealDB 数据库安装与初始化实战'] }]]

要点:第 3 条语句里 author.name AS author_name 直接取到了作者姓名——这是 FETCH author(记录链接展开,文档模型);第 4 条语句用 ->wrote->post 图方向遍历拿到同一批文章标题(图模型)。两者在同一会话、同一查询语言中协同,这就是「多模型统一查询」的直观体验。

六、适用场景与限制

6.1 适合的场景

  • 全栈单体/边缘部署:一个二进制带 Web 服务、鉴权(记录用户)、实时推送(LIVE SELECT),适合 SaaS 单租户、私有化交付、嵌入式网关等「后端收敛」场景。
  • 知识图谱 + 内容库混合:文章(文档)、作者关系(图)、正文检索(全文)、语义搜索(向量)四类数据天然同库,免去多库同步。
  • 原型与小中型生产:SCHEMALESS 起步快速迭代,业务稳定后切换 SCHEMAFUL 收紧约束。
  • 需要行级权限的多租户应用:表级/字段级 PERMISSIONS + 记录用户 + $auth 可把「谁能读哪行」下沉到数据库层。

6.2 限制与注意(实测归纳)

  • 许可限制:BSL 1.1 禁止把 SurrealDB 本身作为 Database Service 出售(如托管 DBaaS);内部业务系统使用不受限。Change Date 2030-01-01 前引用需评估合规。
  • 生态成熟度:第三方 BI/ETL 工具连接器远少于 MySQL/PostgreSQL,数仓类需求需自行导出(surreal export)。
  • 单机引擎无内建高可用:rocksdb/surrealkv 后端为单机文件,高可用需 TiKV 后端或外部复制方案。
  • 中文分词需自行配置 NGRAM 类分析器:默认分词器不切分中文词(实测已验证),索引体积与召回质量需权衡(NGRAM 全量 gram 索引偏大)。
  • CLI 多语句事务注意:管道方式逐行喂给 surreal sql 时每行是独立隐式事务,跨行 BEGIN/COMMIT 不生效,实测报 ['Invalid statement: Cannot CANCEL without starting a transaction'];事务必须写在同一查询内。

七、同类选型对比

7.1 多模型能力矩阵

能力SurrealDB 3.3MongoDB 8.xPostgreSQL 16+pgvectorFauna
文档模型原生(SCHEMALESS/SCHEMAFUL 可混用)原生JSONB 模拟原生
图查询原生 RELATE + 图方向遍历(实测两跳)$graphLookup(受限)递归 CTE(写法繁琐)无原生图
全文检索内建 ANALYZER + BM25 + HIGHLIGHTSAtlas Search(托管版)tsvector/中文需扩展内建
向量检索内建(MTREE/HNSW 索引)Atlas Vector Searchpgvector 扩展内建
实时订阅LIVE SELECT(实测推送)Change StreamsLISTEN/NOTIFY事件流
事务多语句 ACID(单查询内实测回滚)多文档事务完整 ACID严格事务
自托管支持(单二进制/TiKV 集群)社区版支持支持不支持(仅 SaaS)
许可BSL 1.1(禁 DBaaS,2030-01-01 转 Apache 2.0)SSPLPostgreSQL License商业

关键差异解读:若业务核心是关系型分析,PostgreSQL 仍是第一选择;若核心是文档 + 生态工具链,选 MongoDB;若要一套引擎覆盖文档/图/搜索/向量且自托管,SurrealDB 的能力集中度最高;Fauna 仅适合愿意全托管、无自托管诉求的团队。

7.2 社区活跃度与版本节奏(2026-10-17 实查)

  • GitHub 主仓库 surrealdb/surrealdb Releases 节奏:3.x 分支持续迭代(v3.1.6 → v3.2.5 → v3.3.0,平均每月多个补丁),2.x 分支仍发布维护版本(v2.7.0),beta 预发布(v3.3.0-beta.1~4)公开可测。
  • 发布件覆盖 linux-amd64/arm64、darwin、windows,单二进制形态对运维非常友好。

7.3 选型建议(「如果…则…」)

  • 如果你的服务要同时用到文档存取、关系遍历、中文全文检索与向量召回,且希望运维一个实例 → 选 SurrealDB(本专栏其余各篇即为此路径)。
  • 如果已有重型 PostgreSQL 体系,只缺向量 → 优先 pgvector,不必引入新数据库。
  • 如果团队强依赖 SQL 生态工具(BI 报表、CDC、数仓同步) → SurrealDB 需评估导出链路,或退回 PostgreSQL。
  • 如果产品形态本身就是「向客户卖数据库服务」 → SurrealDB 因 BSL 1.1 条款不可用(除非取得商业授权)。

八、参考链接