MyGoNavi/docs/HighGo_SM3_Integration_Guide.md

HighGo SM3 国密驱动集成指南

一、背景说明

HighGo（瀚高）数据库需要使用支持 SM3 国密认证的 PostgreSQL 驱动。瀚高官方提供了基于 lib/pq 的安全增强版本。

二、集成步骤

步骤 1：下载瀚高 pq 驱动

1. 访问百度网盘链接：

   https://pan.baidu.com/s/1xuz6uJz0utRgKWecXhpOiA?pwd=o0tj
   

2. 下载驱动源码压缩包

步骤 2：放置驱动源码

1. 在项目根目录创建目录（如果不存在）：

   mkdir -p third_party/highgo-pq
   

2. 解压下载的驱动源码到 third_party/highgo-pq/ 目录

3. 确保目录结构如下：

   GoNavi/
   ├── third_party/
   │   └── highgo-pq/
   │       ├── go.mod
   │       ├── conn.go
   │       ├── ... (其他 pq 驱动源文件)
   

步骤 3：修改 go.mod

在 go.mod 中添加独立的 HighGo 驱动依赖与本地替换：

require github.com/highgo/pq-sm3 v0.0.0
replace github.com/highgo/pq-sm3 => ./third_party/highgo-pq

完整示例：

module GoNavi-Wails

go 1.24.3

require (
    // ... 现有依赖
    github.com/lib/pq v1.11.1
    github.com/highgo/pq-sm3 v0.0.0
    // ... 其他依赖
)

// 在文件末尾添加
replace github.com/highgo/pq-sm3 => ./third_party/highgo-pq

并将 third_party/highgo-pq/go.mod 的 module 修改为：

module github.com/highgo/pq-sm3

同时在驱动源码中把注册名改为 highgo，确保不覆盖 postgres：

sql.Register("highgo", &Driver{})

步骤 4：更新 HighGo 连接配置（可选）

根据瀚高官方文档，建议修改 internal/db/highgo_impl.go:43 的 sslmode：

当前代码：

q.Set("sslmode", "disable")

建议修改为（瀚高默认）：

q.Set("sslmode", "require")

⚠️ 注意：如果您的 HighGo 服务器未配置 SSL，保持 disable 即可。

步骤 5：验证集成

1. 清理依赖缓存：

   go clean -modcache
   

2. 重新下载依赖：

   go mod download
   

3. 编译项目：

   go build ./...
   

4. 测试 HighGo 连接：

   • 启动应用
   • 创建 HighGo 连接
   • 测试连接是否成功

三、重要说明

⚠️ 影响范围

采用独立驱动名后，影响范围如下：

1. PostgreSQL 继续使用原生 github.com/lib/pq
2. HighGo 使用 github.com/highgo/pq-sm3（本地替换到官方源码）
3. 两条连接链路互不覆盖，降低兼容性风险

兼容性验证

集成后，请务必测试：

1. ✅ HighGo 数据库连接（SM3 认证）
2. ✅ 标准 PostgreSQL 连接（确保仍然可用）

若 PostgreSQL 或 HighGo 任一连接异常，优先检查驱动注册名与 go.mod replace 是否一致。

回滚方案

如果集成后出现问题，可以快速回滚：

1. 删除 go.mod 中的 replace 指令
2. 删除 go.mod 中 github.com/highgo/pq-sm3 的 require
3. 删除 third_party/highgo-pq/ 目录
4. 运行 go mod tidy
5. 重新编译

四、瀚高驱动特性

根据官方文档：

• 项目内包路径：github.com/highgo/pq-sm3（映射到本地 third_party/highgo-pq）
• 驱动名：highgo（项目内独立注册，避免覆盖 postgres）
• SM3 支持：自动启用国密认证
• 默认端口：5866
• 默认数据库：highgo
• 默认用户：sysdba
• sslmode 默认：require

五、故障排查

问题 1：编译失败

现象：go build 报错找不到 github.com/highgo/pq-sm3

解决：

1. 检查 third_party/highgo-pq/ 目录是否存在
2. 检查 go.mod 中 github.com/highgo/pq-sm3 的 require/replace 是否正确
3. 运行 go mod download

问题 2：HighGo 连接失败

现象：连接 HighGo 时报认证错误

解决：

1. 确认瀚高驱动已正确替换（检查 go.mod）
2. 确认项目内驱动注册名为 highgo
3. 确认 HighGo 服务器支持 SM3 认证
4. 检查用户名、密码、端口是否正确

问题 3：PostgreSQL 连接失败

现象：集成后标准 PostgreSQL 无法连接

解决：

1. 检查是否误将 github.com/lib/pq 全局 replace 到 HighGo 驱动
2. 确认 PostgreSQL 仍使用 sql.Open("postgres", dsn)
3. 确认 HighGo 使用 sql.Open("highgo", dsn)

六、后续优化建议

如果后续需要增强，可考虑：

1. 将 HighGo sslmode 做成可配置项（前后端联动）
2. 增加 HighGo/PG 驱动链路健康检查项
3. 联系瀚高技术支持确认 SM3 + SSL 最佳参数组合

七、参考资料

• 瀚高官方文档：https://www.highgo.com/document/zh-cn/application/pq%E6%8E%A5%E5%8F%A3.html
• 瀚高驱动下载：https://pan.baidu.com/s/1xuz6uJz0utRgKWecXhpOiA?pwd=o0tj
• 标准 lib/pq：https://github.com/lib/pq