CloudBeaver 26.2.3 Docker Compose 部署指南

Ubuntu 24.04 + Docker Compose 从零部署 CloudBeaver 26.2.3 实测指南：镜像标签选型、PostgreSQL/MariaDB 编排、初始管理员自动初始化、JVM 堆限 256-512MB 配置与三重验证、工作区持久化、HTTPS 前置反代建议，以及 CB_ADMIN_PASSWORD 双重哈希缺陷的完整排障实录。

CloudBeaverCloudBeaverDocker ComposeDocker2026/10/25

CloudBeaver 26.2.3 Docker Compose 部署指南

目标：在 Ubuntu 24.04 服务器上用 Docker Compose 从零部署 CloudBeaver Community 26.2.3（网页版数据库管理台），覆盖镜像选型、应用与 PostgreSQL 16 / MariaDB 11.8 三服务编排、初始管理员自动初始化、JVM 堆内存限制与验证、工作区持久化、HTTPS 前置反代建议与管理员口令排障实录。文中全部命令与回显均在真实部署环境（Ubuntu 24.04.5、Docker 29.9.2、Docker Compose v5.6.1）实测，取材日期 2026-10-25。产品定位与竞品对比见《CloudBeaver 26.2.3 介绍与选型指南》。

一、环境信息

本篇的实测环境与部署目标如下，读者操作时把路径、端口与口令换成自己的取值即可：

  • 操作系统：Ubuntu 24.04.5 LTS，x86_64
  • Docker 引擎：29.9.2（Compose v2 插件，实测 v5.6.1）
  • 应用发行：dbeaver/cloudbeaver:26.2.3（CloudBeaver Community，构建号 26.2.3.202610190842）
  • 内嵌运行时：OpenJDK 25.0.4.1（Eclipse Adoptium）、Jetty 12.1.11
  • 配套数据库：PostgreSQL 16、MariaDB 11.8（作为被管理的演示库，可选）
  • 对外端口：8978（CloudBeaver 默认监听端口）
  • 部署目录：/opt/cloudbeaver，编排文件为 docker-compose.yml，工作区挂到 ./workspace
  • 编排项目名：cloudbeaver-2623-stack（由编排文件 name: 字段固定）

版本与宿主机能力取证：

docker --version && docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

二、镜像选型说明

CloudBeaver 官方只以 Docker 镜像形式分发社区版，镜像仓库为 dbeaver/cloudbeaver。标签规则（官方 Wiki《CloudBeaver release cycles》）：

标签含义适用
ea最新 Early Access 版（每两周一个）尝鲜，不建议生产
latest最新稳定版会随版本发布漂移，不建议写进编排
xx.y.z（如 26.2.3）精确版本生产推荐，本文取值
xx.y（如 26.2）该小版本系列最新补丁愿意自动跟补丁时使用
xx（如 26）该大版本系列最新同上，跨度更大

关键差异解读：稳定版每 3 个月一个（每年 4 次），补丁大约每 2–3 周一个（26.2 系列：26.2.0 于 2026-08-31、26.2.1 于 2026-09-21、26.2.2 于 2026-10-05、26.2.3 于 2026-10-19 推送）。生产环境锁定 26.2.3 这样的精确标签，升级动作由自己控制。

拉取后核对发行信息：

docker images --filter reference='dbeaver/cloudbeaver' --format '{{.Repository}}:{{.Tag}} {{.ID}} {{.Size}}'

实测回显：

dbeaver/cloudbeaver:26.2.3 0c875296f85f 1.14GB

镜像 ID 前缀 0c875296f85f 与 Docker Hub 上 26.2.3/latest 标签的摘要一致（2026-10-19 推送），可确认拉到的是官方当前稳定版。镜像约 1.14 GB，内置 OpenJDK 与全部预下载数据库驱动，不需要另外安装 Java。

三、前置条件

3.1 宿主机资源

  • 磁盘：镜像约 1.14 GB，加上工作区与驱动缓存，建议预留 5 GB 以上。
  • 内存：本文把 JVM 堆限制在 256–512 MB（见 4.6），加上 JVM 元空间与操作系统开销，建议整机可用内存不少于 2 GB。
  • CPU：2 核即可满足中小团队日常使用。

3.2 端口检查

先确认 8978 未被占用：

ss -ltn | grep ':8978' || echo "8978 空闲"

部署前实测回显：

8978 空闲

部署成功后同一命令应能看到 LISTEN 行（见 4.3）。

3.3 基础工具

curl 用于后续全部验证。若服务器访问 Docker Hub 缓慢，先为 Docker 引擎配置代理或加速地址再拉取镜像。

四、部署步骤

4.1 编写编排文件

mkdir -p /opt/cloudbeaver
cd /opt/cloudbeaver

在 /opt/cloudbeaver/docker-compose.yml 写入以下内容（与本文实测运行文件一致）：

name: cloudbeaver-2623-stack

services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:26.2.3
    ports:
      - "8978:8978"
    environment:
      CB_SERVER_NAME: "CloudBeaver Lab"
      CB_SERVER_URL: "http://localhost:8978/"
      CB_ADMIN_NAME: "root"
      CB_ADMIN_PASSWORD: "q1w2e3r4"
      JAVA_OPTS: "-Xms256m -Xmx512m"
      TZ: "Asia/Shanghai"
    volumes:
      - ./workspace:/opt/cloudbeaver/workspace
    depends_on:
      - pg
      - maria
    networks:
      cbn:
        ipv4_address: 10.89.57.10

  pg:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: "q1w2e3r4"
      POSTGRES_DB: "demo"
      TZ: "Asia/Shanghai"
    networks:
      cbn:
        ipv4_address: 10.89.57.11
        aliases:
          - pg.demo.local

  maria:
    image: mariadb:11.8
    environment:
      MARIADB_ROOT_PASSWORD: "q1w2e3r4"
      MARIADB_DATABASE: "demo"
      TZ: "Asia/Shanghai"
    networks:
      cbn:
        ipv4_address: 10.89.57.12
        aliases:
          - maria.demo.local

networks:
  cbn:
    name: cloudbeaver-26.2.3-net
    ipam:
      config:
        - subnet: 10.89.57.0/24

编排要点逐项说明：

  • image: dbeaver/cloudbeaver:26.2.3：锁定精确版本（见第二章），不用 latest。
  • ports: 8978:8978：CloudBeaver 默认监听 8978（配置文件 serverPort 的默认值），宿主机直接映射同名端口。
  • CB_SERVER_NAME / CB_SERVER_URL：首次初始化时写入的服务名称与对外访问地址。CB_SERVER_URL 要填用户浏览器实际访问的地址，生产环境换成域名。
  • CB_ADMIN_NAME / CB_ADMIN_PASSWORD：首次启动时自动创建管理员并跳过浏览器初始化向导。本文演示账号为 root + q1w2e3r4（生产环境务必换成强口令）。⚠️ 注意：内置角色已占用 admin 标识，管理员账号名不要用 admin；且 26.2.3 的自动初始化存在口令双重哈希缺陷，首次登录会报「Invalid user credentials」，须按第十一章 Q1 的步骤一次性修复。
  • JAVA_OPTS：JVM 堆内存限制，本文取 -Xms256m -Xmx512m，验证方法见 4.6。
  • volumes：把宿主机 ./workspace 绑定挂载到应用工作区，用户、连接、权限全部落在这里（见第五章）。
  • pg / maria：两套被管理的演示数据库，初始口令同为 q1w2e3r4、库名 demo。已有目标数据库时可整段删除。
  • 网络：独立网桥 cloudbeaver-26.2.3-net（10.89.57.0/24），服务之间用服务名（pg、maria）互访；固定 IP 与别名便于在防火墙与 DNS 场景引用。

4.2 启动服务

cd /opt/cloudbeaver
docker compose up -d

实测回显（输出节选，实测首尾）：

 Container cloudbeaver-2623-stack-maria-1 Created
 Container cloudbeaver-2623-stack-pg-1 Created
 Container cloudbeaver-2623-stack-cloudbeaver-1 Creating
 Container cloudbeaver-2623-stack-cloudbeaver-1 Created
 Container cloudbeaver-2623-stack-maria-1 Starting
 Container cloudbeaver-2623-stack-pg-1 Starting
 Container cloudbeaver-2623-stack-maria-1 Started
 Container cloudbeaver-2623-stack-pg-1 Started
 Container cloudbeaver-2623-stack-cloudbeaver-1 Starting
 Container cloudbeaver-2623-stack-cloudbeaver-1 Started

首次启动会拉取镜像，耗时取决于网络；后续启动在秒级完成。

4.3 核验运行状态

docker compose ps

实测回显：

NAME                                   IMAGE                        COMMAND                  SERVICE       CREATED          STATUS          PORTS
cloudbeaver-2623-stack-cloudbeaver-1   dbeaver/cloudbeaver:26.2.3   "./launch-product.sh"    cloudbeaver   16 seconds ago   Up 15 seconds   0.0.0.0:8978->8978/tcp, [::]:8978->8978/tcp
cloudbeaver-2623-stack-maria-1         mariadb:11.8                 "docker-entrypoint.s…"   maria         16 seconds ago   Up 15 seconds   3306/tcp
cloudbeaver-2623-stack-pg-1            postgres:16                  "docker-entrypoint.s…"   pg            16 seconds ago   Up 15 seconds   5432/tcp

三个服务均为 Up 即启动成功。再看端口监听：

ss -ltn | grep ':8978'

实测回显：

LISTEN 0      4096         0.0.0.0:8978       0.0.0.0:*
LISTEN 0      4096            [::]:8978          [::]:*

4.4 接口与页面验证

首页返回 200 与 HTML：

curl -s -o /dev/null -w 'HTTP %{http_code} type=%{content_type}\n' http://127.0.0.1:8978/

实测回显：

HTTP 200 type=text/html;charset=utf-8

健康接口直接报告产品名与版本：

curl -s http://127.0.0.1:8978/status

实测回显：

{"health":"ok","product.name":"CloudBeaver Community","product.version":"26.2.3.202610190842"}

浏览器访问 http://<服务器地址>:8978 即可打开登录页。

4.5 查看启动日志

docker compose logs cloudbeaver --since 5m

实测回显（输出节选，关键行）：

25-10-2026 19:10:55.648 [main] DEBUG o.j.d.r.DataSourceProviderRegistry - Total database drivers: 139 (139)
25-10-2026 19:10:55.649 [main] DEBUG io.cloudbeaver.server.CBApplication - CloudBeaver Community 26.2.3.202610190842 is starting
25-10-2026 19:10:55.649 [main] DEBUG io.cloudbeaver.server.CBApplication - 	Java version: 25.0.4.1 by Eclipse Adoptium (64bit)
25-10-2026 19:10:55.649 [main] DEBUG io.cloudbeaver.server.CBApplication - 	Memory available 256Mb/512Mb
25-10-2026 19:10:55.649 [main] DEBUG io.cloudbeaver.server.CBApplication - 	Listen port: 8978 on all interfaces
25-10-2026 19:10:55.761 [main] ERROR i.c.registry.WebDriverRegistry - 	Driver 'yandex_clickhouse' is missing library 'ru.yandex.clickhouse:clickhouse-jdbc:RELEASE'
25-10-2026 19:10:56.039 [main] DEBUG o.j.dbeaver.model.sql.db.InternalDB - 	Security Manager DB server started (H2 2.1.214 (2022-06-13))
25-10-2026 19:10:56.504 [main] INFO  org.eclipse.jetty.server.Server - jetty-12.1.11; built: 2026-07-02T20:57:42.640Z; git: 6c1ced3f077bc633716c54758a743b09b21328e8; jvm 25.0.4.1+1-LTS
25-10-2026 19:10:56.550 [main] INFO  o.e.j.server.AbstractConnector - Started oejs.ServerConnector@4fa6fb7f{HTTP/1.1, (http/1.1)}{0.0.0.0:8978}

这段日志包含六个关键信号：

  1. Total database drivers: 139：驱动注册表共识别 139 个数据库驱动定义（含未预下载库的占位定义）；
  2. CloudBeaver Community 26.2.3.202610190842 is starting：版本与构建号；
  3. Java version: 25.0.4.1 by Eclipse Adoptium：内嵌 JDK，无需自行安装；
  4. Memory available 256Mb/512Mb：JVM 堆下限/上限，证明 JAVA_OPTS 生效（见 4.6）；
  5. Security Manager DB server started (H2 2.1.214)：存用户与权限的内嵌 H2 库已就绪；
  6. Started ... {0.0.0.0:8978}：Jetty 12.1.11 已在 8978 端口接单。

中间那行 Driver 'yandex_clickhouse' is missing library 是 ERROR 级别但无害：社区版不随包分发该驱动的商业库文件，仅影响 ClickHouse 旧版驱动的连接能力，其他驱动不受影响（见第十一章 Q2）。

💡 说明：默认日志级别下 org.jkiss/com.dbeaver/io.cloudbeaver 三个包都是 DEBUG，输出较啰嗦属正常现象；生产环境可把日志级别调到 INFO（见第七章日志配置）。

4.6 初始管理员与首次登录

编排中设置了 CB_ADMIN_NAME/CB_ADMIN_PASSWORD，首次启动会自动创建管理员并跳过浏览器向导，日志中可见：

25-10-2026 11:06:16.764 [main] DEBUG i.c.s.s.CBEmbeddedSecurityController - Create user: root

若不设置这两个变量，首次访问会进入「Easy Config」初始化向导，在浏览器里创建管理员。两种方式任选其一，不要混用（向导只在空工作区上出现）。

用 API 直接验证登录（这也是后续脚本化使用的入口）：

curl -s -H 'Content-Type: application/json' http://127.0.0.1:8978/api/gql \
  -d '{"query":"query { authLogin(provider: \"local\", credentials: { user: \"root\", password: \"q1w2e3r4\" }) { userTokens { userId loginTime } } }"}'

实测回显：

{
    "data": {
        "authLogin": {
            "userTokens": [
                {
                    "userId": "root",
                    "loginTime": "2026-10-25T19:11:39.416+08:00"
                }
            ]
        }
    }
}

⚠️ 注意：26.2.3 的 CB_ADMIN_PASSWORD 自动初始化存在口令双重哈希缺陷——按上面编排首次部署后，无论网页还是 API 登录都会报 Invalid user credentials。本文实测环境中已按第十一章 Q1 的步骤修复（修复后登录回显如上）。全新部署的读者请先照 Q1 做一次修复，再继续。

4.7 JVM 堆内存限制与验证

CloudBeaver 是纯 Java 服务，默认不限制堆上限，长时间使用可能吃掉整机内存。官方启动脚本读取 JAVA_OPTS 环境变量传给 JVM，编排中已注入 -Xms256m -Xmx512m。修改后必须验证实际生效值，两种方式互证：

方式一，看进程命令行：

docker compose exec cloudbeaver ps -ef | grep '[j]ava'

实测回显（行长有截断，关键参数完整可见）：

dbeaver     9   1  1 19:10 ?  00:00:07 java -Xms256m -Xmx512m -Dfile.encoding=UTF-8 --enable-native-access=ALL-UNNAMED --add-modules=ALL-DEFAULT ... -jar server/plugins/org.jkiss.dbeaver.launcher_1.0.63.202610190842.jar -product io.cloudbeaver.product.ce.product -web-config conf/cloudbeaver.conf -nl en -registryMultiLanguage

方式二，用 JDK 自带工具：

docker compose exec cloudbeaver jps -v

实测回显（节选）：

9 org.jkiss.dbeaver.launcher_1.0.63.202610190842.jar -Xms256m -Xmx512m -Dfile.encoding=UTF-8 ...

再叠加启动日志里的 Memory available 256Mb/512Mb，三处一致即可确认堆限制生效。若三处不一致（例如改过 JAVA_OPTS 但只用了 docker compose restart），按第十章用 up -d 重建服务。

五、数据持久化说明

5.1 持久化对象

CloudBeaver 的全部状态都在工作区目录里，编排已把 ./workspace 绑定挂载到 /opt/cloudbeaver/workspace。实测目录结构：

ls -la /opt/cloudbeaver/workspace /opt/cloudbeaver/workspace/.data

实测回显：

/opt/cloudbeaver/workspace:
drwxrwxr-x 2 8978 8978 4096 .data
drwxrwxr-x 3 8978 8978 4096 GlobalConfiguration
drwxrwxr-x 4 8978 8978 4096 .metadata

/opt/cloudbeaver/workspace/.data:
-rw-r--r-- 1 8978 8978 159744 cb.h2v2.dat.mv.db
-rw-r--r-- 1 8978 8978    620 cb.h2v2.dat.trace.db
-rw-r--r-- 1 8978 8978   4240 .cloudbeaver.runtime.conf
-rw-r--r-- 1 8978 8978   4242 .cloudbeaver.runtime.conf.bak
-rw-r--r-- 1 8978 8978      8 .database-credentials.dat
路径内容说明
.data/cb.h2v2.dat.mv.db内嵌 H2 库用户、口令哈希、连接定义、凭据、角色权限全在这里
.data/.cloudbeaver.runtime.conf运行时配置初始化向导/管理界面写入，优先级高于静态配置文件
.data/.database-credentials.dat内部库凭据每个工作区首次初始化时随机生成
GlobalConfiguration/全局连接与资源管理员下发的连接模板
.metadata/Eclipse 工作区元数据插件状态与索引

5.2 重启与重建验证

把整套编排停掉再拉起（比 restart 更彻底的重建）：

docker compose down
docker compose up -d

重新登录后查询连接列表，此前创建的 pg-demo、maria-demo 两个连接仍在：

{
    "data": {
        "userConnections": [
            {"id": "postgres-jdbc-1a172a8859d-66a0bb96dac402dc", "name": "pg-demo", "host": "pg", "port": "5432", "databaseName": "demo"},
            {"id": "mariaDB-1a172ab0e54-d5008b42ec7a307", "name": "maria-demo", "host": "maria", "port": "3306", "databaseName": "demo"}
        ]
    }
}

结论：只要 ./workspace 目录在，服务重建、升级镜像都不丢配置与连接。

5.3 备份与恢复

备份就是打包工作区目录（建议先停服务，保证 H2 文件一致）：

cd /opt/cloudbeaver
docker compose stop cloudbeaver
tar -czf cloudbeaver-workspace-$(date +%Y%m%d).tar.gz workspace
docker compose start cloudbeaver
ls -lh cloudbeaver-workspace-*.tar.gz

恢复则反向操作：停服务、清空 workspace/、解包、启动。迁移到另一台服务器时连 docker-compose.yml 一起拷贝即可。

⚠️ 注意：工作区属主是 uid/gid 8978（应用运行用户），手工增删文件后注意保持属主，否则服务可能因权限不足无法写入。

六、环境变量表

部署期常用环境变量如下（配置体系与环境变量全覆盖另有专篇，本表保证部署可独立完成）：

变量默认值作用本文取值
CB_SERVER_NAMECloudBeaver服务显示名，写入初始化配置CloudBeaver Lab
CB_SERVER_URL空对外访问地址，用于链接拼接http://localhost:8978/
CB_ADMIN_NAME空自动创建的管理员账号；不设则走浏览器向导root
CB_ADMIN_PASSWORD空自动管理员的口令（26.2.3 需修复，见 Q1）q1w2e3r4
JAVA_OPTS空JVM 参数，必配堆限制-Xms256m -Xmx512m
TZ容器默认时区Asia/Shanghai
CLOUDBEAVER_WEB_SERVER_PORT8978服务监听端口默认
CLOUDBEAVER_EXPIRE_SESSION_AFTER_PERIOD1800000会话空闲过期毫秒数默认
CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLEDtrue是否允许匿名访问默认
CLOUDBEAVER_FORCE_HTTPSfalse强制 HTTPS 跳转与安全 Cookie见第八章

命名规律：配置文件里几乎所有 ${CLOUDBEAVER_XXX:默认值} 占位都可以用同名环境变量覆盖，改动后用 docker compose up -d 重建生效。

七、配置参数说明

7.1 两层配置文件

CloudBeaver 有两层配置，修改前先想清楚改哪层：

层位置读取时机优先级
静态配置应用内 /opt/cloudbeaver/conf/cloudbeaver.conf进程启动时低
运行时配置工作区 .data/.cloudbeaver.runtime.conf启动时覆盖静态配置高

两层都是 JSONC 格式（允许注释），键值形如 "${CLOUDBEAVER_XXX:默认值}"，即「环境变量优先，缺省用默认值」。初始化向导与管理界面的改动写入运行时层；环境变量两层都能穿透。改完任意一层都要重启服务生效。

7.2 端口与监听

默认 serverPort: 8978、监听全部网卡。改端口只需改编排映射（如 "8080:8978"），不必动服务内部配置；确需改内部端口时设 CLOUDBEAVER_WEB_SERVER_PORT。

7.3 自定义配置文件挂载

需要固化配置（如纳入版本管理）时，把自己的配置文件挂进去：

services:
  cloudbeaver:
    volumes:
      - ./workspace:/opt/cloudbeaver/workspace
      - ./cloudbeaver.conf:/opt/cloudbeaver/conf/cloudbeaver.conf:ro

日志配置同理：自定义 logback.xml 挂到 /opt/cloudbeaver/conf/custom 目录后重启。默认日志级别为 root INFO、org.jkiss/com.dbeaver/io.cloudbeaver 三个包 DEBUG，生产环境建议把这三个包调到 INFO 减少噪音。

八、HTTPS 与前置反向代理

生产环境不要让 8978 直接对公网，标准做法是由前置反向代理终止 TLS。社区版不内置反代，需手工配置（官方 Wiki 给出 Nginx 参考配置）：

server {
    listen 443 ssl;
    server_name cloudbeaver.example.com;
    client_max_body_size 500M;

    ssl_certificate     /etc/nginx/ssl/cloudbeaver.crt;
    ssl_certificate_key /etc/nginx/ssl/cloudbeaver.key;

    location / {
        proxy_pass http://127.0.0.1:8978;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

三个要点：

  1. WebSocket 头必须透传（最后两行）。CloudBeaver 用 WebSocket 推送实时事件与任务进度；代理不放行 Upgrade 头时界面看似正常但永不刷新，服务端会降级为 HTTP 长轮询。
  2. 真实 IP：要在审计日志里看到真实客户端地址，把应用参数 forwardProxy 设为 true（配置文件的 app 段）。
  3. 强制 HTTPS：代理 TLS 就绪后，设环境变量 CLOUDBEAVER_FORCE_HTTPS=true 并重建服务，之后 HTTP 请求全部跳转 HTTPS、会话 Cookie 带 Secure 标记。⚠️ 顺序不能反——先开 force HTTPS 再配证书，服务会立刻不可达。

💡 技术拓展：前置反向代理的常见选型。

方案特点适用场景
Nginx生态最成熟，配置直白，官方 Wiki 示例即用 Nginx通用首选
HAProxy负载均衡能力强，25.1 起商业版编排内置支持多后端、四层需求
Caddy自动签发/续期证书，配置最简小团队、不想管证书
Traefik与容器编排标签联动，服务发现自动化容器平台统一入口

本文按官方参考采用 Nginx；只需自动证书时 Caddy 更省事。

九、等价 docker run

不用 Compose 时，与 4.1 编排等价的单服务启动命令如下（演示数据库需另外准备）：

docker run -d --name cloudbeaver \
  -p 8978:8978 \
  -e CB_SERVER_NAME="CloudBeaver Lab" \
  -e CB_SERVER_URL="http://localhost:8978/" \
  -e CB_ADMIN_NAME="root" \
  -e CB_ADMIN_PASSWORD="q1w2e3r4" \
  -e JAVA_OPTS="-Xms256m -Xmx512m" \
  -e TZ="Asia/Shanghai" \
  -v /opt/cloudbeaver/workspace:/opt/cloudbeaver/workspace \
  dbeaver/cloudbeaver:26.2.3

要点：工作区卷必须挂载，否则重启丢全部配置；CB_ADMIN_PASSWORD 自动初始化的口令缺陷同样需要按 Q1 修复。

十、常用运维命令

cd /opt/cloudbeaver
docker compose ps                    # 查看服务状态与端口映射
docker compose logs -f cloudbeaver   # 跟踪应用日志
docker compose restart cloudbeaver   # 只重启进程（不应用新的环境变量定义）
docker compose up -d                 # 按编排文件重建并应用新配置
docker compose stop                  # 停止全部服务
docker compose down                  # 停止并删除服务与网络（工作区目录不受影响）

升级与回滚：

# 升级：备份工作区 → 改标签 → 拉新镜像 → 重建
tar -czf cloudbeaver-workspace-$(date +%Y%m%d).tar.gz workspace
# 编辑 docker-compose.yml 把 26.2.3 改成目标版本
docker compose pull cloudbeaver
docker compose up -d

回滚把标签改回旧版本再 up -d 即可；但工作区数据可能被新版本改写，升级前的备份是回滚的前提。跨小版本升级（如 26.1→26.2）建议先读对应版本 Release Notes。

十一、常见问题

Q1：首次部署后管理员登录报 Invalid user credentials（26.2.3 自动初始化缺陷，本文实测排障实录）

现象：编排中用 CB_ADMIN_NAME=root、CB_ADMIN_PASSWORD=q1w2e3r4 自动初始化，启动日志明确打印 Create user: root，但网页与 API 登录都失败：

{
    "errors": [
        {
            "message": "User authentication failed:\nInvalid user credentials",
            "path": ["authLogin"],
            "extensions": {"exceptionClass": "org.jkiss.dbeaver.DBException", "classification": "DataFetchingException"}
        }
    ],
    "data": null
}

定位：CloudBeaver 校验登录时计算的是 MD5(用户名 + 明文口令) 的大写十六进制。本文实测 MD5("rootq1w2e3r4") 为 23DBE8E7F928005DCD067AFD9A3B440D。停掉服务后直接查内嵌 H2 库（工作区 .data/.cloudbeaver.runtime.conf 里有自动生成的库账号口令，本文实测为 cb-data / 随机串），发现自动初始化写入的却是双重哈希 MD5("root" + MD5("q1w2e3r4")) = 53E99C310B8A799FC68BBB3963AE4D8F，与登录校验口径不一致，因此永远登录失败。

修复（先停服务，再用应用发行自带的 JDK 与 H2 驱动直改库文件；以下为完整实录）：

cd /opt/cloudbeaver
docker compose stop cloudbeaver
# 从运行时配置里读 H2 账号口令
grep -oE '"(user|password)": "[^"]+"' workspace/.data/.cloudbeaver.runtime.conf

实测回显（每次新工作区随机生成，以实际为准）：

"user": "${CLOUDBEAVER_DB_USER:cb-data}"
"password": "${CLOUDBEAVER_DB_PASSWORD:HEZ4uxLJ}"

用一条命令挂工作区执行 SQL（镜像内自带 JDK 与 H2 驱动，路径固定）：

docker run --rm -v /opt/cloudbeaver/workspace:/ws --entrypoint /opt/java/openjdk/bin/java \
  dbeaver/cloudbeaver:26.2.3 \
  -cp /opt/cloudbeaver/drivers/h2_v2/h2-legacy-2.jar org.h2.tools.Shell \
  -url "jdbc:h2:/ws/.data/cb.h2v2.dat" -user cb-data -password HEZ4uxLJ \
  -sql "SELECT USER_ID, CRED_ID, CRED_VALUE FROM CB_USER_CREDENTIALS"

实测回显（修复前，口令为双重哈希）：

USER_ID | CRED_ID  | CRED_VALUE
root    | user     | root
root    | password | 53E99C310B8A799FC68BBB3963AE4D8F
(2 rows, 10 ms)

把它改成登录校验口径的单重哈希并复核：

docker run --rm -v /opt/cloudbeaver/workspace:/ws --entrypoint /opt/java/openjdk/bin/java \
  dbeaver/cloudbeaver:26.2.3 \
  -cp /opt/cloudbeaver/drivers/h2_v2/h2-legacy-2.jar org.h2.tools.Shell \
  -url "jdbc:h2:/ws/.data/cb.h2v2.dat" -user cb-data -password HEZ4uxLJ \
  -sql "UPDATE CB_USER_CREDENTIALS SET CRED_VALUE='23DBE8E7F928005DCD067AFD9A3B440D' WHERE USER_ID='root' AND CRED_ID='password'; SELECT USER_ID, CRED_ID, CRED_VALUE FROM CB_USER_CREDENTIALS"

实测回显：

(Update count: 1, 6 ms)
USER_ID | CRED_ID  | CRED_VALUE
root    | user     | root
root    | password | 23DBE8E7F928005DCD067AFD9A3B440D
(2 rows, 6 ms)

docker compose start cloudbeaver

重新登录即成功（回显见 4.6）。换一个口令时哈希值用 echo -n 'root<新口令>' | md5sum | tr a-f A-Z 现算。规避方案：不使用 CB_ADMIN_* 自动初始化，改为浏览器向导创建管理员；已用自动初始化的按本节修复一次即可。

Q2：启动日志报 Driver 'yandex_clickhouse' is missing library 'ru.yandex.clickhouse:clickhouse-jdbc:RELEASE'

无害提示。社区版不分发该旧版 ClickHouse 驱动的商业库文件，仅影响「ClickHouse (Legacy)」这一类连接；当前 ClickHouse 驱动（clickhouse:com_clickhouse）正常。不需要旧版驱动时忽略即可。

Q3：改了 environment: 里的变量，重启后没生效

docker compose restart 只重启进程，不会应用编排文件里新的环境变量定义。改用 docker compose up -d 让服务按新配置重建，再按 4.7 的方式验证。

Q4：忘记管理员口令

无法在线找回（库里只存哈希）。按 Q1 的方法停服后直改 H2：CRED_VALUE 写入 MD5(用户名+新口令) 的大写十六进制，重启生效。

Q5：8978 端口被占用

只改编排映射，如 "8899:8978"，再 docker compose up -d；服务内部端口无需改动。同步把 CB_SERVER_URL 改成新地址。

Q6：部署后被匿名用户看到连接

社区版默认允许匿名访问（anonymousAccessEnabled: true）。团队服务器建议设 CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED=false 并重建服务，只留账号登录入口。

十二、参考链接