Flexible Sync Realm本地变更无法同步至Atlas问题排查

问题背景 #

存储Group对象的Realm Schema设计如下：

class Group : BaseEntity(), RealmObject {
    class UserInfo : EmbeddedRealmObject {
        var userId: Id? = null
        var username: String? = null
        var userBalance: Double = 0.0
    }

    @PrimaryKey
    override var _id: Id = createId()
    var groupName: String? = null
    var users: RealmList<Id> = realmListOf()
    var userInfo: RealmList<UserInfo> = realmListOf()
}

其中Group.users与Group.userInfo用于模拟字典结构（因Kotlin SDK暂不支持RealmDictionary及嵌入式对象查询）。同步订阅配置如下：

val config =
        SyncConfiguration.Builder(realmUser, setOf(Group::class, Group.UserInfo::class))
        .initialSubscriptions(rerunOnOpen = true) { realm ->
            add(realm.query<Group>("$0 IN users", userId))
        }
        .name("groupRealm")
        .build()

val realm: Realm by lazy { Realm.open(config) }

订阅目标是同步当前userId所属的所有Group对象，但出现以下问题：

• 本地Realm读写操作正常，但Atlas中的Group集合无对应更新；
• 添加.waitForInitialRemoteData()后代码超时，App Services日志出现OtherSessionError: operation canceled (ProtocolErrorCode=201)错误，且订阅查询结果为空。

排查步骤与解决方案 #

1. 修正订阅查询语法 #

Realm Kotlin SDK中针对RealmList的IN查询需确保语法和类型匹配，建议改用更直观的查询方式：

// 方式1：使用CONTAINS操作符
add(realm.query<Group>("users CONTAINS $0", userId))
// 方式2：Lambda式查询（推荐，可读性更高）
add(realm.query<Group> { users contains userId })

同时确认userId的类型为Realm原生Id类型，类型不匹配会导致查询无结果，引发订阅空数据问题。

2. 验证App Services权限配置 #

• 检查Group集合的同步规则，确保当前用户有权限访问包含自身userId的Group文档，示例规则：

  {
    "users": {
      "$elemMatch": {
        "$eq": "%%user.id"
      }
    }
  }
  

• 确认写入权限未被限制，若用户仅拥有读取权限，本地修改无法同步至Atlas。

3. 排查同步会话状态 #

• 先移除.waitForInitialRemoteData()：该方法会阻塞至初始同步完成，若订阅无匹配数据会直接超时。通过监听同步进度排查：

  realm.syncSession.addProgressListener(ProgressDirection.DOWNLOAD) { progress ->
      println("下载进度: ${progress.transferredBytes}/${progress.totalBytes}")
      if (progress.isTransferComplete) {
          println("初始同步完成")
      }
  }
  

• 启用详细日志排查细节：

  SyncConfiguration.Builder(realmUser, setOf(Group::class, Group.UserInfo::class))
      .log(LogLevel.ALL)
      .initialSubscriptions(rerunOnOpen = true) { realm ->
          add(realm.query<Group> { users contains userId })
      }
      .name("groupRealm")
      .build()
  

  查看日志中是否存在订阅创建失败、权限拒绝或数据不匹配的提示。

4. 确认嵌入式对象同步兼容性 #

确保Group.UserInfo作为嵌入式对象已正确注册到同步配置中，且Atlas的Group集合Schema与本地实体类结构一致（嵌入式对象会嵌套在Group文档内，无需单独集合）。若Schema不匹配，会导致同步数据丢失或失败。

5. 处理ProtocolErrorCode=201错误 #

该错误表示同步会话被取消，常见原因及解决：

• 订阅查询无匹配文档：确认Atlas中存在包含当前userId的Group数据，或调整查询逻辑；
• 网络不稳定：检查设备网络连接，尝试切换网络环境；
• App Services服务异常：重启App Services应用，或检查服务状态是否正常。

内容的提问来源于stack exchange，提问作者spikanor