couchbase/edge-server

Couchbase Edge Server Docker镜像文档

镜像概述和主要用途

Couchbase Edge Server是Sync Gateway的轻量级自包含替代方案，用于安全管理https://www.couchbase.com/products/lite%E3%80%81%E5%85%B6%E4%BB%96Edge Server部署与https://www.couchbase.com/products/sync-gateway%E4%B9%8B%E9%97%B4%E7%9A%84%E6%95%B0%E6%8D%AE%E5%90%8C%E6%AD%A5%E3%80%82%E5%AE%83%E8%AE%BE%E8%AE%A1%E7%94%A8%E4%BA%8E%E4%B8%8D%E9%80%82%E5%90%88%E5%AE%8C%E6%95%B4%E4%BA%91%E9%83%A8%E7%BD%B2%E7%9A%84%E7%8E%AF%E5%A2%83%EF%BC%8C%E6%8F%90%E4%BE%9B%E6%9C%AC%E5%9C%B0%E6%95%B0%E6%8D%AE%E7%AE%A1%E7%90%86%E5%92%8C%E5%90%8C%E6%AD%A5%E8%83%BD%E5%8A%9B%E3%80%82

核心功能和特性

• 轻量级部署：自包含架构，资源占用低，适合边缘环境
• 安全同步：支持TLS加密和用户认证，确保数据传输安全
• 灵活配置：可通过配置文件自定义数据库路径、TLS证书、用户权限等
• 持久化存储：支持Docker卷挂载，实现配置和数据的持久化
• 兼容性：与Couchbase Lite客户端和Sync Gateway无缝集成

使用场景和适用范围

• 边缘计算环境：物联网设备、本地服务器等资源受限场景
• 离线优先应用：需要本地数据存储和同步的移动或桌面应用
• 分布式部署：多边缘节点间的数据协同与同步
• 测试与开发：快速搭建本地Edge Server环境进行应用测试

详细使用方法和配置说明

快速开始：使用Docker运行Edge Server

基本运行命令

通过以下命令快速启动Edge Server容器：

bash
docker run -d --name edge-server -p 59840:59840 docker.xuanyuan.run/couchbase/edge-server

验证服务状态

启动后可通过curl验证服务是否正常运行：

bash
curl http://localhost:59840

预期响应：

json
{"couchdb":"Welcome","vendor":{"name":"Couchbase Edge Server","version":"1.0.0 (26; )"},"version":"CouchbaseEdgeServer/1.0.0 (26; ) CouchbaseLiteCore/0.0.0-EE (770a516a19d505b7+219a0c1909febc53)"}

此默认配置启动一个空数据库，容器关键路径如下：

• /opt/couchbase-edge-server/bin：可执行文件目录
• /opt/couchbase-edge-server/lib：库文件目录
• /opt/couchbase-edge-server/etc/config.json：配置文件
• /opt/couchbase-edge-server/var/databases：数据库存储目录

查看日志

通过Docker日志命令查看Edge Server运行日志：

bash
docker logs edge-server

示例日志输出：

2025-01-24T01:59:00.276Z        Using server TLS certificate: CN=127.0.0.1
2025-01-24T01:59:00.277Z        Starting Couchbase Edge Server 1.0.0 (26; )
2025-01-24T01:59:00.339Z        Sharing database https://localhost:59840/db/ from file /opt/couchbase-edge-server/var/databases/example.cblite2

自定义Edge Server配置

使用Docker卷实现持久化部署

生产环境需将配置和数据目录挂载到容器外部，实现持久化存储。部署架构如下：

!https://raw.githubusercontent.com/couchbase/docker/master/generate/resources/couchbase-edge-server/diagrams/docker-mount.png

步骤1：准备本地工作目录

在本地创建工作目录（记为$LOCALPATH），并在其中创建etc（配置目录，只读）和databases（数据库目录，可读写）两个子目录：

bash
mkdir -p $LOCALPATH/{etc,databases}

[!CAUTION] Docker卷挂载的文件和文件夹权限配置可能较复杂。默认情况下，/opt/couchbase-edge-server目录下的所有挂载文件和文件夹必须可被UID 1000或GID 1000访问。请在$LOCALPATH中提前配置好权限，详情参见文件和文件夹权限说明。

步骤2：启动交互式容器并挂载配置目录

以交互模式启动容器，将本地etc目录挂载到容器内，并将入口点设为bash：

bash
docker run -it --rm --entrypoint=bash -v $LOCALPATH/etc:/opt/couchbase-edge-server/etc docker.xuanyuan.run/couchbase/edge-server

步骤3：创建TLS证书和密钥

容器内执行以下命令生成自签名TLS证书（仅用于测试，生产环境需使用正式证书）：

bash
couchbase-edge-server --create-cert $HOSTNAME cert.pem key.pem

• $HOSTNAME：服务器主机名，将记录在证书的CN字段中
• 生成的cert.pem（证书）和key.pem（密钥）将保存在挂载的etc目录中

[!IMPORTANT] key.pem包含敏感私钥信息，需严格保护，建议设置权限为600。

步骤4：创建服务器用户

在容器内执行以下命令创建HTTP认证用户（示例用户名为"alice"）：

bash
couchbase-edge-server --add-user --create users.json alice

执行后将提示输入两次密码（记为$PASSWORD），用户信息将保存到users.json文件中。

步骤5：创建配置文件

退出容器后，在$LOCALPATH/etc目录下创建config.json配置文件，内容如下：

json
{
    "$schema": "https://packages.couchbase.com/couchbase-edge-server/config_schema.json",
    "https": {
        "tls_cert_path": "/opt/couchbase-edge-server/etc/cert.pem",
        "tls_key_path": "/opt/couchbase-edge-server/etc/key.pem"
    },
    "users": "/opt/couchbase-edge-server/etc/users.json",
    "databases": {
        "db": {
            "path":  "/opt/couchbase-edge-server/var/databases/example.cblite2",
            "create": true,                   
            "enable_client_writes": true,
            "enable_client_sync": true
        }
    }
}

步骤6：启动生产环境容器

挂载etc和databases目录，启动生产环境容器：

bash
docker run -d -p 59840:59840 -v $LOCALPATH/etc:/opt/couchbase-edge-server/etc -v $LOCALPATH/databases:/opt/couchbase-edge-server/var/databases docker.xuanyuan.run/couchbase/edge-server

• 启动后，databases目录将自动创建example.cblite2数据库文件
• 访问API时需使用用户"alice"和密码$PASSWORD进行HTTP基本认证

[!IMPORTANT] 服务器运行期间修改配置文件或证书不会生效，需重启容器后生效。

文件和文件夹权限说明

此部分仅适用于Linux主机，非Linux主机可忽略，只需确保本地etc目录可读、databases目录可读写即可。

权限要求：

• etc目录：需可读（至少755权限），可被UID 1000或GID 1000访问
• databases目录：需可读写（至少775权限），可被UID 1000或GID 1000访问

自定义UID/GID：

若当前用户的UID非1000且GID列表不包含1000，可通过--user参数指定运行用户：

• 指定自定义UID：--user $uid
• 指定自定义UID和GID：--user $uid:$gid

推荐使用当前用户的GID配合UID 1000运行：

bash
--user 1000:$gid  # $gid为当前用户的GID（可通过`id`命令查看）

参考链接

• https://docs.couchbase.com/couchbase-edge-server/current/index.html
• https://forums.couchbase.com/c/mobile/edge-server