21 · 部署

目标：把 Netbook（静态站）与 Ainet（二进制/集群）部署到可访问环境。本文给出 Cloudflare Pages / Vercel / 自托管三种路径；实际域名/账号由部署者提供。

21.1 Netbook：Cloudflare Pages

已部署：https://interactive-netbook.pages.dev（Cloudflare Pages，production branch main）。

已提供 apps/netbook/wrangler.toml（pages_build_output_dir = "./dist"）与 public/_headers。

# 首次
cd apps/netbook
pnpm install
pnpm build
npx wrangler pages project create interactive-netbook --production-branch main --force
npx wrangler pages deploy dist --project-name interactive-netbook --branch main

# 后续（仓库根目录）
./scripts/deploy-netbook.sh

--force 只用于首次创建项目（wrangler v4 会把 Pages 委托给 Workers）；之后部署不需要 --force。

自定义域：Cloudflare Dashboard → Pages → Custom domains。
_headers 已设置 X-Frame-Options、Referrer-Policy、Permissions-Policy、CSP。
- CSP 为兼容 Astro 内联引导脚本保留了 'unsafe-inline'；后续可抽 nonce/hash 收紧。
纯静态，无服务端 API；WASM 由同源提供。
隐私：不接第三方 analytics；如需，使用 Cloudflare Web Analytics（无 cookie）。

21.2 文档站：Cloudflare Pages

已部署：https://interactive-docs.pages.dev

cd apps/docs
pnpm install
pnpm build
npx wrangler pages project create interactive-docs --production-branch main --force  # 首次
npx wrangler pages deploy dist --project-name interactive-docs --branch main

后续在仓库根目录：

./scripts/deploy-docs.sh

构建脚本 apps/docs/build.mjs 直接读取 docs/*.md 和 specs/*.md，不复制内容。

21.3 Netbook：Vercel

cd apps/netbook
pnpm build
npx vercel deploy --prebuilt

dist/ 为静态输出；_headers 不生效，需在 vercel.json 配 headers（可选）。
自定义域：Vercel Project → Domains。

21.4 Ainet：单机二进制

cargo build --release -p ain-cli
./target/release/ain version

部署 ain 到 /usr/local/bin 或容器镜像。
运行时数据：journal/checkpoint/trace 目录挂载持久卷。
建议 systemd unit 或 Kubernetes Deployment；cell serve/node serve 分别监听端口。

21.5 Ainet：3 节点集群

# 每个节点（mTLS）
ain cell serve --bind 0.0.0.0:7200 --id n1 \
  --secret "$AIN_SECRET" --token "$AIN_TOKEN" \
  --tls-cert /etc/ain/server-cert.pem \
  --tls-key  /etc/ain/server-key.pem \
  --tls-ca   /etc/ain/ca.pem

# 控制端
ain cluster demo \
  --nodes n1@node1:7200,n2@node2:7200,n3@node3:7200 \
  --secret "$AIN_SECRET" --token "$AIN_TOKEN" \
  --tls-cert /etc/ain/client-cert.pem \
  --tls-key  /etc/ain/client-key.pem \
  --tls-ca   /etc/ain/ca.pem

flow 调度器：

ain node serve --bind 0.0.0.0:7100 --id n1 --token "$AIN_TOKEN" \
  --tls-cert /etc/ain/server-cert.pem \
  --tls-key  /etc/ain/server-key.pem \
  --tls-ca   /etc/ain/ca.pem

ain flow distribute examples/research.flow \
  --nodes node1:7100,node2:7100 --repeat 100 --chunk-steps 2 --health-check \
  --tls-cert /etc/ain/client-cert.pem \
  --tls-key  /etc/ain/client-key.pem \
  --tls-ca   /etc/ain/ca.pem

cell 集群与 flow 调度器都已内置 mTLS；仍需在防火墙层限制端口。
AIN_HTTP_ALLOW 必须设置为允许的出站前缀。
端口：cell worker 7200、flow worker 7100；不要暴露到公网。
日志：ain ... 结构化 JSON 尚未实现；当前为文本。

21.6 OpenCode Go 作为 provider

OpenCode Go 提供 OpenAI-compatible chat completions：

export OPENCODE_API_KEY=...   # 从 https://opencode.ai/console 复制
ain cluster llm100 \
  --nodes n1@node1:7200,n2@node2:7200,n3@node3:7200 \
  --openai-base https://opencode.ai/inference/go/openai/v1 \
  --openai-key "$OPENCODE_API_KEY" \
  --openai-model deepseek-v4.1-flash

effects 在 coordinator 执行，cell worker 不需要 provider key。
OpenAiEffect 会发送 user-agent: ainet/<version> 与 x-opencode-session；可用 OPENCODE_SESSION_ID 固定 session。
Go 有订阅用量/速率限制；100 个短请求建议串行或低并发，先小规模验证。
一键真实演练：OPENCODE_API_KEY=... ./scripts/opencode-go-demo.sh（默认 step-5-preview，可用 AIN_LLM_MODEL 覆盖）。
2026-11-11 实测：100 cells + kill-after 30 → 100 effects、34 failover、~316–358s。

21.7 环境变量

变量	用途
`AIN_TOKEN`	共享 transport token（建议通过 secret manager）
`AIN_SECRET`	cell capability HMAC secret
`AIN_HTTP_ALLOW`	逗号分隔的 HTTP 出站前缀 allowlist
`AIN_EFFECT_LEDGER`	建议的 ledger 路径（当前用 `--effect-ledger` 传入）
`AIN_CELL_QUEUE_LIMIT`	建议的 per-destination 队列上限（当前用 `--cell-queue-limit` 传入）
`AIN_TLS_CERT`/`AIN_TLS_KEY`/`AIN_TLS_CA`	建议的证书路径（当前用 `--tls-*` 传入）
`OPENAI_API_KEY`	真实 LLM provider（`--openai-*`）
`OPENCODE_API_KEY`	OpenCode Go API key（OpenAI-compatible）
`OPENCODE_SESSION_ID`	可选，OpenCode Go 的稳定路由/缓存 session ID
`AIN_LOG`	预留（尚未实现）

21.8 本地 release 打包

./scripts/package-release.sh 0.1.2

产物在 dist/release/：

ain-0.1.2-<target>.tar.gz：二进制、docs、specs、examples、licenses（macOS arm64 + Linux x86_64/aarch64 musl）；
netbook-0.1.2.tar.gz：静态站；
docs-site-0.1.2.tar.gz：文档站；
SHA256SUMS。

Linux 交叉构建：rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl + cargo install cargo-zigbuild；脚本会自动检测并打包。

GitHub Release 可用 gh release create v0.1.2 dist/release/*.tar.gz dist/release/SHA256SUMS --prerelease。

21.9 发布检查

wrangler.toml + _headers
静态构建（6 pages）
单机/集群命令文档
实际 Cloudflare Pages 部署
自定义域名/DNS
cell 集群 mTLS
flow 调度器 mTLS
生产 secret 轮换
监控/告警（uptime、错误率、成本）

在 GitHub 编辑本文