Agent X-Ray

本文早期版本写过「每活跃会话叠 300–500MB」,那是没有实测依据的估算,已被 R1 推翻(实测空闲会话增量 0.04–0.4MB,差三个数量级)。但也不能反过来用 0.04MB 去推——真实活跃会话还会因上下文、消息历史、事件队列、工具输出、provider 在途响应而增长。用下面的公式:

text

API_RSS_p95 = B                                  # 基座:Encore runtime + pi import(实测口径)
            + N_active    × S_active_p95         # 活跃会话净增量(上下文 + 消息历史 + 会话对象)
            + N_streaming × S_stream_p95         # 正在流式的会话附加(provider 在途响应 + SSE 写缓冲)
            + N_active    × S_eventbuf_cap       # 事件缓冲上限(结构性常数,见下)
            + G                                  # GC / 分配器余量

mem_limit  = API_RSS_p95 × 1.3(突发余量)
并发上限   = MAX_ACTIVE_SESSIONS ≤ (mem_limit / 1.3 − B − G) / (S_active_p95 + S_eventbuf_cap)
主机校验   = Σ(所有容器 mem_limit) + OS/Docker + cache 保留 ≤ 物理内存

各系数的来源:

系数	取值	来源

这是本站自己的源码,与线上运行的版本一致;快照随每次发版更新。

主机预算参考(3.6 GiB 物理内存,与 deploy/docker-compose.yml 的 mem_limit 对齐):

组件	预算
OS + systemd + sshd + fail2ban + dockerd	~450–550 MB
postgres(shared_buffers=256MB,mem_limit 768m)	~300–500 MB
api(mem_limit 1g)	1 GiB 上限
web(mem_limit 384m,常态 ~100–150MB)	384 MB 上限
caddy(mem_limit 128m)	~30–50 MB
skill-runner(mem_limit 384m,R-SKILLS-2;常态 ~20 MB,跑脚本时每个子进程 rlimit AS 256 MB、并发 2)	384 MB 上限
skill-runner-egress(mem_limit 256m,R-WEBFETCH 所有者裁定 C7;同一镜像,并发 1;常态 ~20 MB,抓一页时 trafilatura 进程按 dev.ps1 runner-test 的病态夹具实测)	256 MB 上限
filesystem cache 与余量	剩余 ~50–450 MB(加 egress 之后;OS 那一行按下限算才剩 ~650 MB)。这是六个容器全顶到上限的最坏值,常态远宽松;egress 容器 RSS p95 进 R-SKILLS-2 同一套观察口径,超 60% 再议

关于 api 的 1g:这是初始生产上限,依据是「Bun 口径实测基座 162.5MB + 事件缓冲的结构性上限 + 3.6GiB 主机的总预算」三者取平衡。它不代表「已证明 1GB 足够所有真实负载」——S_active_p95 目前是空值,任何容量结论都还缺这一项。

同样地,不要用空闲会话的 0.04MB 去推真实活跃会话的容量。空闲会话不持有上下文、消息历史、在途 provider 响应与流式写缓冲,两者不是一个量级的东西。

什么时候提高 limit / 升配:容器 RSS p95 持续一周超 mem_limit 的 60%,或出现首次 OOM kill → 先查泄漏,确认是真实负载后按上式重算。若推出 api 常态 >700MB,先做「把 PostgreSQL 拆到云托管」再考虑升配——拆库比升配便宜,且顺路解锁多实例前置。

1. ICP 备案清单(境内必做)

域名在阿里云/腾讯云购入(备案要求域名与服务器同厂商最顺)
服务器购买 ≥3 个月(备案要求)
在云厂商备案控制台提交:个人备案,网站名称避免「Agent/AI 服务」等敏感表述,建议以「个人技术学习分享」类目申报
审核周期约 1–3 周;备案通过前,云厂商会拦截 80/443 的 HTTP 服务 → 开发期用 IP:8080 等非标端口自测
备案通过后:域名解析 A 记录 → 服务器 IP,.env 填 SITE_ADDRESS=<域名>,Caddy 在 443 自动签发 TLS。生产 80 刻意不给响应(所有者要求),证书走 TLS-ALPN-01(见 docs/security.md §5)——别按「放开 80/443」的老口径去核 80
网站底部挂备案号(.env 的 ICP_BEIAN,运行期注入;web footer 预留位)。ICP 之外还有公安联网备案:网站开通后 30 个工作日内办,底部要同时挂公安备案号并链到 beian.mps.gov.cn。2026-09-10 已办并落地(苏公网安备,SiteFooter 同时支持两个号):
- 号码走 .env 的 MPS_BEIAN=<备案号原文>,与 ICP_BEIAN 同一套运行期注入;查询链接的 ?code= 由组件从号码里取数字串,不用另填
- 备案编号图标必须是备案系统「点击下载备案编号图标」下来的原文件,已按原字节存为 apps/web/public/beian-mps.png(36×40 PNG);格式要求是「图标在前、号码在右」
- 桌面底栏版式:两个号并排一行,高度仍 26px;窄到一行放不下时折行(号码必须可见,不截断)
- 移动端(≤768px)不在屏底挂(所有者裁定 2026-09-10,R-MOBILE-2):底栏在窄视口整条不渲染,两个号搬到 About 页尾 (两号各一行居中、公安图标在左、可点,画板 5d ③)。原因是屏底那 26px 会把移动端 Tab Bar 顶离屏幕底缘, 还让 Tab Bar 随滚动收起时剩一条残条压在号码上(生产实测 footerCovered = 26px)。 已认的残余风险:移动端首页(Runtime)自身不滚动,搬走后手机上首页看不到号码 —— 备案抽查通常看首页底部, 所有者认此风险(桌面底栏照旧、移动 About 里有);更稳的变体(Notes / Skills 页尾也各挂一条)记 rounds/BACKLOG.md

2. 服务器初始化(一次性)

bash

# 1) 新建部署用户 + SSH 仅密钥
adduser deploy && usermod -aG docker deploy
# sshd_config: PasswordAuthentication no; PermitRootLogin no

# 2) 防火墙(云控制台安全组同步配置)
ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 443/udp && ufw allow <SSH端口>/tcp && ufw enable
# 443/udp 是 HTTP/3(QUIC);云控制台安全组也要加一条 UDP 443,少一层都不通

# 3) fail2ban + 自动安全更新
apt install -y fail2ban unattended-upgrades

# 4) Docker(境内用镜像加速)
curl -fsSL https://get.docker.com | sh
# /etc/docker/daemon.json 配置 registry-mirrors(阿里云个人加速地址)

# 5) egress 执行容器的宿主出网过滤(R-WEBFETCH;compose 首次 up 起 skill-runner-egress 之后、开 web-fetch 之前)
#    幂等;--install-unit 把脚本复制到 /usr/local/sbin 并装 After=docker.service 的 systemd oneshot,重启后自动重放。
#    只对 egress 网络的固定网段(172.30.0.0/24)DROP 到私网 / link-local / CGNAT / 回环;docs/security.md §5
sudo ~/deploy/egress-filter.sh --install-unit && sudo ~/deploy/egress-filter.sh --status

3. 应用部署(不可变镜像)

服务器上不构建、不 clone 仓库、不装 encore/node/bun 工具链(CLAUDE.md 规则 10)。服务器只需要 docker + docker compose + 四个部署资产:docker-compose.yml、Caddyfile、migrate.sh、.env(由 .env.example 复制)。这四个文件首次部署随镜像一起 scp,之后仅在变更时重传——migrate.sh 是部署必经步骤,漏传就做不了迁移。

powershell

# —— 本机(Windows)——
.\dev.ps1 build          # 出 xray-api:<sha> 与 xray-web:<sha>
# ⚠️ 传输走文件。不要在 PowerShell 里 `docker save … | ssh … docker load`:
#    PS 5.1 管道按文本重编码,二进制 tar 会被破坏,远端 load 必失败。
docker save -o xray-<sha>.tar local/xray-api:<sha> local/xray-web:<sha>
ssh <host> "mkdir -p ~/deploy"      # 首次:scp 不会自建目标目录
scp xray-<sha>.tar deploy/docker-compose.yml deploy/Caddyfile deploy/migrate.sh deploy/.env.example <host>:~/deploy/
ssh <host> "docker load -i ~/deploy/xray-<sha>.tar && chmod +x ~/deploy/migrate.sh"

bash

# —— 服务器 ——
cd ~/deploy && cp .env.example .env && chmod 600 .env    # 首次
# 填 IMAGE_TAG=<sha> / POSTGRES_PASSWORD / MCP_AUTH_TOKEN_HASH / CONFIG_ENCRYPTION_KEY / METRICS_IP_SALT
#   / SITE_ADDRESS=<域名> / SITE_REDIRECT_FROM=<裸域> / SITE_ORIGIN=https://www.<域名> / ICP_BEIAN=<备案号>
#   / MPS_BEIAN=<公安联网备案号原文>(2026-09-10 起;留空则底栏只挂 ICP 一个号)
#   / XRAY_IMAGEGEN_EXTRA_HOSTS=<生图网关域名>(R-IMAGEGEN;与上一条是两份清单,网关域名两处都写)
#   / XRAY_WEBSEARCH_EXTRA_HOSTS=<LLM/搜索网关域名>   ← 生产首次部署最容易漏:内置白名单只有两个域,
#     不补这项 websearch_provider_upsert 直接拒(R11 实测;130 早就设了所以从没暴露)
# 密钥类三项在服务器上就地 `openssl rand -base64 32` 生成,原文不经本机、不进对话
# (R6 起没有 LLM 引导密钥:起完服务后经 MCP 的 llm_provider_upsert 写入 provider)

docker compose up -d --wait postgres   # 1) 只起库,等到 healthy
./migrate.sh                           # 2) schema 就位(镜像不会自跑迁移)
docker compose up -d                   # 3) 再起 api / web / caddy

升级 = 构建新 SHA → 传输 → 改 .env 的 IMAGE_TAG → docker compose stop api web(先停旧版,否则旧二进制会踩着迁移中的新 schema 继续服务) → up -d --wait postgres → ./migrate.sh → docker compose up -d。不停机升级仅当迁移确认对旧版后向兼容时才允许,V1 默认不做该保证
回滚 = 把 IMAGE_TAG 改回上一个 SHA → docker compose up -d(镜像即回滚单元;迁移不自动回退,涉及不可逆迁移时先恢复备份)
禁止 latest:compose 里 ${IMAGE_TAG:?} 会拒绝空值启动
⚠️ 迁移不会自动执行,且必须在 api/web/caddy 起来之前完成。忘了跑或顺序颠倒的表现是:健康检查全绿、Caddy 已放流量,而业务接口 500(relation "sessions" does not exist)——监控发现不了,只能靠部署顺序消除。migrate.sh 幂等,可安全重复执行;详见 deploy-environments.md
.env 永不入 Git;LLM key 不进镜像,经 deploy/infra-config.json 的 {"$env": …} 在运行时注入
LLM 出口:境内直连 Anthropic/OpenAI 不通或不稳。用海外中转端点(自备官方 key + 自建或可信中转);中转基址属于 secrets
未来若在前面加 CDN / 云防护:必须为两条 SSE 路径(/api/agent/*、/api/trace/stream)单独关闭响应缓冲与空闲超时,否则轨迹面板会静默卡死

见 deploy/Caddyfile:/ → web、/api/* → api、/notes/**.webp 按扩展名分流到 api 供图;/api/mcp* 可选 IP 白名单段;全局限速可用 caddy-ratelimit 插件或前置云厂商防护。

Postgres:每日 pg_dump 到本机 + 异地(对象存储)各一份;保留 14 天
.env 与 Caddy 证书目录纳入备份

6. 上线前检查单

每个环境各过一遍,不是过一次就完。130 预发的留证见 rounds/round-10/checklist.md(R10,SHA 5c98b3e,1–11 全绿); 生产尚未重跑:R11 收工时所有者裁定不重跑,13 项里 6 项静态属性在生产没有留证(哪 6 项见 rounds/round-11/round-11.md「收工」段);将来若重跑,留证补进 releases.md 对应发版行。下面括号里的判据是 R9/R10 实测校准过的,照着核不会误判。

gitleaks 扫描仓库无密钥。两条都要跑:gitleaks dir <repo>(工作区)与 gitleaks git <repo>(历史),期望均为 no leaks found。判据由仓库根的 .gitleaks.toml 定义(排除构建产物与 gitignored 的本地密钥文件,并按具体的值放行脱敏测试的假密钥字面量——不按文件放行,否则那两个文件会变成盲区)。不带这个配置裸跑会报十几条全是噪音的命中;改动这个配置后要跑一次证伪探针(往几处各插一行新的真实形状 key,确认都被抓到),做法见 rounds/round-10/checklist.md §1
.env 权限 600;docker compose config 无明文 key 泄漏到镜像。判据:把 .env 里的密钥值逐个拿去比对 docker history --no-trunc 与镜像的 Config.{Env,Cmd,Entrypoint,Labels},期望命中 0;密钥只应出现在容器的运行期 env 里
api 容器:非 root、read_only、无 docker.sock、cap_drop ALL、pids_limit、mem_limit 生效(docker inspect 逐项核)。docker.sock 要对全机所有运行中容器扫一遍挂载源,不只是本 compose 的四个
最终运行镜像内无 node、只有 bun。判据见 deploy-environments.md 冒烟清单第 12 条(node -p "process.versions.bun" 有值 + 真实 node/nodejs 二进制不存在 + dpkg -l 无 nodejs 包)。~~node --version 应失败~~ 别用这条:oven/bun 基座自带一个指向 bun 的 node 软链,它确实会以退出码 1 失败,但报的是 Missing script to execute … Node.js-compatible REPL —— 一句会让人得出相反结论的错误信息。注:web 镜像的 builder 阶段本来就有 node/npm,这里查的是 runner 阶段产物
/spike/* 全部 404(R1 验证脚手架不得进公网镜像;--services 白名单已在构建期挡住)。同时跑一组正式端点作对照——全站都 404 时这条会假通过
IMAGE_TAG 是 git SHA 而非 latest;该 SHA 与预发验过的完全一致
迁移已带外施加且版本可追溯;空库直起会 500 的坑已规避
postgres 仅在 back 内部网段可达(caddy/web 连不上)。域名 NXDOMAIN 不够,还要按容器 IP 直连 5432 也不通
/api/mcp 无 token / 错 token / 格式不对的 token / 未认证的 GET 全拒(401)且有审计记录;三种 401 的响应体必须完全一致、不回显失败原因。注:带正确 token 的 GET 是 405,不是 401(认证闸在方法校验之前)。可选 IP 白名单
SSE 事件流抽查:无 Authorization/api-key 字段。判据是结构化的——遍历每帧 JSON 看有没有凭据形状的键;grep -i authorization 会命中对话正文里的那个英文单词(R10 实测 7 次全是误报)
SSE 优雅关闭:docker compose stop api 时客户端在停机同刻(+0s)拿到确定的终止而非挂到超时。别钉死 curl 退出码(R9 见 18、R10 见 0,取决于断开落在响应分块的哪个位置)
限额:小额度演练超限路径(拒新会话 + 前端提示)
两个备案号都已挂上,且两种视口各看一次(ICP 链到 beian.miit.gov.cn;公安联网备案是「图标 + 号码」且链到 beian.mps.gov.cn/#/query/webSearch?code=<数字串>)。判据是在生产页面上看:.env 少填一项那半边就静默不渲染,本机与 130 都不配、看不出来。桌面看任意页的底栏;移动端(≤768px)看 About 页尾 —— 屏底那条在窄视口刻意不渲染(R-MOBILE-2,见 §1 第 6 步)
egress 出网过滤(R-WEBFETCH):sudo ~/deploy/egress-filter.sh --install-unit 跑过,sudo ~/deploy/egress-filter.sh --status 六条全 ok(退出码 0),systemctl is-enabled xray-egress-filter 回 enabled;容器内 create_connection(('169.254.169.254',80),3) 失败而 ('1.1.1.1',443) 成功(deploy-environments.md 冒烟第 21 条 ②)。compose 改了 egress 网段时脚本的 EGRESS_SUBNET 与单元文件里的值要一起改

B	~162MB(bun 口径;node 口径 228MB)	R-BUN 实测,见 rounds/round-bun/round-bun.md。每次升级 bun / pi / encore 版本重测
S_eventbuf_cap	每会话对抗性最坏 ~56MB	不用测,是代码里的结构性常数:MAX_EVENTS_PER_SESSION=2000 × 单事件 ≤8KB(MAX_EVENT_BYTES)≈16MB,加 PENDING_FLUSH_MAX=5000×8KB≈40MB(apps/api/spike/runtime.ts、apps/api/spike/events.ts)。R3 改这三个常数,预算随之改
S_active_p95 / S_stream_p95	目前证据不足	R1/R-BUN 只有空闲会话数字。R3/R4 落地后在预发用真实使用数据采 p95(长对话、大轨迹、并发流式各取),不做压测
N_active / N_streaming	先给保守值(8 / 4)	由 R3 的并发上限与空闲回收参数决定——是「配出来」的,不是「测出来」的
G	bun 口径需重新标定	bun 用 JSC 堆与自有分配器,RSS 语义与 V8 不同,Node 时代的余量系数不可迁移

部署:境内轻量服务器(阿里云 / 腾讯云)

0. 采购建议与容量规划

容量怎么算(不要用「每会话固定 X MB」)

1. ICP 备案清单(境内必做)

2. 服务器初始化(一次性)

3. 应用部署(不可变镜像)

4. Caddyfile 要点

5. 数据备份

6. 上线前检查单