跳到主内容
快讯直播
AI智模界
教程

依赖蒸发演练:私有镜像、vendoring 与 SBOM

上游仓库忽然 404、网页打不开、pip install git+https://github.com/... 直接报错,这种事在开源生态里并非假设。ONNX Runtime 的 GitHub 仓库曾出现短时间无法访问的情况,社区里立刻有人发现:CI 流水线失败、Dockerfile 里的 ADD 失败、镜像重建失败。不管是误操作、临时故障还是别的原因,机制是一样的:你的构建链路上有一根线,另一头攥在别人手里。

这篇教程做一件事:把那条线接回自己手里,并且验证它真的接上了。

这篇能做出什么

完整跟做一遍,你会得到七样可直接使用的东西:

1. 一张依赖地图:列出服务里所有“外部来源”,区分 PyPI 包、Git 仓库、二进制、模型权重。

2. 一个私有包源:断外网也能 pip install 的内网地址。

3. 一份离线归档:wheel、sdist、Git bundle、容器镜像 tar、模型文件,全部落在自己的存储上,带校验和。

4. 一份 SBOM:CycloneDX 或 SPDX 格式的组件清单,能回答“这个服务里到底有哪 187 个包、什么版本、什么许可证”。

5. 一份锁定文件:带 hash 的依赖锁,装错版本会直接失败而不是静默降级。

6. 一个 restore.sh:一条命令从零恢复到可用状态。

7. 一份演练记录:从“拔网线”到“服务起来”用了多少分钟,哪一步需要人工介入。

最后一项其实是重点。供应链韧性的度量单位不是“有没有备份”,而是“恢复要多久、要几个人”。

前置条件清单

动手前确认这些就位:

  • 一台 Linux 机器(x86_64 或 arm64 都行),装好 Docker 或 Podman。
  • Python 3.10 以上环境,能正常 pip install。具体版本以官方文档当前版本为准。
  • 一块共享存储:NFS、S3/MinIO、对象存储都行,用来放离线归档。建议预留 20–50 GB。
  • 服务当前的依赖清单:requirements.txt、poetry.lock、Dockerfile,至少要有一份能装起来的。
  • 一台可以“主动断网”的测试机,或者能改 /etc/hosts、能封出站流量的权限。
  • 工具:pip、git、jq、sha256sum,以及后面按官方文档安装的 syft 和 pip-audit。
  • 时间窗口 2–4 小时。第一次做会慢,第二次开始 30 分钟内能跑完。

以下命令里的域名、路径、镜像名都是占位,照着换成你自己的即可。

步骤一:先定义“蒸发”,列出你要演练的断点

不要一上来就搭基础设施。先写清楚:哪些外部资源消失时,你会疼。

断点蒸发时的表现影响面
GitHub 仓库不可访问pip install git+https://... 失败、git submodule 拉不下来构建直接失败
PyPI 上某个版本被删除或 yankpip install pkg==x.y.z 找不到重建镜像失败
容器 registry 不可达docker pull 超时部署失败
模型权重下载地址失效推理服务起不来线上不可用
文档/配置示例被删排障变慢隐性成本

把这张表存成 docs/dependency-breaks.md,后面演练对照着打勾。

扫描一下现有仓库里有多少“对外引用”:

```bash

grep -rnE "git\+|https?://|ADD |curl |wget " \

Dockerfile* requirements*.txt pyproject.toml .github/ 2>/dev/null \

| grep -v "127.0.0.1" > external-refs.txt

wc -l external-refs.txt

```

external-refs.txt 里每一行都是一个候选断点。第一次看到这个数字通常会被吓一跳,这是好事。

步骤二:盘点依赖,生成锁文件

```bash

python -m venv .venv && source .venv/bin/activate

pip install -r requirements.txt

pip install pipdeptree

pipdeptree --json-tree > deps-tree.json

pip freeze > deps-before.txt

```

pip freeze 只给出扁平列表,pipdeptree 的树能告诉你“是谁把 onnxruntime 拉进来的”。如果某个包是被某个上层库间接引入的,你得知道该替换谁。

生成带 hash 的锁文件。不同工具做法不同,用 pip + requirements 的话:

```bash

pip download -r requirements.txt -d /tmp/wheels-all

pip hash /tmp/wheels-all/* > hashes.txt

```

更省事的做法是用 pip-tools 或 uv 生成 requirements.lock,让每条依赖都带 --hash。以各自官方文档为准。

步骤三:搭一个私有包源

私有源有两个层次,建议都做:

A. 静态文件仓库(离线友好)

```bash

mkdir -p /srv/pypi/wheels /srv/pypi/simple

pip download -r requirements.txt -d /srv/pypi/wheels \

--only-binary=:all: \

--platform manylinux2014_x86_64 \

--python-version 3.11 \

--implementation cp

```

注意:--platform 必须和 --only-binary=:all: 一起用。纯 Python 包和源码包要单独下一次,去掉这两个参数即可。

装的时候直接指向本地目录:

```bash

pip install --no-index --find-links=/srv/pypi/wheels -r requirements.txt

```

B. 内网 HTTP 源(团队共享)

用 nginx 把目录暴露出去:

```nginx

server {

listen 443 ssl;

server_name pypi.internal.example.com;

root /srv/pypi;

location /simple/ {

autoindex on;

}

location /wheels/ {

autoindex on;

}

}

```

客户端配置 ~/.pip/pip.conf:

```ini

[global]

index-url = https://pypi.internal.example.com/simple

trusted-host = pypi.internal.example.com

timeout = 30

```

要生成符合 pip simple API 的 HTML 索引,可以用 dumb-pypi、pip2pi 这类工具,或直接用 devpi、Nexus、Harbor 的 pypi 仓库功能,按各自官方文档配置。不想上服务的话,--find-links 那一套已经够用。

步骤四:做 vendoring 归档

私有源解决了 Python 包,还有三类东西要归档。

Git 依赖

```bash

mkdir -p /srv/vendor/git

git clone --mirror https://github.com/your-org/your-lib.git /srv/vendor/git/your-lib.git

git bundle create /srv/vendor/git/your-lib.bundle --all

```

bundle 是单文件,好传输、好校验。恢复时 git clone /srv/vendor/git/your-lib.bundle ./your-lib 即可。

容器镜像

```bash

docker pull your-registry/your-service:1.0

docker save -o /srv/vendor/images/your-service-1.0.tar your-registry/your-service:1.0

```

多架构镜像用 skopeo 更省心:

```bash

skopeo copy --all \

docker://your-registry/your-service:1.0 \

docker-archive:/srv/vendor/images/your-service-1.0.tar

```

--all 会把所有架构一起打包,避免在 arm 机器上恢复 x86 镜像时才发现不对。

模型权重与二进制

```bash

mkdir -p /srv/vendor/models

curl -fL -o /srv/vendor/models/model.onnx "https://example.com/path/model.onnx"

```

下载完立刻算校验和,并把校验和单独存一份:

```bash

cd /srv/vendor

find . -type f \( -name "*.whl" -o -name "*.tar.gz" -o -name "*.onnx" -o -name "*.bundle" \) \

-exec sha256sum {} \; > SHA256SUMS

wc -l SHA256SUMS

```

恢复时 sha256sum -c SHA256SUMS 一条命令就能验证全部文件没被截断或篡改。

最后建一份人可读的清单:

```bash

cat > /srv/vendor/manifest.tsv <<'EOF'

类型 路径 来源 用途

wheel wheels/onnxruntime-*.whl PyPI 推理运行时

git git/your-lib.bundle github.com/your-org/your-lib 内部库

image images/your-service-1.0.tar your-registry 应用镜像

model models/model.onnx example.com 推理权重

EOF

```

步骤五:生成 SBOM 并锁定

SBOM 的价值不是“合规交差”,而是让你在别人喊“某某包出事了”的时候,五分钟内回答“我们用没用、用的哪个版本”。

扫目录:

```bash

syft dir:. -o cyclonedx-json=sbom.cdx.json

syft dir:. -o spdx-json=sbom.spdx.json

```

扫镜像更准确,因为镜像里还包含系统包:

```bash

syft registry:your-registry/your-service:1.0 -o cyclonedx-json=service.cdx.json

```

加上漏洞信息(可选):

```bash

pip-audit -r requirements.lock --format cyclonedx-json > audit.cdx.json

```

pip-audit 的具体参数以官方文档为准。

查询某个组件:

```bash

jq -r '.components[] | select(.name|test("onnxruntime";"i")) | "\(.name) \(.version)"' sbom.cdx.json

```

把 SBOM 提交进仓库,并加一道门禁:SBOM 有新增组件时,PR 里必须有人 review。伪代码:

```bash

CI 里跑

syft dir:. -o cyclonedx-json=sbom.new.json

diff <(jq -S . sbom.cdx.json) <(jq -S . sbom.new.json) > sbom.diff || {

echo "SBOM 发生变化,请评审 sbom.diff"

cat sbom.diff

exit 1

}

```

步骤六:断网演练

这一步是整篇的核心。前面都是准备,这里才是验证。

方法一:改 hosts(最省事)

```bash

sudo cp /etc/hosts /etc/hosts.bak

sudo tee -a /etc/hosts > /dev/null <<'EOF'

127.0.0.1 github.com

127.0.0.1 pypi.org

127.0.0.1 files.pythonhosted.org

127.0.0.1 registry-1.docker.io

EOF

```

方法二:用隔离网络(更干净)

```bash

docker network create --internal offline-net

docker run --rm -it \

--network offline-net \

-v /srv/vendor:/vendor:ro \

python:3-slim bash

```

--internal 创建的桥接网络没有出站路由,容器里连 DNS 都出不去,比改 hosts 更接近真实故障。

方法三:防火墙规则

```bash

sudo iptables -I OUTPUT -m owner --uid-owner 1000 -d 0.0.0.0/0 -j DROP

```

恢复时 sudo iptables -D OUTPUT 1。生产环境慎用,容易把自己也锁在外面。

演练时记录三件事:

```bash

1. 开始时间

date +%s > /tmp/drill-start

2. 执行恢复

bash restore.sh

3. 结束时间与耗时

echo "$(( $(date +%s) - $(cat /tmp/drill-start) )) 秒" | tee /tmp/drill-rto.txt

```

失败点逐条记下来。常见的失败点是:某个包没被 pip download 覆盖到、镜像 tar 是单架构、bundle 里没有 submodule。

步骤七:写一键回滚脚本

restore.sh,放在仓库根目录:

```bash

#!/usr/bin/env bash

set -euo pipefail

VENDOR="${VENDOR:-/srv/vendor}"

WORKDIR="${WORKDIR:-./restore-out}"

echo "==> 校验归档完整性"

cd "$VENDOR"

sha256sum -c SHA256SUMS

echo "==> 恢复源码"

mkdir -p "$WORKDIR"

git clone "$VENDOR/git/your-lib.bundle" "$WORKDIR/your-lib" 2>/dev/null || true

echo "==> 恢复 Python 环境"

cd "$WORKDIR"

python -m venv .venv

shellcheck disable=SC1091

source .venv/bin/activate

pip install --no-index --find-links="$VENDOR/wheels" --require-hashes -r "$OLDPWD/requirements.lock"

echo "==> 恢复容器镜像"

docker load -i "$VENDOR/images/your-service-1.0.tar"

echo "==> 恢复模型"

cp "$VENDOR/models/model.onnx" "$WORKDIR/model.onnx"

echo "==> 冒烟测试"

curl -fsS http://127.0.0.1:8000/health || {

echo "健康检查失败,请查看日志"

exit 1

}

echo "==> 完成,耗时 $(echo "$SECONDS") 秒"

```

配一个对比脚本,确认恢复出来的组件和 SBOM 里记录的一致:

```bash

jq -r '.components[] | "\(.name)@\(.version)"' sbom.cdx.json | sort > /tmp/expected.txt

pip freeze | sort > /tmp/actual.txt

comm -23 /tmp/expected.txt /tmp/actual.txt

```

输出为空说明组件集合对得上。

常见坑与排错

--require-hashes 报某包缺 hash

这个参数要求锁文件里每一个包(包括传递依赖)都带 hash。如果你只给顶层包加了 hash,一定会失败。用 pip-tools、uv 或 pip hash 把整棵依赖树的 hash 都补上。

pip download 下下来的 wheel 装不上,platform tag 不匹配

在目标架构的容器里下载,而不是在开发机上:

```bash

docker run --rm -v "$PWD:/w" -w /w python:3-slim \

pip download -r requirements.txt -d wheels --only-binary=:all:

```

私有源 404,但文件明明在

pip 的 simple API 对包名做了归一化:Foo_Bar 会去找 foo-bar。如果你用 autoindex 直接暴露目录,路径大小写和下划线会对不上。用 pip2pi、dumb-pypi 生成规范索引,或者干脆只用 --find-links。

用了 trusted-host 之后警告不断

trusted-host 是关闭证书校验的临时手段。正式做法是把内网 CA 证书装进系统信任链,然后去掉这个配置。

docker save 出来的 tar 换台机器 load 失败

多半是多架构问题。x86 上 save 的镜像 load 到 arm 机器上跑不了。用 skopeo copy --all 归档全架构。

SBOM 里少了系统包

syft dir:. 只扫当前目录。要对镜像做扫描:syft registry:... 或 syft docker-archive:...tar。

git bundle 恢复后缺 submodule

bundle 不会包含 submodule 内容。每个 submodule 单独做一份 bundle,并在 manifest.tsv 里登记。

断网演练时 pip 还是装成功了

八成是 pip 缓存命中。用干净容器,或者 pip install --no-cache-dir。同理,Docker 本地层缓存也会让 docker pull 看起来成功。

演练时 TLS 报证书过期

测试机常年不动,系统时间和 CA 库都老了。演练前先 date 看一眼,apt update && apt install ca-certificates 更新一下。

下一步建议

把静态源升级成 pull-through 缓存。devpi、Nexus、Harbor 都支持代理上游并缓存,第一次拉取后即命中本地,比手工 pip download 省心。注意首次缓存仍然是单点,重要包还是要显式归档。

给制品加签名。SBOM 告诉你“有什么”,签名告诉你“是不是我构建的”。cosign、sigstore、in-toto 都能做到,把 SBOM 和镜像一起签。

把演练写进日历。每月一次,每次记录 RTO。连续三次 RTO 稳定在目标值以内,才算这条供应链真的可恢复。数字要写进团队文档,别只留在某个人脑子里。

扩大演练范围。这次只做了 Python 和镜像,下次加上数据库迁移脚本、证书、DNS 记录、API key 的轮换预案。真实故障很少只断一条线。

把手工步骤全部脚本化。restore.sh 里每多一行手工复制粘贴的命令,就是一次凌晨三点的手抖机会。

最后一句:依赖不是“装上了就完事”,它是一份需要定期更新的关系。演练的意义不在于证明你准备得多好,而在于提前知道哪里会断。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。