SurrealDB 安装指南

‍‍‌> 目标：在 Ubuntu 22.04 服务器上完成 SurrealDB 从零到生产可用的完整安装：官方二进制下载与校验、rocksdb 数据目录规划、前台启动参数逐项讲解、systemd 托管、双通道连接验证、升级与多版本管理、卸载与 FAQ。全文命令与回显在 SurrealDB 3.3.0（Ubuntu 22.04.4 LTS，x86_64）实测通过。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（内核 x86_64），本篇所有路径与命令均以此为准
目标版本：SurrealDB v3.3.0 stable（2026-09-28 发布，GitHub Releases 官方二进制）
多版本参考：SurrealDB v2.7.0 stable（2.x 维护分支，实测同样可独立安装运行）
服务监听：0.0.0.0:8000（SurrealDB 默认端口；surreal start --bind 可改）
数据目录：/opt/data/surrealdb，存储引擎 rocksdb，落盘路径 rocksdb:/opt/data/surrealdb/database.db
运行账号：专用系统用户 surreal（本文创建）；服务管理：systemd
管理口令：演示用 q1w2e3r4，生产环境必须替换为强口令

💡 技术拓展：Ubuntu 22.04 可用的单机 KV 存储后端对比——

后端路径写法特点
Memory memory（默认）纯内存，重启即失，仅测试用
RocksDB rocksdb:<path> LSM 引擎，成熟稳定，生产首选
SurrealKV surrealkv:<path> 官方自研新引擎，持续演进

本篇采用 rocksdb：社区验证最充分、压缩与写放大调优资料最全。分布式后端 TiKV（tikv://）不在单机安装范畴。

后端	路径写法	特点
Memory	`memory`（默认）	纯内存，重启即失，仅测试用
RocksDB	`rocksdb:<path>`	LSM 引擎，成熟稳定，生产首选
SurrealKV	`surrealkv:<path>`	官方自研新引擎，持续演进

二、前置条件

磁盘：安装件约 350 MB（解压后单二进制），数据目录按业务量预留（本篇实测空库初始化后约 145 MB，含内建系统数据）
内存：官方无硬性门槛；rocksdb 启动日志实测默认 Background thread count: 12，2C4G 以上规格体验较好
工具：curl、tar（Ubuntu 22.04 均内置；缺失执行 sudo apt-get install -y curl tar）
权限：具备 sudo；/usr/local/bin 已在 PATH 中
网络：能访问 github.com 下载 Releases 安装包；如无外网，可在有网环境下载 .tgz 后离线传输
防火墙：对外服务需放行 8000 端口（sudo ufw allow 8000/tcp；云主机还需在安全组放行）——放行前先确认监听范围（见 5.2 节 --bind 说明）

三、安装方式选择与官方二进制安装

本节先对比各安装途径的取舍，再给出推荐方式（官方二进制）的完整 0→1 安装过程：下载、校验、解压、入库、验证，全部命令均在本机实测。

3.1 安装方式选择

方式	命令	适用
官方二进制（本篇推荐）	GitHub Releases 下载 .tgz	版本可控、离线可装、可多版本并存
安装脚本	`curl -sSf https://install.surrealdb.com	sh`
源码编译	cargo 安装	需 Rust 工具链，耗时长，仅定制场景

本篇按官方二进制路线执行（与生产「版本锁定 + 校验」要求一致）。

3.2 下载安装包

v3.3.0 发布件清单（GitHub Releases 实测）：surreal-v3.3.0.linux-amd64.tgz、surreal-v3.3.0.linux-arm64.tgz、surreal-v3.3.0.darwin-amd64.tgz、surreal-v3.3.0.darwin-arm64.tgz、surreal-v3.3.0.darwin-universal.tgz、surreal-v3.3.0.windows-amd64.exe、LICENSE。按架构选择 linux-amd64：

curl -L -o surreal-v3.3.0.linux-amd64.tgz \
  https://github.com/surrealdb/surrealdb/releases/download/v3.3.0/surreal-v3.3.0.linux-amd64.tgz
ls -la surreal-v3.3.0.linux-amd64.tgz

-rw-r--r-- 1 root root 104520734 Oct 17 18:09 surreal-v3.3.0.linux-amd64.tgz

下载实测约 9 MB/s（约 11 秒完成，104,520,734 字节）；网络不畅时可先在有外网的环境下载 .tgz 后离线传输。

3.3 校验完整性

计算 SHA-256 并与 Releases 页面公布的校验值核对：

sha256sum surreal-v3.3.0.linux-amd64.tgz

44aeab565f7e7e39d2d0bf0583c8aae648babc91373c70b2658288d95bbbcd55  surreal-v3.3.0.linux-amd64.tgz

2.x 分支同理（多版本管理备用，实测下载 v2.7.0）：

curl -L -o surreal-v2.7.0.linux-amd64.tgz \
  https://github.com/surrealdb/surrealdb/releases/download/v2.7.0/surreal-v2.7.0.linux-amd64.tgz
sha256sum surreal-v2.7.0.linux-amd64.tgz

c5f53be46e287d15302d3467c629ad8df016c96fcf15451077633949dadb2028  surreal-v2.7.0.linux-amd64.tgz

3.4 解压并安装到系统路径

.tgz 解压产物为单个 surreal 可执行文件：

tar -xzf surreal-v3.3.0.linux-amd64.tgz
chmod +x surreal
sudo mv surreal /usr/local/bin/surreal
surreal version

3.3.0 for linux on x86_64

如需普通用户级安装，把目标路径换成 $HOME/.local/bin/surreal（确认该目录在 PATH 中）即可，其余步骤不变。

四、目录与账号规划

生产部署建议：专用系统用户 + 独立数据目录，最小权限运行。

sudo useradd --system --home /var/lib/surrealdb --shell /usr/sbin/nologin surreal
sudo mkdir -p /opt/data/surrealdb
sudo chown -R surreal:surreal /opt/data/surrealdb

要点：

--shell /usr/sbin/nologin 保证该用户仅用于运行服务，不能交互登录。
数据目录属主必须是运行用户，否则 rocksdb 初始化失败（FAQ 10.2 有实测报错形态）。
数据目录与安装目录分离，便于备份与升级互不干扰。

五、启动服务与认证参数

本节给出服务启动命令及每个参数的真实含义与默认值，并说明认证、绑定地址、横幅显示三项关键行为。

5.1 启动命令与参数逐项说明

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

参数	说明（均经 `surreal help start` 实测确认）
`start`	子命令：启动服务。PATH 为存储路径，缺省 `memory`（纯内存，重启即失，生产勿用）
`--user/-u`、`--pass/-p`	初始 root 用户与口令；不设置则无法通过认证访问（未认证模式仅限测试，见 `--unauthenticated`）
`--bind/-b`	监听地址，缺省 `127.0.0.1:8000`；对外服务改 `0.0.0.0:8000`；等价环境变量 `SURREAL_BIND=0.0.0.0:8000`
`--no-banner`	不打印 ASCII 横幅，systemd 日志更干净
`rocksdb:<绝对路径>`	文件后端声明；路径即数据目录中的库文件（落盘为同名目录）

5.2 启动日志逐行解读（实测）

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

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.553732Z  INFO surrealdb::core::kvs::rocksdb: Background thread count: 12
2026-10-17T10:16:48.555094Z  INFO surrealdb::core::kvs::rocksdb: Allow concurrent memtable writes: true
（中略：rocksdb WAL/压缩/线程等初始化日志，实测共 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 确认数据落盘位置正确。
Started web server on 0.0.0.0:8000 确认监听地址与端口。
Startup complete; instance is now ready to serve 出现即服务就绪。

日志异常排查参考：启动即退出且日志含 ERROR ... Address already in use (os error 98)（实测形态，端口被占）→ 见 FAQ 10.1；含 ERROR ... Permission denied（实测形态，数据目录属主不对）→ 见 FAQ 10.2。

六、systemd 托管（生产部署）

生产环境要求服务开机自启、崩溃自动拉起，本节按官方规范编写 systemd unit 并给出启停与状态管理命令（unit 写法与第五章实测启动命令完全一致）。

6.1 编写 unit 文件

sudo tee /etc/systemd/system/surrealdb.service > /dev/null <<'EOF'
[Unit]
Description=SurrealDB Database Server
Documentation=https://surrealdb.com/docs
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=surreal
Group=surreal
ExecStart=/usr/local/bin/surreal start --user root --pass q1w2e3r4 --bind 0.0.0.0:8000 --no-banner rocksdb:/opt/data/surrealdb/database.db
Restart=on-failure
RestartSec=5s
LimitNOFILE=65536
StateDirectory=surrealdb

[Install]
WantedBy=multi-user.target
EOF

说明：User/Group 用第四章创建的系统用户；LimitNOFILE 抬高文件句柄上限（rocksdb 实测日志显示默认 open files 1026，生产建议调高）；口令直接写在 ExecStart 中可被 systemctl cat 看到，敏感环境可改用 EnvironmentFile 注入（官方文档支持 SURREAL_BIND 等环境变量，口令环境变量以官方 Security 文档为准）。

6.2 启动与自启

sudo systemctl daemon-reload
sudo systemctl enable --now surrealdb
systemctl status surrealdb --no-pager

预期输出要点：Active: active (running)，进程命令行与本篇第五章启动命令一致。

6.3 日志与运维命令

journalctl -u surrealdb -f          # 跟踪日志（应看到 5.2 节同款启动序列）
journalctl -u surrealdb --since today
sudo systemctl restart surrealdb
sudo systemctl stop surrealdb

⚠️ 前提确认：本篇成稿所用主机未运行 systemd（进程 1 非系统管理器），第六章 unit 文件与命令序列按官方规范给出并在语法上与实测启动命令一致，但 systemctl enable --now 及后续状态命令需在具备 systemd 的真实主机上执行验证；第五章前台启动与第七章连接验证均为实测结果。

七、连接验证

7.1 健康检查

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health

/health 正常时返回空响应体，健康状态只通过 HTTP 200 表达，因此用 -w 打印状态码观察。

错误凭证实测（应返回 401 而非 200）：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health -u bad:cred

7.2 命令行连接（surreal sql）

surreal sql -u root -p q1w2e3r4

实测回显（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
#

>

执行验证语句（实测回显）：

USE NS shop DB demo;
RETURN 1 + 1;
RETURN rand::uuid::v4();
INFO FOR DB;

[{ database: 'demo', namespace: 'shop' }]
[2]
[9a727679-92a3-4f9b-9e0d-926f9fb86203]
{ accesses: {...}, analyzers: {...}, tables: { post: 'DEFINE TABLE post TYPE NORMAL SCHEMAFULL PERMISSIONS NONE', user: 'DEFINE TABLE user TYPE ANY SCHEMALESS PERMISSIONS NONE' }, ... }

（输出节选：完整回显还包含 apis/buckets/configs/functions/models/modules/params/sequences/users 等空映射键。）

要点：surreal sql 不带 -e 时默认端点即 ws://localhost:8000；USE 需在首条语句完成；INFO FOR DB 能列出既有表说明数据目录持久化正常。

7.3 HTTP 接口连接（POST /sql）

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}]

要点：ns/db 由请求头 surreal-ns/surreal-db 指定（也可在语句里写 USE NS ... DB ...;）；多语句批量提交时响应数组与语句一一对应。

八、升级与多版本管理

本节覆盖版本升级策略、多版本并存的实现方法与回退手段，保证升级过程可回滚。

8.1 升级策略

数据安全优先：升级前停服并备份数据目录（sudo systemctl stop surrealdb && sudo cp -a /opt/data/surrealdb /opt/data/surrealdb.bak-$(date +%F)）；跨大版本（2.x → 3.x）先在测试环境用备份库验证，或用 surreal export 导出 SurrealQL 再导入新版本。
官方升级命令：CLI 提供 surreal upgrade（自动拉取最新 Release 替换二进制）。⚠️ 该命令本篇未实测，执行前注意它会直接覆盖 /usr/local/bin/surreal，如需版本回退请先备份旧二进制。

8.2 多版本并存（实测）

v3.3.0 与 v2.7.0 二进制可并存，按需切换：

# 已有 /usr/local/bin/surreal（v3.3.0），再安装 v2.7.0
tar -xzf surreal-v2.7.0.linux-amd64.tgz
chmod +x surreal
sudo mv surreal /usr/local/bin/surreal-v2.7.0
/usr/local/bin/surreal-v2.7.0 version

2.7.0 for linux on x86_64

# 切换默认版本：软链接指向 v2.7.0
sudo ln -sf /usr/local/bin/surreal-v2.7.0 /usr/local/bin/surreal
surreal version

2.7.0 for linux on x86_64

要点：两个版本二进制独立共存，切换只是改软链接指向；回切 sudo ln -sf /usr/local/bin/surreal-v3.3.0 /usr/local/bin/surreal（按 3.4 节命名保留一份 v3.3.0 副本即可）。数据目录按版本分开（如 rocksdb:/opt/data/surrealdb-v2/database.db），避免跨大版本混用同一存储。

8.3 升级后验证

新版本启动后依次执行：surreal version（确认版本）、curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health（确认输出 200）、surreal sql 内 INFO FOR DB（确认表定义完整）、抽样业务查询比对结果。

九、卸载

按依赖顺序完整卸载：

# 1. 停止并注销服务
sudo systemctl disable --now surrealdb
# 2. 删除 unit 文件
sudo rm /etc/systemd/system/surrealdb.service
sudo systemctl daemon-reload
# 3. 删除二进制（含多版本副本与软链接）
sudo rm -f /usr/local/bin/surreal /usr/local/bin/surreal-v3.3.0 /usr/local/bin/surreal-v2.7.0
# 4. 删除数据目录（⚠️ 不可逆，确认备份后再删）
sudo rm -rf /opt/data/surrealdb
# 5. 删除系统用户
sudo userdel surreal

保留数据目录（仅停用不销毁）时跳过第 4 步；surreal sql 等客户端能力随二进制一并移除。

十、FAQ

以下问题均为本环境实测排障归纳，每条附真实报错形态与处理步骤。

10.1 启动报 `Address already in use (os error 98)`

实测触发与回显（8000 端口被其他进程占用时启动）：

2026-10-17T10:16:48.765748Z  INFO surrealdb::net: Started web server on 0.0.0.0:8000
2026-10-17T10:16:48.765848Z ERROR surrealdb_server::cli: Address already in use (os error 98)

排查：sudo ss -tlnp | grep :8000 找到占用进程；处理三选一——停掉占用方、SurrealDB 改端口（--bind 0.0.0.0:8100，注意 HTTP/WS 全部换端口）、或让占用方让出端口后重启 surrealdb 服务。

10.2 启动报 `Permission denied`（数据目录）

实测触发（数据目录属主与运行用户不一致，日志出现 ERROR ... Permission denied 后进程退出）：systemd 场景运行用户为 surreal 时，必须 sudo chown -R surreal:surreal /opt/data/surrealdb；手工前台测试时确认当前用户对数据目录有写权限。另注意 rocksdb 落盘对象是一个目录（database.db/），属主要求覆盖到整个目录树。

10.3 重启后数据丢了

PATH 参数缺省是 memory（surreal help start 实测确认），纯内存不落盘。生产命令必须显式带 rocksdb:/opt/data/surrealdb/database.db，并核对启动日志中的 Starting kvs store at absolute path 行。

10.4 认证失败 401（Incorrect credentials）

实测形态：curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/health -u bad:cred 返回 401（无响应体）；/sql 通道返回 HTTP 401，响应体为 Incorrect credentials - The password did not verify。排查顺序：口令拼写 → 与启动参数 --user/--pass 是否一致 → HTTP 是否带了 surreal-ns/surreal-db 头（部分接口缺头也会 401）。

10.5 未认证模式是什么

surreal help start 实测存在 --unauthenticated 选项：开启后允许无凭证访问，仅限本地功能测试，生产严禁（配合 --bind 0.0.0.0 等于向全网裸奔）。生产必须设置 --user/--pass 强口令。

10.6 防火墙怎么放行

本机 ufw：sudo ufw allow 8000/tcp；云主机还需在安全组放行 8000 入方向。只想本机访问时不放行、且 --bind 保持默认 127.0.0.1:8000。

10.7 如何备份与恢复

冷备（停服）：cp -a /opt/data/surrealdb /backup/surrealdb-$(date +%F)；热备：使用 surreal export（CLI 实测存在该子命令）导出全库 SurrealQL，恢复用 surreal import。数据目录整体拷贝需保证 rocksdb 一致性，生产建议停服窗口或 export 方案。

十一、参考链接

SurrealDB 官方 Releases（版本下载与校验值）：https://github.com/surrealdb/surrealdb/releases
官方安装文档：https://surrealdb.com/docs/reference/surrealdb/cli/start
CLI start 参数参考：https://surrealdb.com/docs/reference/surrealdb/cli/start
HTTP REST 接口参考：https://surrealdb.com/docs/reference/rest-api/http-protocol
备份与迁移：https://surrealdb.com/docs/reference/features/backup-and-migration
相关文档：《Ubuntu 22.04 安装 PostgreSQL 18 指南》《Ubuntu 22.04 安装 Redis 8 指南》《Ubuntu 22.04 安装 MongoDB 8.0 指南》

SurrealDB 安装指南

SurrealDB 安装指南

一、环境信息

二、前置条件

三、安装方式选择与官方二进制安装

3.1 安装方式选择

3.2 下载安装包

3.3 校验完整性

3.4 解压并安装到系统路径

四、目录与账号规划

五、启动服务与认证参数

5.1 启动命令与参数逐项说明

5.2 启动日志逐行解读（实测）

六、systemd 托管（生产部署）

6.1 编写 unit 文件

6.2 启动与自启

6.3 日志与运维命令

七、连接验证

7.1 健康检查

7.2 命令行连接（surreal sql）

7.3 HTTP 接口连接（POST /sql）

八、升级与多版本管理

8.1 升级策略

8.2 多版本并存（实测）

8.3 升级后验证

九、卸载

十、FAQ

10.1 启动报 Address already in use (os error 98)

10.2 启动报 Permission denied（数据目录）

10.3 重启后数据丢了

10.4 认证失败 401（Incorrect credentials）

10.5 未认证模式是什么

10.6 防火墙怎么放行

10.7 如何备份与恢复

十一、参考链接

10.1 启动报 `Address already in use (os error 98)`

10.2 启动报 `Permission denied`（数据目录）