mirror of
https://github.com/Syngnat/GoNavi.git
synced 2026-05-12 08:39:40 +08:00
de8fb60a30
- 引入 third_party/highgo-pq 作为 HighGo 专用驱动实现 - 调整驱动注册与连接入口，避免覆盖 postgres 驱动 - 保持 PG 数据源行为不变并补充接入文档
197 lines
4.7 KiB
Markdown
197 lines
4.7 KiB
Markdown
# HighGo SM3 国密驱动集成指南
|
||
|
||
## 一、背景说明
|
||
|
||
HighGo（瀚高）数据库需要使用支持 SM3 国密认证的 PostgreSQL 驱动。瀚高官方提供了基于 `lib/pq` 的安全增强版本。
|
||
|
||
## 二、集成步骤
|
||
|
||
### 步骤 1：下载瀚高 pq 驱动
|
||
|
||
1. 访问百度网盘链接：
|
||
```
|
||
https://pan.baidu.com/s/1xuz6uJz0utRgKWecXhpOiA?pwd=o0tj
|
||
```
|
||
|
||
2. 下载驱动源码压缩包
|
||
|
||
### 步骤 2：放置驱动源码
|
||
|
||
1. 在项目根目录创建目录（如果不存在）：
|
||
```bash
|
||
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 驱动依赖与本地替换：
|
||
|
||
```go
|
||
require github.com/highgo/pq-sm3 v0.0.0
|
||
replace github.com/highgo/pq-sm3 => ./third_party/highgo-pq
|
||
```
|
||
|
||
完整示例：
|
||
```go
|
||
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 修改为：
|
||
|
||
```go
|
||
module github.com/highgo/pq-sm3
|
||
```
|
||
|
||
同时在驱动源码中把注册名改为 `highgo`，确保不覆盖 `postgres`：
|
||
|
||
```go
|
||
sql.Register("highgo", &Driver{})
|
||
```
|
||
|
||
### 步骤 4：更新 HighGo 连接配置（可选）
|
||
|
||
根据瀚高官方文档，建议修改 `internal/db/highgo_impl.go:43` 的 sslmode：
|
||
|
||
**当前代码**：
|
||
```go
|
||
q.Set("sslmode", "disable")
|
||
```
|
||
|
||
**建议修改为**（瀚高默认）：
|
||
```go
|
||
q.Set("sslmode", "require")
|
||
```
|
||
|
||
> ⚠️ 注意：如果您的 HighGo 服务器未配置 SSL，保持 `disable` 即可。
|
||
|
||
### 步骤 5：验证集成
|
||
|
||
1. 清理依赖缓存：
|
||
```bash
|
||
go clean -modcache
|
||
```
|
||
|
||
2. 重新下载依赖：
|
||
```bash
|
||
go mod download
|
||
```
|
||
|
||
3. 编译项目：
|
||
```bash
|
||
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
|