开源实时数据库Lark：兼容Firebase SDK的自托管实战指南

在做实时协作类小工具的时候，最顺手的客户端方案往往是 Firebase Realtime Database：前端几条 API 就能完成数据读写、实时监听和离线缓存，开发效率确实很高。但一旦需要把服务部署到自有环境，或者业务有数据本地化、私有化要求，Firebase 这类云托管服务就会卡住——它本身不提供自托管能力。最近我在 HN 上看到一个名为 Lark 的开源实时数据库项目，主打与 Firebase SDK 的 drop-in compatible（即插即用兼容），于是把它完整地部署、接入、压了一遍，整理成这篇教程。文章会从项目背景、核心概念、部署方式、客户端接入、常见报错一直讲到生产环境建议，适合已经熟悉 Firebase、正在调研开源替代方案的开发者，也适合想了解实时数据库底层原理的读者。

1. 背景：为什么需要开源实时数据库

1.1 从 Firebase Realtime Database 说起

Firebase Realtime Database 是 Google 推出的一款实时云数据库，它的特点是数据以 JSON 树形结构存储，客户端 SDK 可以监听某个路径下的数据变化，服务端会通过长连接把变更实时推送给所有订阅者。

它在原型验证、小中型应用里面很受欢迎，尤其是在 Web、Android、iOS 多端同步场景下，官方 SDK 几乎把底层通信全部封装好了，开发者只要关心业务数据结构即可：

• 写入数据：set(ref(db, 'todos/1'), { title: 'hello' })
• 读取数据：get(child(ref(db), 'todos/1'))
• 监听变化：onValue(ref(db, 'todos/1'), callback)

这种 API 设计的优点是学习成本低、调用链路短。但对于有私有化部署需求的产品而言，Firebase 作为托管服务无法直接搬进内网，也缺少对数据存储位置的自主控制权，这就促使团队去寻找自托管方案。

1.2 云托管服务的现实痛点

在实际工程中，团队决定放弃云托管实时数据库，原因通常集中在以下几个方面：

• 数据主权和合规要求：某些行业要求业务数据必须存放在指定地域的私有环境中，不能直接上传到第三方云平台。
• 网络可用性：公网云服务的访问质量在不同地区差异较大，自建服务可以部署到离用户更近的机房，或者直接放在内网。
• 成本控制：实时数据库的流量和连接数在用户量上来之后会成为一笔不小的开销，自托管能比较稳定地预估运行成本。
• 定制需求：云服务很难改底层实现，例如自定义鉴权逻辑、修改推送策略、接入已有的监控体系，开源项目则不存在这个限制。

这意味着“开源实时数据库”的需求是真实存在的：既要做到客户端接入足够简单，又要让团队能把服务端完全掌握在自己手中。

1.3 认识 Lark：开源实时数据库

Lark 就是这样一个面向上述场景的开源项目。它对外提供与 Firebase Realtime Database 高度一致的接口，包括数据读写路径、实时推送机制和客户端 SDK 兼容层，让原本运行在 Firebase 上的前端代码可以尽量少改动地迁移到自己托管的服务上。

项目标题里强调了两个关键词：

• OSS：这里指的是 Open Source Software，即开源软件，说明项目是开放源码、可自行构建和部署的。
• drop-in compatible：可以理解为“即插即用替代”。在工程语境里，drop-in replacement 表示替换组件时不需要修改原有调用方代码，只要接上就能工作。

所以 Lark 的核心价值不是重新发明一套实时数据库 API，而是做一个兼容层，让 Firebase 开发者能无缝切换到自托管环境。

1.4 先分清两个 OSS

搜索 Lark 相关资料时，你可能会搜到大量关于“OSS”的教程，不过那些教程大多讨论的是阿里云对象存储（Object Storage Service），也就是 OSS 的另一种常见含义。做技术检索时很容易踩到这个坑：

• Open Source Software（OSS）：开源软件，Lark 项目标题里的 OSS 是这层含义。
• Object Storage Service（OSS）：对象存储服务，例如阿里云 OSS、AWS S3，用于保存图片、文件等静态资源。

如果你看到“头像啥的图片用服务器的 oss 对象存储”“fastadmin 上传到阿里云 oss”这类内容，它们讨论的是对象存储，和 Lark 数据库不在一个技术栈里。本文只围绕开源实时数据库展开，不涉及对象存储的配置。

2. 环境准备

在开始部署和接入之前，先确认环境。由于 Lark 是近几年出现的开源项目，版本更新节奏较快，以下版本信息不作为唯一标准，请以你实际拉取到的项目文档为准。

2.1 服务端运行环境

Lark 服务端以独立进程方式运行，部署方式主要有两种：

• 直接下载编译好的二进制文件，运行在 Linux 或 macOS 服务器上。
• 使用 Docker 容器运行，适合已有容器化基础设施的团队。

建议本地开发环境至少满足：

如果你打算从源码编译，再准备一套 Go 开发环境，并确保能够正常拉取项目依赖。

go version

如果输出正常，就可以继续。

2.2 客户端开发环境

客户端我们使用最熟悉的 Web 环境来验证集成效果：

这里要强调一个概念：Lark 兼容的是 Firebase Realtime Database 的协议与接入方式，所以客户端仍然使用firebase官方 npm 包，不需要额外引入 Lark 自己的客户端。

2.3 示例项目结构

我们用一个很简单的待办事项应用来演示完整链路：

my-lark-demo/ ├── package.json ├── index.js └── public/ └── index.html

• package.json：声明依赖和启动脚本。
• index.js：Node.js 端的数据写入脚本，负责初始化 SDK 并写入基础数据。
• public/index.html：浏览器端页面，展示实时监听效果。

3. 核心原理拆解

要理解 Lark 为什么能做到与 Firebase SDK 兼容，先要理解实时数据库的几个核心机制。

3.1 实时数据库的数据模型

Firebase Realtime Database 的数据结构是一棵 JSON 树。也就是说，整个数据库可以看作一个大的 JSON 对象，每条数据都有唯一路径：

{ "todos": { "task1": { "title": "写博客", "done": false }, "task2": { "title": "部署 Lark", "done": true } } }

路径/todos/task1对应对象{ "title": "写博客", "done": false }。这种模型的优势是访问路径直观，客户端只需要关心自己要读写的子路径，而不需要了解全局表结构。

Lark 在数据组织上沿用同样的思路，因此 Firebase SDK 里所有基于路径的读写操作都能映射到 Lark 服务端。

3.2 实时同步的底层通道

所谓“实时数据库”，指的是服务端能在数据发生变化时，主动通知所有正在监听该路径的客户端。这个“主动通知”不可能通过普通 HTTP 轮询来实现，通常需要持久连接。

常见的实时推送技术有：

• WebSocket：全双工通信，适合高频双向交互。
• SSE（Server-Sent Events）：单向服务端推送，实现简单，浏览器原生支持。
• 长轮询：兼容性好，但实时性略差。

Firebase SDK 在 Web 端会根据环境自动选择合适的连接方式。Lark 要做 drop-in compatible，就要求服务端至少实现与 Firebase SDK 相同的连接协商逻辑，客户端才能无感知地建立通道。这也是整个兼容层最核心的部分。

3.3 与 Firebase SDK 的兼容逻辑

从开发者视角看，Lark 的兼容性体现在两个层面：

1. REST API 兼容：Firebase Realtime Database 的 REST 接口是https://<databaseURL>/<path>.json，Lark 同样遵循这一风格。
2. SDK 连接协议兼容：Firebase Web SDK 初始化时，会向服务的根路径发送请求做能力探测，并尝试建立实时通道；Lark 需要正确响应这些探测，SDK 才会继续后续数据操作。

这也是为什么前面说“代码几乎不用改”：因为前端面对的还是同一个 SDK，只是databaseURL指向了 Lark 服务。

3.4 离线缓存与数据一致性

之前看到有开发者搜索“lark 缓存放哪里可以设置吗”，这里其实有两个层面的缓存问题：

• 如果问的是 Lark 服务端的数据落盘位置，这取决于部署时配置的数据目录，一般通过环境变量或启动参数指定。
• 如果问的是 Firebase SDK 本地离线缓存，那属于浏览器端能力，和 Lark 服务端没有直接关系。

Firebase Web SDK 默认会维护本地缓存，以加快重复读取速度，并在离线期间暂存写入操作。切换成 Lark 后，SDK 的离线缓存机制仍然生效，但要注意：离线期间的数据冲突策略由客户端决定，服务端只负责最终的数据合并请求。自托管场景下，如果业务对数据一致性要求很高，建议在应用层做好冲突检测。

4. 完整实战案例

接下来一步步完成部署、接入、验证。整个流程里，请你留意“为什么这样做”，而不是只复制命令。

4.1 部署 Lark 服务端

4.1.1 通过二进制方式启动

到 Lark 官方 Release 页面下载对应平台的二进制文件后，放入~/bin，然后启动：

mkdir -p ~/lark-data ./lark --port 8080 --data-dir ~/lark-data

启动后终端会出现类似日志：

[Lark] listening on :8080 [Lark] data dir: /root/lark-data

如果--data-dir参数名称不同，请以项目 README 为准。重点是确认两个信息：监听端口、数据持久化目录。

4.1.2 通过 Docker 启动

如果你用 Docker，可以用下面的方式启动：

docker run -d --name lark \ -p 8080:8080 \ -v $PWD/lark-data:/data \ -e DATA_DIR=/data \ <lark-image>

这里<lark-image>需要替换为项目文档中提供的镜像名称。使用-v把宿主机目录挂载进容器，这样才能保证容器重建后数据不丢。

启动后，用 curl 验证服务可用：

curl http://localhost:8080/.json

如果返回null或空 JSON，说明服务正常响应了根路径请求。

4.2 初始化前端 SDK

新建项目并安装依赖：

mkdir my-lark-demo cd my-lark-demo npm init -y npm install firebase

在 Node.js 侧，初始化 SDK 只需要一个关键参数：databaseURL。

// 文件路径：my-lark-demo/index.js const { initializeApp } = require('firebase/app'); const { getDatabase, ref, set, update } = require('firebase/database'); const firebaseConfig = { databaseURL: 'http://localhost:8080' }; const app = initializeApp(firebaseConfig); const db = getDatabase(app); async function main() { const todoRef = ref(db, 'todos/task1'); await set(todoRef, { title: '写一篇 Lark 实战教程', done: false }); const statusRef = ref(db, 'status'); await update(statusRef, { online: true, updatedAt: Date.now() }); console.log('数据写入成功'); process.exit(0); } main().catch((err) => { console.error('写入失败', err); process.exit(1); });

需要注意的是，自托管环境下如果databaseURL是http协议，浏览器访问时会被当作混合内容拦截。建议本地联调时用http://localhost，生产环境则用 HTTPS 域名，后面排查部分会再展开。

运行脚本：

node index.js

正常情况下控制台输出“数据写入成功”。此时用 REST API 可以查看到刚才写入的数据：

curl http://localhost:8080/todos/task1.json

返回结果：

{ "title": "写一篇 Lark 实战教程", "done": false }

4.3 浏览器端实时监听

写入数据只是第一步，实时功能才是重点。创建一个页面，用它展示数据变化：

<!-- 文件路径：my-lark-demo/public/index.html --> <!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8" /> <title>Lark Realtime Demo</title> </head> <body> <h3>待办事项监控面板</h3> <div id="task-title">暂无数据</div> <script type="module"> import { initializeApp } from 'https://www.gstatic.com/firebasejs/10.12.0/firebase-app.js'; import { getDatabase, ref, onValue, child } from 'https://www.gstatic.com/firebasejs/10.12.0/firebase-database.js'; const firebaseConfig = { databaseURL: 'http://localhost:8080' }; const app = initializeApp(firebaseConfig); const db = getDatabase(app); const taskRef = child(ref(db, 'todos'), 'task1'); onValue(taskRef, (snapshot) => { const data = snapshot.val(); const titleEl = document.getElementById('task-title'); if (data) { titleEl.textContent = `${data.title} - 完成状态：${data.done}`; } else { titleEl.textContent = '暂无数据'; } }); </script> </body> </html>

这里使用的是 Firebase Web SDK v10 的 CDN 写法。你可以根据项目实际情况选择 npm 打包或 CDN 引用，关键是databaseURL指向 Lark。

启动一个本地静态服务器：

npx serve public

浏览器打开http://localhost:3000，页面会显示 task1 的数据。这种实时监听是双向的：服务端数据变化后，浏览器不用刷新页面就能收到推送。

为了验证这一点，可以再执行一次 Node 脚本，把done改成true：

// 文件路径：my-lark-demo/update.js const { initializeApp } = require('firebase/app'); const { getDatabase, ref, update } = require('firebase/database'); const app = initializeApp({ databaseURL: 'http://localhost:8080' }); const db = getDatabase(app); update(ref(db, 'todos/task1'), { done: true }).then(() => { console.log('更新完成'); }).catch((err) => { console.error(err); });

运行：

node update.js

回到浏览器页面，你会看到“完成状态”由 false 变成 true，整个过程不需要刷新页面。

4.4 REST API 快速验证

有时候不想引入 SDK，只想验证服务端数据，可以直接使用 REST API。Firebase Realtime Database 风格的接口在 Lark 下同样适用。

新增数据：

curl -X PUT http://localhost:8080/todos/task2.json \ -H 'Content-Type: application/json' \ -d '{"title": "完成部署", "done": true}'

查询整棵数据树：

curl http://localhost:8080/todos.json

删除数据：

curl -X DELETE http://localhost:8080/todos/task2.json

注意：删除操作不可逆，生产环境务必确认路径无误。

4.5 结果说明

到这里你已经跑通了一条完整链路：

1. Lark 服务端接收 REST 请求并持久化数据。
2. Firebase SDK 通过databaseURL连接 Lark，正常执行set、update。
3. 浏览器端onValue监听能实时收到变化。
4. 用 curl 直接操作 REST 接口也能读写数据。

这意味着，如果之前项目里的客户端代码只依赖 Firebase Realtime Database 的常规 API，迁移成本确实很低。

5. 常见问题与排查

自托管实时数据库和云托管不同，很多问题需要自己处理。下面按“现象—原因—排查—解决”的路径来梳理。

5.1 连接不上服务端

本地调试时，优先用curl http://localhost:8080/.json来判断服务是否存活。如果 curl 正常但 SDK 连接失败，要检查databaseURL是否写成了https://而服务端只支持http://。

5.2 数据写入失败、无反馈

写入操作报错的情况通常集中在路径权限和请求格式上。Firebase 的set会覆盖目标路径的整个子树，update只做深层合并。如果你不确定数据是否写入，先用 REST 查一次：

curl http://localhost:8080/<你的路径>.json

如果返回null，说明路径下还没有数据，需要检查写入代码是否执行成功。

5.3 实时监听不触发

onValue不触发，常见原因有几个：

• 监听的路径和数据写入路径不一致，比如监听todos/task1，写入的是todos/task1/title，这种情况 task1 节点仍然会触发回调，但如果你监听的是更深的路径就可能错过。
• 页面存在多个 Firebase 实例，但databaseURL指向了不同服务。
• 浏览器缓存了旧连接，刷新页面或强刷（Ctrl+Shift+R）后重试。

建议先在新开的无痕窗口里验证，排除浏览器缓存干扰。

5.4 跨域请求被拦截

浏览器安全策略会拦截跨域 HTTP 请求。如果你把页面部署在http://localhost:3000，而 Lark 运行在http://localhost:8080，跨域问题就必然存在。

解决方向有两个：

• 开发阶段：让 Lark 支持合适的 CORS 响应头，允许来源域名访问。
• 生产阶段：用 Nginx 做反向代理，把/路径同时代理到前端静态资源服务和 Lark 服务，使前端页面与数据库服务处于同源下，从根源消除跨域。

如果 Lark 暂未内置 CORS 配置项，可以前置一层 Nginx 处理，这也是自托管服务最灵活的地方。

# 文件路径：/etc/nginx/conf.d/lark.conf（示意） server { listen 80; server_name your-domain.com; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } }

这段配置能让 WebSocket 和普通 HTTP 请求都正确代理到 Lark 服务。

5.5 缓存与数据一致性

浏览器端 Firebase SDK 自带本地缓存，这是它的特性而不是 bug。但要注意：如果多个客户端都处于离线状态，各自写入同一路径的数据在恢复连接时可能发生冲突。

自托管场景下，建议在应用层面保持一个单调递增的版本号或时间戳字段，业务在读取时自行判断以哪条数据为准。不要依赖服务端做复杂的事务合并，除非项目文档明确说明支持。

6. 最佳实践与工程建议

6.1 私有化部署的安全边界

把实时数据库部署到自有环境，意味着安全防护责任也从云厂商转移到了自己身上。最重要的原则是最小权限。

• 不要直接把 Lark 端口暴露到公网，除非你做好了身份认证和加密传输。
• 在服务前面加一层反向代理，统一管理 HTTPS 证书、访问日志和限流策略。
• 如果 Lark 本身没有实现类似 Firebase Security Rules 的权限体系，你需要在应用网关层自行校验请求来源，或者在内网中让 Lark 只对可信服务开放。
• 生产环境不要使用默认管理员凭证，也不要让客户端直接持有写权限的密钥。

6.2 数据备份与恢复

实时数据库是核心状态服务，备份策略必须先行。建议：

• 定时导出 JSON 快照到独立存储：curl http://localhost:8080/.json > backup-20250101.json。
• 对数据目录做持久化备份，Docker 部署时确保-v挂载的是持久卷。
• 任何变更操作前，先在测试环境验证备份可恢复，不要等到生产故障才检查备份脚本。

备份文件如果包含用户敏感信息，还需要做好加密存储和访问控制。

6.3 高性能读写策略

数据量增大后要注意写路径的拆分。因为 Firebase 风格的数据是一棵 JSON 树，一次set可能覆盖较大的子树，频繁更新大节点会带来不必要的网络和数据序列化开销。

建议：

• 把更新频率高的字段拆到独立子路径，例如online/status单独维护。
• 页面实时监听时，尽量监听最小需要的路径，而不是监听根路径。
• 对历史数据做冷热分离，不把日志类数据高频写入实时数据库主节点。

6.4 开源许可证与合规排查

使用开源软件时，许可证合规不能忽视。团队引入 Lark 后，建议在项目里做一次开源依赖扫描。过程中可能会用到 Black Duck、FOSSA 之类的扫描工具，它们能自动列出项目依赖的开源组件、对应许可证以及潜在风险。

扫描时重点确认：

• Lark 自身采用什么开源许可证：MIT、Apache-2.0 还是其他，不同许可证对商用、修改和再分发的要求不同。
• 客户端引入的 Firebase SDK 与项目本身的许可证是否冲突。
• 如果公司有开源合规规范，需要把扫描结果归档，并记录到依赖清单里。

这类合规排查在商业化产品中很重要，不要等到上架前才发现某个依赖使用了不合适的许可证。

7. 总结与学习路线

本文从实际需求出发，围绕 Lark 这个开源实时数据库项目，梳理了它出现的背景、核心原理和完整接入流程。你可以在自己的服务器上部署一套与 Firebase SDK 兼容的实时数据库，用 Web SDK 完成数据写入、读取和实时监听，并通过 REST API 做快速验证和调试。同时，你还掌握了自托管实时数据库在安全、备份、缓存和开源合规方面的基本注意事项。

如果想继续深入，下一步可以从这几个方向入手：

• 研究 Lark 的源码，重点看实时推送通道的实现方式，对比 HTTP 轮询、SSE、WebSocket 的差异。
• 在真实业务项目中设计一套数据结构，测试大节点更新性能和多端并发一致性。
• 研究 Firebase Security Rules 的语义，思考如何在 Lark 服务端复刻类似的权限模型。
• 做一次完整的开源许可证合规扫描，把 Lark 接入公司依赖治理流程。

自托管实时数据库的技术栈还在快速发展，Lark 这类兼容层项目降低了 Firebase 用户迁移的门槛。建议你在测试环境小范围验证，确认数据模型、权限设计和运维工具都满足要求后，再逐步把流量迁过去。