Deploy-Laboratory/docs/04-14-nodejs-GitOps与CI流水线.md

04-14-nodejs-GitOps与CI流水线

从 Node.js 应用仓库 视角串联：持续集成（CI） 构建镜像并推送仓库，持续交付 通过 GitOps 或流水线步骤把声明式清单下发到 K3s。细节以仓库内 GitLab/GitOps 文档为准，本篇给 最小闭环与引用。

TL;DR

• 自动化验收：./scripts/verify.sh run 04-14
• 关键前置：按本文「前置条件」准备环境变量/Secret/入口 IP
• 成功判据：达到本文「预期」且 playbook 断言通过
• 排障：见本文「排障」

前置条件

• 集群可拉取镜像（私有仓库需 imagePullSecrets，见 04-02 相关说明）。
• 若使用 GitLab：05-03-k3s-安装gitlab-含runner.md、05-04-k3s-配置gitlab-cicd.md。

清单与仓库（唯一真源）

• 本文无独立流水线 YAML（GitLab CI、Argo CD、Flux 随版本变化大）；流程见 05-04、03-09。
• 应用清单真源：ansible/files/04-01/（例如 04-14-nodejs-demo.yaml）。将 该目录或单文件 纳入 Git，由 CI 改 image: tag 或由 GitOps 同步到集群。

场景说明（白话）

• CI（持续集成）：你 git push 之后，自动 测试、打镜像、推到镜像仓库。
• CD / GitOps：要么流水线里 kubectl apply，要么让 Argo CD / Flux 盯着 Git，集群状态跟仓库对齐。
• 和 04-01 的关系：04-01 是「手写能跑」的最小示例；上流水线后，只是把同样这些 YAML 改成自动化维护。

CI 典型阶段（概念）

flowchart LR
  A[git push] --> B[lint test build]
  B --> C[docker build]
  C --> D[push registry]
  D --> E[update manifest tag]
  E --> F[deploy to cluster]

1. 源码：Dockerfile 多阶段构建（node:xx 构建 → distroless/alpine 运行）。
2. 镜像 tag：推荐 commit SHA 或 semver，避免一律 latest。
3. 推送：docker push registry.example.com/app:tag。
4. 更新清单：修改 Deployment 的 image: 或 Kustomize overlay / Helm values。

GitLab CI 示例结构与 Runner 注册见 05-04。

下发到集群的两种方式

方式	说明
流水线内 kubectl	CI Job 使用 KUBECONFIG 或 in-cluster ServiceAccount kubectl apply；简单，密钥管理要求高。
GitOps	仓库仅存 YAML/Helm；Argo CD / Flux 监听 Git 自动同步集群；见 03-09-k3s-gitops-集群配置管理.md。

GitOps 最小路径（Flux / Argo CD 通用思路）

1. 清单仓库与镜像仓库分离或同库不同目录。
2. 集群内安装 GitOps 控制器，指向 Git 分支 + 路径。
3. CI 只负责 构建推送镜像 + 提 PR 改 image tag（或机器人提交），合并后由控制器 拉取并 apply。

与 04-01 的关系

• 04-01 的 nodejs-demo.yaml 可作为 GitOps 仓库中的基准清单；CI 只替换 image: 与 metadata.labels.version 等字段。

验证（流程级）

• CI：Pipeline 成功、镜像在 registry 可见。
• 集群：kubectl get deploy -n <ns> -o jsonpath='{.items[*].spec.template.spec.containers[*].image}' 与预期 tag 一致。
• 应用：curl Ingress 路径与 04-01 验证方式相同。

失败排查

• ImagePullBackOff：tag 错误、未认证 registry、节点网络限制。
• GitOps 不同步：分支/path 配置错误、RBAC 不足、CRD 冲突。
• 06-01-k3s-networkpolicy-故障排查.md（部署后服务不可达时）

相关文档

• 05-03-k3s-安装gitlab-含runner.md
• 05-04-k3s-配置gitlab-cicd.md
• 03-09-k3s-gitops-集群配置管理.md
• 04-03-nodejs-镜像与运行命令.md

排障

• 先看 playbook 输出：失败时先定位是 deploy/wait/http_check 哪一步。
• 集群侧总览：kubectl get nodes -o wide、kubectl -n kube-system get pods -o wide。
• 事件与日志：kubectl -n <ns> describe ...、kubectl -n <ns> logs ... --tail=200。