金仓数据库（KingbaseES）Windows 安装避坑指南：从 Connection Refused 到服务启动的完整实战记录

摘要：本文记录了在 Windows 系统上安装金仓数据库（KingbaseES）过程中遇到的各种坑点及解决方案，包括命令行安装后服务缺失、初始化参数错误、认证失败、编码不兼容等问题，希望能帮助后来者少走弯路。

一、环境信息

项目	版本/配置
操作系统	Windows 10/11
数据库版本	KingbaseES V8R6 / V9R1
安装方式	命令行安装（ISO 解压后 `setup.bat -i console`）
默认端口	54321

二、问题一：安装完成后 Connection Refused，服务列表中没有金仓服务

2.1 现象

执行 ksql 连接时报错：

复制代码

connection refused. check that the hostname and port are correct and that the postmaster is accepting tcp/ip connections

打开 services.msc 发现没有金仓数据库相关服务。

2.2 原因分析

金仓数据库的 Windows 命令行安装不会自动初始化数据库实例 ，也不会注册 Windows 服务，需要手动完成。

2.3 解决方案

步骤 1：初始化数据库（initdb）

cmd 复制代码

cd /d "C:\Program Files\Kingbase\ES\V8\Server\bin"

# 创建数据目录
mkdir "C:\Program Files\Kingbase\ES\V8\data"

# 初始化数据库（注意参数用法！）
initdb.exe -D "C:\Program Files\Kingbase\ES\V8\data" -U system -x 123456 -E UTF8

⚠️ 避坑点：

-W 是开关参数，不需要值（交互式输入密码）
-x 直接指定密码，如 -x 123456
不要同时使用 --pwfile 和 -x，会报错 password and password file cannot be specified together

步骤 2：注册 Windows 服务

cmd 复制代码

# 注册服务
sys_ctl.exe register -N "kingbase8_instance" -D "C:\Program Files\Kingbase\ES\V8\data" -S auto

# 启动服务
net start kingbase8_instance

三、问题二：sys_ctl start 卡住无响应

3.1 现象

执行 sys_ctl start 后命令行一直卡住，没有返回。

3.2 原因分析

最常见原因是 License 文件缺失或过期，或残留进程导致。

3.3 解决方案

cmd 复制代码

# 1. 强制结束卡住的命令（Ctrl+C），检查残留进程
tasklist | findstr kingbase
taskkill /F /IM kingbase.exe

# 2. 删除 PID 文件
del "C:\Program Files\Kingbase\ES\V8\data\kingbase.pid"

# 3. 检查 License 文件
dir "C:\Program Files\Kingbase\ES\V8\license.dat"

# 4. 如果没有，从官网下载对应版本 License 放入该目录

# 5. 重新启动
sys_ctl.exe -w -t 60 -D "C:\Program Files\Kingbase\ES\V8\data" start

四、问题三：ksql 连接认证失败

4.1 现象

复制代码

FATAL: password authentication failed for user "system"

4.2 原因分析

Windows 系统不支持 scram-sha-256 认证方式 ，需要改为 trust 或 md5。

4.3 解决方案

临时方案：免密登录修改密码

停止服务
cmd 复制代码
```
net stop kingbase8_instance
```

修改 sys_hba.conf

文件路径：C:\Program Files\Kingbase\ES\V8\data\sys_hba.conf

将：

复制代码

host    all             all             127.0.0.1/32            scram-sha-256

改为：

复制代码

host    all             all             127.0.0.1/32            trust

重启服务

cmd 复制代码

sys_ctl.exe restart -D "C:\Program Files\Kingbase\ES\V8\data"

免密登录并修改密码

cmd 复制代码

ksql.exe -U system -d test -p 54321

sql 复制代码

-- 修改密码
ALTER USER "system" WITH PASSWORD 'Kingbase@2025';

恢复安全认证

将 trust 改回 md5，重启服务。

五、问题四：SQL 操作报错

5.1 角色不存在（大小写问题）

现象：

复制代码

ERROR: role "SYSTEM" does not exist

原因：SQL 中不加引号的标识符自动转为大写，但金仓默认用户是小写 system。

解决：

sql 复制代码

-- 错误
ALTER USER system WITH PASSWORD 'xxx';

-- 正确（使用双引号保留大小写）
ALTER USER "system" WITH PASSWORD 'Kingbase@2025';

5.2 创建数据库编码不兼容

现象：

复制代码

错误：新的编码(UTF8)与模板数据库(GBK)的编码不兼容
Hint: 在模板数据库中使用同一编码，或者使用template0作为模板

原因：template1 默认编码为 GBK（Windows 系统默认），与 UTF8 不兼容。

解决：

sql 复制代码

-- 使用 template0 创建 UTF8 数据库
CREATE DATABASE myapp 
    WITH 
    ENCODING = 'UTF8' 
    TEMPLATE = template0;

六、完整安装配置流程（建议收藏）

cmd 复制代码

# ========== 1. 初始化数据库 ==========
cd /d "C:\Program Files\Kingbase\ES\V8\Server\bin"
mkdir "C:\Program Files\Kingbase\ES\V8\data"

initdb.exe -D "C:\Program Files\Kingbase\ES\V8\data" -U system -x 123456 -E UTF8

# ========== 2. 放置 License 文件 ==========
# 将 license.dat 复制到 C:\Program Files\Kingbase\ES\V8\

# ========== 3. 注册并启动服务 ==========
sys_ctl.exe register -N "kingbase8_instance" -D "C:\Program Files\Kingbase\ES\V8\data" -S auto
net start kingbase8_instance

# ========== 4. 连接测试 ==========
ksql.exe -U system -d test -p 54321

# ========== 5. 创建业务数据库 ==========
CREATE DATABASE myapp WITH ENCODING 'UTF8' TEMPLATE template0;

七、核心避坑总结

问题类型	避坑要点
服务缺失	命令行安装需手动 `initdb` + `sys_ctl register`
initdb 参数	`-x` 直接指定密码，`-W` 交互输入，不要混用 `--pwfile`
启动卡住	检查 License 文件，删除残留进程和 PID 文件
认证失败	Windows 不支持 `scram-sha-256`，改用 `md5` 或 `trust`
大小写敏感	用户名用双引号包裹，如 `"system"`
编码不兼容	UTF8 数据库使用 `TEMPLATE template0` 创建

八、参考资源

金仓官网：https://www.kingbase.com.cn
官方文档：https://help.kingbase.com.cn
技术支持：400-601-1188

结语：金仓数据库作为国产数据库的重要代表，在 Windows 环境下的安装配置相比 Linux 有更多细节需要注意。希望本文能帮助大家顺利完成部署，避免踩坑！

关键词：KingbaseES、金仓数据库、Windows 安装、Connection Refused、initdb、sys_ctl、编码不兼容、角色不存在