如何用 Nix 从 SurrealDB 源码构建 Docker 镜像与静态二进制

如何用 Nix 从 SurrealDB 源码构建 Docker 镜像与静态二进制

【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb

如果你需要从 SurrealDB 的源码仓库构建出一个完整功能的 Docker 镜像，或一个可在 Linux 上直接运行的静态二进制，Nix 是项目官方文档给出的构建路径。SurrealDB 仓库内置了 Nix 支持（pkg/nix/README.md、flake.nix），文档明确了两条路线：已安装 Docker 的机器可以直接在nixos/nix容器里跑 Nix，不往本机装任何东西；已经装了 Nix 的 Linux 机器则可以本地构建。最终产物分别是docker/surreal.tar.gz（Docker 镜像归档）和bin/surreal（静态二进制）。

先确认你要构建哪个产物

两个产物的能力差异很大，选错会直接影响后续部署：

• Docker 镜像（文档推荐）：支持 SurrealDB 的全部功能与存储后端。对应 flake 里的 docker.nix，使用dockerTools.buildLayeredImage打包，镜像名为surrealdb/surrealdb，tag 形如v<版本号>（版本号来自 Cargo.toml 的 workspace 版本并附加构建元数据，+因 Docker 不支持而替换为-）。
• 静态二进制：文档明确警告它"非常有限"——不带任何可选功能，只支持内存存储（对应 musl 规格 中features = [ storage-mem ]），因此无法持久化数据。只适合快速试用，不适合生产。

另外注意文档给出的平台边界：Nix 虽然跨平台，但目前仅支持在 Linux 上构建 Linux 二进制。如果想在其他平台构建，文档建议走"从 Docker 运行 Nix"的路径。

路径 A：只装了 Docker，用 nixos/nix 容器构建

这是文档给出的最短路径：前提是本机已安装 Docker，仓库已克隆并进入仓库根目录。构建命令会在nixos/nix容器里执行 Nix，不会修改你本机的其他环境。

git clone https://gitcode.com/GitHub_Trending/su/surrealdb cd surrealdb

构建 Docker 镜像

docker run -it --rm -v $(pwd):/surrealdb -w /surrealdb nixos/nix sh -c "nix-build -A packages.x86_64-linux.docker-image && mkdir docker && cp -vL ./result docker/surreal.tar.gz && rm result"

该命令把当前仓库目录挂载到容器的/surrealdb，构建结束后把产物复制为docker/surreal.tar.gz。

构建静态二进制

docker run -it --rm -v $(pwd):/surrealdb -w /surrealdb nixos/nix sh -c "nix-build -A packages.x86_64-linux.static-binary && mkdir bin && cp -v ./result/bin/surreal bin/ && rm result"

产物保存在bin/surreal。再次提醒：该二进制只有内存存储，不能用于需要持久化的场景。

路径 B：本地已安装 Nix，直接在仓库内构建

如果你要构建本机平台的二进制或进行开发，需要按官方说明安装 Nix，然后完成两步配置。

启用 Nix Flakes（文档推荐）

编辑~/.config/nix/nix.conf或/etc/nix/nix.conf，加入：

experimental-features = nix-command flakes

Flakes 默认未启用，属于实验性功能。如果 Nix 以 multi-user 模式安装，改完配置后需要重启守护进程；使用 systemd 的系统可执行：

sudo systemctl restart nix-daemon

配置二进制缓存（可选）

从零构建 SurrealDB 及其依赖耗时较长，文档提供了加速方式：

nix run nixpkgs#cachix use surrealdb

注意该命令会下载并运行 Cachix 工具来配置本机使用 SurrealDB 的缓存，副作用是往系统中引入并配置一个新工具，执行前确认你接受这一点。

执行构建

在仓库根目录（克隆仓库后cd进去）下，根据目标选择构建属性：

# 构建 Docker 镜像 nix build .#docker-image # 构建静态二进制 nix build .#static-binary # 构建默认二进制（动态链接，带全部功能），产物在 result/bin nix build

文档同时给出等价的远程引用写法，不依赖本地克隆，例如nix build github:surrealdb/surrealdb#docker-image，并说明可以用分支/tag/commit后缀指定版本（如v1.0.0）。

验证构建结果

文档给出的成功判据是产物落盘与镜像可加载：

1. 产物位置：Docker 镜像归档应为docker/surreal.tar.gz（路径 A）；静态二进制应为bin/surreal；本地nix build的产物则在result/bin下。
2. 加载镜像：用下面的命令把归档导入本机 Docker，能正常加载即说明镜像构建成功：

docker load -i docker/surreal.tar.gz

加载后镜像按 docker.nix 的定义以surrealdb/surrealdb为仓库名、v<版本号>为 tag 存在，Entrypoint指向构建出的surreal可执行文件。

限制与后续

• 静态二进制的硬限制：文档原文指出它"目前非常有限，不带任何可选功能，只支持内存存储，无法持久化数据"。需要持久化时请使用 Docker 镜像。
• 平台限制：目前仅支持在 Linux 上构建 Linux 二进制；其他平台请走路径 A（从 Docker 运行 Nix）。
• 磁盘占用：Nix 的工作方式会占用较多磁盘空间，文档建议定期用nix-collect-garbage -d回收。
• 继续深入：Nix 环境同样服务于开发（nix develop、direnv 自动配置等），完整说明见 pkg/nix/README.md；各平台非 Nix 构建方式见 doc/BUILDING.md，该文档末尾同样指向 Nix 构建章节。

【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb