摘要：国产数据库正在崛起，KingbaseES 作为其中的代表之一，正在越来越多的政企项目中落地。本文将带你一步步在 Linux 系统中使用 Docker 快速体验 KingbaseES 的部署过程，全程亲测，踩坑记录一并奉上。

---

一、为什么选择 Docker 部署 KingbaseES？

传统数据库部署流程繁琐，依赖环境多，容易出错。而使用 Docker 部署，不仅环境隔离、迁移方便，还能快速回滚，特别适合测试、开发或临时演示场景。

如果你公司业务需求要windows部署KingbaseES，可以看一下我往期文章：

零改造迁移实录：2000+存储过程从SQL Server滑入KingbaseES V9R4C12的72小时

如果你公司业务需求要Ubuntu部署KingbaseES，也可以看一下我往期文章：

在Ubuntu服务器上安装KingbaseES V009R002C012（Orable兼容版）数据库过程详细记录

KingbaseES 官方提供了完整的 Docker 镜像包，支持 X86_64、龙芯、飞腾、鲲鹏等国产 CPU 架构，部署门槛大大降低。

---

二、环境准备：万事开头难，但这里不难

1. 硬件要求

• 支持 X86_64、龙芯、飞腾、鲲鹏等架构

• 建议至少 2 核 4G 内存，10GB 可用磁盘空间

2. 软件要求

• Docker 版本 ≥ 20.10.0（推荐 24.x 稳定版）

小提示：使用 docker --version 快速确认当前版本。本文用docker 26.1.3进行实操记录！

---

三、实战开始：一步步部署 KingbaseES

Step 1：创建数据目录

为了避免容器销毁后数据丢失，我们先在宿主机创建持久化目录：

mkdir -p /opt/kingbase/data
chmod -R 755 /opt/kingbase/data

小提示：建议统一放在 /opt 下，方便管理。

Step 2：获取镜像包

你可以通过以下方式获取 KingbaseES 镜像：

1、官网下载：https://www.kingbase.com.cn/（需注册）

2、入口位置：服务与支持 > 下载中 > KES，如下图所示：

3、KingbaseES数据库Docker镜像，根据自己电脑配置选择对应的版本下载。

点击下载会提示下载验证，输入相关信息后就可以下载啦！

如果有特殊需求镜像：

• 联系销售人员或代理商获取

• 内部项目提供（如涉密项目）

本文使用的是KingbaseES_V009R001C010B0004_x86_64_Docker.tar 镜像包，大小约 754MB。

Step 3：导入镜像

1、将镜像包上传至 /opt/kingbase 目录下，这个目录可根据自身情况自定义，如下图：

2、将镜像包上传至 /opt/kingbase 目录后，执行导入：

docker load -i /opt/kingbase/KingbaseES_V009R001C010B0004_x86_64_Docker.tar

3、导入成功后，使用 docker images 查看：

REPOSITORY                                                                         TAG                                  IMAGE ID       CREATED         SIZE
kingbase_v009r001c010b0004_single_x86                                              v1                                   10ba6f33e228   2 months ago    754MB

如果 docker load 报错，可尝试 docker import，但推荐使用 load，兼容性更好。

---

四、启动容器：两条命令，数据库跑起来

1.最小启动（无持久化）

适合临时测试，容器删除后数据不保留：

docker run -tid --privileged \
  -p 54321:54321 \
  --name kingbase \
  kingbase_v009r001c010b0004_single_x86:v1 /usr/sbin/init

2.推荐启动（数据持久化）

生产或长期使用建议挂载数据卷：

docker run -tid --privileged \
  -p 9099:54321 \
  --name kingbase \
  -v /opt/kingbase/data:/home/kingbase/userdata \
  kingbase_v009r001c010b0004_single_x86:v1 /usr/sbin/init

端口说明：KingbaseES 默认使用 54321 端口，非 PostgreSQL 的 5432，注意区分。

---

五、验证部署：确认服务是否正常运行

1.查看容器状态

docker ps

输出示例：

CONTAINER ID   IMAGE                                                                                                  COMMAND                  CREATED         STATUS                  PORTS                                                                            NAMES
6f2958b65b3d   kingbase_v009r001c010b0004_single_x86:v1                                                               "/bin/bash /home/kin…"   5 seconds ago   Up 5 seconds            0.0.0.0:9099->54321/tcp, :::9099->54321/tcp                                      kingbase

2.进入容器

docker exec -it kingbase /bin/bash

[kingbase@6f2958b65b3d ~]$ du -sh *
8.0K    docker-entrypoint.sh
439M    install
167M    userdata

进入跟目录，可以打印 docker-entrypoint.sh 启动类出来看看，看一下启动都发生了什么事，搞技术就喜欢追究底层原理，常话说：知其然，知其所以然！

[kingbase@6f2958b65b3d ~]$ vi docker-entrypoint.sh 

#!/bin/bash
  

source /etc/profile
cron_file="/etc/cron.d/KINGBASECRON"


command_options="-q -o ConnectTimeout=10 -o StrictHostKeyChecking=no -p 22"
default_pass="MTIzNDU2NzhhYgo="


function err_log()
{
    local exit_flag=$?
    local message="$1"

    if [ ${exit_flag} -ne 0 ]
    then
        echo "${message} fail"
    else
        echo "${message} success"
    fi
}

function pre_exe(){
    DB_PATH=/home/kingbase/install/kingbase
    etc_PATH=${DB_PATH}/etc
    if [ "$DATA_DIR"x == ""x ]
    then
        DATA_DIR=/home/kingbase/userdata/data
    fi
    persist_etc_PATH=${DATA_DIR}/../etc
    LOG_FILE=${DATA_DIR}/logfile
    [ "$PASSWORD"x == ""x ] && PASSWORD=`echo "${default_pass}" | base64 -d`
    [ "$DB_USER"x == ""x ] && DB_USER=system
    [ "$DB_MODE"x == "pg"x -o "$DB_MODE"x == "mysql"x ] && ENABLE_CI=""
    kingbase_user_exist=`cat /etc/bashrc |grep KINGBASE_USER|wc -l`
    [ $kingbase_user_exist -eq 0 ] && sudo echo "export KINGBASE_USER=${DB_USER}" | sudo tee -a /etc/bashrc
    local DB_NAME="kingbase" # 仅在注入 ksql 环境变量时生效
    kingbase_database_exist=`cat /etc/bashrc |grep KINGBASE_DATABASE|wc -l`
    [ $kingbase_database_exist -eq 0 ] && sudo echo "export KINGBASE_DATABASE=${DB_NAME}" | sudo tee -a /etc/bashrc
    sudo mkdir -p $DATA_DIR
    sudo chown -R kingbase:kingbase /home/kingbase/
    sudo chmod -R 700 $DATA_DIR
    test ! -d ${persist_etc_PATH} && mkdir -p ${persist_etc_PATH}
    test ! -d ${etc_PATH} && ln -s ${persist_etc_PATH} ${etc_PATH}
}
function load_env(){
   [ "$DB_PASSWORD"x != ""x ] && PASSWORD=$DB_PASSWORD
   [ "$USER_DATA"x != ""x ] && DATA_DIR=/home/kingbase/$USER_DATA
   [ "$NEED_START"x == ""x ] && NEED_START=yes
   [ "$ENCODING"x == ""x ] && ENCODING=UTF-8
}
function param_check(){
    if [ "$DB_MODE"x != ""x ]
    then
        if ! [[ "${DB_MODE}"x == "mysql"x || "${DB_MODE}"x == "oracle"x || "${DB_MODE}"x == "pg"x || "${DB_MODE}"x == "sqlserver"x ]];
        then
            echo "[ERROR] env [DB_MODE]:${DB_MODE} set error, it just could be set as {mysql,oracle,pg,sqlserver}"
            exit 1
        fi
    fi

    if [ "$ENABLE_CI"x != ""x ]
    then
        if ! [[ "${ENABLE_CI}"x == "yes"x || "${ENABLE_CI}"x == "no"x ]]
        then
            echo "[ERROR] env [ENABLE_CI]:${ENABLE_CI} set error, it just could be set as {yes, no}"
            exit 1
        fi
    fi
}
function check_and_run(){
   local DATA_DIR=$1
   pre_exe
   ${DB_PATH}/bin/sys_ctl -D ${DATA_DIR} status  2>/dev/null
   if [ $? -ne 0 ];then
       echo "[`date`]db is not running, ${DB_PATH}/bin/sys_ctl -D ${DATA_DIR} -l ${DATA_DIR}/logfile start"
       ${DB_PATH}/bin/sys_ctl -D ${DATA_DIR} -l ${LOG_FILE} start
       [ $? -eq 0 ] &&  echo "[`date`]db started" && return 0
       echo "[`date`]db start fail"
       return 0
   fi
}

function start_cron()
{
    local i=0
    local cron_command="* * * * * kingbase /home/kingbase/docker-entrypoint.sh check_and_run ${DATA_DIR} >> /home/kingbase/cronlog"
    #  root用户添加CRON任务
    local cronexist=`sudo cat $cron_file 2>/dev/null| grep -wFn "${cron_command}" |wc -l`
    if [ "$cronexist"x != ""x ] && [ $cronexist -eq 1 ]
    then
        local realist=`sudo cat $cron_file | grep -wFn "${cron_command}"`
        local linenum=`echo "${realist}" |awk -F':' '{print $1}'`
        sudo sed ${linenum}s/#*// $cron_file > ${persist_etc_PATH}/KINGBASECRON
        sudo cat ${persist_etc_PATH}/KINGBASECRON | sudo tee -a  $cron_file
    elif [ "$cronexist"x != ""x ] && [ $cronexist -eq 0 ]
    then
        sudo chmod 777 $cron_file
        sudo echo -e "${cron_command}\n" |sudo tee -a  $cron_file
        sudo chmod 644 $cron_file
    else
        return 1
    fi
    return 0
}


function db_init(){
    local db_init_command="${DB_PATH}/bin/initdb -U$DB_USER -x ${PASSWORD} -D ${DATA_DIR} -E ${ENCODING}"
    if [ "$ENABLE_CI"x == "yes"x ]
    then
        db_init_command="$db_init_command --enable_ci"
    fi
    if [ "$DB_MODE"x != ""x ]
    then
        db_init_command="$db_init_command -m $DB_MODE"
    fi
    echo "[`date`]start initdb..."
    eval "$db_init_command"
    echo "[`date`]start initdb...ok"

    sed -i 's/local   all             all                                     scram-sha-256/local   all             all                                     trust/g' ${DATA_DIR}/kingbase.conf
    sed -i 's/local   replication     all                                     scram-sha-256/local   replication     all                                     trust/g' ${DATA_DIR}/kingbase.conf
    sed -i 's/^#\(\s*archive_mode\s*=\s*\)off/\1on/'  ${DATA_DIR}/kingbase.conf
    sed -i "s|^#\(\s*archive_command\s*=\s*\)''|\1'/bin/true'|"  ${DATA_DIR}/kingbase.conf

    mv ${DB_PATH}/bin/license.dat ${etc_PATH}/license.dat
    ln -s ${etc_PATH}/license.dat ${DB_PATH}/bin/license.dat

}

function main(){
    load_env
    pre_exe
    param_check
    if [ "$(ls -A ${DATA_DIR})" ];then
       echo "[`date`]data directory:${DATA_DIR} is not empty,don't need to initdb"
    else
       db_init
    fi

    if [ "$NEED_START"x == "yes"x ]
    then
        ${DB_PATH}/bin/sys_ctl -D ${DATA_DIR} -l ${LOG_FILE} start
        sudo chown -R root:root /etc/cron.d/
        sudo chmod -R 644 /etc/cron.d/
        test ! -f $cron_file &&  sudo touch $cron_file && sudo chmod 644 $cron_file
        start_cron
    elif [ "$NEED_START"x == "no"x ]
    then
        echo "[`date`]NEED_START be set as ${NEED_START},not yes, do not need start db"
        touch  ${LOG_FILE}
    fi

    if test -f ${etc_PATH}/logrotate_kingbase
    then
       echo "[`date`]cp logrotate_kingbase from  ${etc_PATH}/logrotate_kingbase  to /etc/logrotate.d/kingbase"
       sudo cp ${etc_PATH}/logrotate_kingbase  /etc/logrotate.d/kingbase
       err_log "cp ${etc_PATH}/logrotate_kingbase  /etc/logrotate.d/kingbase"
       sudo chmod 644 /etc/logrotate.d/kingbase
       sudo chown root:root /etc/logrotate.d/kingbase
    fi

    if test -f  ${etc_PATH}/KINGBASECRON
    then
       echo "[`date`]cp KINGBASECRON from  ${etc_PATH}/KINGBASECRON  to /etc/cron.d/KINGBASECRON"
       sudo cp ${etc_PATH}/KINGBASECRON  /etc/cron.d/KINGBASECRON
       err_log "sudo cp ${etc_PATH}/KINGBASECRON  /etc/cron.d/KINGBASECRON"
       sudo chmod 644 /etc/cron.d/KINGBASECRON
       sudo chown root:root /etc/cron.d/KINGBASECRON
    fi

    if test -f ${etc_PATH}/${USER}
    then
       crontab ${etc_PATH}/${USER}
    fi

    if test -f ${etc_PATH}/.encpwd
    then
       echo "[`date`]cp .encpwd from  ${etc_PATH}/.encpwd to ~/.encpwd"
       cp ${etc_PATH}/.encpwd  ~/.encpwd
       err_log "cp ${etc_PATH}/.encpwd  ~/.encpwd"
       sudo chmod 600 ~/.encpwd
       sudo chown ${USER}:${USER} ~/.encpwd
    fi
    while true;do sleep 1000;done
}
case $1 in
    "check_and_run")
        shift
        check_and_run $1
        exit 0
        ;;
    *)
        main
esac

3.连接数据库

使用 ksql 命令连接：

ksql -U kingbase -d test

你遇到的问题是：默认用户 kingbase 不存在，这是 KingbaseES 镜像——它并没有默认创建 kingbase 这个 role（用户），所以连接失败。

✅ 正确做法：先登录数据库，再查看/创建用户

✅ Step 1：用默认超级用户登录

KingbaseES 默认超级用户是 system，密码通常也是 system（或空密码），你可以这样登录：

ksql -U system -d test

✅ Step 2：查看已有用户

登录后执行：

\du

你会看到类似输出：

Role name  |                         Attributes                         | Member of 
------------+------------------------------------------------------------+-----------
 kcluster   | Cannot login                                               | {}
 sao        | No inheritance, Create role                                | {}
 sao_oper   | No inheritance, Cannot login                               | {}
 sao_public | No inheritance, Cannot login                               | {}
 sso        | No inheritance, Create role                                | {}
 sso_oper   | No inheritance, Cannot login                               | {}
 sso_public | No inheritance, Cannot login                               | {}
 system     | Superuser, Create role, Create DB, Replication, Bypass RLS | {}

✅ Step 3：创建你需要的用户（如 kingbase）

CREATE USER kingbase WITH PASSWORD 'kingbase';
GRANT ALL PRIVILEGES ON DATABASE test TO kingbase;

✅ Step 4：退出并用新用户登录

\q
ksql -U kingbase -d test

✅ 总结一句话：

第一次别用 kingbase 用户登录，先用 system 登录，再自己创建用户。

🔍 步骤总结：

步骤	情况内容	操作说明
登录失败	ksql: error: could not connect to server: FATAL: role "kingbase" does not exist	默认kingbase用户不存在
登录成功	ksql -U system -d test 进入 test=#	第一次用 system 用户成功登录
创建用户	执行 CREATE USER kingbase...	手动创建 kingbase 用户
最终登录	ksql -U kingbase -d test 成功	自定义用户也能用了！

---

六、常见问题与踩坑记录

问题	原因	解决方案
docker load 报错	镜像包损坏或格式不符	使用 docker import 尝试
容器启动后无法连接	端口未映射或防火墙拦截	检查 -p 参数及防火墙设置
数据丢失	未挂载宿主机目录	使用 -v 参数持久化数据
登录失败	用户名或数据库错误	默认用户为 system，数据库为 test

小提示：sys_user和sys_users是系统数据库默认创建的表，新建表的时候不要用这2个表名，避免跟系统冲突哦！

---

七、总结：十分钟搞定国产数据库部署

通过 Docker 部署 KingbaseES，不仅快速高效，还能避免传统安装中的依赖问题。对于开发测试、产品演示、教学培训等场景，都是非常理想的选择。

1、如何修改默认密码

# 进入容器
docker exec -it kingbase /bin/bash

# 用超级用户登录
ksql -U system -d test

-- SQL 层修改密码
ALTER USER system PASSWORD 'K1ngb@se2025!';

原理：KingbaseES 兼容 PostgreSQL 协议，ALTER USER 会立刻写入系统 catalog，重启容器也生效。
坑提示：密码复杂度默认开启，太简单会报 ERROR: password is too simple。

2、如何初始化自己的数据库

# 进入容器
docker exec -it kingbase /bin/bash

# 仍用 system 登录
ksql -U system -d test

-- 1 创建新库
CREATE DATABASE myapp OWNER kingbase;

-- 2 连接新库
\c myapp

-- 3 跑初始化脚本（举例）
CREATE TABLE users(
  id SERIAL PRIMARY KEY,
  name VARCHAR(32) UNIQUE NOT NULL,
  pwd VARCHAR(64) NOT NULL
);

-- 4 赋权
GRANT ALL ON SCHEMA public TO kingbase;
GRANT ALL ON ALL TABLES IN SCHEMA public TO kingbase;

原理：CREATE DATABASE 会复制模板库 template1，因此自带 Kingbase 方言。
提示：如果把 SQL 文件放在宿主机，可通过 docker cp init.sql kingbase:/tmp 再 ksql -U kingbase -d myapp -f /tmp/init.sql 执行。

3、增删改查真实案例

跟前面一样，先进入容器，登录上面创建的myapp数据库，如下所示：

docker exec -it kingbase /bin/bash

ksql -U kingbase -d myapp

-- 1 建表（一次性）
CREATE TABLE IF NOT EXISTS king_user(
  id   SERIAL PRIMARY KEY,
  name VARCHAR(32) UNIQUE NOT NULL,
  pwd  VARCHAR(64) NOT NULL
);

-- 2 增
INSERT INTO king_user(id, name, pwd) VALUES (1,'alice', 'aaa123') RETURNING *;
INSERT INTO king_user(id, name, pwd) VALUES (2,'Augenstern', 'Augenstern') RETURNING *;
INSERT INTO king_user(id, name, pwd) VALUES (3,'正在走向自律', '2025@King') RETURNING *;

-- 3 查
SELECT * FROM king_user WHERE name = 'alice';

-- 4 改
UPDATE king_user SET pwd = 'new123' WHERE name = 'alice' RETURNING *;

-- 5 删
DELETE FROM king_user WHERE name = 'alice' RETURNING *;

4、后续我还会分享

• 如何在客户端操作数据库？

• 如何创建自己的数据库有哪些注意事项？

• 如何与 SpringBoot 项目集成？

后续会继续分享，敬请关注！

---

八、附录：常用命令速查

# 导入镜像
docker load -i /opt/kingbase/KingbaseES_V009R001C010B0004_x86_64_Docker.tar

# 启动容器（持久化）
docker run -tid --privileged \
  -p 9099:54321 \
  --name kingbase \
  -v /opt/kingbase/data:/home/kingbase/userdata \
  kingbase_v009r001c010b0004_single_x86:v1 /usr/sbin/init

# 进入容器
docker exec -it kingbase /bin/bash

# 连接数据库
ksql -U system -d test

如需获取镜像包或更多技术支持，建议访问 电科金仓官网 或联系官方渠道。

---

如果你也亲自动手部署了，欢迎评论区分享你的经验和问题，一起交流国产数据库的实战经验！

 

关于本文，博主还写了相关文章，欢迎关注《电科金仓》分类：

第一章：基础与入门

1、【金仓数据库征文】政府项目数据库迁移：从MySQL 5.7到KingbaseES的蜕变之路

2、【金仓数据库征文】学校AI数字人：从Sql Server到KingbaseES的数据库转型之路

3、电科金仓2025发布会，国产数据库的AI融合进化与智领未来

4、国产数据库逆袭：老邓的“六大不敢替”被金仓逐一破解

5、《一行代码不改动！用KES V9 2025完成SQL Server → 金仓“平替”迁移并启用向量检索》

6、《赤兔引擎×的卢智能体：电科金仓如何用“三骏架构”重塑AI原生数据库一体机》

7、探秘KingbaseES在线体验平台：技术盛宴还是虚有其表？

8、破除“分布式”迷思：回归数据库选型的本质

9、KDMS V4 一键搞定国产化迁移：零代码、零事故、零熬夜——金仓社区发布史上最省心数据库迁移评估神器

10、KingbaseES V009版本发布：国产数据库的新飞跃

第二章：能力与提升

1、零改造迁移实录：2000+存储过程从SQL Server滑入KingbaseES V9R4C12的72小时

2、国产数据库迁移神器，KDMSV4震撼上线

3、在Ubuntu服务器上安装KingbaseES V009R002C012（Orable兼容版）数据库过程详细记录

4、金仓数据库迁移评估系统（KDMS）V4 正式上线：国产化替代的技术底气

5、Ubuntu系统下Python连接国产KingbaseES数据库实现增删改查

6、KingbaseES V009版本发布，新特性代码案例

7、Java连接电科金仓数据库（KingbaseES）实战指南

8、使用 Docker 快速部署 KingbaseES 国产数据库：亲测全过程分享