本文基于 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；它自带另一套库，不替代主库镜像。二者关系见下文「一、是什么 & 什么关系」。

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

场景

部署后怎么用

开发 / 联调

Compose 拉起后，应用或客户端连 服务器IP:5432，库名默认 postgres，用户 gaussdb

学习与实验

在容器内用 /usr/local/opengauss/bin/gsql 建表、写 SQL，数据挂到本机目录

浏览器轻操作

可选起 opengauss-webclient，打开 http://IP:8081（需先启用服务）

内网私有化试跑

库与数据不出域，适合选型评估与教学环境

本文按「能跟做」写完整链路：用 轩辕镜像 加速拉取 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 数据库引擎

（官方主镜像）

有更新，但标签质量不一

开发测试、学习、自托管联调
opengauss/opengauss-webclient Web UI

（浏览器操作库）

约 3 年前，标签 1.0.4

快速在浏览器里看库；不宜当长期生产前端
  • opengauss/opengauss

    ：容器内默认监听 5432。必须设置 GS_PASSWORD；默认有超级用户 omm 与测试用户 gaussdb。容器内本机信任连接通常可不输密码；从宿主机或其他容器连库则需密码。

  • opengauss/opengauss-webclient

    ：映射 8081 后用浏览器访问。镜像内会尝试自带库初始化，与主库不是同一份数据；且受宿主机 core_pattern 影响，在 Ubuntu 上易失败（见 FAQ）。

1.2 二者什么关系

方案 A（推荐主路径）  应用 / gsql / 图形客户端  ──:5432──▶  opengauss/opengauss（权威数据）  ./data                     ──挂载──▶  /var/lib/opengauss/data方案 B（可选体验）  浏览器  ──:8081──▶  opengauss/opengauss-webclient（Web UI，可含内置库）

问题

结论

是否必须一起部署？

 否

。只部署 opengauss/opengauss 即可。

webclient 能否替代主库？

 不建议

。

生产 / 联调数据放哪？

 opengauss/opengauss + ./data

。

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

1.3 关键参数一览

项

 opengauss/opengauss opengauss-webclient

跟做标签

 5.0.0 1.0.4

容器端口

 5432 8081

必填环境变量

 GS_PASSWORD

；实测另需 LD_LIBRARY_PATH

官方示例无额外必填项

privileged

 需要

建议需要（尤其 Linux）

默认库 / 用户

库 postgres，用户 gaussdb

以界面为准

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

二、环境要求

项目

建议

系统

Linux（如 Ubuntu 24.04）或 macOS + Docker Desktop

CPU

 x86_64 且支持 AVX / AVX2

（实测：无 AVX 的 Core2 Duo 会 SIGILL）

Docker

Engine + Compose V2

内存

≥ 1～2 GB 可用

磁盘

 5.0.0

 CONTENT SIZE 约 464MB 量级（DISK USAGE 约 1.7GB，以本机为准）+ 数据增长

端口

宿主机 5432；可选 8081

 
docker --versiondocker compose version# macOS：查看是否具备 AVX2（有则较稳）sysctl -a | grep -i leaf7_features# Linux：# grep -oE 'avx[^ ]*' /proc/cpuinfo | sort -u

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

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

备用地址：

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

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

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

三、标签怎么选

镜像

标签

实测结论

推荐
opengauss/opengauss 5.0.0

可起库、gaussdb -V 正常

 跟做 / 本文
opengauss/opengauss latest

缺 libopenblas.so.0，容器 Restarting

 暂勿跟做
opengauss/opengauss

其它版本号

需自测

生产钉版本前先验证
opengauss/opengauss-webclient 1.0.4

Ubuntu 上易因 core_pattern 初始化失败

可选体验

完整列表：opengauss tags、webclient tags。

四、拉取镜像

macOS 实测（主库 5.0.0）：

5.0.0: Pulling from opengauss/opengaussbf37c47dc58e: Already exists416428d7bb5a: Already exists15d09040b6af: Pull complete44de8bf8b4ac: Pull complete2ae1d2ac404d: Pull completeae0bcc1b03b5: Pull completea3d132d18f28: Pull complete7133e4484edf: Pull completeDigest: sha256:f8679ef310000452f7d1ce4c7752cee6fe63575fb6aa05fe8807090042645380Status: Downloaded newer image for docker.xuanyuan.run/opengauss/opengauss:5.0.0docker.xuanyuan.run/opengauss/opengauss:5.0.0

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

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

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

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

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:USER:PATH; gsql -d postgres -U gaussdb -c "SELECT version();"'

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

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

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

5.4 可选环境变量（主库）

变量

含义

默认 / 备注
GS_PASSWORD 必填

无
LD_LIBRARY_PATH

共享库搜索路径

实测设为 /usr/local/opengauss/lib
GS_USERNAME

连接用户名

 gaussdb
GS_NODENAME

节点名

 gaussdb
GS_PORT

库端口

 5432

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

6.1 进入交互式会话

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 建表示例

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 应用侧连接要点

项

值（本文跟做）

Host

服务器 IP 或 127.0.0.1

Port

 5432

Database

 postgres

User

 gaussdb

Password

与 GS_PASSWORD 一致

七、可选：使用 opengauss-webclient

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

7.1 启用并启动

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

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

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

  webclient:    image: docker.xuanyuan.run/opengauss/opengauss-webclient:1.0.4    container_name: opengauss-webclient    restart: unless-stopped    privileged: true    ports:      - "8081:8081"
docker compose up -d
docker compose psdocker 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 浏览器访问

http://服务器IP:8081

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

你想用什么

地址 / 方式

主库（权威数据，./data，5.0.0）

 5432

 + gsql / 应用（第五、六节）

Web UI（镜像内置库，实测 3.1.0）

 8081

（本节）

7.3 界面怎么用（实测）

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

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

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

SELECT version();

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

图片

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

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：




图片



 
  

   
    
区域 / 操作

   
    
说明

  

 
 
  

   
    
顶部库名 postgres

   
    
当前数据库

  

  

   过滤数据库对象
   
    
按名称筛选 schema / 表 / 视图

  

  

   SQL操作 → 执行
   
    
手写 SQL；结果可导出 JSON / CSV / XML

  

  

   数据 / 表结构 / 索引 / 约束
   
    
选中表后查看内容与元数据

  

  

   操作历史 / 会话 / 链接信息
   
    
历史、监控与连接属性

  

 



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


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


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






八、安全与生产加固





 
  

   
    
建议

   
    
做法

  

 
 
  

   
    
改密码

   
    
换强密码；已初始化数据目录不会因改环境变量自动改密

  

  

   
    
网络

   
    
5432 / 8081 仅内网；公网加防火墙 / HTTPS

  

  

   
    
标签

   
    
钉死版本（如 5.0.0），验证后再升

  

  

   
    
privileged

   
    
仅可信环境

  

  

   
    
备份

   
    
定期备份 ./data

  

 







九、备选：docker run




9.1 仅主库




# Linux 示例；macOS 把路径换成 ~/docker/opengauss/datamkdir -p /www/wwwroot/opengauss/datadocker 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



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




9.2 仅 Web UI（可选）




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. 
 
  2. 换标签
  
    ：改 image: → pull → up -d；跨大版本先查发行说明。
    3. 
 
  3. 勿盲目升到 latest
  
    ：先确认镜像内依赖完整（见 FAQ Q8）。
    4. 





十一、常见问题 FAQ




Q1：gsql: command not found？

   A：非交互 shell 默认 PATH 不含 /usr/local/opengauss/bin。使用：


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 为准。




十二、命令速查


# 拉取docker pull docker.xuanyuan.run/opengauss/opengauss:5.0.0# Compose（Linux）cd /www/wwwroot/opengauss# macOS：cd ~/docker/opengaussdocker compose up -ddocker compose psdocker compose logs --tail 100docker 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:5.0.0（避开有问题的 latest）。
    • 
 
  • 
  
    Compose：privileged + GS_PASSWORD + LD_LIBRARY_PATH + 数据卷；用 /usr/local/opengauss/bin/gsql 验证。
    • 
 
  • 
  
    webclient 可选，且默认不启用；与主库数据不共用。
    • 
 
  • 
  
    关注 CPU（AVX）与 Linux 上 webclient 的 core_pattern 坑。
    • 



转载：公众号源码跳动
 
  

        # docker
      
        # 开源
      
        # 数据库
      
        # 网络
      
  
 
 Logo 
华为开发者空间
 
华为开发者空间，是为全球开发者打造的专属开发空间，汇聚了华为优质开发资源及工具，致力于让每一位开发者拥有一台云主机，基于华为根生态开发、创新。
 
 
  
更多推荐
  
cover
 
DataArts Studio LakeAgent企业数据平台的智能员工
 
 
avatar 华为开发者空间
 
cover
 
【公共云三十问 之二十】中国公共云产业的“关键一跃”是什么？
 
 
avatar 华为开发者空间
 
 
从“一屏一态”到“一屏多能”：WPS通过HarmonyOS多窗口能力重塑移动办公体验
 
多屏协同、自由分屏，正成为移动办公的新常态。面对多样化的设备形态和用户场景，WPS Office与HarmonyOS SDK深度合作，通过全新的窗口管理与响应式布局能力，实现跨设备无缝适配与高效多任务处理。一次开发，多端自适应——这场关于“一屏多用”的体验升级，如何重新定义手机办公？
 
avatar 华为开发者空间