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

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

## 前置条件

- 集群可拉取镜像（私有仓库需 `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-nodejs-demo/`](../ansible/files/04-01-nodejs-demo/)（例如 `04-01-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 典型阶段（概念）

```mermaid
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-03-k3s-安装gitlab-含runner.md)
- [`05-04-k3s-配置gitlab-cicd.md`](05-04-k3s-配置gitlab-cicd.md)
- [`03-09-k3s-gitops-集群配置管理.md`](03-09-k3s-gitops-集群配置管理.md)
- [`04-02-nodejs-镜像与运行命令.md`](04-02-nodejs-镜像与运行命令.md)