企业官网建设流程全解析

Bernstein 是一个开源的 AI Agents 治理与编排框架（Governance & Orchestration）：用声明式规则约束 AI 智能体行为，并产出可验证、可回放的审计记录，基于 Apache-2.0 协议免费使用。本指南面向完全无法访问互联网的 Air-gap 离线环境，教你 6 步完成签名 Wheelhouse 的构建、校验与完整安装——全程只需要一台联网构建机，目标主机零 PyPI 流量。

一、为什么需要 Air-gap 离线部署？

以下场景中，默认的联网安装路径走不通：

• 🔒 目标主机没有 PyPI 出口（受监管、主权客户或纯离线环境）
• 📋 合规要求对每一个依赖做密码学来源证明
• 🚫 出站流量必须默认拒绝（fail closed），除非运维显式放行
• 🔍 部署需要端到端可审计，不能依赖托管控制平面

Bernstein 的离线方案非常优雅：同一个 wheel，两种模式，变的只是出站策略。离线部署在标准安装之上只多三样东西：

二、准备构建机（唯一需要联网的机器）

构建机要求：

• 可访问 PyPI 的出网能力
• 已安装uv和 Python 3.12+
• 安装了cosign（v2.4.x / v2.6.x / v3.x 均支持，脚本会自动适配参数差异）

三、Step 1：构建签名 Wheelhouse

在构建机上执行（二选一）：

# 方式一：直接跑脚本 python scripts/build_airgap_wheelhouse.py --version 1.10.0 # 方式二：operator 友好的子命令 bernstein wheelhouse build --version 1.10.0

脚本会解析 Bernstein 的固定依赖闭包，下载全部 wheel，生成MANIFEST.json（含每个文件的 sha256 与大小），产物落在dist/airgap-wheelhouse/<version>/。

四、Step 2：用 cosign 对每个文件签名

COSIGN_KEY=/secure/path/cosign.key \ bash scripts/sign_airgap_wheelhouse.sh dist/airgap-wheelhouse/1.10.0

签名脚本的关键细节：

• 对每个 wheel 和 MANIFEST生成分离签名（<wheel>.sig），密钥绝不埋进包体
• 默认--tlog-upload=false，避免向公网 Rekor 日志发起连接
• 自动适配 cosign v3 的sign-blob默认值变化，保证跨版本可验签

最终目录结构如下：

dist/airgap-wheelhouse/1.10.0/ ├── bernstein-1.10.0-py3-none-any.whl ├── bernstein-1.10.0-py3-none-any.whl.sig ├── fastapi-0.115.x-py3-none-any.whl ├── fastapi-0.115.x-py3-none-any.whl.sig ├── ...（全部传递依赖及其签名） ├── MANIFEST.json └── MANIFEST.sig

五、Step 3：通过加密介质交付

将上述整个目录拷贝到加密介质（切勿漏掉.sig文件），并单独携带公钥（PEM 格式）供客户提前验证。

如果客户无法访问 attestation 端点，可让构建机预下载 Sigstore 构建来源证明：

gh attestation download \ ./airgap-wheelhouse/1.10.0/bernstein-1.10.0-py3-none-any.whl \ --owner sipyourdrink-ltd

每个 wheel 旁会多出一个<wheel>.sigstore伴生文件，随目录一起交付。

六、Step 4：安装前先验证（关键一步）

⚠️ 铁律：从未验证过的 wheelhouse，绝不直接pip install。

bernstein verify ./airgap-wheelhouse/1.10.0 \ --ca-pubkey ./bernstein-release.pub \ --require-signatures

• 任一 sha256 不匹配或签名失败 → 非零退出，并在错误信息中点名问题 wheel
• 偏好 GPG 的客户可切换验证后端：--verifier gpg --keyring ./customer.gpg
• 离线主机做 Sigstore 验证时追加--sigstore --sigstore-offline，利用随包交付的.sigstore文件

客户若不完全信任上游签名密钥，还能用自己的密钥二次重签整个 wheelhouse，再用--ca-pubkey ./customer.pub验证——分离签名方案让密钥永不进入交付物。

七、Step 5：pip --no-index 离线安装

验证通过后即可安装：

python -m venv .venv && source .venv/bin/activate pip install --no-index --find-links ./airgap-wheelhouse/1.10.0 bernstein bernstein --version

最容易踩的坑：漏写--no-index，pip 会偷偷回连 PyPI。请始终成对出现：--no-index --find-links <dir>。

八、Step 6：airgap 运行与自检

先跑离线姿态自检（首次运行前的 pre-flight）：

bernstein doctor airgap # 人类可读 bernstein doctor --json airgap # 机器可读，可作为合规证据

doctor airgap会检查 8 项内容：airgap profile 是否生效、网络策略是否为 deny-all、各 adapter 声明的端点是否全被拦截、MCP 目录是否全部关闭、memo 缓存是否锁定在本地.sdd/runtime/memo/、审计链 HMAC 是否有效、运行时 socket guard 是否就绪、运行时配置中是否残留外部主机名。只有FAIL行会导致非零退出，WARN行（如合法的运维放行项）不阻断。

然后以 airgap profile 运行，显式放行内网本地模型端点：

bernstein run --profile airgap --allow-network 127.0.0.1:11434 \ --goal "Refactor my-detection-rule.yml so the selection clause is stricter"

放行白名单语法

重复使用--allow-network添加规则：

若某个 plan 尝试使用端点不在白名单内的 adapter，Bernstein 会在子进程启动之前直接拒绝并报错，例如：

NetworkPolicyDenied: network egress denied by policy: api.anthropic.com:443 (from adapter:Claude Code)

这就是"默认拒绝"安全模型的落点：未声明external_endpoints的纯本地 adapter（如本地 Ollama 上的 Aider）不受影响，而云端 adapter 在无白名单时永远出不了边界。

九、常见问题速查

十、已知限制

• 官方 wheelhouse 构建覆盖Linux x86_64；macOS / Windows / arm64 需按同一 pin 集自建
• 原生依赖（cffi、lxml）固定为manylinux_2_28_x86_64，客户发行版不匹配时需换更近的基底镜像重编
• bernstein doctor airgap报告的是状态而非运行时网关，用于确认本次运行干净，不作运行时拦截使用

十一、延伸阅读

• 完整离线安装文档：docs/installation/air-gap.md
• Wheelhouse 构建脚本：scripts/build_airgap_wheelhouse.py
• 签名脚本：scripts/sign_airgap_wheelhouse.sh
• 校验命令实现：src/bernstein/cli/commands/verify_cmd.py、src/bernstein/core/distribution/verifier.py
• Sigstore 构建来源验证：src/bernstein/core/distribution/sigstore_attestation_verify.py
• 离线自检实现：src/bernstein/core/distribution/doctor_airgap.py
• 网络策略核心：src/bernstein/core/security/network_policy.py