4. 环境准备与基础搭建：开发环境配置、依赖安装、版本控制仓库初始化

本章聚焦于搭建一套可复现的本地开发与实验环境，为后续变更冻结闸口逻辑开发、Runbook 脚本编写以及 CI/CD 流水线集成奠定基础。我们将依次完成：开发工具链安装、核心依赖管理、Python 虚拟环境配置、以及 Git 仓库的标准化初始化。

4.1 开发环境配置清单

以下表格列出了本课程实验环境所需的软件及其推荐版本。请确保所有工具已正确安装并加入系统 PATH。

4.2 依赖安装与虚拟环境配置

为避免项目依赖与系统全局 Python 包冲突，我们强制使用虚拟环境。以下是标准操作步骤：

1. 创建项目目录：mkdir -p ~/projects/freeze-gate-runbook && cd ~/projects/freeze-gate-runbook
2. 初始化虚拟环境：python3 -m venv .venv
3. 激活虚拟环境：
   • Linux/macOS：source .venv/bin/activate
   • Windows (WSL)：source .venv/bin/activate
4. 升级 pip 与基础工具：pip install --upgrade pip setuptools wheel
5. 安装核心依赖：创建 requirements.txt 文件，写入以下内容：

# 核心依赖
pyyaml==6.0.1
requests==2.31.0
click==8.1.7
jinja2==3.1.2
pydantic==2.5.0

# 测试与质量
pytest==7.4.3
pytest-cov==4.1.0
flake8==6.1.0
black==23.12.0

# 可选：Runbook 执行与通知
paramiko==3.4.0
slack-sdk==3.27.0

6. 执行安装：pip install -r requirements.txt

4.3 版本控制仓库初始化

一个结构清晰的 Git 仓库是团队协作与自动化闸口的基础。我们采用标准的分支策略与目录布局。

4.3.1 仓库目录结构

在项目根目录下创建以下目录与文件：

freeze-gate-runbook/
├── .gitignore
├── README.md
├── Makefile
├── requirements.txt
├── .venv/                  # 虚拟环境（不提交）
├── config/                 # 闸口配置与策略文件
│   ├── freeze_policy.yaml
│   └── runbook_definitions.yaml
├── src/                    # 核心源码
│   ├── gate_engine/        # 变更冻结闸口引擎
│   ├── runbook_executor/   # Runbook 执行器
│   └── utils/              # 通用工具函数
├── tests/                  # 单元测试与集成测试
│   ├── test_gate_engine/
│   └── test_runbook_executor/
├── docs/                   # 文档与架构图
└── scripts/                # 辅助脚本（部署、数据迁移等）

4.3.2 Git 初始化与首次提交

1. 初始化仓库：git init
2. 创建 .gitignore 文件，排除虚拟环境与临时文件：

# Python
__pycache__/
*.py[cod]
*.egg-info/
.venv/
venv/
env/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# 日志与临时文件
*.log
*.tmp

3. 创建 README.md，简要描述项目目标与快速开始指南。
4. 暂存并提交：

git add .
git commit -m "chore: 初始化项目结构与基础依赖"

4.4 环境验证与架构总览

完成上述步骤后，我们通过一张架构图来理解各组件之间的关系，并执行快速验证脚本确保环境就绪。

4.5 快速验证脚本

执行以下命令，确认环境配置无误：

# 1. 确认 Python 版本
python3 --version

# 2. 确认虚拟环境已激活（应显示 .venv）
which python

# 3. 确认核心依赖已安装
pip list | grep -E "pyyaml|requests|click|pydantic"

# 4. 确认 Git 仓库状态
git status

# 5. 运行测试框架验证（确保无报错）
python -m pytest --version