schemaCheck/docs/CI集成说明.md

缓存序列化结构检测 — CI 集成说明

---

1. 集成概览

开发者 push 代码
    ↓
Gitea Actions 触发
    ↓
浅克隆业务仓库（depth=2）
    ↓
从 Nexus 下载 cache-schema-checker.jar
    ↓
java -jar 执行（对比 HEAD~1 与 HEAD）
    ↓
有结构变更 → 企微通知（按 Key 骨架；删除橙/新增绿）
    ↓
mode=block 且含任意结构变更 → exit 1（流水线失败）

---

2. 前置条件

项	说明
Gitea Runner	标签 jdk11，已安装 Java 11
Nexus 私库	可访问 http://192.168.3.25:18081/nexus/repository/maven-releases
工具 JAR	com.codechecker:cache-schema-checker:1.0.0 已发布

---

3. 业务仓库文件清单

在 jnpf-java-cloud 中新增：

jnpf-java-cloud/
├── .gitea/
│   ├── workflows/
│   │   └── cache-schema-check.yaml      # 流水线
│   └── config/
│       └── cache-schema-check-config.yaml  # 检测配置

---

4. 流水线模板

name: 缓存序列化结构检查
run-name: ${{ gitea.actor }}的缓存结构检查

on:
  push:
  workflow_dispatch:

env:
  CACHE_SCHEMA_CHECKER_VERSION: "1.0.0"
  CACHE_SCHEMA_CHECKER_REPO_URL: "http://192.168.3.25:18081/nexus/repository/maven-releases"

jobs:
  cache-schema-check:
    if: ${{ gitea.ref != 'refs/heads/pre' && gitea.ref != 'refs/heads/dev' && gitea.ref != 'refs/heads/master-2.0' }}
    runs-on: jdk11
    steps:
      - name: 检出代码
        run: |
          git config --global http.sslVerify false
          git clone --depth 2 --single-branch --branch "${{ gitea.ref_name }}" \
            "https://${{ gitea.token }}@git.niujiekeji.com/${{ gitea.repository }}.git" .
          git checkout -B "${{ gitea.ref_name }}" "${{ gitea.sha }}"

      - name: 检查配置文件
        run: |
          if [ ! -f .gitea/config/cache-schema-check-config.yaml ]; then
            echo "错误: 缺少 .gitea/config/cache-schema-check-config.yaml"
            exit 1
          fi

      - name: 从 Nexus 下载检测工具
        run: |
          GROUP_PATH="com/codechecker/cache-schema-checker"
          JAR_NAME="cache-schema-checker-${CACHE_SCHEMA_CHECKER_VERSION}.jar"
          JAR_URL="${CACHE_SCHEMA_CHECKER_REPO_URL}/${GROUP_PATH}/${CACHE_SCHEMA_CHECKER_VERSION}/${JAR_NAME}"
          JAR_PATH="/tmp/${JAR_NAME}"

          echo "下载: ${JAR_URL}"
          if command -v curl >/dev/null 2>&1; then
            curl -fsSL -o "${JAR_PATH}" "${JAR_URL}"
          elif command -v wget >/dev/null 2>&1; then
            wget -q -O "${JAR_PATH}" "${JAR_URL}"
          else
            echo "错误: Runner 缺少 curl 或 wget"
            exit 1
          fi

          if [ ! -s "${JAR_PATH}" ]; then
            echo "错误: 下载失败或文件为空"
            exit 1
          fi

          ls -lh "${JAR_PATH}"

      - name: 验证 JDK
        run: java -version

      - name: 执行 缓存结构检测
        env:
          WECOM_ROBOT_WEBHOOK: ${{ secrets.WECOM_ROBOT_WEBHOOK }}
        run: |
          OLD_SHA=$(git rev-parse HEAD~1 2>/dev/null || echo "")
          if [ -z "$OLD_SHA" ]; then
            echo "首次提交，跳过检测"
            exit 0
          fi

          COMMIT_TIME=$(git log -1 --format=%cd --date=format:'%Y-%m-%d %H:%M:%S')

          java -jar "/tmp/cache-schema-checker-${CACHE_SCHEMA_CHECKER_VERSION}.jar" \
            --config .gitea/config/cache-schema-check-config.yaml \
            --repo-root . \
            --old-sha "$OLD_SHA" \
            --new-sha "$(git rev-parse HEAD)" \
            --branch "${{ gitea.ref_name }}" \
            --modifier "${{ gitea.actor }}" \
            --modify-time "$COMMIT_TIME"

---

5. 与现有流水线的关系

流水线	作用	关系
demo.yaml (AI代码质量分析)	AI Code Review	并行，互不影响
code-check (CodeChecker)	通用变更检测	同模式，可并列执行
cache-schema-check	缓存结构检测	新增

---

6. 工具发布流程（redisCheck 仓库）

# 在 redisCheck 仓库根目录
mvn clean package -DskipTests

# 发布到 Nexus（需配置 settings.xml，并开启 deploy-nexus profile）
mvn clean deploy -Dnexus.deploy.enabled=true -DskipTests

发布产物：

com/codechecker/cache-schema-checker/1.0.0/
  ├── cache-schema-checker-1.0.0.jar          # 可执行 fat-jar
  └── cache-schema-checker-1.0.0.pom

---

7. 退出码约定

退出码	含义	流水线表现
0	通过（含 notify 模式下的告警）	绿色
1	阻断（block 模式）	红色
2	执行错误（配置缺失、jar 异常等）	红色

---

8. 故障排查

现象	可能原因	处理
首次提交跳过	无 HEAD~1	正常行为
下载 jar 失败	Nexus 地址/版本错误	检查 env 变量
未收到企微	Secret 未配 / notify.enabled=false	检查配置
大量误报	锁/计数器未过滤	补充 ignore.key_patterns
漏报	写入模式未覆盖 / 模块过滤过窄	确认 W01~W05 已启用；检查 include_modules
类型展开不完整	类型在依赖 jar 中	补充 manual_mappings.value_type

---

9. 本地调试

# 在 jnpf-java-cloud 根目录
java -jar /path/to/cache-schema-checker-1.0.0.jar \
  --config .gitea/config/cache-schema-check-config.yaml \
  --repo-root . \
  --old-sha HEAD~1 \
  --new-sha HEAD \
  --branch $(git branch --show-current) \
  --modifier "$(git log -1 --format=%an)" \
  --modify-time "$(git log -1 --format=%cd --date=format:'%Y-%m-%d %H:%M:%S')"

可加 --dry-run 仅输出报告不发企微。