AiSOC 线上 Demo 运维实战:tryaisoc.com 的可用性契约、故障回退与 Fly.io 复活手册
AiSOC 线上 Demo 运维实战:tryaisoc.com 的可用性契约、故障回退与 Fly.io 复活手册
本文以 AiSOC 仓库中的线上演示运维手册为骨架,完整拆解 tryaisoc.com 这个"尽力而为"型公开 Demo 的可用性边界:当它挂掉时如何用 Codespaces 或本地 Docker 在几分钟内拿到一个可交互的控制台,以及维护者如何用 flyctl + cloudflared 把 Fly.io 上的四服务栈重新拉起来。读完后你能独立判断"打不开"属于哪一类故障、执行对应的恢复路径,并用仓库里已有的验收脚本而不是部署工具的退出码来证明它真的恢复了。
一、先明确契约:这是一个最佳努力型 Demo,不是企业 SLA
tryaisoc.com 曾经(在设计上)是一个真实运行的 AiSOC 实例:部署在 Fly.io 上,前面挂 Cloudflare Tunnel。手册开篇就把话说得很清楚——它不是企业级 SLA,而是 best-effort,随时可能离线。
这个定位决定了后续所有设计取舍:
- 它不需要 99.9%,但需要"挂了以后任何人都能在几分钟内自己跑起来";
- 它不追求全栈能力,只保留演示路径所需的最小服务集合;
- 它的恢复动作必须幂等,因为维护者往往在深夜、在手机热点下、在只记得几条命令的情况下操作。
需要提前说明一个重要事实:当前仓库的 infra/fly/README.md 与 infra/fly/*/fly.toml 文件头都记录了状态测量结果——Fly 组织因欠费被回收,三个 *.fly.dev 主机名在 2026-09-28 测量时为 NXDOMAIN,api. 与 ws. 子域返回 HTTP 525(边缘还在、源站已消失)。也就是说,这份手册描述的是"如何恢复一套当前并不存在的栈",而它的回退路径(Codespaces / 本地 Docker)才是今天真正可用的入口。理解这一点,才不会把文中 flyctl 命令当成"现在就能跑通"的结论。
二、tryaisoc.com 现在就打不开时的两条回退路径
手册给出的第一原则是:永远先给访问者一条能走通的替代路径,再谈修复。替代路径有两条,都依赖仓库内的既有脚本。
2.1 恒在回退:在 GitHub Codespaces 中启动
打开仓库的 Codespaces 快速启动入口后,.devcontainer/devcontainer.json 会准备好 Node 22、Python 3.11、Go 1.26、Docker-in-Docker 与 GitHub CLI。随后只需一条命令:
pnpm aisoc:demo --no-open
提示出现时,在 Ports 面板点击被转发的 3000 端口,那就是 AiSOC 控制台。
这条一句话背后有相当多工程细节,值得展开,因为它解释了"为什么 Codespaces 能跑起来而你本地可能不行":
| 配置项 | 值 | 作用 |
|---|---|---|
image |
ghcr.io/beenuar/aisoc-devcontainer:latest |
预构建镜像,把 Node + pnpm + Python(+uv) + Go + Docker + gh 烤进单层,冷启动从约 5 分钟降到约 30 秒 |
runArgs |
["--privileged", "--init"] |
容器创建时授权,Dockerfile 无法自授;没有 --privileged 时 CapEff: 0,连 dockerd 都起不来 |
mounts |
命名卷 aisoc-dind-var-lib-docker → /var/lib/docker |
dockerd 的 overlay2 不能跑在容器自身的 overlay 上;同时保留已拉取镜像,停止/恢复 Codespace 不必重拉 |
hostRequirements |
4 CPU / 16GB 内存 / 32GB 存储 | 低于此配置栈会因内存不足而反复重启 |
forwardPorts |
3000 / 3001 / 8000 / 8001 / 8086 | 分别对应控制台、文档站、FastAPI、LangGraph agents、WebSocket |
onCreateCommand |
pnpm install --frozen-lockfile |
与 CI、web 镜像保持一致,避免"我的首次成功运行和别人不是同一个构建" |
postStartCommand |
bash .devcontainer/start-docker.sh |
放在 postStart 而非 onCreate,保证 stop/resume 后 dockerd 依然在 |
containerEnv |
AISOC_DEV_MODE=1 |
标记开发环境 |
注意 postAttachCommand 打印的提示与手册正文的措辞存在一处有意为之的差异:容器提示推荐 make up 与 make smoke,而手册给的是 pnpm aisoc:demo。原因写在 devcontainer 配置的注释里——demo 用的 Compose 文件没有 ingest 与 fusion 服务、且 AISOC_DISABLE_KAFKA=true,它只能让你看见界面,不能用来判断产品是否工作。什么时候该用哪个,见下文 2.3。
2.2 本地回退:有 Docker 就是同一条命令
git clone https://github.com/beenuar/AiSOC && cd AiSOC && pnpm aisoc:demo
aisoc:demo 由 scripts/aisoc-demo.ts 提供,本质是一个七阶段编排器。它默认使用预构建镜像 infra/compose/docker-compose.demo.yml,因此不需要你本地编译任何东西。
命令行参数(覆盖了从日常演示到 CI 门禁的全部场景):
| 参数 | 作用 |
|---|---|
--no-pull |
跳过 docker compose pull,使用缓存镜像 |
--no-open |
不启动浏览器(CI / 无头环境) |
--rebuild |
改为 docker compose up --build,从源码构建 |
--tag <tag> |
覆盖 AISOC_TAG(默认 latest) |
--budget-ms <n> |
总耗时超过 n 毫秒则以退出码 3 结束 |
--results-file <p> |
写出分阶段耗时 JSON |
--demo-quick / --quick |
只种 4 个确定性 DEMO-* 案例(录制路径) |
--clock <iso> |
覆盖 --demo-quick 的时间锚点 |
--record / --screenshots |
启动后录制 screencast 或截图(隐含 --no-open) |
七个阶段与关键实现点:
- 校验 Docker:
docker --version、docker compose version(v1 不支持)、docker info确认守护进程在跑。 - 拉取镜像:失败时自动降级为本地构建(等价于打开
--rebuild)。 - 分配端口并启动:这是最容易被低估的一步。脚本会先用
docker ps --format '{{.Ports}}'收集 Docker 已发布的宿主端口,再对每个候选端口做一次真实的bind探测——两者缺一不可。注释里记录了一个真实事故:某容器已占用 5432 时,Node 在127.0.0.1上仍能 bind 成功(Docker Desktop 通过代理转发),于是探测判定"空闲",compose 启动 postgres 时没有报错却未接入网络,结果是 postgres 显示 healthy、API 显示 healthy、seed 静默退出、控制台打开后案例列表为空。端口从各自的规范默认值(web 3000 / api 8000 / agents 8001 / realtime 8086 / postgres 5432 / redis 6379 / kafka 9092)出发独立向上找空闲端口,窗口 50,遇到address already in use之类错误会换端口重试,最多 3 次。 - 等待健康:postgres 端口探测 60s,api
/health120s,web 120s(web 慢只警告不失败)。 - 重新执行 seeder:
docker compose exec -T api python -m app.scripts.seed_demo。Compose 里还有一个一次性的seed服务会在 api 健康后自动跑一次然后退出,这里属于双保险。 - 定位展示案例:轮询
/api/v1/cases?page_size=50,找INC-RT-001(--demo-quick模式下找DEMO-004);找不到则回退到列表第一条并告警,同时对返回的 UUID 与 case_number 分别做正则校验,避免把任意字符串拼进 URL。 - 打开
http://localhost:<web>/cases/INC-RT-001?tab=ledger,并输出 API 文档地址与 realtime 地址。
一个细节值得单独指出:脚本无论是否传 --results-file,都会把最近一次运行报告写到 .aisoc/last-demo-run.json。注释里的理由很朴素——"demo 没跑起来"是最常见、也最难处理的反馈,因为等人来报时栈已经没了;这份本地记录不联网、不外传,而 pnpm aisoc:doctor --bundle 会把它一起打包,于是 bug 报告自带分阶段耗时,能看出究竟卡在 pull、boot 还是 seed。
2.3 必须讲清的边界:demo 栈不等于产品流水线
infra/compose/docker-compose.demo.yml 的文件头用了一个醒目的方框声明:
这个栈不运行 AiSOC 流水线。它没有 ingest 服务、没有 fusion 服务,并设置
AISOC_DISABLE_KAFKA=true。你在控制台里看到的一切都来自seed_demo.py直接写入 Postgres 的合成数据。没有任何事件被归一化、检测、关联或提升,因为做这些事的代码一个都没在跑。用它看界面,不要用它评估 AiSOC 是否能工作。
这也解释了文件头记录的历史:这份 compose 文件曾是 v8.2 之前的官方快速开始,直到有用户照着 README 看到一个"有数据的控制台",从而得出"平台能用"的错误结论。于是现在真正的入口是:
make up # 10 个服务,真实流水线
make smoke # 证明它:一个真实事件 → 一条可检索的告警
make demo # 之后再加同一份合成数据,且明确标注 is_synthetic=true
如果你的目标是恢复一个可以给客户看的公开 Demo,pnpm aisoc:demo 是对的;如果目标是验证产品是否工作,必须走 make up + make smoke。把这两件事混为一谈,是这套文档最想避免的错误。
三、把"打不开"拆成可判定的故障假设
手册按可能性从高到低列出四类原因。它们可以直接映射到一组互斥的观测手段:
| 序号 | 假设 | 判据 | 处置 |
|---|---|---|---|
| 1 | Fly.io 机器休眠(最小付费实例可缩容到零) | 首次请求约 30s 慢,之后恢复 | 等待后刷新,不要立刻重部署 |
| 2 | 最新部署的 release_command(迁移 + seed)失败 |
flyctl releases 可见失败,flyctl logs 有迁移/种子报错 |
回滚或热修,或从 main 重新部署 |
| 3 | Cloudflare Tunnel 重连(控制面刷新后 agent 偶发需要重启) | 源站健康但域名 5xx/不可达 | 检查 cloudflared tunnel info,必要时重跑隧道 |
| 4 | 维护者的免费 Fly.io 额度耗尽 | 所有 flyctl 调用返回欠费错误 |
结算账单,非工程可解 |
当前仓库的实测记录补充了第五种、也是最彻底的一种:应用被回收。flyctl 对组织的任何调用都会回答 Your account has overdue invoices. Please update your payment information。这不是代码能绕过的,因为 [deploy].release_command 的迁移阶段也会先撞上它。
对普通访问者,区分第 1 类和第 2/3/4 类只需一个动作:等 30 秒再刷新一次。休眠唤醒是唯一"自己会好"的故障;其余都需要维护者介入。这也是手册把回退路径放在最前面的原因——不要在故障定位上花费访问者的时间。
四、维护者恢复手册:从 flyctl status 到重跑隧道
4.1 前置条件
- 已安装 Fly CLI,并已针对 AiSOC 组织执行
flyctl auth login; - 一个对
tryaisoc.com区域具备Tunnel:Edit权限的 Cloudflare API Token。
前置条件里没有"数据库凭据"或"应用密钥",因为部署脚本自己负责 provision 与 secret 注入。
4.2 查看状态与最近一次发布
# 1. 检查 Fly 状态
flyctl status -a aisoc-api
flyctl status -a aisoc-agents
flyctl status -a aisoc-web
flyctl status -a aisoc-realtime
# 2. 查看最近一次部署的 release_command 输出
flyctl releases -a aisoc-api | head
flyctl logs -a aisoc-api | tail -200
手册里的应用名是 aisoc-api / aisoc-agents / aisoc-web / aisoc-realtime,而仓库中 infra/fly/api/fly.toml 等配置里的 app 字段是 aisoc-demo-api / aisoc-demo-agents / aisoc-demo-web / aisoc-demo-realtime。这是一个必须按实际环境核对的差异:fly-demo-deploy.sh 全文使用 -demo- 形式,infra/fly/README.md 的主机名表也用 aisoc-demo-*。照抄手册里的短名很可能得到 Could not find App。建议先用 flyctl apps list --org "$FLY_ORG" 确认真实名称,再决定用哪一组。
4.3 如果只是休眠,唤醒它
flyctl machine start --select -a aisoc-api
flyctl machine start --select -a aisoc-agents
flyctl machine start --select -a aisoc-web
flyctl machine start --select -a aisoc-realtime
--select 会进入交互式选择,适合"这台机器只有一个 machine"的 demo 场景。注意顺序:api 先起,因为其它服务通过 Fly 的 6PN .internal DNS 依赖它。
顺带说明配置层面的取舍:infra/fly/api/fly.toml 里 auto_stop_machines = "off",注释给出的理由是——web 会通过 aisoc-demo-api.internal:8000 走 6PN 代理 /api/v1/*,而 6PN 连接不会触发 Fly 的 auto-start,机器一旦停掉,即使公网 api.tryaisoc.com 的边缘能唤醒它,仪表盘的指标请求也会 500。realtime 同理设成 off,因为"休眠等于杀死 WebSocket 连接"。web 则允许 auto_stop_machines = "stop",靠 min_machines_running = 1 保持一台常热以守住 sub-60s 的 TTFI 预算。
4.4 如果迁移或种子失败,从 main 重新部署
git checkout main
git pull --rebase origin main
./infra/fly/fly-demo-deploy.sh
手册强调这个脚本幂等,可以安全重跑。它把迁移和 demo seed(python -m app.scripts.seed_demo)作为 release_command 执行,所以一次成功部署之后,INC-RT-001 这个 LockBit 案例永远存在。
脚本的实际结构(infra/fly/fly-demo-deploy.sh)比手册描述的要丰富,值得按执行顺序梳理,因为排障时你需要知道每一步会失败成什么样:
| 步骤 | 命令要点 | 幂等策略 |
|---|---|---|
| 解析参数 | --provision / --skip-seed / --org=,环境变量 FLY_ORG(默认 personal)、FLY_REGION(默认 iad) |
纯本地 |
| provision Postgres | flyctl postgres create --name aisoc-demo-postgres --vm-size shared-cpu-1x --volume-size 3 --initial-cluster-size 1 |
失败时打印 (already provisioned) 并继续 |
| provision Redis | flyctl redis create ... --no-replicas --enable-eviction --plan "Pay-as-you-go",并用 printf 'n\n' 关闭 ProdPack 交互提示 |
从输出里 grep -oE 'redis://[^[:space:]]+' 捕获 URL;捕获不到就跳过 secret 传播 |
| 预置 marketplace 索引 | python3 scripts/build_marketplace.py 后把 marketplace/index.json 复制进 services/api/marketplace/ |
每次部署重建,避免用过期的签入文件 |
| 部署 api | cd services/api && flyctl deploy --remote-only --config <abs>/api/fly.toml |
ensure_app 先建应用,attach_pg/attach_redis 失败即忽略 |
| 部署 agents / realtime / web | 同上,web 的构建上下文是仓库根 | 同上 |
| 申请证书 | flyctl certs add tryaisoc.com / api. / ws. |
重复添加返回非零,被吞掉 |
| 种数据 | flyctl ssh console -C "python -m app.scripts.seed_demo" |
失败只告警;--skip-seed 可跳过 |
| 建每日 cron | flyctl machine run --schedule daily --name aisoc-demo-seed-cron ... |
名称冲突返回非零,静默跳过 |
脚本里有几处注释本身就是"踩坑档案",对排障极有价值:
- 为什么 Redis URL 要从 stdout 抓:
flyctl redis create是唯一暴露连接串的地方,没有redis attach,redis status也不打印 URL。 - 为什么 plan 名大小写敏感:
flyctl redis plans打印的是Pay-as-you-go,传小写会得到Error: plan "pay-as-you-go" not found。 - 为什么必须喂
n:flyctl 0.4.x 新增了 ProdPack($200/月)交互提示,没有--no-prodpack反向开关,脚本化运行会直接死于Error: prompt: non interactive。 - 为什么
flyctl的--config用绝对路径、而 cwd 要切到服务目录:各服务 Dockerfile 假定构建上下文是服务源码目录(COPY pyproject.toml ./、COPY . .),而 flyctl 默认以当前目录为构建上下文。 - 为什么 api 的 fly.toml 不写
[build] dockerfile:flyctl 解析该字段是相对fly.toml所在目录,而非构建上下文;写了会去找infra/fly/api/Dockerfile然后失败。反过来,web 的 fly.toml 必须写../../../apps/web/Dockerfile,因为 web 的构建上下文是仓库根。
release_command 那一段同样值得逐字理解,它是"为什么一次部署失败会把整个 Demo 拖黑"的核心:
[deploy]
release_command = "/bin/sh -c 'rm -f /tmp/aisoc-migrations-ok && python -m app.scripts.run_migrations && { [ -f /tmp/aisoc-migrations-ok ] && python -m app.scripts.seed_demo || echo \"[release_command] migrations soft-failed (DB unreachable) — seed_demo skipped, API code deploy proceeds\"; }'"
配合 AISOC_MIGRATIONS_REQUIRED = "0",语义是:迁移在 Postgres 完全不可达时重试耗尽后退出 0(不让数据库故障绑架代码部署),但只要 SQL 层面出错就照常非零退出并终止部署。而 seed 只在迁移成功写下 /tmp/aisoc-migrations-ok 哨兵文件时才执行——否则 SQLAlchemy 会以同样的连接失败把整个部署搞崩。这一层包装解释了手册里"release_command 失败是最常见故障"的背后机制,也解释了为什么恢复时第一步该看 flyctl releases 的输出而不是直接重部署。
4.5 Cloudflare Tunnel:只在 DNS / TLS 退化时动它
cloudflared tunnel info tryaisoc
cloudflared tunnel route dns tryaisoc tryaisoc.com
仓库里对应的自动化是 infra/cloudflare/tunnel.sh。它有两条认证路径,覆盖不同场景:
- 源证书流程(经典):
cloudflared tunnel login写入~/.cloudflared/cert.pem,脚本负责创建/复用命名隧道、渲染 ingress 配置、写 DNS 路由、前台运行。 - 隧道 Token 流程(现代,无需 cert.pem):直接
export CLOUDFLARE_TUNNEL_TOKEN='ey…',脚本跳过 cert/创建/DNS 全部步骤,只执行cloudflared tunnel run --token,由 Zero Trust 仪表盘托管 ingress 与 DNS。
环境变量(全部可选):DOMAIN(默认 tryaisoc.com)、TUNNEL_NAME(默认 aisoc-tryaisoc)、SUBDOMAINS(默认 api ws docs)、TUNNEL_ORIGIN_CERT、SKIP_DNS=1、SKIP_RUN=1。
脚本里两个设计点对"改完就好、但好像没生效"这类问题特别有用:
- 渲染后先校验再落盘:配置先写临时文件,用
cloudflared tunnel --config <tmp> ingress validate验证,通过才mv到~/.cloudflared/<name>.yml。这样不会出现"半个配置生效"的中间态。 - DNS 误路由检测:
cloudflared tunnel route dns在 cert.pem 属于另一个 Cloudflare 账户/区域时会"成功",但创建的是把$DOMAIN当作标签的 CNAME(例如tryaisoc.com.intel.nexus)。脚本从日志里解析Added CNAME <fqdn>,一旦 fqdn 与请求的 host 不一致就中止并给出四步修复指引(备份证书、用正确账户重新 login、可选按域名改名保存并 exportTUNNEL_ORIGIN_CERT、重跑脚本)。这个 footgun 之所以值得写进脚本,是因为它"看起来成功了"。
另外注意隧道名的不一致:手册写 cloudflared tunnel info tryaisoc,而脚本默认 TUNNEL_NAME=aisoc-tryaisoc。执行前先 cloudflared tunnel list 核对实际名称。
4.6 部署脚本自带的冒烟检查
脚本在最后会打印一组直接可用的验证命令,本质上就是"不要相信部署工具的退出码":
curl -sf https://aisoc-demo-api.fly.dev/health
curl -sf https://api.tryaisoc.com/health # DNS 生效后
open https://tryaisoc.com/cases/INC-RT-001?tab=ledger
infra/fly/README.md 的"Smoke checks"还补了三个更能证明 demo 语义的检查:
# demo 响应头可见
curl -sI https://aisoc-demo-api.fly.dev/api/v1/cases | grep -i x-aisoc
# 写操作被拒绝
curl -si -X POST https://aisoc-demo-api.fly.dev/api/v1/cases | head -3
# 期望: HTTP/2 403 …
# 证书状态(DNS 生效后)
flyctl certs show tryaisoc.com --app aisoc-demo-web
flyctl certs show api.tryaisoc.com --app aisoc-demo-api
flyctl certs show ws.tryaisoc.com --app aisoc-demo-realtime
这组检查的存在理由写在 README 里:flyctl deploy 返回 0 不代表 demo 可用——机器可能启动、首个请求失败、然后就这样待着。曾经因为只信"绿色流水线",公开 Demo 在无人察觉的情况下下线了数周。这也是被删除的两个 GitHub Actions 工作流唯一真正提供的价值,如今由脚本 + 人工冒烟承担。
五、部署之后的客户旅程清单(逐项可勾选)
手动步骤最容易漏,所以手册给了一份"每次部署到 tryaisoc.com 之后都要走一遍"的清单。任何一项断链都属于部署回归,必须在宣布完成前修掉:
- [ ] 落地页(
/)渲染正常,控制台无报错。 - [ ] 三个 CTA("Try the demo"、"Run on Fly.io"、"Run on Render")全部可解析。
- [ ] 登录按钮落到
/dashboard;已废弃的/signup应重定向过去,而不是 404。 - [ ]
/dashboard加载 demo,且展示真实的/metrics数据与一个进行中的调查。 - [ ]
/cases/INC-RT-001打开时 Investigation Ledger 已有内容(这是录屏的标准路径)。 - [ ]
/alerts至少有一条告警,/hunt至少有一个 hunt 能加载。 - [ ]
/docs(Docusaurus)与/papers/*渲染正常。 - [ ] 页脚链接全部可解析。
其中第 3 项在源码里有明确依据:apps/web/next.config.js 的 redirects() 把 /signup 以 permanent: true(308)永久重定向到 /dashboard,并注明原因是 /signup 是刻意不做页面的——AiSOC 是 MIT 许可、可自托管,公开入口就是匿名 demo,但旧搜索结果、旧博文、旧 deck 里仍有这个 URL,所以用 308 保住外链价值而不是让它 404。这也意味着如果你在验收时看到 404,那一定是部署的镜像/配置不对,而不是"这个页面本来就没有"。
第 5 项的数据来源同样可查:INC-RT-001 是 _purge_demo_quick 之外的完整种子产物,services/api/app/scripts/seed_demo.py 里它对应 LockBit 3.0 场景,是全量种子 15 个事件中的"在办"案例,并且会被发布成公开回放 /r/demo-lockbit。
六、从 runbook 到自动化门禁:acceptance 与 doctor
手册是给人读的,仓库还提供了两个可执行的等价物,用来把"看起来好了"变成"有证据地好了"。
6.1 pnpm aisoc:acceptance:把"克隆到调查"变成可测量的预算
scripts/aisoc-acceptance.ts 封装 pnpm aisoc:demo,强制 5 分钟预算(DEFAULT_BUDGET_MS = 5 * 60 * 1000),并把每次结果追加到 .aisoc/acceptance-history.jsonl 以便看趋势。
| 退出码 | 含义 |
|---|---|
| 0 | 通过(在预算内,所有阶段达成) |
| 1 | 栈启动失败 |
| 2 | 测试骨架自身崩溃 |
| 3 | 超预算(可用性回归:栈能用但太慢) |
| 4 | 栈起来了,但 seed/kickoff 没到达展示案例 |
参数:--cold(先清理镜像,模拟真正的首次克隆)、--budget-ms <n>、--history-only(只看趋势不跑)、--tag <tag>、--keep-stack(默认跑完拆栈,因为"一次干净克隆能否到达调查"这个问题会被残留容器污染)。
为什么用 TS 而不是 shell:需要解析 demo 输出的 JSON 结果文件,而 tsx 已经是 devDependency,且要在 macOS 开发机与 Linux CI 上行为一致。
6.2 pnpm aisoc:doctor:五类环境检查加可安全公开的诊断包
scripts/aisoc-doctor.ts 检查:端口是否空闲或由预期服务占用、.env 必需变量是否就绪、compose 容器是否健康、demo 数据是否已种(alerts > 0)、WebSocket realtime 是否可达。退出码 0 表示全通过,1 表示至少一项 FAIL。
--bundle 会额外写出一个脱敏诊断包:平台与版本、检查结果、容器状态、脱敏后的日志尾部,以及已设置的环境变量名(永不包含值),可安全附在公开 issue 里。它与 .aisoc/last-demo-run.json 组合,正好覆盖"demo 没跑起来"这类最难复现的反馈。
七、Demo 模式的安全边界:为什么公开实例可以被任意人点击而不会被写坏
公开 Demo 最大的风险不是被 DDoS,而是"某个访客改了共享数据集,后面所有人都看到被改过的状态"。仓库用两层正交机制处理。
7.1 API 侧:DemoModeMiddleware
services/api/app/middleware/demo_mode.py 在 AISOC_DEMO_MODE=true 时启用,行为有三段:
- 安全方法与白名单前缀直接放行,并给响应打上三个头:
X-AiSOC-Demo: true、X-AiSOC-Demo-Tenant、X-AiSOC-Demo-Banner。 - 少量写操作允许,用正则精确匹配,保证"点一下就看到调查"的剧情能跑通:
^/api/v1/cases/INC(?:-RT)?-\d{3}/investigate$^/api/v1/investigations/[^/]+/cancel$^/api/v1/alerts/[^/]+/ack$
- 其余写操作返回 403,载荷是结构化的自助指引:
error: "demo_mode_read_only",附self_host_url、blocked_path、blocked_method,同时记录一条demo-mode blocked ...日志(含来源 IP)。
常放行的前缀包括 /health、/metrics、/api/docs、/api/redoc、/api/openapi.json、/api/v1/auth/、/api/v1/dev-auth、/api/v1/waitlist/、/saml/、/oidc/。其中 /api/v1/waitlist/ 的注释记录了一次真实 QA 事故:托管版候选名单的 POST 在 demo 模式下被 403,导致公开转化漏斗对每个访客都失效(QA 2026-07-19);而名单表与 demo SOC 数据集是分开的,写它不会污染演示数据。
模块 docstring 还特意强调:这不是认证/RBAC 的替代品,而是叠加在 demo 租户只读角色之上的一层纵深防御。把它当成唯一防线,就等着某个非 RESTful 入口绕过它。
7.2 前端侧:DemoBanner
apps/web/src/components/demo/DemoBanner.tsx 在 NEXT_PUBLIC_DEMO_MODE === 'true' 时于 AppShell 顶部渲染一条琥珀色固定条,文案为"Demo data resets daily at 00:00 UTC. All write actions are disabled.",并附"Self-host AiSOC"链接。两个设计决定值得注意:
role="status"+aria-live="polite":读屏用户在页面加载时就能听到"写操作已禁用";- 不可关闭:注释写得很直白——访客必须知道写操作会 403,否则他们会以为应用坏了。
而"重置"这件事本身由每日 00:00 UTC 的 cron machine 完成,它在 demo 租户的 RLS 作用域内重跑同一个 seeder,因此不会跨租户污染。
7.3 构建期与运行期的坑:NEXT_PUBLIC_* 必须进 build.args
infra/fly/web/fly.toml 里有一段容易被忽略但会导致"页面正常、按钮全废"的说明:Next.js 在 next build 时把 NEXT_PUBLIC_* 内联进客户端 bundle,只在 [env] 里设运行期值对浏览器无效。所以 NEXT_PUBLIC_DEMO_MODE、NEXT_PUBLIC_DEMO_DEEPLINK、NEXT_PUBLIC_DEMO_BANNER、NEXT_PUBLIC_DEMO_AUTOLOGIN_EMAIL/PASSWORD、NEXT_PUBLIC_API_URL、NEXT_PUBLIC_WS_URL 以及服务端代理目标 API_URL/AGENTS_URL/REALTIME_URL 都必须同时出现在 [build.args] 中。
如果漏了后者,next.config.js 会按 Dockerfile 默认值(http://api:8000 等,为本地 Compose 设计)把 rewrite 目标写进 .next/routes-manifest.json,Fly 的 6PN DNS 里没有 api 这条记录,于是浏览器看到 api.tryaisoc.com 是健康的、同源的 /api/v1/* 却报 Internal Server Error。这类"边缘健康、应用报错"的症状,根因常常在构建参数而不在运行时。
八、成本的现实边界:为什么它只能 best-effort
infra/fly/README.md 给出的成本目标是"单个维护者能负担"的 <$30/月,实际估算约 $14/月:
| 资源 | 月成本(估算) |
|---|---|
3 × shared-cpu-1x(api、web、realtime,auto_stop=stop) |
~$6 |
| 1 × shared-cpu-2x(agents) | ~$5 |
| 1 × 定时 seed 机器(约 1 分钟/天) | <$0.10 |
| Fly Postgres(dev,3GB) | ~$2 |
| Upstash Redis(Free) | $0 |
| 出站带宽(约 50GB) | ~$1 |
| 合计 | ~$14/月 |
这些数字是估算,不是账单实测,且依赖若干前提(auto_stop 生效、流量不超过 50GB/月)。超过 50GB 时的预案是把种子快照缓存到 Cloudflare R2。这也解释了手册最后那句判断:如果"始终在线"的托管需求大到值得专项经费,资金模型在 .github/FUNDING.yml;在此之前,这份文件就是运维手册。
而 FUNDING.yml 的现状需要如实说明:所有赞助条目(GitHub Sponsors、Open Collective、custom 等)都是注释掉的,文件里明确写着 AiSOC 由 Cyble 资助工程时间并以 MIT 发布,项目本身不收款,因此不渲染 "Sponsor" 按钮。注释还留了一条经验:custom: 里的链接必须返回 HTTP 200 才能取消注释,因为曾经放了一个 404 路径,"而 Sponsor 按钮是仓库最显眼的链接"。
架构侧还有一份"刻意不做"的清单,它直接决定了成本与故障面:
| 组件 | Demo 状态 | 原因 |
|---|---|---|
| Kafka | 禁用 | 实时走 Redis pub/sub |
| ClickHouse | 禁用 | 演示流程无分析查询 |
| OpenSearch | 禁用 | 检测规则自带合成匹配载荷 |
| Neo4j | 禁用 | 攻击图不在标准演示路径上 |
| Qdrant | 禁用 | 知识库走镜像内 Postgres + pg_trgm |
自托管者要全栈时,这些会随根目录 docker-compose.yml 一起回来。
九、把这份 runbook 用成肌肉记忆
把上面的内容压缩成一张操作卡,故障时按顺序执行即可:
| 场景 | 第一个动作 | 判定成功的证据 |
|---|---|---|
| 访问者:页面打不开 | 等 30 秒刷新 | 页面出来(休眠唤醒) |
| 访问者:仍然打不开 | Codespaces 打开仓库 → pnpm aisoc:demo --no-open → 点端口 3000 |
控制台出现 INC-RT-001 的 ledger |
| 访问者:有本地 Docker | git clone … && cd AiSOC && pnpm aisoc:demo |
浏览器自动打开 /cases/INC-RT-001?tab=ledger |
| 维护者:怀疑机器睡着 | flyctl status -a <app> 后 flyctl machine start --select -a <app> |
flyctl status 显示 started |
| 维护者:怀疑部署坏了 | flyctl releases -a <app> | head + flyctl logs -a <app> | tail -200 |
找到迁移或 seed 的具体报错 |
| 维护者:确认需要重部署 | git checkout main && git pull --rebase origin main && ./infra/fly/fly-demo-deploy.sh |
脚本末尾的 curl -sf …/health 返回 200 |
| 维护者:域名/TLS 异常 | cloudflared tunnel info <name>,必要时重跑 infra/cloudflare/tunnel.sh |
flyctl certs show <host> 显示 issued |
| 维护者:宣布完成前 | 走完第五章八项客户旅程清单 | 八项全绿,尤其 /signup 是 308 而非 404 |
| 任何人:需要复现证据 | pnpm aisoc:doctor --bundle |
生成含分阶段耗时的脱敏诊断包 |
贯穿始终的三条原则,也是这份文档真正想传递的东西:
- 先给替代路径,再修主路径。Demo 的价值是让人看到产品,不是让人研究运维。
- 幂等优先。部署脚本、seeder、隧道脚本、证书申请全部 fail-soft 或可重跑,因为它们的使用者是在压力下操作的。
- 用应用自己的回答证明它活着。
flyctl deploy的退出码、容器的healthy、流水线的绿色,都不能替代一次curl -sf /health和一次人工点击INC-RT-001。这条教训在仓库里以"公开 Demo 曾在绿色流水线后面下线数周"的形式被记录下来,值得每一个自建 Demo 的团队抄走。