Sync Gateway无法同步自定义Collection至移动端数据库的问题排查

问题 #

我是Couchbase新手，现需解决以下同步问题：在React Native Android（Kotlin）应用中启动复制流程时，若Sync Gateway未配置自定义Scope和Collection，默认Collection可正常同步；但使用自定义Collection时数据无法同步，Sync Gateway抛出相关错误。

错误日志 #

2025-02-05 11:00:26 2025-02-05T05:30:26.057Z [INF] HTTP: c:#008 db:sampledb GET /sampledb/_blipsync (as <ud>syncuser</ud>)
2025-02-05 11:00:26 2025-02-05T05:30:26.057Z [INF] HTTP+: c:[53456386] db:sampledb #008:     --> 101 [53456386] Upgraded to WebSocket protocol BLIP_3+CBMobile_3 (as <ud>syncuser</ud>)  (0.0 ms)
2025-02-05 11:00:26 2025-02-05T05:30:26.057Z [INF] WS: c:#008 db:sampledb Start BLIP/Websocket handler
2025-02-05 11:00:26 2025-02-05T05:30:26.066Z [INF] SyncMsg: c:[53456386] db:sampledb #1: Type:getCheckpoint   --> 400 Collection property not specified and default collection is not configured for this database Time:55.009µs
2025-02-05 11:00:26 2025-02-05T05:30:26.068Z [INF] SyncMsg: c:[53456386] db:sampledb #2: Type:proposeChanges   --> 400 Collection property not specified and default collection is not configured for this database Time:12.612µs
2025-02-05 11:00:26 2025-02-05T05:30:26.073Z [INF] SyncMsg: c:[53456386] db:sampledb #3: Type:subChanges   --> 400 Collection property not specified and default collection is not configured for this database Time:20.531µs
2025-02-05 11:00:26 2025-02-05T05:30:26.082Z [INF] WS: c:#008 db:sampledb Error: receiveLoop exiting with WebSocket error: failed to get reader: received close frame: status = StatusCode(4002) and reason = "Unrecognized collection"
2025-02-05 11:00:26 2025-02-05T05:30:26.133Z [INF] WS: c:#008 db:sampledb BLIP/Websocket Handler exited with error: failed to get reader: received close frame: status = StatusCode(4002) and reason = "Unrecognized collection"
2025-02-05 11:00:26 2025-02-05T05:30:26.133Z [INF] HTTP: c:[53456386] db:sampledb #008:     --> BLIP+WebSocket connection error: failed to get reader: received close frame: status = StatusCode(4002) and reason = "Unrecognized collection"
2025-02-05 11:00:26 2025-02-05T05:30:26.133Z [INF] HTTP: c:[53456386] db:sampledb #008:    --> BLIP+WebSocket connection closed

Sync Gateway配置 #

数据库配置

{
    "bucket": "sample",
    "scopes": {
        "scope1": {
            "collections": {
                "collection1": {
                    "sync": "function(doc){channel(\"*\");}",
                    "import_filter": "function(doc) { return true; }"
                }
            }
        }
    },
    "name": "sampledb",
    "import_docs": true,
    "enable_shared_bucket_access": true,
    "num_index_replicas": 0
}

用户配置

{
    "name": "syncuser",
    "admin_channels": [
        "!",
        "*",
        "project1"
    ],
    "collection_access": {
        "scope1": {
            "collection1": {
                "admin_channels": [
                    "!",
                    "*",
                    "project1"
                ],
                "all_channels": [
                    "!",
                    "*",
                    "project1"
                ]
            }
        }
    },
    "email": "",
    "disabled": false
}

React Native Android（Kotlin）代码 #

var database = Database("sampledb")
val config = ReplicatorConfigurationFactory.newConfig(
        collections = mapOf(database.collections to null),  
        target = URLEndpoint(URI("ws://IPADDRESS/sampledb")),
        type = ReplicatorType.PUSH_AND_PULL,
        authenticator = BasicAuthenticator("syncuser", "helloworld".toCharArray())
    )

val replicator = Replicator(config)
replicator.start()

解决方案 #

1. 修正客户端代码的集合映射配置 #

问题核心是客户端代码使用了默认集合（database.collections），但Sync Gateway未配置默认集合，仅配置了自定义的scope1.collection1，导致同步时无法匹配到正确集合。修改代码指定自定义集合的映射：

var database = Database("sampledb")

// 获取或创建本地的自定义Scope和Collection
val scope = database.getOrCreateScope("scope1")
val collection = scope.getOrCreateCollection("collection1")

// 配置复制器时，映射本地集合到远程的scope1.collection1
val config = ReplicatorConfigurationFactory.newConfig(
        collections = mapOf(collection to "scope1.collection1"),  
        target = URLEndpoint(URI("ws://IPADDRESS/sampledb")),
        type = ReplicatorType.PUSH_AND_PULL,
        authenticator = BasicAuthenticator("syncuser", "helloworld".toCharArray())
    )

val replicator = Replicator(config)
replicator.start()

2. 验证Couchbase Server端的Scope和Collection存在 #

确保Couchbase Server的sample bucket中已创建scope1和collection1，Sync Gateway的配置是映射到Server端已存在的Scope/Collection，否则会出现无法找到集合的错误。

3. 可选：为Sync Gateway配置默认集合（兼容默认场景） #

如果需要保留默认集合的同步能力，可在Sync Gateway的数据库配置中添加默认集合配置：

{
    "bucket": "sample",
    "scopes": {
        "_default": {
            "collections": {
                "_default": {
                    "sync": "function(doc){channel(\"*\");}",
                    "import_filter": "function(doc) { return true; }"
                }
            }
        },
        "scope1": {
            "collections": {
                "collection1": {
                    "sync": "function(doc){channel(\"*\");}",
                    "import_filter": "function(doc) { return true; }"
                }
            }
        }
    },
    "name": "sampledb",
    "import_docs": true,
    "enable_shared_bucket_access": true,
    "num_index_replicas": 0
}

此步骤为可选，若仅需使用自定义集合，无需配置。

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