kra-oa/deploy/DEPLOYMENT.md

KRA 部署与配置文档

本文档完整描述 kra 框架项目从代码推送到双集群部署的全链路：各组件如何串联、GitLab / Jenkins / Harbor 三块各自需要配置什么、首次部署步骤与排障方法。

快速接入新项目只看 README.md；本文是完整运维文档。 文中账号密码遵循内网环境约定，不写入仓库，凭据统一存放在 Jenkins Credentials 中。

1. 环境拓扑

节点	角色	关键端口 / 路径
192.168.200.128	Rancher + RKE2 集群1（dev）	前端 30080 / 后端 30081，命名空间 <APP_NAME>-dev
192.168.200.129	RKE2 集群2（prod）	前端 30080 / 后端 30081，命名空间 <APP_NAME>-prod
192.168.200.130	GitLab	仓库 http://192.168.200.130/root/kra，分支 main / dev
192.168.200.131	Jenkins	8080（容器挂载宿主机 docker.sock）
192.168.200.132	Harbor	HTTPS（自签名证书），项目 library

所有节点 SSH 使用 root；各系统账号密码见内网环境约定。

2. 总体流程

开发者
  │ git push (dev 或 main)
  ▼
GitLab ──(Jenkins 集成,请求内嵌凭据)──► Jenkins job「kra」
                                          │ gitlab-plugin 解析 push payload
                                          │ 注入环境变量 gitlabBranch
            ┌─────────────────────────────┤
            ▼ Test/Build（宿主机 Docker）  ▼ Build & push
      Go 编译 / pnpm 构建 ────────► Harbor（镜像 tag: {分支}-{commit前12位}）
            │
            ▼ Deploy（kubectl + 对应集群 kubeconfig）
  ┌─────────┴─────────┐
  ▼                   ▼
128 / kra-dev     129 / kra-prod
（3 后端 + 3 前端 + MySQL + Redis）

分支路由的核心：GitLab 集成发送的 push payload 中带 ref（分支），Jenkins 的 gitlab-plugin 把它注入为环境变量 gitlabBranch，并把 push 的最终提交注入为 gitlabAfter。deploy/Jenkinsfile 的 Select environment 阶段按分支派生出命名空间、环境标识、目标集群与 kubeconfig 凭据，随后优先按 gitlabAfter 的 SHA 检出构建内容。单 job 同时服务两个环境，不会串：

• 镜像 tag 含分支与 commit（如 dev-f0657c1abc12），按 commit 不可变；
• 构建不并发（disableConcurrentBuilds），同时推送时排队执行；
• job 的 SCM 分支规格 */main 只影响 Jenkinsfile 脚本本身的加载（两分支脚本内容同步），不影响实际构建内容。

tag 推送不触发部署（GitLab 集成未启用标签事件，Jenkinsfile 也只认 dev/main），tag 仅作 GitLab 版本标记。

3. GitLab 侧配置

只需配置一项：Jenkins 集成（不需要手工建 webhook）。

路径：项目 → 设置 → 集成 → Jenkins

字段	值
Jenkins 服务器 URL	http://192.168.200.131:8080
Project name	kra（与 Jenkins job 名一致）
Username / Password	Jenkins 的 admin 账号
触发事件	仅勾选"推送"

原理：GitLab 把 Jenkins 用户名/密码内嵌进 URL，POST 到 http://<user>:<pass>@131:8080/project/kra，请求体为完整 push 事件 JSON（含分支 ref）。带凭据的请求天然通过 Jenkins 权限检查，无需匿名授权、无需维护自定义请求头。

• 交付记录：集成编辑页底部的"最近事件"（hook_logs），可看每次请求体与响应码，是排障第一入口。
• 修改 Jenkins 密码后：只需回此表单改一次密码，所有分支自动生效。
• 注意：GitLab 的 Jenkins 集成每个项目只能配一个（所以采用单 job 分支路由模型）。

4. Harbor 侧配置

1. 项目：library（镜像最终路径 library/kra-backend、library/kra-frontend）。
2. 机器人账号：项目管理 → library → 机器人账户 → 创建 kra-ci（push/pull 权限），凭据存入 Jenkins 凭据 harbor-library-push。
3. 自签名证书信任（Harbor 用自签 HTTPS，docker/kubelet 需要信任）：

# ① Jenkins 宿主机（131）——docker login/push 用
mkdir -p /etc/docker/certs.d/192.168.200.132
cp harbor-ca.crt /etc/docker/certs.d/192.168.200.132/ca.crt
# docker daemon 自动读取，无需重启

# ② 两台 RKE2 节点（128/129）——kubelet 拉镜像用
cat >/etc/rancher/rke2/registries.yaml <<'EOF'
mirrors:
  "192.168.200.132":
    endpoint:
      - "https://192.168.200.132"
    rewrite:
      "^rancher/(.*)": "library/$1"
configs:
  "192.168.200.132":
    tls:
      insecure_skip_verify: true
    auth:
      username: kra-ci
      password: "<robot 密码>"
EOF
systemctl restart rke2-server

集群内另有流水线自动创建/更新的 harbor-registry imagePullSecret（每次部署时同步 robot 凭据），Pod 拉镜像走它；registries.yaml 是节点级兜底。

5. Jenkins 侧配置

5.1 部署形态与系统依赖

• Jenkins 以容器运行在 131，容器内挂载宿主机 /var/run/docker.sock：流水线里的 docker build/push 实际跑在宿主机 daemon 上（注意容器内 docker CLI 无 buildx，Dockerfile 不能用 BuildKit 语法）。
• 宿主机依赖缓存：/var/lib/kra-ci-cache/{go-mod,go-build,pnpm-store,corepack} 挂进构建容器，避免重复下载。
• 容器内需有 kubectl、envsubst、git。

5.2 插件清单（关键）

插件	作用
gitlab-plugin	/project/<job> 接收端点、触发构建、注入 gitlabBranch
Pipeline	流水线核心（Pipeline script from SCM）
Git	SCM 检出
Credentials / Credentials Binding	凭据管理与注入

5.3 凭据（5 个，ID 与 deploy/Jenkinsfile 中变量对应）

凭据 ID	类型	来源 / 获取方式
gitlab-root-http	用户名/密码	GitLab 账号（代码检出用）
harbor-library-push	用户名/密码	Harbor robot 账号 kra-ci
kra-rke2-128-kubeconfig	Secret file	128 节点 /etc/rancher/rke2/rke2.yaml，把 server 的 127.0.0.1 改为 192.168.200.128 后保存
kra-rke2-129-kubeconfig	Secret file	129 节点同上，server 改为 192.168.200.129
kra-mysql-root-password	Secret text	自定的 MySQL root 密码（与节点上 MySQL 一致）

kubeconfig 添加路径：系统管理 → 凭据 → Add Credentials → 类型 Secret file → 上传文件 → 填 ID。

kubeconfig 可用性验证：kubectl --kubeconfig <文件> -n kra-dev get pods。若报证书错误，在节点 /etc/rancher/rke2/config.yaml 追加 tls-san: <节点IP> 并 systemctl restart rke2-server。

5.4 Job 配置（唯一 job「kra」）

1. 新建 Item → Pipeline，命名 kra。
2. 勾选"不允许并发构建"。
3. 触发器：勾选 Build when a change is pushed to GitLab（gitlab-plugin 的 /project/<job> 端点依赖该触发器存在）。
4. 流水线：定义 = Pipeline script from SCM；SCM = Git；仓库 http://192.168.200.130/root/kra.git；凭据 gitlab-root-http；分支规格 */main；脚本路径 deploy/Jenkinsfile；勾选轻量级检出。
5. Jenkins 安全策略保持"登录用户可做任何事"即可——集成请求自带凭据，天然有构建权限。

5.5 分支解析优先级（Jenkinsfile）

gitlabBranch（集成/推送触发）
  > BRANCH_NAME（多分支流水线场景）
    > JOB_NAME（手动触发兜底：以 -dev 结尾按 dev，否则默认 main）

6. Kubernetes 节点配置

项	说明
Harbor 拉镜像信任	见 §4 第 3 步 registries.yaml
应用配置文件	Jenkins 将 k8s/config.example.yaml 渲染为 <APP_NAME>-config-template ConfigMap，初始化容器复制到共享配置 PVC /data/conf
配置与上传存储	<APP_NAME>-config（1Gi）和 <APP_NAME>-uploads（20Gi），均要求存储类支持 ReadWriteMany
数据持久化	/var/lib/<APP_NAME>/mysql、/var/lib/<APP_NAME>/redis（节点本地目录，当前单节点集群适用；Redis initContainer 需要允许 root 修正 hostPath 权限）
kubectl	节点用 /var/lib/rancher/rke2/bin/kubectl，并 export KUBECONFIG=/etc/rancher/rke2/rke2.yaml

首次部署初始化流程（kra 框架约定，勿用环境变量注入数据库 DSN）：

1. 服务启动时数据库未就绪，首页显示"前往初始化"。
2. 走完 /init/initdb 向导：建库建表 + 写入种子数据（默认账号 admin）。
3. 向导最后一步把数据库连接写回共享 PVC 中的 /data/conf/config.yaml，配置不会随 Pod 消失。
4. 初始化期间建议先把后端缩容到 1 个副本：kubectl -n <APP_NAME>-dev scale deployment/<APP_NAME>-backend --replicas=1。初始化完成后再恢复副本数并滚动重启：kubectl -n <APP_NAME>-dev scale deployment/<APP_NAME>-backend --replicas=3，然后 kubectl -n <APP_NAME>-dev rollout status deployment/<APP_NAME>-backend。后续手工改配置也需要执行滚动重启。

<APP_NAME>-config-template ConfigMap 只负责首次创建配置文件。初始化后，运行时配置以共享 PVC 中的 /data/conf/config.yaml 为准；更新 ConfigMap 不会覆盖已有配置，避免覆盖初始化写入的数据库连接。

7. 首次部署清单（按顺序）

1. Harbor：建 library 项目 + robot 账号；证书分发到 131 宿主机与 128/129 节点。
2. RKE2 集群：确认 KRA_SHARED_STORAGE_CLASS 对应的存储类支持 ReadWriteMany。
3. Jenkins：安装插件；添加 §5.3 所列 5 个凭据；按 §5.4 建 kra job。
4. GitLab：配置 Jenkins 集成（§3）。
5. 推送任意分支触发构建，观察首次构建（有依赖缓存预热，耗时会比后续长）。
6. 初始化向导（§6），完成后浏览器验证。

8. 部署验证

curl -I http://192.168.200.128:30080/     # 前端 200
curl    http://192.168.200.128:30081/health   # "ok"
curl -I http://192.168.200.129:30080/     # 同上验证 129

构建日志里的 resolved branch='xxx' 和 building commit <sha> 两行可分别确认部署环境和实际构建版本。

9. 排障速查

现象	排查点
push 后没有构建	GitLab 集成"最近事件"（hook_logs）看响应码与请求体；确认集成启用且勾选推送
构建失败	Jenkins 构建日志；先看 resolved branch 是否符合预期
Pod 镜像拉取失败	节点 registries.yaml、Harbor robot 是否有效、harbor-registry Secret
后端 503 / 初始化异常	配置 PVC 是否已绑定、ConfigMap 是否存在、后端日志是否连上 <APP_NAME>-mysql:3306
登录态全部失效	是否在系统设置中更换了 JWT 签名密钥（换值即失效所有 token）
构建慢	缓存目录是否挂载成功；镜像源（goproxy/npmmirror/daocloud）偶发卡顿需重试

10. 附录：安全与维护

• 所有账号密码只存 Jenkins Credentials / 各系统自身，不写入仓库；configs/config.yaml 不要提交真实密钥。
• 轮换 Jenkins 密码：GitLab 集成表单改一次即可。
• 轮换 Harbor robot：更新 Jenkins 凭据后重新部署即可。轮换 MySQL 密码必须先在 MySQL 中执行 ALTER USER 并确认连接正常，再更新 Jenkins 凭据并重启相关 Pod；仅更新 Secret 不会修改已初始化 MySQL 数据目录中的 root 密码。JWT 签名密钥通过系统设置修改并保存到共享配置 PVC，随后滚动重启后端；换值会使现有登录态失效。