基本框架

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

@@ -0,0 +1,73 @@
+# 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/nodejs-demo/`](../ansible/files/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)