KingbaseES Docker、兼容模式与 JDBC 开发验证手册

KingbaseES Docker、兼容模式与 JDBC 开发验证手册参考图KingbaseES 从官方下载、Docker tar、54321、DB_USER / DB_PASSWORD、DB_MODE、ENCODING、ksql、JDBC、兼容模式、license 与团队治理的落地链路。高清原图

从“能连上”走到“可以交付”

KingbaseES 在研发环境里也容易被写偏：有人只知道它默认端口 54321，却不知道 Docker 镜像是 tar 包导入；有人把系统账号或文档示例密码写进项目；有人把 DB_MODE=oracle 当成运行时开关，建完表再想切 PostgreSQL 或 MySQL；有人把 Docker 精简镜像当成包含所有客户端和驱动的完整安装包，结果 JDBC、ksql、license、encoding 和 volume 都没有写清。

真正的适配证据不是一条 select 1，而是版本与补丁可追踪、初始化参数一致、应用账号最小授权、迁移脚本可重复执行、关键 SQL 语义经过正反验证、备份能够恢复，并且团队知道何时应该停用开发容器，进入 RAC、RWC、备份平台或正式容灾方案的评审。

KingbaseES 也不能简单视作“换了端口的 PostgreSQL”或“兼容 Oracle 的数据库”。兼容模式会改变初始化后的 SQL 语义，驱动和数据库补丁又分别迭代；一个在开发机能工作的 SQL、JDBC 驱动或 ORM 方言，未必能在目标版本和目标模式中保持相同行为。

准备一套可丢弃的验证环境

第一次操作前准备：

KingbaseES 官方下载账号或邮箱验证码，按项目需要下载安装包、Docker 镜像 tar 和 JDBC 驱动。Docker / Compose，或一台符合 KingbaseES 安装要求的 Linux / Windows 开发机。预留端口 54321，本机已有 KingbaseES 或共享环境时映射为 154321:54321。

至少一种客户端：ksql、DBeaver、DataGrip、应用 JDBC 或企业内部工具。一个强密码占位符，例如 YOUR_STRONG_KINGBASE_PASSWORD，真实值只放本机 .env 或密钥系统。一套明确标记为开发或验证环境的主机、账号和数据。试用授权、开发 Compose 与本地 volume 都不能直接承担生产数据。

先检查端口：

docker version
docker compose version
lsof -i :54321

Windows：

netstat -ano | findstr ":54321"

KingbaseES Docker 镜像不是公共仓库里随手拉取的通用镜像，而是从产品下载中心取得 tar 包后导入。下载页把 ISO 描述为包含数据库主体、接口驱动和工具的全量包，把 Docker 镜像描述为只含数据库主体的精简 tar 包；数据库、接口驱动和工具的补丁还会分别迭代。因此环境清单至少要记录数据库版本与补丁、驱动版本、镜像文件哈希、license owner 和到期处置人。

下文容器参数以官方 V8 Docker 手册展示的镜像行为为验证基线，不代表任意 V8/V9 构建都能混用同一镜像、驱动或补丁。下载到介质后先记录 docker image inspect 结果、数据库 SELECT version() 输出和 JDBC 驱动版本；项目目标若是 V9 或指定补丁线，应回到对应版本手册重新核对参数和兼容矩阵，不能因为产品名相同就沿用 V8 示例。

冻结版本和初始化参数

Docker 安装手册给出的容器内默认端口是 54321，DB_USER、DB_PASSWORD、DB_MODE、ENCODING 等变量在首次初始化时参与创建数据库。DB_MODE 对应 initdb --dbmode 的初始化选择；已有数据目录会保留旧状态，修改 Compose 环境变量并不会把现有库转换成另一种模式。

首次启动前冻结这些字段：

字段	决定什么	修改后的代价
数据库版本与补丁	SQL 行为、安全修复、系统目录和工具兼容	需要升级验证与回退包
JDBC 驱动版本	URL 解析、类型映射、连接与协议兼容	需要应用回归和连接池验证
DB_MODE	Oracle、PG、MySQL 等兼容语义	通常应重建并迁移，不能原地当开关
ENCODING / locale	字符存储、排序、大小写与客户端转换	建库后修改成本高，可能要导出导入
timezone	时间显示、默认值与跨系统比对	需要数据库、JVM、业务字段统一
数据目录与 license 路径	数据和授权能否跨容器重建保留	路径错会表现为“新库”或授权失效

下载页或手册发生变化时，应在升级工单中重新核对包类型、哈希、补丁关系、支持平台和授权条款；这些事实影响的是可部署性，不应靠旧环境截图推断。

主流部署方式

方式	定义	适用场景	不适合
官方 Docker tar	下载官方 tar，docker load 后运行	本地学习、CI smoke、短期联调	未授权分发、生产
Linux / Windows 安装包	使用官方安装介质完整安装	固定开发机、工具链完整体验	快速清理、多版本并存
共享开发实例	DBA 或平台团队提供的非生产 KingbaseES	多人联调、权限验证、兼容模式验证	个人 reset、随意改初始化模式
企业非生产实例	与生产版本接近的测试库	上线前验证、迁移演练	替代生产 runbook
云化或托管能力	云或企业服务提供的 KingbaseES 能力	云上联调、托管运维体验	直接把开发 Docker 命令用于生产

选型建议：

个人学习：官方 Docker tar 或完整安装包。团队联调：共享开发实例，明确 DB_MODE、encoding、license、账号和 owner。兼容验证：按目标应用选择 Oracle / PG / MySQL 模式，在初始化前定稿。

生产兼容验证：使用与生产同版本、同补丁、同初始化参数的非生产实例。生产部署：由 DBA 和平台团队按容量、高可用、备份与安全要求实施，不复制开发 Compose。

Docker tar 单容器

官方手册的核心流程是先导入 tar：

docker load -i kingbase.tar
docker images

学习环境运行示例：

docker run -tid --privileged \
  -p 54321:54321 \
  -v /tmp/kingbase-data:/home/kingbase/userdata/ \
  -e DB_USER=kingbase \
  -e DB_PASSWORD=YOUR_STRONG_KINGBASE_PASSWORD \
  -e DB_MODE=oracle \
  -e ENCODING=utf8 \
  --name kingbase \
  kingbase:v1 \
  /usr/sbin/init

说明：

kingbase:v1 是导入后的本地镜像名示例，实际以 docker images 为准。DB_USER / DB_PASSWORD 必须显式设置，不把手册示例密码写进项目。DB_MODE 是初始化模式，不能建完表后随便切。

ENCODING 建议显式设置并用 SQL 验证。volume 目录权限不足会导致 Permission denied。

Docker Compose

Compose 是由官方 docker run 参数改写的本地学习模板，不是官方通用模板：

services:
  kingbase:
    image: "${KINGBASE_IMAGE}"
    container_name: tool-kingbase-dev
    privileged: true
    environment:
      DB_USER: "kingbase"
      DB_PASSWORD: "${KINGBASE_PASSWORD}"
      DB_MODE: "oracle"
      ENCODING: "utf8"
      NEED_START: "true"
    ports:
      - "54321:54321"
    volumes:
      - kingbase-data:/home/kingbase/userdata/
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "ksql -Ukingbase -d test -c 'select 1;' >/dev/null 2>&1"
        ]
      interval: 20s
      timeout: 10s
      retries: 30
      start_period: 90s

volumes:
  kingbase-data:

.env.example：

KINGBASE_IMAGE=kingbase:v1
KINGBASE_PASSWORD=YOUR_STRONG_KINGBASE_PASSWORD
KINGBASE_APP_PASSWORD=YOUR_STRONG_KINGBASE_APP_PASSWORD

团队模板必须补充：

tar 包来源、下载日期、版本、试用授权和 owner。镜像 tag / digest。DB_MODE、ENCODING、locale、timezone。

客户端和 JDBC 驱动获取方式。volume、license、配置文件持久化路径。

用户、库和 schema

KingbaseES 支持 database，但兼容模式会影响对象、类型和 SQL 行为。学习环境可以用：

CREATE USER app_tool_efficiency WITH PASSWORD 'YOUR_STRONG_KINGBASE_APP_PASSWORD';
CREATE DATABASE app_tool_efficiency OWNER app_tool_efficiency;

连接目标库后：

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

原则：

应用不使用 system 或安装管理账号。runtime / migration / readonly 账号分离。共享实例中每个项目独立 database 或 schema。

初始化模式和 encoding 先定，再建业务对象。search_path 写进初始化脚本和项目文档。

共享环境把建表与运行权限拆开。迁移账号拥有目标 schema 的 DDL，运行账号只获得业务所需的 DML，只读账号只获得查询权限。授权语句要按目标版本验证，不能直接给所有账号管理员角色。完成授权后，用运行账号故意执行一条 DROP TABLE：预期应返回权限拒绝；如果成功，说明最小权限没有真正落地。

还要验证新对象的默认权限。只给现有表执行一次 GRANT，后续迁移新建的表可能对运行账号不可见；由 schema owner 配置默认权限，或让迁移流程在每次建表后显式授权，并在 CI smoke 中用运行账号访问最新对象。

兼容模式

DB_MODE / initdb --dbmode 是初始化模式，常见取舍：

模式	适用	风险
oracle	Oracle 迁移、PL/SQL 风格、空串语义验证	不能按 PostgreSQL 行为猜
pg	PostgreSQL 生态和工具接近	Oracle 空串兼容参数不要乱开
mysql	MySQL 迁移样例验证	类型、函数、大小写仍需逐项验证

模式不是万能兼容开关。类型、空串、大小写、日期、序列、自增、函数、分页和锁行为都要用项目样例验证。

JDBC

官方 JDBC 口径：

spring.datasource.url=jdbc:kingbase8://localhost:54321/app_tool_efficiency
spring.datasource.username=app_tool_efficiency
spring.datasource.password=YOUR_STRONG_KINGBASE_APP_PASSWORD
spring.datasource.driver-class-name=com.kingbase8.Driver

如果密码或连接参数包含 %、?、&、/ 等特殊字符，优先使用 Properties 或框架的独立 username/password 字段，不把所有参数拼进 URL。

跑通第一条可回滚的验证链

导入并启动：

docker load -i kingbase.tar
docker run -tid --privileged -p 54321:54321 \
  -v /tmp/kingbase-data:/home/kingbase/userdata/ \
  -e DB_USER=kingbase \
  -e DB_PASSWORD=YOUR_STRONG_KINGBASE_PASSWORD \
  -e DB_MODE=oracle \
  --name kingbase kingbase:v1 /usr/sbin/init

检查日志和状态：

docker logs kingbase --tail 160
docker exec -it kingbase sys_ctl -D /home/kingbase/userdata/data status

先用镜像自带的 ksql 走容器内本地连接。官方 Docker 初始化日志会提示本地连接采用 trust，因此这一步不把密码写进命令行；它只证明数据库进程和容器内客户端可用，不证明宿主机 TCP 认证已经通过：

docker exec kingbase ksql -Ukingbase -d test -c "select 1;"

连接成功时应返回一行 1。随后再用完整安装介质中的宿主机 ksql、JDBC 或项目应用验证 127.0.0.1:54321 的 TCP 路径；远程连接会按 sys_hba.conf 要求提示密码。如果出现 connection refused，先看容器状态和端口映射；如果出现认证失败，确认 DB_USER、密码和已有 volume 是否来自同一次初始化。不要在认证失败时改用管理账号绕过问题，也不要把密码拼进命令参数。

SQL 验证：

SELECT version();
SHOW server_encoding;
SHOW timezone;

CREATE USER app_tool_efficiency WITH PASSWORD 'YOUR_STRONG_KINGBASE_APP_PASSWORD';
CREATE DATABASE app_tool_efficiency OWNER app_tool_efficiency;

连接业务库后：

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 这一行。随后做一次事务回滚，证明连接不只是能执行自动提交：

BEGIN;
INSERT INTO user_demo(username) VALUES ('should_rollback');
SELECT count(*) FROM user_demo WHERE username = 'should_rollback';
ROLLBACK;
SELECT count(*) FROM user_demo WHERE username = 'should_rollback';

事务内第一次计数应为 1，回滚后应为 0。如果回滚后仍为 1，要检查客户端是否拆分了连接、是否启用了自动提交，或 SQL 是否实际进入了另一个 schema。

备份与恢复也从容器内工具开始，避免只下载 Docker tar 的读者在宿主机遇到 sys_dump: command not found。先在容器内生成纯文本 dump，再复制到宿主机：

docker exec kingbase sys_dump -U app_tool_efficiency \
  -f /tmp/app_tool_efficiency.sql app_tool_efficiency
docker cp kingbase:/tmp/app_tool_efficiency.sql ./app_tool_efficiency.sql

恢复必须在临时库试跑，不要只生成文件。下面的临时库不得指向共享或生产实例：

docker cp ./app_tool_efficiency.sql kingbase:/tmp/app_tool_efficiency.sql
docker exec kingbase ksql -Ukingbase -d test \
  -c "CREATE DATABASE app_tool_efficiency_restore OWNER app_tool_efficiency;"
docker exec kingbase ksql -Uapp_tool_efficiency \
  -d app_tool_efficiency_restore -f /tmp/app_tool_efficiency.sql
docker exec kingbase ksql -Uapp_tool_efficiency \
  -d app_tool_efficiency_restore \
  -c "SELECT count(*) FROM app.user_demo;"

恢复结果应能查到与源库一致的业务行数。保留导出和恢复退出码、文件大小、对象数量、关键表行数与应用只读自检结果；校验完成后先断开恢复库连接，再由管理账号执行 DROP DATABASE app_tool_efficiency_restore;，最后删除源库中的 app.user_demo、容器内 /tmp 文件和宿主机测试 dump。若恢复失败，保留临时库和日志用于定位，不要覆盖原 dump，也不要在原库反复重放。

项目里建议保留：

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

迁移工具接入前先验证：

JDBC 驱动是否进入内部 Maven 仓库或依赖管理。目标 DB_MODE 下 Flyway / Liquibase DDL 是否可用。schema history 表落在哪个 schema。

类型、自增、序列、空串、大小写、分页、日期函数是否符合项目预期。Docker 精简镜像是否缺少客户端或驱动，是否需要额外工具镜像。

连接池还要显式配置连接超时、校验查询、最大池大小、最小空闲连接和连接最长生命周期。池大小不能按“线程越多越快”设置：每个数据库连接都会占用服务端会话、内存和事务资源，应用实例数乘以单实例池上限必须落在数据库连接预算内，并为迁移、排障和管理连接留余量。

Spring Boot 可以把敏感字段拆开，避免完整 URL 进入日志：

spring:
  datasource:
    url: jdbc:kingbase8://127.0.0.1:54321/app_tool_efficiency
    username: ${KINGBASE_APP_USER}
    password: ${KINGBASE_APP_PASSWORD}
    driver-class-name: com.kingbase8.Driver
    hikari:
      connection-timeout: 3000
      validation-timeout: 2000
      maximum-pool-size: 10
      minimum-idle: 2
      max-lifetime: 1500000

这些数值是开发示例，不是生产万能值。生产池大小由并发事务数、平均持有时间、数据库 max_connections 预算和实例数量共同决定；max-lifetime 还要短于网络设备或服务端强制断连时间，并通过连接重建指标验证。

用正反实验识别兼容差异

兼容模式的价值是降低迁移成本，不是抹平所有差异。先在目标 DB_MODE 中建立项目最小样例：主键生成、空字符串、大小写标识符、日期函数、分页、批量写入和锁等待。每个样例既要有预期成功路径，也要故意触发一个源库与目标库可能不同的结果。

以空字符串为例，先执行：

CREATE TABLE app.compat_probe (
  id INTEGER PRIMARY KEY,
  value_text VARCHAR(20)
);
INSERT INTO app.compat_probe(id, value_text) VALUES (1, '');
SELECT id,
       CASE WHEN value_text IS NULL THEN 'NULL' ELSE 'NOT_NULL' END AS null_state,
       LENGTH(value_text) AS value_length
FROM app.compat_probe;

不要预先把结果写死成某一种数据库的语义。把目标环境实际返回的 null_state 和 value_length 固化为迁移测试，再与源库结果比较。反向实验是让 ORM 写入空字符串后，以 IS NULL 和 = '' 分别查询；如果命中集合不同，业务中的必填校验、唯一约束和查询条件都要进入改造清单。

再验证锁等待和回滚。连接 A 执行：

BEGIN;
UPDATE app.compat_probe SET value_text = 'held-by-a' WHERE id = 1;

保持事务不提交，连接 B 对同一行执行更新。连接 B 应等待或在项目配置的超时后失败；此时记录错误码、等待时长和服务端会话状态。连接 A 执行 ROLLBACK 后，连接 B 应继续或按其超时语义退出。这个实验能暴露 ORM 超时、连接池借还、异常后的事务清理是否正确，比单纯跑通 CRUD 更接近真实故障。

一次 JDBC 请求在数据库里怎样落地

应用从连接池借到 JDBC Connection 后，驱动把 SQL 和绑定参数通过 KingbaseES 协议发给后端会话。服务端完成解析、绑定、优化和执行；读取要经过缓冲区与存储页，写入则在事务上下文中修改页面并产生恢复所需的日志。COMMIT 决定事务何时对其他会话可见以及持久化确认的边界，客户端收到成功并不等于备份、副本或异地容灾已经完成。

这条链路解释了几个常见现象：

SQL 很快但借连接很慢，瓶颈在应用连接池或连接预算，不在执行计划。更新阻塞而 CPU 不高，先查事务和锁等待，不要先扩容 CPU。容器重建后数据消失，问题在 volume 或数据目录；容器仍在并不能证明数据已持久化到正确位置。

dump 成功但恢复失败，备份介质存在不等于恢复链路可用。JDBC 类型映射异常，可能来自驱动与数据库补丁组合、兼容模式或 ORM 方言，而不是网络。

排障时先用 ksql 建立“服务端可连”的基线，再比较应用的 URL、账号、schema、驱动和连接池；这样能把网络/认证问题与框架问题分开。

从开发单库演进到生产架构

形态	解决的问题	主要代价	选择信号
单实例	开发、测试、低风险内部系统	单点、维护停机、容量受单机限制	数据可恢复且允许明确停机窗口
主备或读写分离	节点故障与部分读扩展	复制延迟、切换、旧主隔离、客户端路由	RTO 要求低于人工重建时间
RAC / 共享存储多写	更高可用与多节点并发	共享存储、集群协调、许可和运维复杂度	核心交易且平台具备成熟集群能力
分布式或分片形态	数据量和吞吐越过单机边界	分布式事务、路由、扩缩容和治理成本	单机容量经基线与优化后仍不足
托管或企业平台	降低安装、备份、监控负担	服务边界、成本、网络和厂商依赖	团队缺少专职数据库运维能力

高可用不等于数据安全。主备会复制误删除，RAC 不能替代备份，读写分离会引入延迟读，分片会把跨分片事务和全局唯一性推给架构。选型时把 RPO、RTO、峰值 TPS、数据量增长、连接数、最长事务、维护窗口、跨地域延迟、许可成本和团队值守能力放在同一张决策表里。

容量、性能与成本预算

容量预算至少拆成数据、索引、事务日志、临时空间、备份和恢复空间。只按业务表行数估盘会遗漏索引膨胀、长事务保留、排序临时文件和升级时的双份空间。建立基线时记录：

SELECT current_database(), current_user;
SHOW server_encoding;
SHOW timezone;
SHOW max_connections;

再从受支持的监控视图或企业平台采集数据库大小、表与索引增长、活动连接、等待事件、慢 SQL、日志增长和备份时长。具体系统视图会随版本变化，先在目标版本手册中确认字段，再写入监控模板。

成本也不只有 license：还包括计算、内存、数据盘、日志盘、备份介质、跨机房带宽、测试环境、驱动与补丁适配、迁移工具、恢复演练和 DBA 值守。容量评审要给出当前基线、增长率、扩容提前量和触发动作，而不是一个脱离负载的固定阈值。

查看日志：

docker logs kingbase --tail 120

进入容器：

docker exec -it kingbase bash

查看状态：

docker exec -it kingbase sys_ctl -D /home/kingbase/userdata/data status

连接：

ksql -Ukingbase -d test -h 127.0.0.1 -p 54321

查看对象：

SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_schema NOT IN ('sys_catalog', 'information_schema')
ORDER BY table_schema, table_name;

停止开发库：

docker compose down

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

docker compose down -v

Docker tar 和 license 处理不清

现象：

docker pull kingbase 失败。镜像导入后没有 JDBC 驱动或客户端工具。试用授权到期或 license 持久化路径不清。

处理：从产品下载中心取得 tar 和驱动，记录试用授权 owner；不要把 Docker 精简镜像当成完整安装包。

端口占用

排查：

lsof -i :54321
docker ps --format "table {{.Names}}\t{{.Ports}}"

处理：本地可映射 154321:54321，并同步修改 JDBC URL。

volume 权限不足

Docker 手册提醒挂载目录权限不正确会出现 Permission denied。处理：

chmod -R 755 /tmp/kingbase-data

共享开发机不要用世界可写目录承载真实数据，权限策略由平台 owner 统一。

初始化模式选错

现象：

DB_MODE=oracle 下 PostgreSQL 行为不符合预期。DB_MODE=pg 下 Oracle 空串兼容参数被误开。已有数据后想切模式。

处理：初始化前决定模式；已有库以重建学习库或迁移验证为主，不在原库切来切去。

JDBC URL 特殊字符

官方 JDBC 文档提醒 URL 中特殊字符会影响解析。处理：

用 Properties 或框架独立字段传 username/password。需要拼 URL 时做 URL encode。不把真实密码放在 URL 里提交。

不能进入仓库的内容：

KINGBASE_PASSWORD、KINGBASE_APP_PASSWORD、.env。真实 JDBC URL、内网 IP、共享库账号、license 文件。官方下载验证码、受控下载链接、内部镜像仓库凭证。

dump、SQL 导出、日志和客户数据。客户端连接配置、管理工具截图和生产连接历史。

.gitignore 建议：

.env
db/kingbase/dump/*.sql
db/kingbase/dump/*.dump
db/kingbase/logs/**
db/kingbase/license/**

密码轮换要支持新旧凭证短暂并存或按实例滚动重启：先创建或更新目标账号，验证新 Secret 能建立连接，再滚动应用并观察旧凭证连接归零，最后回收旧凭证。直接改密码而不处理连接池，会让旧连接暂时可用、新建连接持续失败，形成难以判断的间歇故障。

共享 KingbaseES 开发库至少要有：

安装包 / Docker tar 来源、版本、试用授权、license owner。镜像 tag / digest 和内网仓库地址。DB_MODE、ENCODING、locale、timezone。

端口、database、schema、user 命名规范。runtime / migration / readonly 账号。JDBC 驱动版本和获取方式。

dump / restore 验证路径和清理周期。Oracle / PostgreSQL / MySQL 兼容模式验证清单。

每个环境还应有数据库 owner、应用 owner、license owner 和恢复演练 owner。季度或重要版本前复核补丁、安全公告、驱动组合、证书与凭证到期、备份恢复、容量趋势和闲置实例；项目下线时先冻结写入并确认数据保留要求，再回收账号、网络规则、Secret、GUI 连接、备份、license 分配和实例资源。

升级和回退要成对设计

升级前在同 DB_MODE、encoding、locale 和 timezone 的隔离实例恢复一份脱敏数据，依次验证数据库补丁、JDBC 驱动、迁移工具和关键 SQL。数据库升级与驱动升级分两个变更窗口，能更快定位协议或类型映射回归。

回退不能只写“换回旧镜像”。一旦新版本修改了数据目录、系统目录或业务 schema，旧二进制未必能安全读取。变更单至少要说明：回退依赖原数据目录还是恢复前快照，业务写入何时冻结，迁移脚本是否可逆，旧驱动如何恢复，以及超过哪一时点只能前向修复。

深水区	现象	判断入口	配置 / 命令 / 取舍
Docker tar 当镜像仓库	docker pull 不存在	下载页、Docker 手册	docker load 并记录来源
精简镜像误判	缺 JDBC / 工具	包类型说明	驱动单独下载
试用授权到期	容器突然不可用	license owner、日志	提前告警并准备续期或下线
54321 冲突	本机多库混连	lsof、JDBC URL	宿主端口项目化
system 滥用	应用拿管理账号连接	配置扫描、session	应用独立用户
DB_MODE 后改	SQL 行为前后矛盾	初始化参数、迁移记录	初始化前定稿
encoding 模糊	中文乱码、排序异常	SHOW server_encoding	显式设置并验证
volume 权限	启动报 Permission denied	docker logs、宿主权限	目录权限和 owner 校准
JDBC 特殊字符	密码含 & 后连接失败	URL、Properties	分离参数
PG/Oracle 兼容混乱	ORM SQL 不符合预期	DB_MODE、dialect	样例验证
导出未恢复	有 SQL 文件但恢复失败	临时库恢复	每次模板保留恢复 smoke
连接预算失控	实例一扩容数据库就拒绝连接	池指标、活动会话、max_connections	按应用实例数分配预算并保留管理余量
长事务拖累存储	日志与磁盘持续增长	事务年龄、锁等待、日志增长	事务超时、批次拆分、owner 告警
补丁与驱动错配	类型映射或连接行为升级后变化	数据库补丁、驱动版本、回归用例	分窗升级并保留回退组合
误连生产	reset 脚本删错库	URL、端口、账号	白名单和二次确认

KingbaseES 的风险不会停在 Docker tar 和端口。初始化模式决定语义，驱动组合决定应用行为，连接与事务决定并发边界，备份恢复决定数据底线，license、补丁和 owner 决定环境能否长期运行。只有这些状态都可追踪，“能连”才真正升级为可交付。

交付环境前逐项确认：

是否核对 KingbaseES 包类型、Docker 参数、JDBC 行为和 initdb 参数。是否说明 Docker 镜像是 tar 导入，不写第三方镜像为推荐入口。是否记录 tar 包来源、版本、license owner、镜像 tag 和 digest。

是否写清 54321、DB_USER、DB_PASSWORD、DB_MODE、ENCODING。是否说明 Docker 精简镜像不等于完整安装介质。是否覆盖 ksql、JDBC driver、连接串和特殊字符处理。

是否提供建库、建用户、schema、建表、写入、读取和清理闭环。是否说明 Oracle / PG / MySQL 兼容模式初始化边界。是否提供导出恢复入口。

是否写清 license、dump、真实连接串和下载凭证的敏感信息风险。是否列出端口冲突、volume 权限、JDBC、encoding、DB_MODE 和误连生产的排查路径。是否根据 RPO、RTO、容量、并发、成本和团队能力选择单机、主备、RAC/RWC、分布式或托管形态。

是否完成最小权限的正向 DML 与反向 DDL 拒绝实验。是否验证连接池预算、事务回滚、锁等待超时和连接清理。是否为升级、回退、恢复演练、凭证轮换和项目下线指定 owner。

KingbaseES 不是“端口 54321 的 PostgreSQL 或 Oracle”。把 Docker tar、初始化模式、JDBC、license 和团队责任写实，它才能成为可交付的开发验证工具。