上游仓库忽然 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 上某个版本被删除或 yank | pip 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 里每多一行手工复制粘贴的命令,就是一次凌晨三点的手抖机会。
最后一句:依赖不是“装上了就完事”,它是一份需要定期更新的关系。演练的意义不在于证明你准备得多好,而在于提前知道哪里会断。
