3. 基础工具链安装
在搭建策略即代码（Policy-as-Code, PaC）资源配额模型的测试验证环境之前，必须完成基础工具链的安装与验证。这些工具构成了后续所有操作——从代码管理、容器化部署到 Kubernetes 集群交互——的底层支撑。本章将依次安装 Python 3.10+、Git、Docker Desktop、kubectl 和 Helm，并提供验证命令以确保每个组件正确就绪。
3.1 工具链全景与依赖关系
下图展示了五款工具在 PaC 测试环境中的角色定位与数据流向。Python 负责策略引擎与测试脚本，Git 管理策略代码版本，Docker Desktop 提供本地容器运行时，kubectl 作为 Kubernetes 控制面客户端，Helm 则用于打包和部署策略相关的 Chart。
3.2 安装步骤与验证命令
以下按推荐安装顺序逐一说明。每个工具安装完成后，请立即执行验证命令，确保路径正确、版本匹配。
3.2.1 Python 3.10+
Python 是策略引擎 OPA（Open Policy Agent）的测试绑定语言，也是后续自动化脚本的核心解释器。推荐使用 pyenv 管理多版本，或直接从官方下载安装包。
| 操作系统 | 安装方式 | 验证命令 |
|---|---|---|
| macOS | brew install python@3.10 |
python3 --version |
| Ubuntu/Debian | sudo apt install python3.10 python3.10-venv |
python3.10 --version |
| Windows | 从 python.org 下载安装包，勾选“Add to PATH” | python --version |
# 验证 Python 版本（macOS / Linux）
python3 --version
# 预期输出：Python 3.10.12
# 验证 pip 可用
python3 -m pip --version
# 预期输出：pip 23.0.1 from ... (python 3.10)
python3 指向 3.10 及以上版本。如果系统默认 Python 版本较低，请使用 python3.10 显式调用，或通过 alias 重定向。
3.2.2 Git
Git 用于拉取策略代码仓库、管理分支与标签，以及后续的 CI/CD 集成。几乎所有 PaC 项目都依赖 Git 作为单一可信源。
# 验证 Git 版本
git --version
# 预期输出：git version 2.34.1
# 验证 Git 配置（至少需要 user.name 和 user.email）
git config --global user.name
git config --global user.email
| 配置项 | 推荐值示例 | 说明 |
|---|---|---|
user.name |
"Your Name" |
提交记录中的作者名 |
user.email |
"your.email@example.com" |
提交记录中的作者邮箱 |
init.defaultBranch |
main |
新仓库默认分支名 |
3.2.3 Docker Desktop
Docker Desktop 提供本地 Kubernetes 单节点集群（可选启用）和容器运行时，是测试资源配额策略最便捷的环境。安装完成后，请确保 Docker Engine 和 Kubernetes（如启用）均正常运行。
# 验证 Docker 客户端与服务端
docker version
# 预期输出：Client + Server 版本信息，Server 部分不能为空
# 验证 Docker 可正常拉取并运行容器
docker run hello-world
# 预期输出：Hello from Docker! 以及相关说明
# 验证 Kubernetes 节点状态（如已启用内置 K8s）
kubectl cluster-info
# 预期输出：Kubernetes control plane is running at ...
3.2.4 kubectl
kubectl 是 Kubernetes 的命令行工具，用于与集群 API Server 通信。安装方式包括原生包管理器、curl 下载或 Docker Desktop 内置版本。
# 验证 kubectl 版本（客户端）
kubectl version --client
# 预期输出：Client Version: v1.28.3
# 验证 kubectl 能否连接集群（需先启动 Docker Desktop K8s）
kubectl get nodes
# 预期输出：显示一个 Ready 状态的节点（如 docker-desktop）
# 验证 kubectl 上下文配置
kubectl config current-context
# 预期输出：docker-desktop（或自定义集群名）
| 安装方式 | 命令（macOS / Linux） | 命令（Windows） |
|---|---|---|
| 包管理器 | brew install kubectl |
choco install kubernetes-cli |
| curl 下载 | curl -LO "https://dl.k8s.io/release/v1.28.3/bin/linux/amd64/kubectl" |
使用 curl.exe 或浏览器下载 |
| Docker Desktop 内置 | 启用 K8s 后自动安装 | 启用 K8s 后自动安装 |
3.2.5 Helm
Helm 是 Kubernetes 的包管理器，用于将策略相关的资源（如 OPA 约束模板、约束、Namespace 配额）打包为 Chart，实现一键部署与升级。
# 验证 Helm 版本
helm version
# 预期输出：version.BuildInfo{Version:"v3.14.0", ...}
# 验证 Helm 仓库可用（添加官方稳定仓库）
helm repo add stable https://charts.helm.sh/stable
helm repo update
# 验证 Helm 能否与集群通信
helm list -n default
# 预期输出：空列表（或已部署的 Release 列表）
3.3 安装验证清单
完成所有安装后，请逐项核对下表。任何一项验证失败都应立即排查，否则后续章节的集群操作将无法正常执行。
| 工具 | 验证命令 | 预期结果 | 常见失败原因 |
|---|---|---|---|
| Python 3.10+ | python3 --version |
Python 3.10.x | PATH 未包含 Python 安装目录 |
| Git | git --version |
git version 2.x | 未安装或 PATH 错误 |
| Docker Desktop | docker run hello-world |
Hello from Docker! | Docker Daemon 未启动 |
| kubectl | kubectl get nodes |
Ready 状态节点 | K8s 未启用或 kubeconfig 配置错误 |
| Helm | helm version |
v3.x | 二进制未下载或版本过旧 |
3.4 环境就绪状态图
以下 SVG 图展示安装验证通过后的完整环境状态：所有工具均已就绪，并指向同一个本地 Kubernetes 集群。
3.5 常见问题与快速修复
- Python 版本冲突：系统同时存在 Python 2 和 Python 3 时，使用
python3而非python；或通过pyenv global 3.10.12设置默认版本。 - Docker Desktop 无法启动：检查 BIOS 中是否启用虚拟化（Intel VT-x / AMD-V），Windows 用户需确保 WSL 2 已正确安装。
- kubectl 连接超时：执行
kubectl config view检查当前上下文；若为空，运行kubectl config use-context docker-desktop。 - Helm 仓库添加失败：检查网络代理设置，或使用
helm repo add bitnami https://charts.bitnami.com/bitnami作为替代仓库。