openGauss Docker Compose 部署指南

使用 Docker Compose 基于 enmotech/opengauss 官方镜像部署 openGauss 5.1.0，覆盖镜像选型、GS_PASSWORD 环境变量、数据卷持久化、healthcheck 健康检查与重启后数据保留验证，命令与回显均为容器环境实测结果

openGaussopenGauss关系型数据库OLTPDocker Compose2026/10/07

openGauss Docker Compose 部署指南

目标：使用 Docker Compose 基于社区维护的 enmotech/opengauss 镜像部署 openGauss 5.1.0 单节点，覆盖镜像选型、环境变量、数据卷持久化、健康检查与升级回滚。本文命令与回显均为容器环境实测结果。

镜像选型

社区最常用且维护活跃的 openGauss 容器镜像是 enmotech/opengauss（恩墨科技基于官方安装包构建），镜像内置 openGauss 5.1.0 与完整工具链（gsql、gs_ctl、gs_guc、gs_dump 等）。

项目说明
镜像名enmotech/opengauss:5.1.0
内置版本openGauss 5.1.0（gsql --version 显示 build b5a8d5b0）
数据目录/var/lib/opengauss
工具目录/usr/local/opengauss/bin
默认超级用户omm
默认端口5432

💡 国内网络拉取 Docker Hub 超时时，可改用镜像源地址 docker.m.daocloud.io/enmotech/opengauss:5.1.0，内容与官方镜像一致（本次实测即通过该镜像源拉取成功）。

前置条件

  • 已安装 Docker Engine 与 Docker Compose v2（docker compose version）
  • 服务器内存 ≥ 2 GB（openGauss 初始化约占用 1 GB 共享内存）
  • 端口 5432 未被占用

部署步骤

步骤 1：准备 compose 文件

创建目录与 docker-compose.yml：

mkdir -p /opt/og-compose/data
cd /opt/og-compose

services:
  opengauss:
    image: enmotech/opengauss:5.1.0
    container_name: opengauss
    privileged: true
    environment:
      - GS_PASSWORD=Q1w2e3r4#
    ports:
      - "5432:5432"
    volumes:
      - /opt/og-compose/data:/var/lib/opengauss
    healthcheck:
      test: ["CMD-SHELL", "LD_LIBRARY_PATH=/usr/local/opengauss/lib /usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d postgres -c \"select 1\" || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12

⚠️ privileged: true 为 openGauss 镜像必需：启动阶段需要调整内核参数（共享内存/信号量），非特权容器会初始化失败。 ⚠️ GS_PASSWORD 为必填项，且必须满足强度要求（≥ 8 位并包含大写、小写、数字、特殊字符中至少三类），否则镜像初始化脚本会直接拒绝启动。

步骤 2：启动服务

cd /opt/og-compose
docker compose up -d
# Network og-compose_default Created
# Container opengauss Creating
# Container opengauss Started

步骤 3：等待健康检查通过

docker compose ps
# NAME        IMAGE                            COMMAND               STATUS              PORTS
# opengauss   enmotech/opengauss:5.1.0         "entrypoint.sh gauss…" Up 22 seconds (healthy)   0.0.0.0:5432->5432/tcp

首次启动约 30~60 秒完成初始化（初始化 gaussdb 数据目录、创建默认库与用户），STATUS 从 starting 变为 (healthy) 即就绪。

步骤 4：验证连接

进入容器执行 gsql（镜像内 gsql 需显式指定动态库路径与全路径）：

docker exec -it opengauss bash
export LD_LIBRARY_PATH=/usr/local/opengauss/lib
/usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d postgres -c "SELECT version();"
#  server_version
# ----------------
#  9.2.4
# (1 row)

步骤 5：建库建表 CRUD 实测

/usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d postgres -c "CREATE DATABASE app_db;"
# CREATE DATABASE

/usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d app_db -c "CREATE TABLE products(id serial PRIMARY KEY, name varchar(64), price numeric(10,2));"
# NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "products_pkey" for table "products"
# CREATE TABLE

/usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d app_db -c "INSERT INTO products(name, price) VALUES ('笔记本', 5999.00), ('平板', 2799.00);"
# INSERT 0 2

/usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d app_db -c "SELECT * FROM products ORDER BY id;"
#  id |  name  |  price
# ----+--------+---------
#   1 | 笔记本 | 5999.00
#   2 | 平板   | 2799.00
# (2 rows)

💡 建议通过 -f 参数执行 SQL 文件，避免在 shell 中直接拼接含中文/引号的 SQL 字符串：

printf "INSERT INTO products(name, price) VALUES ('显示器', 1899.00);\n" > /tmp/ins.sql
docker cp /tmp/ins.sql opengauss:/tmp/ins.sql
docker exec opengauss bash -c "export LD_LIBRARY_PATH=/usr/local/opengauss/lib; /usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d app_db -f /tmp/ins.sql"
# INSERT 0 1

数据持久化

数据目录通过 volume 映射到宿主机 /opt/og-compose/data，删除/重建容器数据不丢失。实测验证：

# 重启容器
docker compose restart
# Container opengauss Started

# 重启后数据仍在
docker exec opengauss bash -c "export LD_LIBRARY_PATH=/usr/local/opengauss/lib; /usr/local/opengauss/bin/gsql -U omm -W Q1w2e3r4# -d app_db -f /tmp/cnt.sql"
#  count
# -------
#      2
# (1 row)

环境变量表

变量必填默认值说明
GS_PASSWORD是无超级用户 omm 的密码；≥ 8 位且包含三类以上字符
GS_USERNAME否gaussdb额外创建的普通用户。实测 5.1.0 镜像同时创建 omm 与 gaussdb，显式指定 GS_USERNAME=gaussdb 会与镜像内置流程冲突（role "gaussdb" already exists 导致初始化脚本异常退出），建议保持默认
GS_DBNAME否gaussdb额外创建的数据库，默认库为 postgres

配置

常用运维命令

docker compose ps                    # 查看状态
docker compose logs -f opengauss     # 跟踪日志
docker compose restart                # 重启
docker compose down                   # 停止并删除容器（保留数据卷）
docker compose down -v                # 停止并删除容器与数据卷（数据丢失，慎用）

gs_guc 修改参数

docker exec opengauss bash -c "export LD_LIBRARY_PATH=/usr/local/opengauss/lib; /usr/local/opengauss/bin/gs_guc set -D /var/lib/opengauss/data -c \"log_min_messages=notice\""

升级回滚

升级

cd /opt/og-compose
# 1. 备份数据目录（卷路径）
cp -a /opt/og-compose/data /opt/og-compose/data.bak.$(date +%F)
# 2. 修改镜像 tag 并重新创建
docker compose pull
docker compose up -d
# 3. 验证版本
docker exec opengauss bash -c "export LD_LIBRARY_PATH=/usr/local/opengauss/lib; /usr/local/opengauss/bin/gsql --version"

回滚

# 1. 停止新版本容器
docker compose down
# 2. 恢复旧数据目录（若主版本升级导致数据目录不兼容）
rm -rf /opt/og-compose/data
mv /opt/og-compose/data.bak.2026-10-07 /opt/og-compose/data
# 3. 将镜像 tag 改回旧版本后启动
docker compose up -d

常见问题

问题 1：拉取镜像超时 / connection refused

  • 现象：docker pull enmotech/opengauss:5.1.0 报 connect: connection refused。
  • 定位：Docker Hub 在国内网络不可达。
  • 解决：使用镜像源拉取：
docker pull docker.m.daocloud.io/enmotech/opengauss:5.1.0
# 并在 compose 文件中将 image 同步改为 docker.m.daocloud.io/enmotech/opengauss:5.1.0

问题 2：容器反复退出（exit 3）

  • 现象：docker compose up -d 后容器立即退出，日志末尾出现 role "gaussdb" already exists。
  • 定位：compose 中显式设置了 GS_USERNAME=gaussdb，与镜像内置创建流程冲突，ON_ERROR_STOP=1 使初始化脚本退出。
  • 解决：删除 GS_USERNAME / GS_DBNAME 变量，仅保留 GS_PASSWORD，重建容器：
docker compose down -v
docker compose up -d

问题 3：容器显示 unhealthy

  • 现象：容器运行但 STATUS 一直为 unhealthy。
  • 定位：健康检查命令中 gsql 未带动态库路径/全路径（镜像内 gsql 需 LD_LIBRARY_PATH=/usr/local/opengauss/lib）。
  • 解决：按本文 healthcheck 写法使用全路径并设置 LD_LIBRARY_PATH；或直接移除 healthcheck 段。

问题 4：gsql 报 libxml2.so.2 / 其他动态库缺失

  • 现象：docker exec 进入容器后直接执行 gsql 报缺库。
  • 定位：镜像内 gsql 依赖 openGauss 自带库目录，exec 的非登录 shell 未加载环境。
  • 解决：执行时设置 LD_LIBRARY_PATH=/usr/local/opengauss/lib，并始终使用全路径 /usr/local/opengauss/bin/gsql。

参考链接