Ascend Deployer 开发容器说明

1. 背景

当前仓库需要一个一致的开发环境。没有 Dev Container 配置时，开发者需要在本机手动安装 Python、Ansible、pytest、pre-commit、YAML 工具和系统依赖。不同开发机之间容易出现依赖版本不一致、环境变量不同、工具缺失等问题。

本配置用于为 Ascend Deployer 提供基于 Docker 的 VS Code Dev Containers 开发环境，方便开发者快速进入一致的 Linux 开发环境。

2. 预期效果

完成配置后，开发者可以：

• 通过 VS Code 的 Dev Containers: Rebuild and Reopen in Container 一键构建并进入开发容器。
• 使用基于 Ubuntu 22.04 的 Linux 开发环境。
• 在容器内使用 Python、pip、Ansible、pytest、pre-commit 和 YAML 工具。
• 通过 PYTHONPATH 直接加载项目源码，不需要执行 pip install -e .。
• 在容器内完成基础环境检查和单元测试。

3. 部署策略

开发环境采用 Docker Desktop + VS Code Dev Containers：

• Docker Desktop 提供 Linux 容器运行环境。
• .devcontainer/Dockerfile 用于构建基础开发镜像并安装系统工具。
• .devcontainer/devcontainer.json 用于定义 VS Code 如何构建、挂载并进入容器。
• .devcontainer/postCreateCommand.sh 用于在容器创建后安装 Python 开发依赖。
• .devcontainer/requirements-dev.txt 作为 Python 开发依赖入口。

源码目录会挂载到容器工作区中，因此在 VS Code 中修改的文件会直接写回本地仓库。

4. 前置条件

Windows 开发机需要提前安装：

• WSL2
• Docker Desktop
• Visual Studio Code
• VS Code 插件：Dev Containers

启动 Docker Desktop，并等待其显示 Engine running。

在 PowerShell 中检查 Docker：

docker version
docker ps

docker version 应能看到 Docker Server 信息，docker ps 应能输出容器列表表头。

5. 打开项目

在 PowerShell 中执行：

cd F:\ascend\ascend-deployer
code .

6. 构建并进入开发容器

在 VS Code 中按 Ctrl + Shift + P，然后执行：

Dev Containers: Rebuild and Reopen in Container

首次构建会下载基础镜像、安装系统依赖、安装 Python 开发依赖，并在容器中启动 VS Code Server。

容器启动完成后，VS Code 状态栏应显示类似：

开发容器: ascend-deployer-dev @ desktop-linux

7. 打开容器终端

在 VS Code 中选择：

终端 -> 新建终端

或使用快捷键：

Ctrl + Shift + `

检查当前工作目录：

pwd

预期输出：

/workspaces/ascend-deployer

8. 验证开发环境

在容器终端执行：

python3 --version
python3 -m pip --version
ansible --version
python3 -m pytest --version

验证项目入口：

python3 ascend_deployer/start_deploy.py --help
python3 ascend_deployer/ascend_download.py --help

如果能正常打印帮助信息，说明容器可以加载项目源码。

9. 运行基础测试

执行：

python3 -m pytest test/test_utils.py -v

也可以继续运行更多测试：

python3 -m pytest test/downloader -v
python3 -m pytest test/module_utils_test -v

当前已验证结果：

9 passed

10. 日常启动方式

首次构建成功后，日常启动流程如下：

• 启动 Docker Desktop。
• 等待 Docker Desktop 显示 Engine running。
• 打开项目：

cd F:\ascend\ascend-deployer
code .

• 在 VS Code 中执行：

Dev Containers: Reopen in Container

只有修改 .devcontainer/Dockerfile、.devcontainer/devcontainer.json 或依赖安装逻辑后，才需要执行：

Dev Containers: Rebuild and Reopen in Container

11. Dockerfile 配置说明

.devcontainer/Dockerfile 用于构建基础开发镜像。

主要配置包括：

• 基础镜像：ubuntu:22.04
• 环境变量：LANG、LC_ALL、PYTHONUNBUFFERED、PIP_DISABLE_PIP_VERSION_CHECK
• 构建参数：APT_MIRROR、PIP_INDEX_URL
• 系统依赖：python3、python3-pip、python3-venv、git、openssh-client、sshpass、curl、wget、jq 等常用工具
• pip 基础工具：pip、setuptools、wheel
• 非 root 用户：developer
• 工作目录：/workspaces/ascend-deployer

Python 开发工具通过 postCreateCommand.sh 使用 .devcontainer/requirements-dev.txt 安装，不直接写入 Dockerfile。这样可以保持镜像层相对稳定，也方便后续调整开发依赖。

12. devcontainer.json 配置说明

.devcontainer/devcontainer.json 用于定义 VS Code 如何使用开发容器。

主要配置包括：

• 容器名称：ascend-deployer-dev
• Dockerfile：.devcontainer/Dockerfile
• 构建上下文：仓库根目录
• 工作目录：/workspaces/${localWorkspaceFolderBasename}
• 远程用户：developer
• 创建后命令：bash .devcontainer/postCreateCommand.sh

挂载的缓存卷包括：

• pip 缓存：/home/developer/.cache/pip
• Ansible 缓存：/home/developer/.ansible
• Ascend Deployer 本地数据：/home/developer/.ascend_deployer

环境变量包括：

• ASCEND_DEPLOYER_HOME=${containerWorkspaceFolder}
• PYTHONPATH=${containerWorkspaceFolder}

推荐安装的 VS Code 插件包括：

• ms-python.python
• ms-python.pytest
• ms-python.vscode-pylance
• redhat.ansible
• redhat.vscode-yaml

13. postCreateCommand.sh 配置说明

.devcontainer/postCreateCommand.sh 会在容器创建完成后执行。

主要步骤包括：

1. 进入项目目录。
2. 将 /home/developer/.local/bin 加入 PATH。
3. 准备本地缓存目录。
4. 安装 .devcontainer/requirements-dev.txt。
5. 安装 pre-commit 钩子。
6. 打印 Python、pip、Ansible 和 pytest 版本。

14. 开发依赖说明

.devcontainer/requirements-dev.txt 是开发依赖入口：

-r ../test/requirements.txt

ansible-core==2.13.0
pre-commit==4.0.1
yamllint==1.35.1

其中 test/requirements.txt 继续管理测试依赖，.devcontainer/requirements-dev.txt 在测试依赖基础上补充开发容器需要的 Ansible 和代码检查工具。