RedBeret/air-gap-deploy-kit
GitHub: RedBeret/air-gap-deploy-kit
一个将 Docker 镜像和 Python wheel 打包并在无网络环境中离线部署的 DevOps 工具包。
Stars: 0 | Forks: 0
# air-gap-deploy-kit
[](https://github.com/RedBeret/air-gap-deploy-kit/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
**用于 acme-parts-cloud 技术栈的离线部署工具包。**
`air-gap-deploy-kit` 将指定的 Docker 镜像和 Python wheel 打包为一个
便携且带有校验和的目录，以便在没有互联网访问的网络上进行部署。它
亲自试用了完整的 acme-parts-cloud 技术栈：
| 组件 | 在此工具包中的角色 |
|-----------|-----------------|
| [`acme-parts-cloud`](https://github.com/RedBeret/acme-parts-cloud) | 打包并验证的 Docker 镜像 |
| [`fde-data-forge`](https://github.com/RedBeret/fde-data-forge) | 打包并验证 CLI 的 Python wheel |
| [`rag-eval-bench`](https://github.com/RedBeret/rag-eval-bench) | 打包并验证 CLI 的 Python wheel |
docker/ · wheels/
manifest · verifier · guide] end B -->|USB · internal transfer| C subgraph AirGap["Air-gapped target"] C[kit-bundle/] --> D[kit deploy] D --> E[kit verify] end E --> F{All checks pass?} F -- Yes --> G[Stack ready] F -- No --> H[Review report] ``` ## 快速开始 ``` # 在有网络连接的机器上安装 git clone https://github.com/RedBeret/air-gap-deploy-kit.git cd air-gap-deploy-kit python -m venv .venv && source .venv/bin/activate pip install -e . # (Windows) 运行 run.bat 来设置 venv # Clone 这个 portfolio stack 使用的两个同级项目 git clone https://github.com/RedBeret/fde-data-forge.git ../fde-data-forge git clone https://github.com/RedBeret/rag-eval-bench.git ../rag-eval-bench git clone https://github.com/RedBeret/acme-parts-cloud.git ../acme-parts-cloud docker build -t acme-parts-cloud:v1.0.0 ../acme-parts-cloud docker pull postgres:16-alpine # 1. 将本地项目和 dependencies 构建为真实的 wheelhouse python -m pip wheel --wheel-dir ./wheelhouse \ . ../fde-data-forge ../rag-eval-bench # 2. 打包明确的本地 artifacts（不假定有未发布的 PyPI 名称） kit bundle --output-dir ./kit-bundle \ --wheel-source ./wheelhouse \ --images acme-parts-cloud:v1.0.0 \ --images postgres:16-alpine \ --compose-file docker-compose.yml # 在没有 image pull 和没有 container 网络的情况下验证 wheel 安装 kit rehearse --bundle-dir ./kit-bundle # 3. 将 kit-bundle/ 传输到 air-gapped 机器 # 4. 从 bundle Bootstrap kit，然后进行部署 python -m pip install --no-index --find-links ./kit-bundle/wheels air-gap-deploy-kit kit deploy --bundle-dir ./kit-bundle # 5. 启动 acme-parts-cloud（Docker Compose 或手动 docker run） # docker load 已由 kit deploy 完成 — 正常启动： # docker compose up -d # 6. 验证 stack kit verify # 7. 可选：保存 JSON 报告 kit verify --report ./deploy-report.json ``` ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `kit bundle` | 将指定的镜像和 wheel 收集到 bundle 目录中 | | `kit deploy` | 从 bundle 安装（无需互联网） | | `kit rehearse` | 在网络隔离的一次性容器中安装 wheel | | `kit verify` | 对每个技术栈组件进行冒烟测试 | | `kit manifest` | 显示现有 bundle 的清单 | | `kit manifest --check` | 重新计算校验和并检测传输损坏 | ### bundle 参数 ``` --output-dir DIR Bundle output directory (default: ./kit-bundle) --images TEXT Docker images to bundle (repeatable) --packages TEXT Python packages to bundle (repeatable) --wheel-source PATH Prebuilt wheel or wheelhouse directory (repeatable) --compose-file PATH Compose file to include and checksum --skip-docker Skip Docker image bundling --skip-wheels Skip Python wheel collection ``` Ollama 模型导出已禁用：没有 Ollama 清单的 blob 无法恢复为 可用的模型。`--models` 会明确报错，而不是创建损坏的 bundle。 ### deploy 参数 ``` --bundle-dir DIR Path to bundle directory (default: ./kit-bundle) --skip-docker Skip docker load step --skip-wheels Skip pip install step --report PATH Save JSON report ``` ### rehearse 参数 ``` --bundle-dir DIR Bundle to verify and rehearse --image TEXT Preloaded Python image (default: python:3.12-slim) --smoke TEXT Post-install command (repeatable) --load-docker Explicitly load Docker tars into the host and verify image IDs ``` `rehearse` 使用 `docker run --pull=never --network none`；镜像必须已经在 本地存在。任何完整性或 wheel 安装失败都会在执行冒烟命令或加载宿主机镜像 之前停止。除非明确提供 `--load-docker`，否则将跳过 Docker tar 加载。 ### verify 参数 ``` --acme-url URL acme-parts-cloud base URL (default: http://localhost:8000) --ollama-url URL Ollama base URL (default: http://localhost:11434) --ollama-model TEXT Optional model check (default: gemma3:4b) --report PATH Save JSON report ``` ## Bundle 结构 ``` kit-bundle/ manifest.json — digest, checksum, and metadata index VERIFY_BUNDLE.py — dependency-free check run before installation INSTALL_OFFLINE.md — component-aware field guide docker/ redberet_acme-parts-cloud_latest.tar postgres_16-alpine.tar wheels/ fde_data_forge-1.1.0-py3-none-any.whl rag_eval_bench-1.1.0-py3-none-any.whl air_gap_deploy_kit-1.1.0-py3-none-any.whl ...dependencies... docker-compose.yml — only when supplied with --compose-file ``` 有关完整的清单示例，请参见 `samples/bundle_manifest_sample.json`。 bundle 中的每个常规文件都记录在 `manifest.json` 的 `file_checksums` 下。传输完成后，运行 `kit manifest --check --bundle-dir ./kit-bundle`，以便在部署之前捕获缺失、更改、意外或损坏的文件。这些未签名的 校验和无法对 bundle 进行身份验证；当涉及恶意替换时，请通过单独的 可信通道比较其清单摘要。 ## 案例研究：部署到隔离的实验室网络 **在构建机器上（有互联网访问）：** ``` # 构建或 pull 所有需要的内容 docker build -t acme-parts-cloud:v1.0.0 ../acme-parts-cloud docker pull postgres:16-alpine python -m pip wheel --wheel-dir ./wheelhouse \ . ../fde-data-forge ../rag-eval-bench # Bundle kit bundle --output-dir ./kit-bundle \ --wheel-source ./wheelhouse \ --images acme-parts-cloud:v1.0.0 \ --images postgres:16-alpine \ --compose-file docker-compose.yml ``` **传输到实验室（USB 驱动器）：** ``` cp -r ./kit-bundle /media/usb/ # 携带驱动器到实验室机器 ``` **在实验室机器上（无互联网）：** ``` python -m pip install --no-index --find-links /media/usb/kit-bundle/wheels \ air-gap-deploy-kit kit deploy --bundle-dir /media/usb/kit-bundle # → docker load：已加载 2 个 images # → pip install --no-index：已安装 12 个 wheels docker compose up -d # start acme-parts-cloud + postgres kit verify # acme-parts-cloud ✓ GET /admin/healthz → 200 ok # fde-data-forge ✓ fde --help exit 0 # rag-eval-bench ✓ rag-eval --help exit 0 # ollama ⚠ 可选服务不可用；model export 已禁用 ``` 一旦 Docker Compose 启动，整个离线安装只需一次 `kit deploy` 和一次 `kit verify`，任何步骤都不需要网络调用。最后一部分才是关键：在您携带驱动器前往现场*之前*，在关闭网络的情况下排练安装。 ## 验证输出示例 ``` Stack Verification Component Status Detail acme-parts-cloud ✓ OK GET /admin/healthz → 200 ok fde-data-forge ✓ OK fde --help exit 0: Usage: fde [OPTIONS]... rag-eval-bench ✓ OK rag-eval --help exit 0: Usage: rag-eval [OPTIONS]... ollama ✗ FAIL Ollama unavailable or requested model not found 3/4 checks passed. ⚠ Ollama check failed — generation scoring unavailable. ``` ## 项目布局 ``` kit/ bundle/ — docker and wheel bundlers + manifest I/O deploy/ — offline installer + stack verifier rehearse/ — fail-closed, network-isolated install rehearsal report/ — rich terminal tables + JSON report builder cli.py — click entry point tests/ test_manifest.py — 8 tests test_bundle.py — 5 tests test_verifier.py — 9 tests test_rehearse.py — injected-runner offline and fail-closed behavior test_rehearse_docker.py — live test only when the image is already present samples/ bundle_manifest_sample.json ``` ## 相关项目 - [`acme-parts-cloud`](https://github.com/RedBeret/acme-parts-cloud) — 合成零件目录 API - [`fde-data-forge`](https://github.com/RedBeret/fde-data-forge) — 缺陷检测与规范化 CLI - [`rag-eval-bench`](https://github.com/RedBeret/rag-eval-bench) — RAG 评估测试套件 ## 许可证 MIT © 2026 Steven Espinoza。请参阅 [LICENSE](LICENSE)。
docker/ · wheels/
manifest · verifier · guide] end B -->|USB · internal transfer| C subgraph AirGap["Air-gapped target"] C[kit-bundle/] --> D[kit deploy] D --> E[kit verify] end E --> F{All checks pass?} F -- Yes --> G[Stack ready] F -- No --> H[Review report] ``` ## 快速开始 ``` # 在有网络连接的机器上安装 git clone https://github.com/RedBeret/air-gap-deploy-kit.git cd air-gap-deploy-kit python -m venv .venv && source .venv/bin/activate pip install -e . # (Windows) 运行 run.bat 来设置 venv # Clone 这个 portfolio stack 使用的两个同级项目 git clone https://github.com/RedBeret/fde-data-forge.git ../fde-data-forge git clone https://github.com/RedBeret/rag-eval-bench.git ../rag-eval-bench git clone https://github.com/RedBeret/acme-parts-cloud.git ../acme-parts-cloud docker build -t acme-parts-cloud:v1.0.0 ../acme-parts-cloud docker pull postgres:16-alpine # 1. 将本地项目和 dependencies 构建为真实的 wheelhouse python -m pip wheel --wheel-dir ./wheelhouse \ . ../fde-data-forge ../rag-eval-bench # 2. 打包明确的本地 artifacts（不假定有未发布的 PyPI 名称） kit bundle --output-dir ./kit-bundle \ --wheel-source ./wheelhouse \ --images acme-parts-cloud:v1.0.0 \ --images postgres:16-alpine \ --compose-file docker-compose.yml # 在没有 image pull 和没有 container 网络的情况下验证 wheel 安装 kit rehearse --bundle-dir ./kit-bundle # 3. 将 kit-bundle/ 传输到 air-gapped 机器 # 4. 从 bundle Bootstrap kit，然后进行部署 python -m pip install --no-index --find-links ./kit-bundle/wheels air-gap-deploy-kit kit deploy --bundle-dir ./kit-bundle # 5. 启动 acme-parts-cloud（Docker Compose 或手动 docker run） # docker load 已由 kit deploy 完成 — 正常启动： # docker compose up -d # 6. 验证 stack kit verify # 7. 可选：保存 JSON 报告 kit verify --report ./deploy-report.json ``` ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `kit bundle` | 将指定的镜像和 wheel 收集到 bundle 目录中 | | `kit deploy` | 从 bundle 安装（无需互联网） | | `kit rehearse` | 在网络隔离的一次性容器中安装 wheel | | `kit verify` | 对每个技术栈组件进行冒烟测试 | | `kit manifest` | 显示现有 bundle 的清单 | | `kit manifest --check` | 重新计算校验和并检测传输损坏 | ### bundle 参数 ``` --output-dir DIR Bundle output directory (default: ./kit-bundle) --images TEXT Docker images to bundle (repeatable) --packages TEXT Python packages to bundle (repeatable) --wheel-source PATH Prebuilt wheel or wheelhouse directory (repeatable) --compose-file PATH Compose file to include and checksum --skip-docker Skip Docker image bundling --skip-wheels Skip Python wheel collection ``` Ollama 模型导出已禁用：没有 Ollama 清单的 blob 无法恢复为 可用的模型。`--models` 会明确报错，而不是创建损坏的 bundle。 ### deploy 参数 ``` --bundle-dir DIR Path to bundle directory (default: ./kit-bundle) --skip-docker Skip docker load step --skip-wheels Skip pip install step --report PATH Save JSON report ``` ### rehearse 参数 ``` --bundle-dir DIR Bundle to verify and rehearse --image TEXT Preloaded Python image (default: python:3.12-slim) --smoke TEXT Post-install command (repeatable) --load-docker Explicitly load Docker tars into the host and verify image IDs ``` `rehearse` 使用 `docker run --pull=never --network none`；镜像必须已经在 本地存在。任何完整性或 wheel 安装失败都会在执行冒烟命令或加载宿主机镜像 之前停止。除非明确提供 `--load-docker`，否则将跳过 Docker tar 加载。 ### verify 参数 ``` --acme-url URL acme-parts-cloud base URL (default: http://localhost:8000) --ollama-url URL Ollama base URL (default: http://localhost:11434) --ollama-model TEXT Optional model check (default: gemma3:4b) --report PATH Save JSON report ``` ## Bundle 结构 ``` kit-bundle/ manifest.json — digest, checksum, and metadata index VERIFY_BUNDLE.py — dependency-free check run before installation INSTALL_OFFLINE.md — component-aware field guide docker/ redberet_acme-parts-cloud_latest.tar postgres_16-alpine.tar wheels/ fde_data_forge-1.1.0-py3-none-any.whl rag_eval_bench-1.1.0-py3-none-any.whl air_gap_deploy_kit-1.1.0-py3-none-any.whl ...dependencies... docker-compose.yml — only when supplied with --compose-file ``` 有关完整的清单示例，请参见 `samples/bundle_manifest_sample.json`。 bundle 中的每个常规文件都记录在 `manifest.json` 的 `file_checksums` 下。传输完成后，运行 `kit manifest --check --bundle-dir ./kit-bundle`，以便在部署之前捕获缺失、更改、意外或损坏的文件。这些未签名的 校验和无法对 bundle 进行身份验证；当涉及恶意替换时，请通过单独的 可信通道比较其清单摘要。 ## 案例研究：部署到隔离的实验室网络 **在构建机器上（有互联网访问）：** ``` # 构建或 pull 所有需要的内容 docker build -t acme-parts-cloud:v1.0.0 ../acme-parts-cloud docker pull postgres:16-alpine python -m pip wheel --wheel-dir ./wheelhouse \ . ../fde-data-forge ../rag-eval-bench # Bundle kit bundle --output-dir ./kit-bundle \ --wheel-source ./wheelhouse \ --images acme-parts-cloud:v1.0.0 \ --images postgres:16-alpine \ --compose-file docker-compose.yml ``` **传输到实验室（USB 驱动器）：** ``` cp -r ./kit-bundle /media/usb/ # 携带驱动器到实验室机器 ``` **在实验室机器上（无互联网）：** ``` python -m pip install --no-index --find-links /media/usb/kit-bundle/wheels \ air-gap-deploy-kit kit deploy --bundle-dir /media/usb/kit-bundle # → docker load：已加载 2 个 images # → pip install --no-index：已安装 12 个 wheels docker compose up -d # start acme-parts-cloud + postgres kit verify # acme-parts-cloud ✓ GET /admin/healthz → 200 ok # fde-data-forge ✓ fde --help exit 0 # rag-eval-bench ✓ rag-eval --help exit 0 # ollama ⚠ 可选服务不可用；model export 已禁用 ``` 一旦 Docker Compose 启动，整个离线安装只需一次 `kit deploy` 和一次 `kit verify`，任何步骤都不需要网络调用。最后一部分才是关键：在您携带驱动器前往现场*之前*，在关闭网络的情况下排练安装。 ## 验证输出示例 ``` Stack Verification Component Status Detail acme-parts-cloud ✓ OK GET /admin/healthz → 200 ok fde-data-forge ✓ OK fde --help exit 0: Usage: fde [OPTIONS]... rag-eval-bench ✓ OK rag-eval --help exit 0: Usage: rag-eval [OPTIONS]... ollama ✗ FAIL Ollama unavailable or requested model not found 3/4 checks passed. ⚠ Ollama check failed — generation scoring unavailable. ``` ## 项目布局 ``` kit/ bundle/ — docker and wheel bundlers + manifest I/O deploy/ — offline installer + stack verifier rehearse/ — fail-closed, network-isolated install rehearsal report/ — rich terminal tables + JSON report builder cli.py — click entry point tests/ test_manifest.py — 8 tests test_bundle.py — 5 tests test_verifier.py — 9 tests test_rehearse.py — injected-runner offline and fail-closed behavior test_rehearse_docker.py — live test only when the image is already present samples/ bundle_manifest_sample.json ``` ## 相关项目 - [`acme-parts-cloud`](https://github.com/RedBeret/acme-parts-cloud) — 合成零件目录 API - [`fde-data-forge`](https://github.com/RedBeret/fde-data-forge) — 缺陷检测与规范化 CLI - [`rag-eval-bench`](https://github.com/RedBeret/rag-eval-bench) — RAG 评估测试套件 ## 许可证 MIT © 2026 Steven Espinoza。请参阅 [LICENSE](LICENSE)。
标签：Docker, Python, 内网部署, 大模型, 安全防御评估, 无后门, 版权保护, 特权提升, 离线部署, 自动化部署, 请求拦截, 运维工具, 逆向工具