Docker 部署 openGauss：轻松搭建企业级开源关系型数据库平台

本文基于 opengauss/opengauss:5.0.0（可选 opengauss/opengauss-webclient:1.0.4），实测引擎 openGauss 5.0.0（x86_64，GCC 7.3.0），测试平台 macOS（Docker Desktop，Intel Core i5-5257U / AVX2）。

openGauss 是一款开源的关系型数据库：用 SQL 建库建表、存业务数据、做查询与事务，角色接近 PostgreSQL / MySQL。常见用途包括业务系统后端库、中间件联调、教学实验，以及信创 / 国产化选型时的自托管试跑。协议口默认 5432，可用官方客户端 gsql，也可用兼容驱动从应用连接。

很多人真正卡在「怎么先跑起来」：裸机装依赖重、云托管又不便做内网联调或数据不出域。更省事的做法是用官方 Docker 镜像，在自己的机器上起一个可连的库实例，数据落在本机目录。

本文主推镜像 opengauss/opengauss（见 镜像页）——容器里就是数据库服务本身。同组织还有可选的 opengauss/opengauss-webclient（见 镜像页），用浏览器点选对象、跑 SQL；它自带另一套库，不替代主库镜像。二者关系见下文「一、是什么 & 什么关系」。

部署跑通之后，你实际能做这些事：

本文按「能跟做」写完整链路：用 轩辕镜像 加速拉取 opengauss/opengauss:5.0.0（不要盲跟当前有缺陷的 latest），Docker Compose 映射宿主机 5432，设置 LD_LIBRARY_PATH，用容器内 gsql 验证；另附可选 webclient（浏览器 8081，内置库实测为 openGauss 3.1.0，与主库数据分离）与 docker run 备选。文内附 10 张 Web UI 实测截图。

上手要点

• 部署：默认 Compose 只起主库（第五节）；Web UI 见 第七节先启用再访问；临时试玩见 第九节 docker run
• 标签：库跟做用 5.0.0（实测可起）；当前 latest 缺 libopenblas.so.0，会 Restarting
• 端口：主库 5432；8081 仅启用 webclient 后才有
• 数据卷：宿主机 ./data → 容器 /var/lib/opengauss/data
• 环境变量：GS_PASSWORD（必填）+ LD_LIBRARY_PATH=/usr/local/opengauss/lib（实测需要）
• gsql：不在默认 PATH，用 /usr/local/opengauss/bin/gsql
• CPU：宿主机需支持 AVX / AVX2；无 AVX 的老 CPU 会 Illegal instruction
• 工作目录：Linux 正文默认 /www/wwwroot/opengauss；macOS 实测用 ~/docker/opengauss
• 特权：privileged: true
• 暴露：勿把 5432 裸暴露公网

镜像说明：opengauss/opengauss、opengauss/opengauss-webclient。标签：opengauss tags、webclient tags。官方容器文档：单节点容器安装。项目站点：opengauss.org。

---

一、是什么 & 什么关系？

1.1 两个镜像分别做什么

• opengauss/opengauss：容器内默认监听 5432。必须设置 GS_PASSWORD；默认有超级用户 omm 与测试用户 gaussdb。容器内本机信任连接通常可不输密码；从宿主机或其他容器连库则需密码。
• opengauss/opengauss-webclient：映射 8081 后用浏览器访问。镜像内会尝试自带库初始化，与主库不是同一份数据；且受宿主机 core_pattern 影响，在 Ubuntu 上易失败（见 FAQ）。

1.2 二者什么关系

text
方案 A（推荐主路径）
  应用 / gsql / 图形客户端  ──:5432──▶  opengauss/opengauss（权威数据）
  ./data                     ──挂载──▶  /var/lib/opengauss/data

方案 B（可选体验）
  浏览器  ──:8081──▶  opengauss/opengauss-webclient（Web UI，可含内置库）

同组织相关镜像：opengauss/opengauss-server、enmotech/opengauss。本文跟做 官方 opengauss/opengauss:5.0.0。

1.3 关键参数一览

密码示例 openGauss@123——仅跟做，上线务必改掉。

---

二、环境要求

bash
docker --version
docker compose version

# macOS：查看是否具备 AVX2（有则较稳）
sysctl -a | grep -i leaf7_features

# Linux：
# grep -oE 'avx[^ ]*' /proc/cpuinfo | sort -u

Linux 未装 Docker 可使用轩辕镜像一键安装脚本：

bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

更多见 轩辕镜像使用手册。

宿主机 5432 已被占用时，Compose 改为 "15432:5432"。

---

三、标签怎么选

完整列表：opengauss tags、webclient tags。

---

四、拉取镜像

用 轩辕镜像 加速拉取：

bash
# 主库（本文跟做）
docker pull docker.xuanyuan.run/opengauss/opengauss:5.0.0

# Web UI（可选）
docker pull docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4

macOS 实测（主库 5.0.0）：

text
5.0.0: Pulling from opengauss/opengauss
bf37c47dc58e: Already exists
416428d7bb5a: Already exists
15d09040b6af: Pull complete
44de8bf8b4ac: Pull complete
2ae1d2ac404d: Pull complete
ae0bcc1b03b5: Pull complete
a3d132d18f28: Pull complete
7133e4484edf: Pull complete
Digest: sha256:f8679ef310000452f7d1ce4c7752cee6fe63575fb6aa05fe8807090042645380
Status: Downloaded newer image for docker.xuanyuan.run/opengauss/opengauss:5.0.0
docker.xuanyuan.run/opengauss/opengauss:5.0.0

可选 webclient（Ubuntu 侧曾拉取成功）：

text
Digest: sha256:2ceb484afcee2f19760cae0097dfd42cd7e74ec9b6dfa8a80804519af573e534
Status: Downloaded newer image for docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4

bash
docker images docker.xuanyuan.run/opengauss/opengauss:5.0.0

冒烟（可选）：确认二进制可跑：

bash
docker run --rm --privileged --entrypoint bash \
  docker.xuanyuan.run/opengauss/opengauss:5.0.0 -c \
  'export LD_LIBRARY_PATH=/usr/local/opengauss/lib; /usr/local/opengauss/bin/gaussdb -V; echo exit:$?'

实测：

text
gaussdb (openGauss 5.0.0 build ) compiled at 2023-04-18 09:47:39 commit 0 last mr
exit:0

---

五、Docker Compose 部署（推荐）

下文命令以 Linux 路径书写；在 Mac 上把路径换成 ~/docker/opengauss 即可（见仓库文档规则）。

5.1 创建目录

bash
# Linux
mkdir -p /www/wwwroot/opengauss/data
chown -R "$USER:$USER" /www/wwwroot/opengauss
cd /www/wwwroot/opengauss

# macOS 实测：
# mkdir -p ~/docker/opengauss/data && cd ~/docker/opengauss

5.2 编写 docker-compose.yml

默认只起主库（webclient 注释掉）：

bash
cat > docker-compose.yml <<'EOF'
services:
  opengauss:
    image: docker.xuanyuan.run/opengauss/opengauss:5.0.0
    container_name: opengauss
    restart: unless-stopped
    privileged: true
    ports:
      - "5432:5432"
    environment:
      TZ: Asia/Shanghai
      GS_PASSWORD: "openGauss@123"
      LD_LIBRARY_PATH: "/usr/local/opengauss/lib"
    volumes:
      - ./data:/var/lib/opengauss/data

  # 可选：Web UI（默认注释；启用见第七节）
  # webclient:
  #   image: docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4
  #   container_name: opengauss-webclient
  #   restart: unless-stopped
  #   privileged: true
  #   ports:
  #     - "8081:8081"
EOF

默认只有 5432：未启用 webclient 时没有 8081。

5.3 启动与验证（仅主库）

bash
docker compose up -d
docker compose ps
docker compose logs --tail 100

macOS 实测 ps：

text
NAME        IMAGE                                           COMMAND                                      SERVICE     STATUS         PORTS
opengauss   docker.xuanyuan.run/opengauss/opengauss:5.0.0   "/var/lib/opengauss/entrypoint.sh gaussdb"   opengauss   Up …           0.0.0.0:5432->5432/tcp

日志关键成功标志（节选）：

text
[gs_ctl]: server started (/var/lib/opengauss/data)
CREATE DATABASE
CREATE ROLE
 default user is gaussdb
openGauss  init process complete; ready for start up.

常见 WARNING（GAUSSLOG / cgroup / HA sockets / gaussdb.version）在容器场景可忽略，只要进程保持 Up 且能连库即可。

容器内用 完整路径 的 gsql 验证（bash -lc 默认 PATH 不含 gsql）：

bash
docker compose exec opengauss /usr/local/opengauss/bin/gsql -d postgres -U gaussdb -c "SELECT version();"

若提示 Password for user gaussdb:，输入与 GS_PASSWORD 相同的密码（跟做示例为 openGauss@123）。

macOS 实测：

text
Password for user gaussdb:
                                                                   version
----------------------------------------------------------------------------------------------------------------------------------------------
 (openGauss 5.0.0 build ) compiled at 2023-04-18 09:47:39 commit 0 last mr   on x86_64-unknown-linux-gnu, compiled by g++ (GCC) 7.3.0, 64-bit
(1 row)

也可用显式 PATH 写法：

bash
docker compose exec opengauss bash -lc \
  'export LD_LIBRARY_PATH=/usr/local/opengauss/lib; export PATH=/usr/local/opengauss/bin:$PATH; gsql -d postgres -U gaussdb -c "SELECT version();"'

从宿主机连接需本机已装客户端：

bash
gsql -d postgres -U gaussdb -W 'openGauss@123' -h 127.0.0.1 -p 5432

主库验证不依赖浏览器与 webclient。

5.4 可选环境变量（主库）

---

六、使用主库：gsql 与简单 SQL

6.1 进入交互式会话

bash
docker compose exec -it opengauss bash -lc \
  'export LD_LIBRARY_PATH=/usr/local/opengauss/lib; export PATH=/usr/local/opengauss/bin:$PATH; gsql -d postgres -U gaussdb'

6.2 建表示例

sql
CREATE TABLE demo_users (
  id   INT PRIMARY KEY,
  name VARCHAR(64) NOT NULL,
  created_at TIMESTAMP DEFAULT now()
);

INSERT INTO demo_users (id, name) VALUES (1, 'alice'), (2, 'bob');

SELECT * FROM demo_users;

退出：\q。

6.3 应用侧连接要点

---

七、可选：使用 opengauss-webclient

前提：第五节默认 Compose 不起 webclient；须先把 webclient 服务写进 Compose（或取消注释）再 up，:8081 才是 Web UI（不是主库的浏览器入口）。

7.1 启用并启动

macOS 实测目录：~/docker/opengauss（Linux 用 /www/wwwroot/opengauss）。

bash
docker pull docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4
cd ~/docker/opengauss   # Linux：/www/wwwroot/opengauss

Compose 中同时保留主库与 webclient（示例）：

yaml
  webclient:
    image: docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4
    container_name: opengauss-webclient
    restart: unless-stopped
    privileged: true
    ports:
      - "8081:8081"

bash
docker compose up -d
docker compose ps
docker compose logs --tail 80 webclient

macOS 实测：两容器均为 Up，端口含 8081->8081；日志出现 creating template1 database … ok、setting password … ok 等即初始化成功。

Ubuntu 上若反复 core dump path is an invalid directory，见 FAQ Q9（core_pattern / apport）。macOS Docker Desktop 实测可正常 init。

7.2 浏览器访问

text
http://服务器IP:8081

本机：http://127.0.0.1:8081。局域网示例：http://192.168.x.x:8081。

7.3 界面怎么用（实测）

打开后通常已连上库名 postgres。左侧是对象浏览器，顶部为功能页签（数据 / 表结构 / 索引 / 约束 / SQL操作 / 操作历史 / 会话 / 链接信息）。

首次进入 SQL操作 时编辑器为空；左侧可能先看到 dbe_perf（性能相关视图很多，Tables 为 0 很正常）：

建议先跑一条确认连接——在 SQL 框输入后点紫色 执行：

sql
SELECT version();

实测结果为 openGauss 3.1.0（与主库容器的 5.0.0 不同，进一步证明是两套库）：

再建表示例（数据落在 webclient 内置库，不会写入主库 ./data）：

sql
CREATE TABLE demo_ui (
  id   INT PRIMARY KEY,
  name VARCHAR(64) NOT NULL
);
INSERT INTO demo_ui VALUES (1, 'alice'), (2, 'bob');
SELECT * FROM demo_ui;

执行后下方结果区可见 alice / bob；左侧切到 public → Tables** 会出现 **demo_ui`：

点选表后切到 数据 页签，可浏览行数据（带筛选与导出）：

表结构 页签查看列定义（如 id integer、name varchar(64)）：

索引 页签可见主键索引 demo_ui_pkey：

约束 页签可见 PRIMARY KEY (id)：

操作历史 可回看已执行的 SQL：

会话 页签可查看当前连接与后台线程（含 openGauss-webclient 应用名）：

链接信息 可确认当前用户、服务端地址等。实测：current_user / session_user 为 opengauss，容器内服务端口为 5433，版本串为 3.1.0：

和主库的关系（务必分清）：

text
浏览器 :8081  →  webclient 内置库（实测 openGauss 3.1.0，容器内 :5433，用户 opengauss）
gsql   :5432  →  opengauss:5.0.0 + ./data（本文权威数据，用户 gaussdb）

要操作主库持久化数据，请用 5432 + gsql；webclient 适合浏览器练手。镜像 1.0.4 久未更新，公网慎暴露 8081。

---

八、安全与生产加固

---

九、备选：docker run

9.1 仅主库

bash
# Linux 示例；macOS 把路径换成 ~/docker/opengauss/data
mkdir -p /www/wwwroot/opengauss/data
docker run -d \
  --name opengauss \
  --privileged=true \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -e GS_PASSWORD='openGauss@123' \
  -e LD_LIBRARY_PATH=/usr/local/opengauss/lib \
  -p 5432:5432 \
  -v /www/wwwroot/opengauss/data:/var/lib/opengauss/data \
  docker.xuanyuan.run/opengauss/opengauss:5.0.0

bash
docker exec opengauss /usr/local/opengauss/bin/gsql -d postgres -U gaussdb -c "SELECT version();"

9.2 仅 Web UI（可选）

bash
docker run -d \
  --name opengauss-webclient \
  --privileged=true \
  --restart unless-stopped \
  -p 8081:8081 \
  docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4

---

十、升级与迁移说明

1. 备份：docker compose stop 后拷贝 ./data。
2. 换标签：改 image: → pull → up -d；跨大版本先查发行说明。
3. 勿盲目升到 latest：先确认镜像内依赖完整（见 FAQ Q8）。

---

十一、常见问题 FAQ

Q1：gsql: command not found？
A：非交互 shell 默认 PATH 不含 /usr/local/opengauss/bin。使用：

bash
docker compose exec opengauss /usr/local/opengauss/bin/gsql -d postgres -U gaussdb -c "SELECT version();"

若出现 Password for user gaussdb:，输入 GS_PASSWORD（跟做示例 openGauss@123）即可。

Q2：latest 一直 Restarting，日志有 libopenblas.so.0？
A：当前实测 latest 镜像内缺少该库。改用 5.0.0（本文）。

Q3：gaussdb -V 报 Illegal instruction（exit 132）？
A：CPU 过旧、无 AVX。换带 AVX2 的机器（云主机注意机型），或换编译选项更保守的镜像后自测。

Q4：密码不符合复杂度？
A：至少 8 位，含大小写、数字与特殊字符。示例 openGauss@123。

Q5：数据目录挂哪？
A：本文与 Docker Hub / 轩辕镜像页一致：/var/lib/opengauss/data。实测 5.0.0 在此路径下可完成 init。

Q6：为什么必须 privileged？
A：官方要求；否则可能无法正常运行。

Q7：webclient 和主库是否共用数据？版本为什么不一样？
A：不共用。主库跟做为 opengauss/opengauss:5.0.0（5432 / gaussdb）；webclient 镜像内置库实测为 openGauss 3.1.0（容器内常听 5433，用户 opengauss），经浏览器 8081 访问。SELECT version() 两边结果不同是正常现象。

Q8：日志里一堆 GAUSSLOG / cgroup WARNING？
A：容器场景常见；只要 Up 且 gsql 可查，可先忽略。

Q9：webclient 反复 core dump path is an invalid directory？
A：宿主机 core_pattern 为 |…apport… 等管道时，openGauss 初始化易失败。可临时改为文件路径再测（影响整机，测完还原），或跳过 webclient，只用主库。

Q10：和 PostgreSQL 客户端通用吗？
A：端口习惯可借鉴，方言与驱动以 openGauss 为准。

---

十二、命令速查

bash
# 拉取
docker pull docker.xuanyuan.run/opengauss/opengauss:5.0.0

# Compose（Linux）
cd /www/wwwroot/opengauss
# macOS：cd ~/docker/opengauss
docker compose up -d
docker compose ps
docker compose logs --tail 100
docker compose exec opengauss /usr/local/opengauss/bin/gsql -d postgres -U gaussdb -c "SELECT version();"
# 若提示 Password，输入 GS_PASSWORD（示例 openGauss@123）
docker compose down

---

十三、延伸阅读

• 轩辕镜像：opengauss/opengauss · 标签
• 轩辕镜像：opengauss/opengauss-webclient · 标签
• 官方文档：容器单节点安装
• 项目站点：opengauss.org
• Docker Hub：opengauss/opengauss · opengauss-webclient
• 轩辕镜像使用手册：https://xuanyuan.cloud/usage

---

总结

• 跟做标签：opengauss/opengauss:5.0.0（避开有问题的 latest）。
• Compose：privileged + GS_PASSWORD + LD_LIBRARY_PATH + 数据卷；用 /usr/local/opengauss/bin/gsql 验证。
• webclient 可选，且默认不启用；与主库数据不共用。
• 关注 CPU（AVX）与 Linux 上 webclient 的 core_pattern 坑。

阅读原文

• 轩辕镜像官方博客：https://xuanyuan.cloud/blog/opengauss-docker-deploy