# Kingbase JDBC 8.6.0 Provisioning

## 背景

RailwaySystem 使用的 Kingbase JDBC 8.6.0 不是公共 Maven 仓库可解析的依赖。全新开发机、GitLab Runner 或本地 Maven 仓库需要在后端构建前完成受控供应。

Maven 坐标为 `com.kingbase:kingbase8:8.6.0`。

## 为什么不将 jar 放入 Git

该驱动是第三方商业二进制文件。将它提交到源码仓库会绕过许可证和二进制品治理流程。仓库只保存供应脚本和完整性元数据，驱动必须来自组织授权的受控渠道。

## 开发机首次初始化

```bash
export KINGBASE_JDBC_JAR=/path/to/authorized/kingbase8-8.6.0.jar
bash scripts/bootstrap/install-kingbase-jdbc.sh
```

安装脚本会在写入 Maven 本地仓库前校验源文件，并在安装后再次校验。

## 日常检查

```bash
bash scripts/bootstrap/check-kingbase-jdbc.sh
```

该检查只验证本地 Maven 仓库中的文件及其 SHA256，不会下载或安装任何内容。

## GitLab Runner 初始化

1. 从合法、受控的供应源取得 vendor jar。
2. 设置 `KINGBASE_JDBC_JAR` 为该文件的绝对路径。
3. 执行 `scripts/bootstrap/install-kingbase-jdbc.sh`。
4. 执行 `scripts/bootstrap/check-kingbase-jdbc.sh`。
5. 确认 preflight 通过后再启用 Runner。

CI 中的后端构建只执行 preflight；它不会自动安装、联网下载或上传驱动。

## SHA256 完整性校验

受控文件的 SHA256 为：

```text
346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32
```

安装和检查脚本都要求文件与该值完全一致。更换 vendor 发布物时，必须先通过组织的许可证与发布物审核，再由负责人更新受控校验值。

## 故障排查

- `Could not find artifact`：先运行日常检查。如果本地 artifact 缺失，从授权源取得驱动并重新执行初始化。
- `checksum mismatch`：不要继续构建。删除受影响的本地 artifact，重新从受控源取得驱动并安装。
- `missing local artifact`：确认 `HOME` 与运行 Maven 的账户一致，再执行安装和检查脚本。

## Runner 迁移与灾备恢复

1. 暂停新 Runner 接受构建任务。
2. 从授权的灾备介质或受控供应系统取得 vendor jar。
3. 按“GitLab Runner 初始化”流程安装并校验。
4. 使用空 Maven 本地仓库执行一次后端构建验证。
5. 记录供应来源、校验值、操作时间和操作人，然后启用 Runner。

## 安全原则

- 只使用组织授权的 vendor 发布物，不从公开网盘或未审核镜像取得驱动。
- 不将商业驱动提交到 Git、编码进文本文件、放入 resources，或通过 `systemPath` 引用。
- 不在脚本、CI 配置或文档中记录认证信息、数据库私有连接信息或个人账户。
- 不将 vendor jar 发布为 CI artifact，不由 preflight 修复或改写 Runner。