diff --git a/.gitignore b/.gitignore index bfd2aefe8..72e655aa0 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,9 @@ node_modules/ **/node_modules1/ **/node_modules2/ +# Local authorized Kingbase JDBC vendor binary; provision via scripts/bootstrap/ +/RuoYi-Vue/lib/kingbase8-8.6.0.jar + # 日志与运行时临时文件 logs/ **/logs/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 8aa2ebf02..b3646ee74 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -21,6 +21,7 @@ build_backend: - export JAVA_HOME=/data2/wzb/tools/jdk8 - export PATH=/data2/wzb/tools/maven/bin:$JAVA_HOME/bin:$PATH - javac -version + - bash scripts/bootstrap/check-kingbase-jdbc.sh - cd RuoYi-Vue - mvn clean package - echo "=== 后端编译成功 ===" diff --git a/docs/handbook/deployment/kingbase-jdbc-provisioning.md b/docs/handbook/deployment/kingbase-jdbc-provisioning.md new file mode 100644 index 000000000..00998fd53 --- /dev/null +++ b/docs/handbook/deployment/kingbase-jdbc-provisioning.md @@ -0,0 +1,69 @@ +# 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。 diff --git a/scripts/bootstrap/check-kingbase-jdbc.sh b/scripts/bootstrap/check-kingbase-jdbc.sh new file mode 100755 index 000000000..7c824112d --- /dev/null +++ b/scripts/bootstrap/check-kingbase-jdbc.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +set -euo pipefail + +readonly EXPECTED_SHA256="346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32" +readonly INSTALLED_JAR="${HOME}/.m2/repository/com/kingbase/kingbase8/8.6.0/kingbase8-8.6.0.jar" + +sha256_file() { + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$1" | awk '{print $1}' + elif command -v shasum >/dev/null 2>&1; then + shasum -a 256 "$1" | awk '{print $1}' + else + echo "No SHA256 utility is available; install sha256sum or shasum." >&2 + return 1 + fi +} + +if [[ ! -f "${INSTALLED_JAR}" ]]; then + echo "Kingbase JDBC 8.6.0 is not provisioned." >&2 + echo "Run scripts/bootstrap/install-kingbase-jdbc.sh" >&2 + echo "with KINGBASE_JDBC_JAR pointing to the authorized vendor driver." >&2 + exit 1 +fi + +installed_sha256="$(sha256_file "${INSTALLED_JAR}")" +if [[ "${installed_sha256}" != "${EXPECTED_SHA256}" ]]; then + echo "Kingbase JDBC 8.6.0 checksum mismatch." >&2 + exit 1 +fi + +echo "Kingbase JDBC 8.6.0 preflight PASS." diff --git a/scripts/bootstrap/install-kingbase-jdbc.sh b/scripts/bootstrap/install-kingbase-jdbc.sh new file mode 100755 index 000000000..42ec61598 --- /dev/null +++ b/scripts/bootstrap/install-kingbase-jdbc.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +set -euo pipefail + +readonly EXPECTED_SHA256="346d5602477ed472b19c5e25729fff5a58b1d83cec56162a56ac4b86d9546c32" +readonly MAVEN_REPOSITORY="${HOME}/.m2/repository" +readonly INSTALLED_JAR="${MAVEN_REPOSITORY}/com/kingbase/kingbase8/8.6.0/kingbase8-8.6.0.jar" + +sha256_file() { + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$1" | awk '{print $1}' + elif command -v shasum >/dev/null 2>&1; then + shasum -a 256 "$1" | awk '{print $1}' + else + echo "No SHA256 utility is available; install sha256sum or shasum." >&2 + return 1 + fi +} + +if [[ -z "${KINGBASE_JDBC_JAR:-}" ]]; then + echo "KINGBASE_JDBC_JAR is not set." >&2 + echo "Set it to the absolute path of the authorized Kingbase JDBC 8.6.0 vendor driver." >&2 + exit 1 +fi + +if [[ ! -f "${KINGBASE_JDBC_JAR}" ]]; then + echo "KINGBASE_JDBC_JAR does not point to an existing regular file." >&2 + exit 1 +fi + +source_sha256="$(sha256_file "${KINGBASE_JDBC_JAR}")" +if [[ "${source_sha256}" != "${EXPECTED_SHA256}" ]]; then + echo "Kingbase JDBC 8.6.0 source checksum mismatch." >&2 + exit 1 +fi + +mvn install:install-file \ + -Dfile="${KINGBASE_JDBC_JAR}" \ + -DgroupId=com.kingbase \ + -DartifactId=kingbase8 \ + -Dversion=8.6.0 \ + -Dpackaging=jar \ + -DgeneratePom=true \ + -Dmaven.repo.local="${MAVEN_REPOSITORY}" + +if [[ ! -f "${INSTALLED_JAR}" ]]; then + echo "Kingbase JDBC 8.6.0 installation failed: local Maven artifact is missing." >&2 + exit 1 +fi + +installed_sha256="$(sha256_file "${INSTALLED_JAR}")" +if [[ "${installed_sha256}" != "${EXPECTED_SHA256}" ]]; then + echo "Kingbase JDBC 8.6.0 installed artifact checksum mismatch." >&2 + exit 1 +fi + +echo "Kingbase JDBC 8.6.0 provisioning PASS."