MongoDB Atlas Realm后端服务怎么用？从配置到实时同步完整实践

MongoDB Atlas Realm 是官方提供的托管后端服务平台，后来被整合进 Atlas App Services。它最吸引人的地方不是多了一个数据库，而是把数据同步、用户认证、权限规则和服务端函数放在同一个体系里，客户端只需要通过 Realm SDK 就能直接读写云端数据，中间的 API 层可以大幅简化。

一、Realm 与 Atlas App Services 的关系

很多第一次接触 Realm 的开发者会把它和移动端本地数据库混在一起。实际上，Realm 早期是一个嵌入式数据库，后来 MongoDB 收购了它，并把它的同步能力接到了 Atlas 云数据库上。现在所说的 Realm 后端服务，通常指的是 Atlas App Services 中的 Device Sync、Data API、Functions 和 Triggers 这些能力。

Device Sync 负责客户端与 MongoDB Atlas 之间的双向同步。它不是简单的轮询，而是基于操作日志和内部版本号来合并冲突。客户端在离线状态下写入的数据会先进入本地队列，网络恢复后再自动上传。服务端如果发生了其他设备的修改，也会推送到当前客户端。这个机制让离线优先应用不用自己实现复杂的同步状态机。

除了同步，App Services 还提供匿名登录、邮箱密码登录、Google、Apple 等多种认证方式。用户体系可以和同步规则配合，例如只允许用户读写自己创建的数据。服务端函数则用来执行一些不适合放在客户端的逻辑，比如调用第三方支付接口、做数据清洗或者发送通知。

二、创建应用并配置数据同步

要使用 Realm 后端服务，首先要有一个 MongoDB Atlas 集群。登录 Atlas 控制台后，在左侧菜单选择 App Services，然后点击 Create a New App。创建时需要关联一个集群，并填写应用名称。应用创建完成后，控制台会显示一个 App ID，客户端初始化时会用到这个 ID。

接下来是开启 Device Sync。在 App Services 控制台进入 Device Sync 页面，选择一个集合并定义分区键。分区键决定数据如何在客户端之间隔离，例如按用户 ID 或项目 ID 分区。分区键不合理的后果是某个分区的读写压力过大，但中小项目通常用固定字符串作为分区值也能跑得很稳。

同步配置里还有一个重要概念叫模式（Schema）。Realm 会把 MongoDB 集合的结构映射成客户端可以理解的对象模型。你可以在控制台手动定义字段类型，也可以直接让客户端在首次同步时自动生成。自动生成适合原型验证，但生产环境建议手动维护，因为字段类型变更会影响旧版本客户端。

下面是一个简单的同步配置示例，它表示对 tasks 集合开启同步，分区键为 ownerId：

{
  "collection": "tasks",
  "database": "todo",
  "partition": {
    "key": "ownerId",
    "type": "string"
  },
  "sync": {
    "state": "enabled"
  }
}

配置完成后，最好先创建一个匿名认证提供者。匿名认证适合快速开发，但正式发布时建议至少加上邮箱密码或第三方登录。认证提供者的开关在 Authentication 页面，打开 Anonymous Authentication 后，客户端就可以用匿名凭证登录并开始同步。

三、用 Node.js SDK 接入并读写数据

在 Node.js 环境中接入 Realm 后端服务，需要安装 realm 包。这个包同时包含本地数据库和同步客户端。创建项目后执行 npm install realm，然后初始化 App 并登录匿名用户。下面的代码展示了从登录到打开同步 Realm 的基本流程：

const Realm = require("realm");

const app = new Realm.App({ id: "your-app-services-id" });

async function openSyncedRealm() {
  const credentials = Realm.Credentials.anonymous();
  const user = await app.logIn(credentials);

  const TaskSchema = {
    name: "Task",
    properties: {
      _id: "objectId",
      name: "string",
      status: "string",
      ownerId: "string"
    },
    primaryKey: "_id"
  };

  const realm = await Realm.open({
    schema: [TaskSchema],
    sync: {
      user: user,
      partitionValue: "demo-partition"
    }
  });

  return realm;
}

openSyncedRealm().then(realm => {
  console.log("同步 Realm 已打开", realm.path);
});

这个例子中，分区值 demo-partition 对应控制台配置的分区键。实际使用时，分区值通常是当前登录用户的 ID 或者项目 ID。schema 里的字段名和类型必须与控制台定义一致，否则同步会报错。objectId 类型对应 MongoDB 的 ObjectId，字符串字段直接写 string。

同步 Realm 打开后，写入数据的方式和本地 Realm 几乎一样。所有写操作必须放在 write 事务里，Realm 会自动把变更上传到 Atlas。如果你需要在写入后立即读取，直接查询即可，本地已经是最新状态。下面的代码创建一个任务，并设置变更监听：

realm.write(() => {
  realm.create("Task", {
    _id: new Realm.BSON.ObjectId(),
    name: "完成周报",
    status: "open",
    ownerId: "demo-partition"
  });
});

const tasks = realm.objects("Task").filtered("status == 'open'");
tasks.addListener((collection, changes) => {
  changes.insertions.forEach(index => {
    console.log("新增任务", collection[index].name);
  });
});

监听器在数据发生变化时触发，无论变化来自本地写入还是远程同步。这个特性很适合用来驱动 UI 更新。需要注意的是，Realm 对象是懒加载的，只有访问属性时才会真正读取数据，所以大量数据场景下要避免一次性遍历所有对象。

在 React Native、Flutter 或 Web 前端中，SDK 的 API 基本一致，只是包名和初始化方式略有差异。核心概念如 partitionValue、sync、write 事务和 addListener 都是通用的。理解了 Node.js 版本，迁移到其他平台会非常自然。

四、服务端函数与数据库触发器

有些业务逻辑放在客户端并不合适，例如发送欢迎邮件、调用支付网关、或者对写入的数据做二次加工。Atlas Functions 就是运行在服务端的 JavaScript 函数，可以通过 SDK 或 HTTP 端点调用。函数里可以直接访问 MongoDB 集合，并且能拿到当前用户上下文。

下面这个函数在任务集合发生插入时被触发，它把高优先级任务自动标记为紧急。代码来自数据库触发器的模板，函数参数 changeEvent 包含变更前后的文档：

exports = async function(changeEvent) {
  const doc = changeEvent.fullDocument;
  const collection = context.services
    .get("mongodb-atlas")
    .db("todo")
    .collection("tasks");

  if (doc.priority === "high") {
    await collection.updateOne(
      { _id: doc._id },
      { $set: { urgent: true } }
    );
  }
};

要让它工作，需要在 Triggers 页面创建一个 Database Trigger，选择监听 tasks 集合的 Insert 操作，并关联到这个函数。触发器可以配置匹配表达式，只处理满足条件的文档，减少不必要的函数执行。函数超时时间默认较短，复杂任务记得在设置里调大，或者拆分成多个小函数。

Functions 还可以通过 SDK 直接调用。客户端执行 app.currentUser.functions.markTaskUrgent(taskId) 就能触发服务端逻辑。与直接操作数据库相比，函数调用会多一次网络往返，但换来的是权限可控和逻辑集中。对于需要服务端校验的操作，优先使用函数而不是开放客户端直接写集合。

五、权限规则与上线前检查

权限规则是 Realm 后端安全模型的核心。即使客户端登录成功，也不意味着它可以读写任何数据。App Services 使用类似 JSON 的规则表达式来限制集合访问。下面是一个常见的 owner 规则，只允许用户读写 ownerId 等于自己用户 ID 的文档：

{
  "roles": [
    {
      "name": "owner",
      "apply_when": {},
      "document_filters": {
        "read": { "ownerId": "%%user.id" },
        "write": { "ownerId": "%%user.id" }
      },
      "read": true,
      "write": true
    }
  ]
}

规则中的 %%user.id 是运行时变量，代表当前登录用户的身份标识。document_filters 会把过滤条件自动附加到每次查询和写入上，即使客户端尝试读取别人的数据，服务端也会返回空集。规则测试器可以在控制台模拟不同用户请求，验证规则是否符合预期。

上线前还需要检查同步分区是否合理、认证提供者是否已经关闭匿名登录、函数是否有异常捕获、以及客户端版本兼容策略。Device Sync 对模式变更比较敏感，生产环境不要直接在控制台修改字段类型，建议通过版本迁移的方式逐步升级。如果数据量很大，也要关注初始同步时间，必要时为移动端设计增量同步窗口。

总体来说，MongoDB Atlas Realm 后端服务适合那些不想自己维护 WebSocket 同步、认证和权限体系的团队。它在移动端和轻量级实时应用里优势明显，但如果你已经有成熟的 REST API 架构，完全迁移过去并不是必须的。用对场景，这个工具可以省下大量基础设施代码。

MongoDB Atlas Realm后端服务实时数据同步修改时间：2026-09-27 03:20:27