4. Flux 安装：使用 CLI 安装 Flux、引导 Git 仓库、检查 Flux 组件运行状态
Flux 的安装遵循“先 CLI、后引导、再验证”的三步流程。本章使用 Flux CLI 完成引导安装，将集群与 Git 仓库绑定，并验证所有控制器组件健康运行。安装完成后，集群即进入“声明式同步”状态，所有后续节点池运维操作均通过 Git 仓库驱动。
4.1 安装前提与版本选择
| 前提条件 | 说明 |
|---|---|
| Kubernetes 集群 | v1.25+，具备集群管理员权限（kubeconfig） |
| Git 仓库 | GitHub / GitLab / Bitbucket，推荐私有仓库 |
| Flux CLI | v2.x 最新稳定版（当前 v2.3.0+） |
| 网络连通 | 集群可访问 Git 仓库（HTTPS 或 SSH） |
版本对齐建议： 本课程统一使用 Flux v2.3.0，与 Argo CD v2.11.x 协同测试通过。生产环境请锁定 Flux 大版本，避免自动升级导致兼容性问题。
4.2 安装 Flux CLI
Flux CLI 是引导安装和日常运维的核心工具。支持 macOS / Linux / Windows（WSL）。
4.2.1 macOS（Homebrew）
brew install fluxcd/tap/flux4.2.2 Linux（官方脚本）
curl -s https://fluxcd.io/install.sh | sudo bash4.2.3 验证 CLI 版本
flux --version
# 输出示例：flux version 2.3.04.3 引导安装：flux bootstrap
flux bootstrap 是安装的核心命令，它完成以下工作：
- 在集群中创建
flux-system命名空间 - 部署所有 Flux 控制器（source-controller、kustomize-controller、helm-controller、notification-controller）
- 将 Git 仓库克隆到集群本地缓存
- 创建初始的
GitRepository和Kustomization资源 - 建立 SSH / HTTPS 密钥对，自动注册到 Git 仓库
4.3.1 GitHub 仓库引导（HTTPS + 令牌）
export GITHUB_=<your-personal-access->
export GITHUB_USER=<your-github-username>
flux bootstrap github \
--owner=$GITHUB_USER \
--repository=gitops-node-pool \
--branch=main \
--path=./clusters/production \
--personal \
---auth4.3.2 GitLab 仓库引导（SSH）
flux bootstrap gitlab \
--owner=my-group \
--repository=gitops-node-pool \
--branch=main \
--path=./clusters/production \
--ssh-hostname=gitlab.com \
--ssh-key-algorithm=ed25519
路径规划：
--path 参数指定集群配置在仓库中的根目录。本课程统一使用 ./clusters/production，后续所有节点池运维清单均放置在此路径下。请勿在引导后随意修改路径，否则 Flux 将丢失同步目标。
4.4 引导流程可视化
下图展示 flux bootstrap 从 CLI 到集群再到 Git 仓库的完整数据流：
4.5 检查 Flux 组件运行状态
引导完成后，使用以下命令验证所有组件健康运行：
4.5.1 查看 Flux 命名空间资源
kubectl get all -n flux-system
# 期望输出（4 个控制器 Deployment 各对应 1 个 Pod）：
# NAME READY STATUS RESTARTS AGE
# pod/helm-controller-xxxxx 1/1 Running 0 2m
# pod/kustomize-controller-xxxxx 1/1 Running 0 2m
# pod/notification-controller-xxxxx 1/1 Running 0 2m
# pod/source-controller-xxxxx 1/1 Running 0 2m4.5.2 使用 flux check 命令
flux check
# 输出示例：
# ► checking prerequisites
# ✔ Kubernetes 1.28.2 >=1.25.0-0
# ► checking controllers
# ✔ helm-controller: deployment ready
# ✔ kustomize-controller: deployment ready
# ✔ notification-controller: deployment ready
# ✔ source-controller: deployment ready
# ► checking crds
# ✔ CRDs installed4.5.3 查看 Git 仓库同步状态
flux get sources git
# 输出示例：
# NAME READY MESSAGE REVISION
# flux-system True Fetched revision: main/abc123def main/abc123def
flux get kustomizations
# 输出示例：
# NAME READY MESSAGE REVISION
# flux-system True Applied revision: main/abc123def main/abc123def
健康检查清单：
- Pod 状态： 4 个控制器 Pod 均为
Running，READY 为1/1 - CRD 安装：
flux check输出✔ CRDs installed - Git 同步：
flux get sources git显示Ready=True，REVISION 有值 - Kustomization 应用：
flux get kustomizations显示Ready=True
4.6 常见安装问题与排查
| 问题现象 | 可能原因 | 解决措施 |
|---|---|---|
flux bootstrap 超时 |
Git 仓库网络不可达 / 令牌权限不足 | 检查 GITHUB_ 权限（repo 全选）；使用 --timeout=10m 延长超时 |
| 控制器 Pod CrashLoopBackOff | 集群资源不足 / 镜像拉取失败 | kubectl describe pod -n flux-system 查看事件；检查镜像仓库限速 |
| Git 同步状态为 False | SSH 密钥未注册 / 分支不存在 | 重新运行 flux bootstrap 并指定 --ssh-key-algorithm；确认分支名称 |
flux check 报 CRD 缺失 |
引导未完成 / 权限不足 | 检查 kubeconfig 集群管理员权限；重新执行 bootstrap |
4.7 卸载 Flux（如需重装）
flux uninstall --namespace=flux-system
# 确认清理：
kubectl get ns flux-system
# 输出：Error from server (NotFound): namespaces "flux-system" not found
卸载影响：
flux uninstall 会删除 flux-system 命名空间及其所有资源，包括 GitRepository、Kustomization 以及集群中由 Flux 管理的所有工作负载。执行前请确认已备份所需配置。
4.8 安装后验证总结
完成本章安装后，集群应满足以下状态：
- CLI 就绪：
flux --version输出 v2.3.0+ - 控制器运行： 4 个控制器 Pod 全部
Running - Git 仓库绑定：
flux get sources git显示Ready=True - 初始同步完成：
flux get kustomizations显示Ready=True - 仓库结构： 仓库根路径下已生成
./clusters/production/flux-system/目录
至此，Flux 已成功安装并接入 Git 仓库。下一阶段将基于此基础设施，开始定义节点池的 GitOps 运维清单。