openGauss 容器部署、PostgreSQL 兼容与国产化开发验证手册

openGauss 容器部署、PostgreSQL 兼容与国产化开发验证手册参考图openGauss 从 6.0.5 LTS、官方容器、gsql、JDBC、omm、业务用户、DBCOMPATIBILITY、pg_hba.conf、PostgreSQL 兼容验证到团队治理的落地链路。高清原图

从一次错误的 PostgreSQL 替换开始

项目把 JDBC 地址从 PostgreSQL 改成 openGauss 后，健康检查很快变绿，第一轮迁移却在类型、函数或系统视图处失败。更隐蔽的情况是 SQL 能执行，但对象建进了 public，应用拿着超级用户运行，或者本地连接的是宿主 PostgreSQL 而不是容器里的 openGauss。客户端协议相近只能证明“能握手”，不能证明方言、权限、事务和恢复链路等价。

把 openGauss 作为独立数据库依赖落地，需要沿同一条证据链推进：固定版本和镜像，启动实例，创建业务 database、用户与 schema，用真实驱动跑正反 SQL，再恢复一次备份。稳定开发环境可采用 openGauss 6.0.5 LTS；下载页同时列出维护周期、CPU、操作系统和配套驱动，实施前要把这些信息写入依赖台账。创新版适合隔离验证新能力，不应和共享环境的稳定基线混用。openGauss 内核采用木兰宽松许可证第二版，企业发行版、云服务和技术支持则可能另有合同边界，不能把开源许可等同于商业服务承诺。

第一次启动前准备这些资源：

Docker / Podman / Compose，或者一台符合 openGauss 官方安装要求的 Linux 开发机。openGauss 官方容器镜像、官方安装包或团队已经验收过的内部镜像。预留端口，例如宿主 8888 或 15432 映射容器 5432，避免和本机 PostgreSQL 冲突。

至少一种客户端：gsql、DBeaver、DataGrip、应用 JDBC 或团队内部数据库客户端。一个符合复杂度的强密码占位符，例如 YOUR_STRONG_OPENGAUSS_PASSWORD，真实值只放本机 .env 或密钥系统。一块可随实验销毁的数据卷，以及一份明确禁止指向生产地址的重置脚本。

先检查端口：

docker version
docker compose version
lsof -i :8888
lsof -i :15432

Windows：

netstat -ano | findstr ":8888"
netstat -ano | findstr ":15432"

如果开发机是 ARM、国产 CPU 或企业专用 Linux 发行版，要按下载页列出的架构和操作系统选择软件包，并在目标机器重跑 smoke test。CPU 架构、OS、glibc、内核参数和镜像来源不能从普通 x86 教程类推。

主流部署方式

方式	定义	适用场景	不适合
固定版本容器镜像	按官方二进制包构建，或使用团队已验收并锁定 digest 的镜像	本地学习、功能验证、CI smoke、短期联调	长期生产、无版本锁定的共享库
官方安装包本机安装	按官方安装文档在 Linux 上安装 openGauss	固定开发机、国产 OS 验证、接近生产依赖	快速清理、多版本并存
团队内部镜像	平台团队基于官方镜像或官方包构建并扫描	多项目统一版本、内网仓库、离线环境	无 owner、无 digest 的临时镜像
共享开发实例	DBA 或平台团队提供的非生产 openGauss	多人联调、国产化适配、权限和 SQL 验证	个人 reset、无清理策略
云化或企业发行版	云厂商或企业服务提供的 openGauss 兼容服务	云上联调、托管运维、企业支持	直接复制容器命令上生产

选型建议：

个人学习：使用官方容器镜像或官方安装包。项目联调：使用团队内部镜像或共享开发实例，并记录版本、镜像 digest、数据库初始化参数和 owner。国产 OS / CPU 适配：必须在目标架构跑 smoke test，不能用普通 x86 镜像结论替代。

生产兼容验证：使用与目标生产同版本、同补丁、同字符集、同参数的非生产实例。生产部署：开发验证通过后仍需独立设计主备、备份、监控、容量和容灾，Compose 结果不能充当生产验收。

Docker 单容器

官方容器安装说明采用“下载对应版本二进制包，再用仓库内构建脚本生成镜像”的方式。先将构建结果或团队镜像写入变量，不要把 latest 当成可复现版本：

export OPENGAUSS_IMAGE='your-registry.example.com/database/opengauss:6.0.5@sha256:<digest>'

docker run --name og-dev --privileged=true -d \
  -e GS_PASSWORD=YOUR_STRONG_OPENGAUSS_PASSWORD \
  -e GS_USERNAME=gaussdb \
  -p 8888:5432 \
  -v og-dev-data:/var/lib/opengauss \
  "$OPENGAUSS_IMAGE"

等待启动：

docker ps
docker logs og-dev --tail 160

进入容器验证：

docker exec -it og-dev bash
su - omm
gsql -d postgres -p 5432

容器外如果已安装 gsql：

gsql -d postgres -U gaussdb -W YOUR_STRONG_OPENGAUSS_PASSWORD -h 127.0.0.1 -p 8888

说明：

GS_PASSWORD 必须至少 8 位并同时包含大小写字母、数字，以及 #?!@& 中的特殊字符；特殊字符还要按当前 Shell 的规则引用或转义。容器内端口是 5432，宿主端口按 -p 映射使用。omm 是超级用户，不作为应用远程连接用户。

GS_PASSWORD、GS_USERNAME、GS_PORT 是官方通用容器文档列出的变量；额外变量必须以目标镜像的 entrypoint 为准。官方示例的持久化挂载点是 /var/lib/opengauss。挂错到子目录可能让数据仍落在容器可写层，删容器后才发现“有 volume 但没有备份到数据”。

Docker Compose

下面的 Compose 把单容器参数固化为可重复的开发环境：

services:
  opengauss:
    image: "${OPENGAUSS_IMAGE}"
    container_name: tool-opengauss-dev
    privileged: true
    environment:
      GS_PASSWORD: "${OPENGAUSS_PASSWORD}"
      GS_USERNAME: "gaussdb"
      GS_PORT: "5432"
    ports:
      - "8888:5432"
    volumes:
      - opengauss-data:/var/lib/opengauss
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "su - omm -c \"gsql -d postgres -p 5432 -c 'select 1;'\" >/dev/null 2>&1"
        ]
      interval: 20s
      timeout: 10s
      retries: 30
      start_period: 90s

volumes:
  opengauss-data:

.env.example：

OPENGAUSS_PASSWORD=YOUR_STRONG_OPENGAUSS_PASSWORD
OPENGAUSS_APP_PASSWORD=YOUR_STRONG_OPENGAUSS_APP_PASSWORD
OPENGAUSS_IMAGE=your-registry.example.com/database/opengauss:6.0.5@sha256:<digest>

团队模板必须补充：

具体镜像版本或 digest。数据目录实际挂载点是否与镜像一致。初始化脚本如何执行。

CI runner 是否允许 privileged。端口、库名、业务用户、兼容模式和清理脚本。

OPENGAUSS_APP_PASSWORD 由后续初始化 SQL 消费，不会被上述通用镜像自动创建为业务账号。把它只写进 .env 却没有执行建用户 SQL，会产生“配置看似齐全、应用用户实际不存在”的假象。

端口、认证和 pg_hba.conf

openGauss 容器内默认数据库端口是 5432。官方示例映射宿主 8888：

localhost:8888 -> container:5432

远程连接必须同时满足：

数据库监听地址允许外部访问。客户端接入认证配置允许当前 IP、database、user 和认证方式。防火墙、容器端口、VPN 和代理没有拦截。

应用连接串和 JDBC 参数正确。不使用 omm 做远程业务连接。

不要为了方便把所有网段改成 trust。开发库也要使用密码认证，并把修改记录到 docs/dependency-setup.md。

database、user、schema 和兼容模式

openGauss 接近 PostgreSQL 的 database / user / schema 组合，但数据库兼容模式会影响语法和行为。开发样例：

CREATE USER app_tool_efficiency PASSWORD 'YOUR_STRONG_OPENGAUSS_APP_PASSWORD';
CREATE DATABASE app_tool_efficiency
  OWNER app_tool_efficiency
  ENCODING 'UTF8'
  DBCOMPATIBILITY 'PG'
  TEMPLATE template0;

连接到目标库后：

CREATE SCHEMA IF NOT EXISTS app AUTHORIZATION app_tool_efficiency;
ALTER ROLE app_tool_efficiency SET search_path = app, public;

权限原则：

应用账号不使用 omm。migration 账号和 runtime 账号分离。共享实例中每个项目独立 database 或独立 schema，不混用个人 schema。

search_path 必须写清，否则迁移脚本容易在错误 schema 建表。DBCOMPATIBILITY 在建库时明确，不能等业务表创建后再随意切。

JDBC

openGauss 的 JDBC 口径要在项目里做一次明确选择：

选择	适用	风险
openGauss-jdbc	使用 org.opengauss.Driver 和 jdbc:opengauss://	要校准驱动包版本和框架兼容
PostgreSQL 兼容包	使用 org.postgresql.Driver 和 jdbc:postgresql://	同 JVM 驱动冲突、metadata、异常码和方言要验证
企业封装数据源	公司平台统一管理	依赖平台配置，不适合本地临时复制

推荐开发连接串：

spring.datasource.url=jdbc:opengauss://localhost:8888/app_tool_efficiency?connectTimeout=10&socketTimeout=30
spring.datasource.username=app_tool_efficiency
spring.datasource.password=YOUR_STRONG_OPENGAUSS_APP_PASSWORD
spring.datasource.driver-class-name=org.opengauss.Driver

如果团队选择 PostgreSQL 兼容驱动，连接串和 driver class 必须另写，并补充兼容验证清单。不能同一项目里一部分用 jdbc:opengauss、一部分用 jdbc:postgresql。

一条写请求在内核里经历什么

连接成功后，SQL 先经过解析、重写和优化，执行器再按计划访问表与索引页。热点数据主要从共享缓冲区读取，修改先形成内存脏页和 WAL；事务提交必须满足当前刷盘与同步复制策略，数据页可以稍后由检查点逐步落盘。崩溃恢复依赖 WAL 重放把数据文件推进到一致状态，所以“表文件已经写入”“事务已经提交”和“备库已经重放”是三个不同状态。

这条链路直接解释了常见现象：

缺索引时，执行计划可能从索引扫描退化成全表扫描，缓冲区命中率与 I/O 会同时恶化。长事务会长期保留旧版本可见性边界，推迟垃圾版本回收，并使 WAL、锁等待和主备追赶成本上升。同步复制把提交延迟暴露给业务，异步复制降低主库等待，但故障切换时必须接受未同步事务的丢失窗口。

备库“可连接”不代表“读到刚提交的数据”；路由到备库前必须定义允许的回放延迟与读一致性语义。

用两个会话可以稳定制造锁等待。会话 A 执行更新但不提交：

BEGIN;
UPDATE app.user_demo SET username = 'held-by-a' WHERE id = 1;

会话 B 更新同一行会等待。第三个管理会话用 pg_stat_activity 查看等待会话及其查询，再由会话 A ROLLBACK。预期会话 B 随后继续执行；若直接终止数据库进程，只会把可诊断的事务竞争变成恢复事件。项目上线前要给连接池设置事务超时与语句超时，并保证异常路径明确回滚、归还连接。

执行计划实验也要做正反两次。在固定数据集上先查询未建索引的选择性字段并保存 EXPLAIN，再创建索引、更新统计信息并重跑：

EXPLAIN SELECT * FROM app.user_demo WHERE username = 'demo';
CREATE INDEX idx_user_demo_username ON app.user_demo(username);
ANALYZE app.user_demo;
EXPLAIN SELECT * FROM app.user_demo WHERE username = 'demo';

小表仍选择顺序扫描并不代表索引失效，优化器可能判断全表读取更便宜。应扩大到接近真实分布的数据量，再比较计划、返回行估算和执行耗时；不要用强制 Hint 掩盖统计信息或数据倾斜问题。

启动：

docker compose up -d
docker compose ps
docker logs tool-opengauss-dev --tail 120

进入 CLI：

docker exec -it tool-opengauss-dev bash
su - omm
gsql -d postgres -p 5432

确认版本、编码和时区：

SELECT version();
SHOW server_encoding;
SHOW timezone;
SELECT current_database(), current_user, current_schema();
SHOW search_path;

创建应用库和用户：

CREATE USER app_tool_efficiency PASSWORD 'YOUR_STRONG_OPENGAUSS_APP_PASSWORD';
CREATE DATABASE app_tool_efficiency
  OWNER app_tool_efficiency
  ENCODING 'UTF8'
  DBCOMPATIBILITY 'PG'
  TEMPLATE template0;

用应用账号连接后：

CREATE SCHEMA IF NOT EXISTS app AUTHORIZATION app_tool_efficiency;
SET search_path TO app, public;

CREATE TABLE user_demo (
  id BIGSERIAL PRIMARY KEY,
  username VARCHAR(64) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
);

INSERT INTO user_demo(username) VALUES ('demo');
SELECT id, username, created_at FROM user_demo ORDER BY id;

预期查询返回一行 demo，并且下面两项都必须成立；第一项证明当前连接没有误落到 postgres，第二项证明对象没有漂到 public：

SELECT current_database(), current_user, current_schema();
SELECT schemaname, tablename FROM pg_tables WHERE tablename = 'user_demo';

接着创建只读运行账号，观察最小权限是否真的生效：

-- 由对象所有者或迁移账号执行
CREATE USER app_tool_readonly PASSWORD 'YOUR_STRONG_OPENGAUSS_READONLY_PASSWORD';
GRANT CONNECT ON DATABASE app_tool_efficiency TO app_tool_readonly;
GRANT USAGE ON SCHEMA app TO app_tool_readonly;
GRANT SELECT ON app.user_demo TO app_tool_readonly;

-- gsql 中切换为只读账号，再执行正反操作
\c app_tool_efficiency app_tool_readonly
SELECT id, username FROM app.user_demo;
INSERT INTO app.user_demo(username) VALUES ('should_fail');

预期查询成功，插入得到 permission denied 一类错误。若仍能写入，通常是只读账号继承了过大的角色，或测试连接仍在使用对象所有者、omm。先用 SELECT current_user; 确认身份，再检查角色授权。

逻辑备份入口：

docker exec -it tool-opengauss-dev bash -lc "su - omm -c 'gs_dump -p 5432 -d app_tool_efficiency -f /tmp/app_tool_efficiency.sql'"

恢复必须在临时库或临时 schema 试跑，不要只生成文件：

docker exec -it tool-opengauss-dev bash -lc "su - omm -c 'gsql -d postgres -p 5432'"

在 gsql 中创建恢复目标：

CREATE DATABASE app_tool_efficiency_restore
  OWNER app_tool_efficiency
  ENCODING 'UTF8'
  DBCOMPATIBILITY 'PG'
  TEMPLATE template0;

退出 gsql 后执行恢复：

docker exec -it tool-opengauss-dev bash -lc \
  "su - omm -c 'gsql -d app_tool_efficiency_restore -p 5432 -f /tmp/app_tool_efficiency.sql'"

备份文件存在不等于可恢复。临时创建 app_tool_efficiency_restore，恢复后比较业务表数量与关键行数；恢复失败时保留 gsql 的首个错误、镜像 digest、数据库版本和建库参数，修正后从空库重跑，不能在半恢复状态上继续补 SQL。

恢复验收完成后再清理源端实验对象：

\c app_tool_efficiency app_tool_efficiency
REVOKE SELECT ON app.user_demo FROM app_tool_readonly;
REVOKE USAGE ON SCHEMA app FROM app_tool_readonly;
REVOKE CONNECT ON DATABASE app_tool_efficiency FROM app_tool_readonly;
DROP USER app_tool_readonly;
DROP TABLE app.user_demo;

项目里建议保留：

compose.yaml
.env.example
db/
  opengauss/
    init/
      001_user.sql
      002_schema.sql
    migration/
    verify/
      verify.sql
    backup/
docs/
  dependency-setup.md
scripts/
  opengauss-up.sh
  opengauss-verify.sh
  opengauss-reset-dev.sh

Flyway / Liquibase 接入要先验证：

DDL 是否兼容当前 DBCOMPATIBILITY。schema history 表落在哪个 schema。BIGSERIAL、sequence、identity、timestamp、boolean、JSON 类型是否符合项目预期。

search_path 是否固定。失败 rollback 是工具处理、手工处理还是重建开发库。本地、CI、共享开发库是否使用同一 JDBC driver。

查看日志：

docker logs tool-opengauss-dev --tail 120

查看连接：

SELECT datname, usename, client_addr, state
FROM pg_stat_activity
ORDER BY datname, usename;

查看 schema 对象：

SELECT schemaname, tablename
FROM pg_tables
WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
ORDER BY schemaname, tablename;

容量判断从趋势开始，而不是先抄一个磁盘告警百分比：

SELECT pg_size_pretty(pg_database_size(current_database())) AS database_size;
SELECT schemaname,
       relname,
       pg_size_pretty(pg_total_relation_size(quote_ident(schemaname) || '.' || quote_ident(relname))) AS total_size
FROM pg_stat_user_tables
ORDER BY pg_total_relation_size(quote_ident(schemaname) || '.' || quote_ident(relname)) DESC;

在固定数据量和固定脚本下连续跑多轮，数据库大小应回到可解释的增长曲线；删除数据后空间未立刻归还操作系统并不等于泄漏。上线容量预算要同时包含表、索引、WAL、临时文件、备份与恢复副本，并用实际增长率和保留期推导磁盘，而不是只看当前表大小。

查看配置入口：

SHOW data_directory;
SHOW hba_file;
SHOW config_file;

停止开发库：

docker compose down

只有确认是本地开发数据，才允许删除 volume：

docker compose down -v

容器启动失败

判断：

docker compose ps
docker logs tool-opengauss-dev --tail 160

常见原因：

GS_PASSWORD 缺失或复杂度不满足要求。CI runner 不允许 privileged。镜像架构和主机架构不匹配。

数据目录已经有旧初始化状态。宿主端口被 PostgreSQL 或旧 openGauss 占用。

容器内能连，容器外连不上

处理路径：

区分容器内 5432 和宿主映射端口。用业务用户连接，不用 omm 做远程连接。检查客户端接入认证。

检查防火墙、VPN、代理和 Docker Desktop 网络。

JDBC 长时间无响应

连接 URL 要设置 connectTimeout 和 socketTimeout，否则网络异常时可能拖到系统超时：

spring.datasource.url=jdbc:opengauss://localhost:8888/app_tool_efficiency?connectTimeout=10&socketTimeout=30

JDBC 驱动冲突

如果同一个 JVM 既连接 PostgreSQL 又连接 openGauss，优先使用 openGauss 独立 JDBC 包和 org.opengauss.Driver，避免与 PostgreSQL 驱动类名冲突。

PostgreSQL 兼容误判

现象：

PostgreSQL 客户端能连，但迁移 SQL 失败。DDL 在 PostgreSQL 通过，在 openGauss 报语法或类型错误。ORM 根据 PostgreSQL dialect 生成了不适合 openGauss 的 SQL。

Python 侧直接使用 psycopg2-binary 在默认模式下失败。

处理：

保留 openGauss smoke test，不只跑 PostgreSQL。迁移前列出 SQL 差异清单。用真实驱动跑 CI。

对 sequence、identity、JSON、函数、分页、锁和事务隔离做样例验证。

旧 volume 保留旧状态

如果数据目录已经初始化，修改 .env 中的密码、初始化 SQL 或兼容模式未必生效。

处理：

本地个人库可以受控 docker compose down -v。共享开发库必须由 owner 执行 SQL 修改和清理。重建前先确认没有测试数据、dump 或联调账号被误删。

不能进入仓库的内容：

OPENGAUSS_PASSWORD、OPENGAUSS_APP_PASSWORD、.env。真实 JDBC URL、内网 IP、VPN 地址、共享库账号。备份 SQL、dump、日志、慢查询样本和客户数据。

内部镜像仓库凭证、registry token 和镜像拉取脚本中的账号。客户端接入认证配置中暴露真实网段的片段。

.gitignore 建议：

.env
db/opengauss/backup/*.sql
db/opengauss/backup/*.dump
db/opengauss/logs/**

共享 openGauss 开发库至少要有：

镜像来源、安装包来源、版本、tag、digest 和 owner。数据库端口、连接方式、JDBC 驱动版本和客户端版本。database / schema / user 命名规范。

runtime / migration / readonly 账号。客户端接入认证变更流程。备份恢复入口和清理周期。

PostgreSQL 兼容验证清单。国产 OS / CPU 适配结果。LTS / RC 版本使用边界。

从单实例走向主备

openGauss 部署方案区分单机、主备和一主多备。单机只有一份数据，适合语法验证和可丢弃开发库；主备通过 WAL 传输与重放保留副本；一主多备可以增加故障承受能力或只读能力，但副本数、同步策略、网络与存储开销都会上升。生产选型不能只问“要几台机器”，而要先写清允许的数据丢失窗口、恢复时间、读一致性和故障域。

架构	写入与复制链路	得到什么	主要代价与验证重点
单实例	应用直接写单节点	成本低、调试简单	节点故障即中断；必须证明备份可恢复
一主一备	主库写入，备库接收并重放 WAL	可承受单实例故障	同步复制增加提交延迟；异步复制存在数据窗口
一主多备	主库向多个备库复制，可设置同步候选	多副本、读扩展与更灵活的切换目标	写放大、网络带宽、WAL 保留和运维复杂度增加
读写分离	写流量到主库，只读流量按策略到备库	降低主库读压力	回放延迟导致读旧值，事务内不能随意跨节点
分片或中间件扩展	路由层按分片键把数据分到多个独立库	突破单机容量或吞吐边界	跨分片事务、全局唯一键、扩容搬迁和排障成本陡增

主备状态不能只看进程存活。切换演练至少记录当前主备角色、发送与接收位置、重放延迟、同步策略和应用重连耗时。计划切换先阻止新写入或确认同步位置，再执行 switchover；故障接管只有在旧主已隔离且数据一致性判断完成后才能 failover，否则旧主恢复联网时会形成双主写入。旧主重新加入通常需要增量或全量 build，不能直接以原数据目录启动。

读写分离也需要反向实验：在主库提交一条带唯一标识的数据，立即从只读入口查询并记录首次可见时间。若业务要求写后立刻读到自己的数据，就应在事务内固定主库，或让路由层在写后的一段语义窗口内保持主库亲和；不能把复制延迟包装成“偶发缓存问题”。

备份、升级与回退不是同一件事

gs_dump 适合对象级迁移和开发验证，gs_probackup 等物理备份能力面向实例级恢复与时间点恢复。逻辑备份无法替代 WAL 归档，主备副本也不是备份：误删、错误 DDL 和逻辑破坏会复制到备库。团队要同时保留逻辑导出、物理备份、WAL/归档保留策略与异地副本，并定期从空环境恢复。

升级前先在同 CPU、OS、扩展、驱动和关键参数的影子环境恢复一份脱敏备份，执行 schema migration、核心 SQL、权限拒绝和主备切换 smoke。数据库数据目录一旦被新版本升级，不能假定旧二进制仍可直接启动；可回退路径应是停止写入、切回未升级副本，或从升级前备份恢复到旧版本兼容环境。应用回退也要检查新版本是否已经写入旧应用不认识的 schema 或数据格式。

容量成本至少拆成五本账：主数据与索引、WAL 与归档、每个备库的完整副本、备份与恢复临时空间、监控审计和网络流量。同步备库跨高延迟网络会把距离直接加到提交路径，一主多备会增加日志发送和重建流量；分片减少单节点压力，却把容量变成更多机器、更多连接池和更多迁移工作。只有当单机经过索引、SQL、分区、冷热治理和硬件扩容后仍无法满足目标，才值得承担分片的长期复杂度。

深水区	现象	判断入口	配置 / 命令 / 取舍
LTS / RC 混用	本地用 RC，团队共享用 LTS	版本页、SELECT version()	稳定项目以 LTS 为主
镜像来源不清	本地能跑但 CI 不接受	镜像仓库、digest、SBOM	官方镜像或内部验收镜像
把 openGauss 当 PostgreSQL	单测过了，联调 SQL 失败	驱动、dialect、DDL diff	每个项目保留 openGauss smoke
容器需要特权	普通 CI runner 起不来	docker logs、runner policy	使用专用 runner 或共享实例
端口冲突	本机 PostgreSQL 和 openGauss 混连	lsof -i、连接串	宿主端口固定为 8888 或 15432
omm 远程滥用	应用拿超级用户连接	session、配置扫描	创建业务用户
认证放开过大	共享库被非预期访问	认证配置、审计日志	精确网段和密码认证
旧 volume	改密码或初始化 SQL 不生效	volume、data_directory	本地可删，团队库走 owner
search_path 错	表建到 public 或个人 schema	SHOW search_path	项目 schema 固定
兼容模式后改	已有表行为不一致	database DDL、迁移记录	建库前确定 DBCOMPATIBILITY
驱动混用	本地 jdbc:postgresql，CI jdbc:opengauss	依赖树、配置中心	单项目统一驱动策略
超时未配置	网络抖动时请求挂住	JDBC URL	配 connectTimeout / socketTimeout
字符集和排序	中文、大小写、排序异常	encoding、collation	初始化前确认，不靠后期修
备份未恢复验证	有 SQL 文件但不可用	临时库恢复	每个模板保留恢复 smoke
误连生产	清理脚本删错库	URL、库名、账号	reset 脚本加白名单和确认

openGauss 的深水区不在“能不能连上”，而在“你到底验证的是 openGauss，还是一个 PostgreSQL 幻觉”。版本、镜像、驱动、认证、兼容样例和团队清理边界必须能被同事复核。

共享环境的准入门禁

一个 openGauss 开发实例可以交给团队使用之前，应留下可复核证据：SELECT version() 与镜像 digest 对得上；真实 JDBC 驱动完成建表、写入、查询和权限拒绝实验；current_database()、current_user、current_schema() 与项目约定一致；临时库恢复成功且关键表行数吻合；重置脚本拒绝生产域名、生产网段和非开发库名。

凭证轮换也要演练。先创建新密码并刷新密钥系统，让连接池建立新连接；确认旧连接自然排空后再撤销旧凭证。验收看的是旧凭证无法新建连接、错误率回落且连接数恢复稳定，而不是“配置中心已经改过”。共享库还要按月复查闲置账号、长期事务、database/schema 增长、备份可恢复性和即将结束维护的版本，给每项异常绑定 owner 与处理期限。

openGauss 不是 PostgreSQL 改名。只有版本、镜像、驱动、认证、兼容样例、恢复证据和团队责任都能重复验证，它才是一项可控的工程依赖。