46 KiB

Raw Blame History

运行手册

怎么把 zcbot 跑起来。env / 常用命令 / 故障兜底。设计看 DESIGN.md,进度看 PROGRESS.md。

最后更新:2026-06-01(update.sh 加自更新重跑守卫;默认源改腾讯/阿里滞后卡 litellm;build 跳过改 --skip-build;pip 不静默,build 走默认 TTY UI)

环境

Python:虚拟环境 .venv/,所有依赖装在里面。一律用 .venv/Scripts/python.exe ...(Windows)/.venv/bin/python ...(Unix),不要全局 python(litellm/python-pptx 等会 ModuleNotFoundError)。

配置文件 .env(项目根,git 忽略,litellm 自动加载):

DEEPSEEK_API_KEY=sk-...
# 用 GLM 的话再加一条;国际站 z.ai 用 ZAI_API_KEY,国内站 bigmodel.cn 用 ZHIPUAI_API_KEY(对应 config/models/glm.yaml 的 api_key_env 字段)
ZHIPUAI_API_KEY=...
# 豆包(火山方舟)图像/视频生成:可选。设了同时挂 seedream tool(0.22 元/张)与 seedance tool
# (Seedance 2.0 Fast,文生视频,480p 4s ¥1.86 ~ 720p 15s ¥12+,异步等 30-90s);未设两个 tool 都不出现
ARK_API_KEY=...
# documents skill(内部知识库 document_search API):可选。设了后注册
# document_list_kb / document_search / document_download 三个 host-side tool;
# key 只留宿主后端,sandbox/run_python 不读取。
DOCUMENT_SEARCH_API_KEY=...
# 可选:覆盖默认 base_url(默认 https://ai.ctc-zc.com:8100/api)
# DOCUMENT_SEARCH_URL=https://ai.ctc-zc.com:8100/api
# pymatgen skill 的 Materials Project 接入:可选。设了后注册
# mp_search_summary / mp_get_structure / mp_get_entries 三个 host-side tool;
# 离线分析(CIF / POSCAR + SpacegroupAnalyzer + XRDCalculator + CEMENT_PHASES)仍在 sandbox 跑。
# 申请 https://materialsproject.org/api(免费)
MP_API_KEY=...
# 本地 / 内网部署 LLM(`config/models/local.yaml`,DeepSeek-R1 满血 / QwQ-32B 原生 32K,
# 共享同一台推理服务 http://182.54.21.126:9000/v1)。涉密任务用户显式选 `local.r1` / `local.qwq`
# 代替默认 deepseek_v4.flash;未设 env 时这两条 variant 调用即抛 RuntimeError(其他模型不影响)
LOCAL_LLM_API_KEY=...
ZCBOT_DB_URL=postgresql://user:pass@host:5432/zcbot
# main.py web 必填(probe/db/user 不验)
PLATFORM_KEY=<≥16 字符随机串,platform 机器对机器入口校验>
JWT_SECRET=<≥32 字符随机串,HS256 签 session token;泄漏 = 任意伪造>
# 可选:覆盖默认 7d JWT TTL
# ZCBOT_JWT_TTL_SECONDS=604800
# 可选:设了之后登录页右下角"+ 管理员添加用户"入口才工作(未设 → 接口返 503)
# ZCBOT_ADMIN_TOKEN=<≥32 字符随机串,管理员发用户共享口令>

litellm 在 import 时副作用加载 .env;入口走 main.py,.env 自动生效。直跑 python -c "from core.storage import ..." 不经 litellm 链路时记得自己 import litellm 触发,或手动 export ZCBOT_DB_URL=...。

依赖:pip install -r requirements.txt(已在 .venv 里;含 bcrypt)。
PG:ZCBOT_DB_URL 必填。本地 docker compose / 远端 dev / 生产任选;未设置时启动清晰报错,不引导 docker(§7.4)。
Auth env:PLATFORM_KEY + JWT_SECRET 任一缺失 web 启动 fail-fast。生成随机串:python -c "import secrets; print(secrets.token_urlsafe(48))"。
用户管理(users.email/password_hash,0005 UNIQUE(email)):dev SPA 登录后端。发用户两条路径任选:CLI main.py user add(下方),或在登录页右下角"+ 管理员添加用户"链接(需先设 ZCBOT_ADMIN_TOKEN env,弹窗输入 email/密码/管理员口令)。撤用户 DELETE FROM users WHERE email=...(先 DELETE 该 user 的 tasks)。改密 / 改邮箱手动 SQL 或先 DELETE 再 add。

一次性初始化

# 1) 装依赖(若 .venv 不在)
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt

# 2) 准备 .env(见上)

# 3) DB schema 上车
.venv/Scripts/python.exe main.py db upgrade head
.venv/Scripts/python.exe main.py db current   # 应输出 0007 (head)

日常命令

入口 main.py {web, db, probe, user}。所有 task / 消息 / 文件交互走 main.py web 起服务后浏览器(dev SPA)或 platform 端 / curl 调 /v1/*。

Web 服务

# 默认 127.0.0.1:8765;dev SPA 在 /,Swagger UI 在 /docs
.venv/Scripts/python.exe main.py web
.venv/Scripts/python.exe main.py web --port 9000
.venv/Scripts/python.exe main.py web --reload   # 文件改动自动重启

DB / probe / user

# 模型能力对账(费 token)
.venv/Scripts/python.exe main.py probe --model deepseek_v4.flash
.venv/Scripts/python.exe main.py probe --model glm.pro          # 智谱 GLM-5.1(走 litellm zai provider + 国内站 bigmodel.cn)
.venv/Scripts/python.exe main.py probe --model local.r1         # 内网 DeepSeek-R1(满血,128K),涉密任务用;需 .env 设 LOCAL_LLM_API_KEY
.venv/Scripts/python.exe main.py probe --model local.qwen3      # 内网 Qwen3-30B-A3B(MoE,原生 32K);共享 LOCAL_LLM_API_KEY

# DB migration
.venv/Scripts/python.exe main.py db upgrade head
.venv/Scripts/python.exe main.py db downgrade -1
.venv/Scripts/python.exe main.py db current

# 发用户(两条路径,任选其一)
# a) CLI:
.venv/Scripts/python.exe main.py user add --email alice@example.com --password "atLeast6"
# → [ok] user added  email=alice@example.com  user_id=<uuid>
# b) 登录页右下角"+ 管理员添加用户":需先在 .env 里设 `ZCBOT_ADMIN_TOKEN`,
#    弹窗输入 email/密码/管理员口令,POST /v1/auth/admin/create_user 落库。
#    没设 env → 接口直接返 503,UI 入口会报"admin create_user disabled"。

# 可选:把已有 user_id(platform_key 入口创的)接到邮箱密码路径
.venv/Scripts/python.exe main.py user add --email bob@x.com --password "s3cret" --user-id <UUID>

# 撤用户:先清 tasks(messages CASCADE)再 DELETE user
# psql> DELETE FROM tasks WHERE user_id=(SELECT user_id FROM users WHERE email='alice@example.com');
# psql> DELETE FROM users WHERE email='alice@example.com';

Auth + curl 用 token 调 /v1/*

两条 login 路径,签同款 JWT。所有 /v1/tasks* 需 Authorization: Bearer <jwt>。

# 路径 1:邮箱密码(dev SPA / 同事试用 — 推荐)
curl --noproxy '*' -s -X POST http://127.0.0.1:8765/v1/auth/login_password \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"atLeast6"}'

# 路径 2:platform_key + 指定 user_id(机器对机器)
curl --noproxy '*' -s -X POST http://127.0.0.1:8765/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<UUID>","platform_key":"<value of $PLATFORM_KEY>"}'

# 调 /v1/*
TOKEN="eyJ..."
curl --noproxy '*' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8765/v1/tasks

dev SPA:打开 http://127.0.0.1:8765/(自动 302 → /static/dev.html),登录页两 tab(默认"邮箱密码",备用"UUID + PLATFORM_KEY",last-used 持久化 LS)进入 3 栏(task / chat / files)。给同事试用:main.py user add 发用户,不用重启 web(每次 login 都查 DB),把 URL + 邮箱密码分别发给同事。

iframe 嵌入(platform 主页内嵌):URL 加 ?embed=1&parent_origin=<父页面 origin>,触发 embed 模式 —— 藏左上 brand / 退出按钮,登录页不显示,新建任务挪到任务面板;父页面通过 postMessage 协议推 JWT(zcbot-ready / zcbot-token / zcbot-401)。完整对接手册见 EMBED.md(URL 参数 / 协议 / 后端 SSO 示例 / 父端前端示例 / 安全 / 故障兜底)。

路由表

全 JSON,CORS allow_origins=["*"];详细 schema 见 /docs。

方法 + 路径	用途	Auth
`GET /healthz`	`{"status":"ok"}`	豁免
`GET /`	302 → `/static/dev.html` dev SPA	豁免
`GET /docs` `/openapi.json`	Swagger UI / OpenAPI schema	豁免
`GET /static/*`	dev.html 等静态文件	豁免
`POST /v1/auth/login`	platform 机器对机器;body `{user_id, platform_key}` → `{token,expires_at,user_id,ttl_seconds}`	豁免
`POST /v1/auth/login_password`	dev SPA 邮箱密码;body `{email, password}` → `{token,...,email,...}`;邮箱不存在 / 密码错 / 未设密码统一 403	豁免
`POST /v1/tasks`	创建 task,body `{name(req), working_dir?, description?, skill?}`	必填
`GET /v1/tasks?page=&page_size=&status=&skill=&working_dir=&q=&ordering=`	列任务,默认 `-created_at`;响应 `{page, page_size, count, results}`;`ordering` DRF 风格逗号分隔 `-field` 倒序,allowlist created_at/updated_at/name/status	必填
`GET /v1/tasks/{id}`	单 task meta + `n_messages`;跨 user → 404	必填
`PATCH /v1/tasks/{id}`	`{status?,description?,name?,skill?}`;active 不让从 web 切回	必填
`DELETE /v1/tasks/{id}`	硬删 DB 行(messages CASCADE);若 working_dir 已无其他 task 引用且 FS 目录为空 → 顺手 rmdir 清孤儿(非空 / 外部 --working-dir 静默跳过)	必填
`GET /v1/folders`	列当前 user 工作目录 + n_tasks + last_used	必填
`GET /v1/tasks/{id}/messages`	LiteLLM payload 透传	必填
`POST /v1/tasks/{id}/messages`	`{content, image_model?=""}` 发消息;返 `{events_url}`;`run_status` 是 running/cancelling → 409(单活 run;error 起新 run 时清);`image_model` 是 `config/media/doubao.yaml` image 段的 variant key(空 → 沿用 yaml 第一个),仅本 run 装配 SeedreamTool 时使用,不入 DB;UI 应 disable send 直到 SSE `done`	必填
`GET /v1/tasks/{id}/events`	SSE 流(`event: <type>` + `data: <json>`);订阅 task 当前活动	必填
`POST /v1/tasks/{id}/cancel`	协作式 cancel;`run_status != running` → 409;LLM 走 streaming,chunk 间 poll cancel — 延迟 100ms 级,基本秒退	必填
`POST /v1/tasks/{id}/clear`	清空当前 task 全部 messages + reset `tasks.tokens_prompt/completion/cost_cny` 三列累计 + `run_status='idle'`;`usage_events`(账单记账)不动,只 `message_id` 列变 NULL;run 活跃中(running/cancelling)→ 409(先 cancel);FS 文件保留	必填
`POST /v1/tasks/{id}/optimize_prompt`	body `{text(req, ≤4000), image_model?=""}`;同步调当前 task model 润色草稿,返 `{optimized, model_profile, tokens_in, tokens_out, cost_cny}`;不写 messages、不累计 task 三列(顶栏数字不污染),只在 `usage_events` 写一行 `kind="prompt_optimize"`(对账可见);不与主对话 run 互斥(允许 streaming 中并行润色)	必填
`GET /v1/files?path=`	列 user_root 下条目 + 面包屑;dotfile 隐藏	必填
`GET /v1/files/download?path=`	下单文件	必填
`POST /v1/files/upload`	multipart 上传到 `<user_root>/<path>/`;路径不存在自动 mkdir,重名覆盖	必填
`POST /v1/files/delete`	`{path, recursive?=false}`;`recursive=false` 文件或空目录(非空 → 400);`recursive=true` `shutil.rmtree` —— 顶层目录被 task 引用 → 409(先 DELETE task);空目录两种模式都可删,task.working_dir 字段不动,下次 build_agent 按需 mkdir 重建	必填
`POST /v1/files/rename`	`{path, new_name}`;sibling 已存在 → 409;path 顶层目录 → 同事务 UPDATE tasks.working_dir + FOR UPDATE 锁;有 running/cancelling → 409;check_no_subtask 防嵌套 → 409	必填
`GET /v1/tasks/{id}/export`	对话导出 .docx	必填
`GET /v1/models`	列 chat LLM 模型清单(扫 `config/models/*.yaml`),前端顶栏切换 / 新建对话框下拉用	必填
`GET /v1/image_models`	列图像生成 variant 清单(扫 `config/media/doubao.yaml` image 段),前端"生图"下拉用;yaml 无 image variant → 空列表 → UI 隐藏下拉	必填

SSE 事件(每帧 event: <type> + data: <JSON>):run_start{} → llm_start{} → text{delta} / tool_call{name,args,args_preview} / tool_result{name,preview,truncated} → llm_end{prompt_tokens,completion_tokens} → done{};cancel 走 cancelled{} 后随 done{} 收流;异常走 error{msg}。30s 无 event 服务端发 : ping 心跳。nginx 反代记得关 buffering(响应头已带 X-Accel-Buffering: no 默认起效)。

SSE 客户端注意:浏览器原生 EventSource 不支持自定义 header,无法塞 Bearer token。要么 fetch + ReadableStream 自解 SSE 帧(dev.html 走的就是这条),要么后端日后加 ?token=... query(目前不支持,避免 token 进 access log)。

部署(Ubuntu / systemd)

单机最小拓扑:/opt/zcbot/(代码 + .venv + .env)+ systemd unit。按需改路径 / user / port。

一次性

sudo useradd -r -s /sbin/nologin -d /opt/zcbot zcbot   # 跑服务的非 root 用户
sudo chown -R zcbot:zcbot /opt/zcbot
# 把 .env 权限收紧(含 JWT_SECRET / PLATFORM_KEY)
sudo chmod 600 /opt/zcbot/.env
sudo chown zcbot:zcbot /opt/zcbot/.env

unit 文件 `/etc/systemd/system/zcbot.service`

[Unit]
Description=zcbot web (FastAPI/uvicorn)
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=zcbot
WorkingDirectory=/opt/zcbot
# 显式让 systemd 装载 .env(KEY=value 行,不展开 ${...},不留 shell 引号)
EnvironmentFile=/opt/zcbot/.env
ExecStart=/opt/zcbot/.venv/bin/python main.py web --host 0.0.0.0 --port 8765
Restart=on-failure
RestartSec=2
KillSignal=SIGTERM
# uvicorn graceful shutdown 会等 in-flight 请求(含 SSE 长连接);
# 10s 后 systemd 兜底 SIGKILL,避免 SSE 拖住 restart 卡死
TimeoutStopSec=10
KillMode=mixed
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

启用 + 日常:

sudo systemctl daemon-reload
sudo systemctl enable --now zcbot
sudo systemctl status zcbot | head
sudo journalctl -u zcbot -f                   # 实时日志
sudo systemctl restart zcbot                  # 重启(REST 抖动 ~2s,SSE 连接断)
sudo systemctl stop zcbot

不要再用 kill -HUP:uvicorn 不响应 SIGHUP(没装 handler,落 Python 默认),也不会 reload 代码。Ubuntu 上要么 systemctl restart,要么用下面 --reload 自动模式。

无感更新(对 SSE 也尽量不抖)

zcbot 现在 5 人级 + SSE 长连接,严格"零中断"(蓝绿 + nginx + SSE 客户端 reconnect 设计)代价高,不值得。有性价比的两挡:

A. 简易档:--reload(推荐当前规模) ExecStart 加 --reload,git pull 后 uvicorn 监听到文件变动自动重起子进程,REST 抖动 < 1s。代价:SSE 连接被切断,dev.html 自动重连 3 次(1s/2s/4s 退避);若新进程已被启动 reaper 标 run_status=error,重连立即收 done,卡片末尾追加红色"连接已断开,请重发"。期间 LLM 吐的 delta 丢失(broker 不持久化 event,接受)。3 次仍失败 → 同上提示,用户重发即可。

ExecStart=/opt/zcbot/.venv/bin/python main.py web --host 0.0.0.0 --port 8765 --reload

sudo systemctl restart zcbot 一次生效。之后只 git pull 即可,不用再 restart;改 unit 文件本身才需 daemon-reload + restart。

B. 真无感档:nginx + 蓝绿双实例(将来流量上来再上) 两个 systemd 实例 zcbot@blue / zcbot@green(模板 unit,--port 8765 / --port 8766),nginx upstream 在中间切。流程:

部署到空闲实例(假设 green):sudo systemctl restart zcbot@green
curl 127.0.0.1:8766/healthz 验新版起来
改 nginx upstream 指向 green,nginx -s reload — 新 REST 走 green,旧 SSE 还连在 blue 不断
等 blue SSE 自然清空(ss -tnp | grep :8765 为空)再关 blue

zcbot 端额外要做的事:消息 broker 当前在 task 进程内(web/broker.py),蓝绿期间同 task 不同进程会丢事件。nginx 侧用 hash $arg_task_id consistent 保同 task 落同实例可以缓解,但 task 创建分布是另一回事。要做这条得先把 broker 改成 Redis pub/sub。10 人内不推,留到真有需要再上。

部署 SOP

一把梭(推荐):deploy/update.sh

# 在服务器上,root 跑(脚本内部文件操作降到 zcbot 用户)
sudo bash /opt/zcbot/deploy/update.sh
# 或(已带可执行位):sudo /opt/zcbot/deploy/update.sh

脚本顺序写死:git pull --ff-only → pip install -r → db upgrade head → docker build sandbox 镜像 → systemctl restart zcbot → curl /healthz 验活。要点:

build 必须在 restart 之前:sandbox 容器 per-user 长驻 + 复用,tools/ 是 build 进镜像的(非 mount)。restart 时 shutdown_all 清旧容器,下次 ensure() 才用新 zcbot-sandbox:latest 重建 —— 顺序反了新 tools/ 要等下次重启才生效。
sandbox build 每次都跑没关系:layer cache 让重活(pip ~1G / chromium / 字体 / mermaid,都在 COPY tools/ 之上)在改代码部署时秒过;只有 requirements.txt 变了才整体重建(~5-10min,正好也是该重建的时候)。host backend 机器 / 临时不想动 docker:sudo bash deploy/update.sh --skip-build。
镜像源默认腾讯(APT_MIRROR=mirrors.cloud.tencent.com / PIP_INDEX_URL=mirrors.cloud.tencent.com/pypi/simple/ / NPM_REGISTRY=mirrors.cloud.tencent.com/npm/,境内快且新包同步及时)。阿里 PyPI 镜像同步滞后(litellm 一度只到 1.82.6,卡死 requirements.txt 的 >=1.83.0),故默认避开阿里。要命中 docker cache 就别两组源来回换(换源从 pip 层炸开全重跑)。想用官方源:PIP_INDEX_URL= sudo -E bash deploy/update.sh(置空即回落 Dockerfile 官方默认)。host venv 的 step 2 pip 也吃这个源(脚本显式 --index-url,不靠 host pip.conf)。
进度可见:step 2 pip 不带 -q,部署时能看到装包进度;step 4 docker build 走默认 TTY 进度 UI(分层折叠刷新,直观)。
脚本会自更新重跑:git pull 若动了 deploy/update.sh 本身,脚本会 exec 新版本从头重跑(旧脚本的变量默认值在 pull 前就求值了、bash 又按字节偏移边读边跑,不重跑会跑出过期行为 —— 这是首次拉到改 update.sh 的提交时"改了源还报旧错"的根因)。日志出现「update.sh 自身有更新 —— 用新版本重跑」即正常;ZCBOT_UPDATE_REEXEC=1 防死循环。
migration 取 DB URL:db/migrations/env.py 直接读 os.environ['ZCBOT_DB_URL'](不读 .env),脚本从 .env 抠出来显式 env ZCBOT_DB_URL=... 喂进 main.py db upgrade。
前置守卫:非 root / 不是 git 仓库 / 工作区脏(已跟踪文件有未提交改动)/ 缺 .env → 直接中止。/healthz 15s 内不返回 ok → dump journalctl -n 50 并以非零退出。

一次性 bootstrap(useradd / 写 unit / enable --now)见上方"一次性"段,不在 update.sh 里。改 .env / unit 文件本身后,update.sh 的 restart 一样会让新 .env 生效;但改 unit 的 [Unit]/[Service] 字段需先手动 sudo systemctl daemon-reload。

手动逐条(脚本跑挂了排查用)

cd /opt/zcbot
sudo -u zcbot git pull --ff-only
sudo -u zcbot .venv/bin/python -m pip install -r requirements.txt
sudo -u zcbot env ZCBOT_DB_URL="$(grep ^ZCBOT_DB_URL= .env | cut -d= -f2-)" \
    .venv/bin/python main.py db upgrade head
sudo -u zcbot docker build -f deploy/sandbox/Dockerfile \
    --build-arg HOST_UID=$(id -u zcbot) --build-arg HOST_GID=$(id -g zcbot) \
    -t zcbot-sandbox:latest .
sudo systemctl restart zcbot
curl -fsS http://127.0.0.1:8765/healthz                # {"status":"ok"}
sudo journalctl -u zcbot -n 50

Sandbox(Stage C,Ubuntu)

为外部用户开放前必须完成。当前 dogfood + 信任同事白名单阶段可跳过 ── 默 backend = host, shell / run_python 仍走 subprocess(未隔离)。Step 3 已接入 DockerExecutor: ZCBOT_SANDBOX_BACKEND=docker 切容器执行;host(默)保留本地 Windows / 同事 dogfood。

启用 docker backend 的前置条件:

部署机有 docker daemon,zcbot 用户在 docker group

zcbot-sandbox:latest 镜像已 build(HOST_UID/GID 对齐)

.env 至少有 ZCBOT_PG_IPS=<PG实际IP>(§7.5 #1 PG 单独 block 一遍)

lifespan 启动失败会 fail-fast(RuntimeError: sandbox init failed),不静默退到 host

镜像构建

容器内 uid/gid 与 host zcbot 用户必须对齐(bind mount 保 host owner;错配导致 EACCES):

# 1) 确保 zcbot 用户存在,uid 拿出来
id -u zcbot      # 期望:整数,后面用作 HOST_UID
id -g zcbot      # 期望:整数

# 2) 构建镜像(build context = repo 根)
cd /opt/zcbot
sudo -u zcbot docker build \
    -f deploy/sandbox/Dockerfile \
    --build-arg HOST_UID=$(id -u zcbot) \
    --build-arg HOST_GID=$(id -g zcbot) \
    -t zcbot-sandbox:latest .

# 境内访问 PyPI 抖动 / ReadTimeout → 加 --build-arg 切换镜像源:
#   腾讯云内网(腾讯云轻量 / CVM 上免外网带宽):
#     --build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/
#   阿里云:
#     --build-arg PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
#   清华:
#     --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/
# 镜像源走 https,通常不需 --trusted-host;若用 http 源加
#     --build-arg PIP_TRUSTED_HOST=<host_without_scheme>

# apt 源同款(chromium + nodejs + npm 体积大,deb.debian.org 境内慢):
#   --build-arg APT_MIRROR=http://mirrors.cloud.tencent.com    # 腾讯云内网(推 http,见下)
#   --build-arg APT_MIRROR=http://mirrors.aliyun.com           # 阿里云
# 推荐 http 而非 https:apt 包用 GPG 签名校验,HTTPS 无额外安全收益,且腾讯云
# 内网 mirror 走 https 偶发触发 OpenSSL 3 严格的 `unexpected eof while reading`
# (旧版 OpenSSL 1.1.1 容忍,新版 fail)。Dockerfile 已加 apt retry=5 + 关
# pipeline + no-cache 兜底偶发抖动。

# npm 源同款(@mermaid-js/mermaid-cli + 依赖,境内访问 registry.npmjs.org 也慢):
#   --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/   # 腾讯云
#   --build-arg NPM_REGISTRY=https://registry.npmmirror.com/          # 阿里(npmmirror)
# 镜像内自带 Chromium + mermaid-cli + puppeteer-config.json,proposal/patent skill
# 的 render_diagrams.py 看到 MERMAID_PUPPETEER_CONFIG env 自动 -p 注入,
# host 上跑时该 env 没设,行为不变

# 3) 创建 sandbox 网络(--internal,默认无 outbound)
sudo -u zcbot docker network create --internal zcbot-sandbox-net
# 或 SandboxPool.setup_pool() 自动 ensure

Sandbox 相关 env(.env 加)

# Backend 选择(默 host):
#   host   = shell/run_python 走 host subprocess(本地 Windows / dogfood)
#   docker = shell/run_python 走 per-user 容器 docker exec(部署机 / 外部用户)
# ZCBOT_SANDBOX_BACKEND=docker

# 容器内 exec 用户(默 zcbot,docker 查容器 /etc/passwd 拿 uid)
# ZCBOT_SANDBOX_EXEC_USER=zcbot

# 容器镜像 tag(默 zcbot-sandbox:latest)
# ZCBOT_SANDBOX_IMAGE=zcbot-sandbox:latest
# 容器 runtime(切 gVisor 用 runsc,Firecracker 用 kata;默 runc)
# ZCBOT_SANDBOX_RUNTIME=
# 空闲多少秒回收(默 300)
# ZCBOT_SANDBOX_IDLE_TTL=300
# 资源限制(优先级 env > yaml `sandbox.*` > 默);改后重启 web 新起容器生效
# ZCBOT_SANDBOX_MEMORY=2g
# ZCBOT_SANDBOX_CPUS=1.0
# ZCBOT_SANDBOX_PIDS_LIMIT=256
# PG 实际 IP,逗号分隔。defense-in-depth ── 即便落内网三段(§7.5 #1),
# init.sh 再加一遍 DROP 规则。生产部署必填。
ZCBOT_PG_IPS=10.1.2.3,10.1.2.4

# workspace 根目录(per-host 覆盖)。来源只有两个:这条 env,或 yaml `workspace_dir`
# (默值 = `workspace`);env 设了就用 env,没设就用 yaml 那条。两者都按 `ROOT/<值>` 解析
# (绝对路径直接生效,相对路径挂 repo 根下)。所以**不设这条 env → 走 yaml 的
# workspace_dir=workspace → ROOT/workspace(即 zcbot 下的 workspace)**,dev 维持原样。
# prod 设成数据盘绝对路径,把重写入的 user 子树落过去(下方「workspace 落独立数据盘」段),
# 不碰提交进仓库的 agent.yaml,两边不抢同一份配置。
# ZCBOT_WORKSPACE_DIR=/data/zcbot-workspace

验证

Step 3 之后,推荐用集成验证(web 起 docker backend + dev SPA 发 shell / run_python 消息):

# 启动 web 时切 docker backend(.env 已设 PG_IPS / SANDBOX_BACKEND=docker)
ZCBOT_SANDBOX_BACKEND=docker .venv/bin/python main.py web

# 触发任一 shell / run_python 消息后,容器应已起
sudo -u zcbot docker ps --filter label=zcbot.product=sandbox
# 应看到 zcbot-sandbox-<your-uid>,STATUS = Up ...
# 5 分钟无新消息后 reaper 自动 rm

也可直接起一个测试容器单验 hardening(不依赖 web 进程):

USER_ID=00000000-0000-0000-0000-000000000001
sudo -u zcbot docker run -d \
    --name zcbot-sandbox-$USER_ID \
    --label zcbot.product=sandbox \
    --label zcbot.user_id=$USER_ID \
    --network zcbot-sandbox-net \
    --read-only --tmpfs /tmp:exec,size=512m,mode=1777 \
    --cap-drop=ALL --cap-add=NET_ADMIN \
    --security-opt=no-new-privileges \
    --pids-limit=256 --memory=2g --cpus=1.0 \
    -v /opt/zcbot/workspace/users/$USER_ID:/workspace \
    -e ZCBOT_PG_IPS=10.1.2.3 \
    zcbot-sandbox:latest

# 看 iptables 规则确实 apply 了(应 6+1 条 DROP)
sudo -u zcbot docker exec zcbot-sandbox-$USER_ID iptables -L OUTPUT -n --line-numbers

# 看 non-root 用户(uid 应 = host zcbot uid)
sudo -u zcbot docker exec --user $(id -u zcbot):$(id -g zcbot) \
    zcbot-sandbox-$USER_ID id

# 看 rootfs read-only(应报 Read-only file system)
sudo -u zcbot docker exec --user $(id -u zcbot):$(id -g zcbot) \
    zcbot-sandbox-$USER_ID touch /badtest

# 销毁
sudo -u zcbot docker rm -f zcbot-sandbox-$USER_ID

Step 4 引入 egress proxy 后,完整 5 条红队用例(metadata / loopback / 跨 user / nohup 残留 / allowlist 外 403)进 tests/test_sandbox_redteam.py 自动化跑。

Stage C 完整部署速查

首次部署 / 改了 init.sh / Dockerfile / requirements.txt → 重 build:

cd /home/lighthouse/zcbot
docker build -t zcbot-sandbox:latest -f deploy/sandbox/Dockerfile \
    --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) \
    --build-arg APT_MIRROR=http://mirrors.cloud.tencent.com \
    --build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/ \
    --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ \
    .

只改 host 侧 docker run flag / pool.py(没动 Dockerfile / init.sh)→ 不用重 build, 清旧容器 + 重启 web 即可:

docker rm -f $(docker ps -aq -f label=zcbot.product=sandbox) 2>/dev/null
systemctl restart zcbot

跑 migration(新增 / 修改了 db/migrations/versions/* / models.py):

.venv/bin/python main.py db upgrade head

启用 docker backend 重启 web(确保 .env 有 ZCBOT_SANDBOX_BACKEND=docker 或 systemd unit 已设):

systemctl restart zcbot
journalctl -u zcbot -e --no-pager | tail -30   # 看 startup log
# 应见:
#   [startup] [warn] fs quota: ext4 on ... (dogfood 阶段 warn 正常)
#   [startup] swept N stale sandbox container(s)
#   [disk_scanner] initial scan: N user(s)
#   INFO: Uvicorn running on 0.0.0.0:8765

日常运维 / 验证

# 当前活跃 sandbox 容器
docker ps --filter label=zcbot.product=sandbox \
    --format 'table {{.Names}}\t{{.Status}}\t{{.RunningFor}}'

# 某容器跑了什么(看 docker run 完整参数 + env + mount)
SBC=$(docker ps -q -f label=zcbot.product=sandbox | head -1)
docker inspect $SBC --format '{{json .Config.Env}}' | python3 -m json.tool
docker inspect $SBC --format '{{json .HostConfig.Binds}}'

# 容器内 DNS + 网络验证(应见 nameserver 8.8.8.8 / 114.114.114.114)
docker exec $SBC cat /etc/resolv.conf
docker exec $SBC getent hosts www.baidu.com
docker exec $SBC curl -sI -m 5 https://www.baidu.com | head -1

# iptables 规则(应见红线段 DROP + 127.0.0.11:53 ACCEPT 例外)
docker exec $SBC iptables -L OUTPUT -n --line-numbers

# 容器内 zcbot user 与 host 对齐(uid 应一致)
docker exec $SBC id
id   # host 上跑

# 容器资源占用
docker stats --no-stream $SBC

# 看本会话 sandbox 启动 stderr(init.sh 的 [init] ... 行)
docker logs $SBC

# 杀某 user 容器(强制下次 ensure 重建,可用于 hotfix 后切镜像)
docker rm -f zcbot-sandbox-<user-uuid>

# 清所有 sandbox 容器(reaper 兜底,不影响 web 进程)
docker rm -f $(docker ps -aq -f label=zcbot.product=sandbox) 2>/dev/null

磁盘配额查看(0008 表):

# 当前所有 user 用量
psql "$ZCBOT_DB_URL" -c "
    SELECT user_id, bytes_used/1024/1024 AS mb, file_count, scanned_at
    FROM user_disk_usage ORDER BY bytes_used DESC;"

# 强制扫描某 user(改 yaml interval 太久不耐烦时)
.venv/bin/python -c "
from pathlib import Path
from uuid import UUID
from core.storage.disk_quota import scan_user_dir, upsert_user_usage
uid = UUID('<your-user-uuid>')
b, c = scan_user_dir(Path('/home/lighthouse/zcbot/workspace/users') / str(uid))
upsert_user_usage(uid, b, c)
print(f'{b/1024/1024:.1f} MB / {c} files')"

DNS / resolv.conf 文件位置(host 侧):

# 由 SandboxPool 在首次 _docker_run 时生成,每次重建容器会覆盖刷新
cat /home/lighthouse/zcbot/workspace/.sandbox/resolv.conf

部署前置对账

切 ZCBOT_SANDBOX_BACKEND=docker 之前跑一次:

sudo -u zcbot .venv/bin/python main.py sandbox check

输出形如 [ok] / [warn] / [err] × 5 项 + 汇总 N/5 passed,exit code 0=可启动 / 1=有 err 要修。5 项对应:① docker daemon 可达 ② zcbot-sandbox:latest 镜像存在 ③ zcbot-sandbox-net network 存在(缺也能跑,lifespan 自动 ensure)④ 镜像内 zcbot uid 与 host uid 对齐(错配 → exec 写 /workspace 全 EACCES)⑤ workspace/users/ 所在 fs 类型可 quota。

lifespan 启动时同样会打第 ⑤ 项的 WARN 到 stdout([startup] [warn] fs quota ...), 应用层周期扫描仍生效;仅外部用户开放前必须把 ⑤ 升级到 OS 层 quota。

workspace 落独立数据盘(prod,大空间 + quota fs)

prod 的 workspace/users/<uuid>/ 是重写入区(报告 / 图 / pptx 等大件落这,DB 只存元数据)。推荐挂一块独立数据盘(xfs prjquota),空间和 OS 层配额一步到位。dev 不动 —— 走提交进仓库的相对 workspace_dir(= ROOT/workspace);prod 在 systemd unit 里设 env ZCBOT_WORKSPACE_DIR 指到数据盘,两边不抢同一份 agent.yaml。

PG 不必跟着搬:它是元数据库,长期个位数~几十 G,根盘够用;留默认 /var/lib/postgresql/<ver>/main 更省坑(pg_ctlcluster / AppArmor 按标准路径来)。等 pg_database_size 真奔 30–40G、根盘紧了再迁,那时 /data 下加个 postgresql/ 子目录布局照样兼容。

# 假设新盘是整块裸盘 /dev/vdb(lsblk 看,无分区表直接整盘格,数据盘惯例)
# 0) 停服务(迁移时别再写 workspace)
sudo systemctl stop zcbot

# 1) 整盘格 xfs
sudo mkfs.xfs /dev/vdb

# 2) 写 fstab(UUID + prjquota),挂 /data
sudo mkdir -p /data
UUID=$(sudo blkid -s UUID -o value /dev/vdb)
echo "UUID=$UUID /data xfs defaults,prjquota 0 0" | sudo tee -a /etc/fstab
sudo mount -a
findmnt -no FSTYPE,OPTIONS /data            # 期望:xfs ... prjquota

# 3) 迁现有 workspace 数据(prod 若 workspace 还空则跳过 rsync),owner 对齐跑服务的账号
sudo rsync -aXS /home/ubuntu/zcbot/workspace/ /data/zcbot-workspace/
sudo chown -R ubuntu:ubuntu /data/zcbot-workspace   # uid 必须 == 容器内 zcbot(HOST_UID)

# 4) systemd unit 加 env 指过去(Environment= 或 EnvironmentFile 的 .env),重启
#    Environment=ZCBOT_WORKSPACE_DIR=/data/zcbot-workspace
sudo systemctl daemon-reload && sudo systemctl start zcbot
python3 main.py sandbox check               # fs quota 那项应变 [ok]

确认 sandbox check 通过、新 task 文件确实落 /data/zcbot-workspace/users/... 后,再删旧 /home/ubuntu/zcbot/workspace。

配额硬化(§7.5 #4,外部开放前必做)

应用层磁盘配额能挡常规超额,但扫描间隙打满共享 fs 拖死同节点这条硬要 OS 层 quota。sandbox check 第 ⑤ 项会探测当前 fs 状态:

探测结果	含义	处理
`fs quota: xfs with prjquota on ...`	ok,可直接 `xfs_quota -x` 给 user 加配额	(无需处理)
`fs quota: ext4 with project quota on ...`	ok,可 `quota -P`	(无需处理)
`fs quota: zfs on ...`	ok,在 dataset 层 `zfs set quota=`	(无需处理)
`fs quota: xfs ... NO prjquota mount option`	fs 支持但 mount 时没启	见下方 xfs 步骤
`fs quota: ext4 ... NO project quota option`	同上	`sudo tune2fs -O project,quota <dev>` + remount
`fs quota: btrfs ...`	qgroup 配置复杂	生产推荐换 xfs 单独分区,或自行验 `btrfs qgroup`
`fs quota: tmpfs/overlay/...`	通常 Docker-in-Docker 或本地 dev	生产必须挂独立分区

xfs 升级步骤(推荐方案):

# 1) 确认 workspace 在哪个 mount(假设 /opt 是独立 xfs 分区)
findmnt --target /opt/zcbot/workspace

# 2) 启用 prjquota(写入 /etc/fstab 让 reboot 后保留)
sudo mount -o remount,prjquota /opt

# 3) 给某 user 加 project quota(<pid> 自定义整数 id,与 user_id 映射建表跟踪)
echo "1001 /opt/zcbot/workspace/users/<user_uuid>" | sudo tee -a /etc/projects
echo "zcbot_<user_uuid>:1001" | sudo tee -a /etc/projid
sudo xfs_quota -x -c "project -s zcbot_<user_uuid>" /opt
sudo xfs_quota -x -c "limit -p bhard=10g zcbot_<user_uuid>" /opt

<pid> ↔ user_uuid 映射手工维护(/etc/projects 是数字 id,zcbot 侧需建表追踪; 首期外部开放前补一个 main.py sandbox quota-set --user-id <uuid> --gb 10 子命令 读写 /etc/projects + 调 xfs_quota,这是 Step 4 / 5 之后真上线前一步,当前不做)。

不做这步等于"软配额 + 信任用户不写满" -- dogfood + 信任同事白名单阶段够用, 外部用户开放是 hard prereq。

故障兜底

现象	原因 / 处理
`ZCBOT_DB_URL is not set`	`.env` 没写 / litellm 链路没触发。直跑脚本时 `import litellm` 或 `export ZCBOT_DB_URL=...`
`ModuleNotFoundError: litellm`	用了全局 `python`,改 `.venv/Scripts/python.exe ...`
Windows 控制台 emoji 崩	Python stdout 是 GBK。用 `[OK]` / `[ng]` 等 ASCII 标签(见 memory)
`db upgrade` 报 `column already exists`	DB 已被改过,`db current` 确认 revision,必要时手 ALTER 或 `db downgrade base` 重来
Resume 找不到 task	dev SPA 左侧 task 列表看 task_id 是否在;或 `curl /v1/tasks` 拉
`--working-dir` 指定后 task 删了目录还在	两种情况:① 目录非空(有用户文件) — 设计如此,绝不 rmtree,手动 `rm -rf <dir>` 清;② 外部 `--working-dir`(DB 存绝对路径)— 不自动清,避免误删用户外部项目。ROOT 内 + 同 working_dir 无其他 task 引用 + FS 空 → DELETE task 时已自动 rmdir
Sandbox 容器内 `touch /workspace/x` 报 `Permission denied`	容器 uid 1000 与 host `zcbot` 用户 uid 不一致(bind mount 保 host owner)。`docker build --build-arg HOST_UID=$(id -u zcbot)` 重建镜像
Sandbox 容器 build 完起不来,`docker logs` 显示 iptables 报错	缺 NET_ADMIN cap(`--cap-add=NET_ADMIN` 漏了)或 kernel 不支持(WSL2 / OpenVZ 环境不能跑)。Ubuntu 物理 / KVM 正常。验:`docker exec ... iptables -V`
启动报 `ZCBOT_SANDBOX_BACKEND=docker but sandbox init failed: ...`	docker daemon 没起 / 用户不在 docker group / network create 失败。先跑 `main.py sandbox check` 看哪一项 err
`[startup] [warn] fs quota: <fstype> on ...`	workspace 所在 fs 没启 OS 层 quota。dogfood 阶段忽略;外部用户开放前必须升级 xfs prjquota / ext4 project / zfs(详 RUN.md「配额硬化」段)
prod 想把 workspace 落独立数据盘,但 `agent.yaml` 是 dev/prod 共用提交的	别改 `workspace_dir`(会带歪 dev)。prod systemd 设 env `ZCBOT_WORKSPACE_DIR=/data/zcbot-workspace`(优先级 env > yaml > 默)。详「workspace 落独立数据盘」段
`docker run zcbot-sandbox:latest` 报 `Unable to find image`	镜像没 build。`sudo -u zcbot docker build -f deploy/sandbox/Dockerfile --build-arg HOST_UID=$(id -u zcbot) --build-arg HOST_GID=$(id -g zcbot) -t zcbot-sandbox:latest .`
镜像 build pip 报 `ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', ...)`	境内访问 PyPI 抖动。加 `--build-arg PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/`(腾讯云内网)或阿里云 / 清华源,详 RUN.md「镜像构建」段。Dockerfile 已把 pip timeout 拉到 60s,主因仍是源不通而非超时
pip 报 `Could not find a version that satisfies the requirement litellm>=1.83.0`(伴随一串 `Ignored ... yanked versions: 0.1.xxxx`)	用的镜像源同步滞后,没有该新版本。阿里 PyPI 一度只到 litellm 1.82.6 —— update.sh 默认已改腾讯源(到 1.88)。若手动 build 撞到:换 `PIP_INDEX_URL=https://mirrors.cloud.tencent.com/pypi/simple/` 或清华源。那串 `0.1.xxxx` 是 litellm 远古版本,纯干扰信息
镜像 build npm 装 mermaid-cli 慢 / fail	npm 源境内慢。加 `--build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/`(腾讯云)或 `https://registry.npmmirror.com/`(阿里)
镜像 build apt 报 `OpenSSL error: ... unexpected eof while reading`	腾讯云 / 阿里 mirror HTTPS 端偶发 close_notify 缺失,OpenSSL 3 严格 fail。改用 http 形式:`--build-arg APT_MIRROR=http://mirrors.cloud.tencent.com`(apt 包 GPG 签名校验,无 HTTPS 安全收益)。Dockerfile 已配 apt retry=5 + 关 pipeline,重 build 一般直接过
容器内 shell 写工作目录报 `Permission denied`(but `sandbox check` ⑤ HOST_UID aligned ok)	DockerExecutor 写死了 `--user 1000:1000` 不会自动跟 build 的 HOST_UID 同步(改 `--user zcbot` 后已修)。仍报错检查镜像内 `docker run --rm --entrypoint id zcbot-sandbox:latest zcbot` 输出 uid 是否 = `id -u $(whoami)`
模型用 run_python 跑 `render_diagrams.py` 报 `mmdc returncode=1: Failed to launch chromium`	容器内 chromium 缺 puppeteer no-sandbox 配置。镜像已落 `/sandbox/puppeteer-config.json` + ENV `MERMAID_PUPPETEER_CONFIG`,render_diagrams.py 已读 env 自动 -p 注入;仍跪查 `docker exec ... env \| grep MERMAID` 看 env 是否在
Export 报 "无可导出内容"	task 没 messages(只 system 不算);先发条消息再 export
`NoSubtaskError: working_dir ... 前缀嵌套`	§7.4 no-subtask:同 user 不允许 working_dir 嵌套(child / parent)。同项目多对话用完全相同的 working_dir;否则改成 sibling(平级)
`main.py web` 启动后 curl 连不上	检查 proxy(`HTTP_PROXY` / `HTTPS_PROXY`):本地服务 127.0.0.1,系统 proxy 拦截会 502。临时 `unset HTTP_PROXY HTTPS_PROXY` 或 `curl --noproxy ''`。验通:`curl --noproxy '' http://127.0.0.1:8765/healthz`
SSE 卡住不流(经 nginx)	反代要关 buffering — 后端响应头已带 `X-Accel-Buffering: no`(nginx ≥1.5.6 默认认)。仍卡看 nginx 配 `proxy_buffering off; proxy_read_timeout 3600s;`
platform CORS preflight 失败	本地 dev `allow_origins=["*"]` 应该没事;部署后看是否按 platform 域名收紧过头
`POST /v1/tasks/{id}/messages` 返 409 `task already has an active run`	上一条消息的 BG run 还没跑完;等流式 done 或点 stop / `POST .../cancel`;服务异常下 `run_status` 卡 `running`/`cancelling`,启动 reaper 会清
`POST /v1/tasks/{id}/cancel` 返 409 `task not running`	`run_status` 不是 `running`(idle / cancelling / error 都不能 cancel);dev SPA 自动忽略不报错
`POST /v1/tasks/{id}/clear` 返 409 `task has an active run`	当前 run 还没跑完;先点停止 / `POST .../cancel` 等流式 done 再清空
点 stop 后流式没立刻停	streaming 改造后正常路径秒退;若仍卡可能是 ① httpx 连接 close 没立刻关(GC 时机)/ ② 模型 thinking 阶段长时间不吐 chunk,等下一个 chunk 到达才能 poll cancel(罕见)
`[startup] reaped N stale active run(s)`	上次 web 进程未正常 finish 留下 N 个孤儿 run,启动 lifespan 自动标 error。info 级,无需处理
`seedream` tool 没出现在对话里	`.env` 没设 `ARK_API_KEY`,build_agent 跳过注册。设了重启 web 即可;无需迁移、无需 DB 改动
`document_*` tool 没出现在对话里	`.env` 没设 `DOCUMENT_SEARCH_API_KEY`,build_agent 跳过注册。设了重启 web 即可;key 不进入 sandbox。
`mp_*` tool 没出现在对话里	`.env` 没设 `MP_API_KEY`,build_agent 跳过注册。设了重启 web 即可;Materials Project 联网查询走 host-side tool,离线 pymatgen 不受影响。
豆包调价了	改 `config/media/doubao.yaml` 的 `price_cny_per_image` 一行 → 重启 web。历史 usage_events 不受影响(units jsonb 里有当时单价 snapshot,聚合查仍按旧价);新写入按新价。涨价瞬间到改 YAML 中间这段记账偏低,开发期接受
`kill -HUP <pid>` 后 `/openapi.json` 没新接口	uvicorn 不响应 SIGHUP(没装 handler,落 Python 默认终止;Windows 上信号本身无效)。Ubuntu 上用 `systemctl restart zcbot`,或 unit 加 `--reload` 让 uvicorn 监听文件自动重起(见"部署"段)。验证:`curl -s http://127.0.0.1:8765/openapi.json \| python3 -c 'import sys,json;print([p for p in json.load(sys.stdin)["paths"] if "auth" in p])'`
`systemctl restart zcbot` 卡 10s 才退	有 SSE 长连接,uvicorn graceful shutdown 等 in-flight。unit 已设 `TimeoutStopSec=10` 兜 SIGKILL,正常现象;真急用 `systemctl kill -s KILL zcbot`
`POST /v1/files/rename` 返 409 `folder has active run(s)`	顶层目录被某 running/cancelling 的 task 占用;先 cancel 等流式 done 再 rename
`POST /v1/files/rename` 返 409 `... 前缀嵌套`	改名后会与其他 task 的 working_dir 形成嵌套;换不冲突的 new_name
`POST /v1/files/upload` 返 413 `已达磁盘配额上限`	per-user 5GB(yaml `quotas.disk_bytes_per_user`)。让用户在 dev SPA 右侧文件栏删旧产物 / 大文件,或改 yaml 升配重启 web
`[warn] network zcbot-sandbox-net is --internal (legacy)`	上一版 sandbox network 创建时带了 `--internal`(完全禁 outbound),当前 dogfood 阶段放开。`docker stop $(docker ps -aq -f label=zcbot.product=sandbox) ; docker network rm zcbot-sandbox-net`,重启 web 自动 recreate 为非 internal
tool write/edit 返 `[Error] 已达磁盘配额上限`	同 upload 413,见上
容器内 `curl https://www.baidu.com` 报 `Temporary failure in name resolution`	docker user-defined bridge network 上 /etc/resolv.conf 默 `nameserver 127.0.0.11`(embedded DNS),腾讯云轻量等场景 daemon 探测上游失败 → embedded DNS forward 跪。修法:yaml `sandbox.dns` 指定 `[8.8.8.8, 114.114.114.114]`,SandboxPool 把 host 侧 `<workspace>/.sandbox/resolv.conf` 文件 bind mount `-v ...:/etc/resolv.conf:ro` 覆盖容器默 ro mount,绕开 embedded DNS。`docker rm -f $(docker ps -aq -f label=zcbot.product=sandbox)` + `systemctl restart zcbot` 让新容器按 mount 配置生效
init.sh 报 `/etc/resolv.conf: Read-only file system`	docker 默把 /etc/resolv.conf 当 ro mount,init.sh 内 `cat >` 写不进。host 侧 bind mount 已是主路径(见上),init.sh 写仅作 fallback 且失败 robust 不退出容器
启动报 `PLATFORM_KEY env not set` / `JWT_SECRET env not set`	D' 过渡 auth 强制双 env 必填。生成 `python -c "import secrets;print(secrets.token_urlsafe(48))"` 各填一,写 `.env` 重起
`/v1/auth/login_password` 返 403 `invalid email or password`	邮箱不存在 / `password_hash` 列为空(platform_key 入口建的 user) / 密码错。`SELECT user_id, email, password_hash IS NOT NULL AS has_pw FROM users WHERE email=...` 核对;无行 → `main.py user add`;有行无密码 → `UPDATE users SET password_hash=...`(用 `.venv/Scripts/python.exe -c "from web.auth import hash_password;print(hash_password('xxx'))"` 算)或 `user add --user-id` 接到现有 user_id
`main.py user add` 报 `IntegrityError ... uq_users_email`	邮箱已存在,改 email 或先 `DELETE FROM users WHERE email=...`(先清该 user 的 tasks)
`main.py user add` 报 `IntegrityError ... users_pkey`	`--user-id` 撞已有 UUID,换一个或不传让随机生成
登录页"+ 管理员添加用户"提交后 503 `admin create_user disabled`	`ZCBOT_ADMIN_TOKEN` env 未设,功能默关。设了 env 重启 web 即可;或临时回退 `main.py user add`
登录页"+ 管理员添加用户"返 403 `invalid admin_token`	弹窗里管理员口令栏填错或没复制完整。跟 `.env` 里 `ZCBOT_ADMIN_TOKEN` 比对(注意末尾空格 / 引号)
改了用户邮箱 / 密码后他登不上	`UPDATE users SET email=...` 不影响 user_id(行同一行,task 仍归属),用新邮箱登即可;DB 里应存小写(后端 lower() 后查)。改密 `UPDATE users SET password_hash=<bcrypt>` 同理
`/v1/*` 全返 401 `missing Authorization: Bearer`	没拿 token 或没带 header。先 login 拿 token,curl 加 `-H "Authorization: Bearer $TOKEN"`
`/v1/*` 返 401 `token expired`	JWT 默 7d TTL 到期,重 login。要更长改 `ZCBOT_JWT_TTL_SECONDS` env
dev.html SSE 收不到流(消息发出去 UI 没动)	EventSource 不支持 header,dev.html 走 `fetch + ReadableStream`。devtools Network 看 POST /messages 是否 202 + events_url GET 是否 200 + Content-Type 是 text/event-stream;401 → token 过期,logout 重 login
matplotlib / mermaid 出的 PNG 里中文全是方块(豆腐块 □)	sandbox 镜像缺中文字体。Dockerfile 已加 `fonts-noto-cjk fonts-wqy-microhei` + `fc-cache`,但改了 Dockerfile 必须重 build 镜像 + 清旧容器才生效(旧容器仍跑老镜像):`docker build -t zcbot-sandbox:latest -f deploy/sandbox/Dockerfile --build-arg HOST_UID=$(id -u) --build-arg HOST_GID=$(id -g) .` → `docker rm -f $(docker ps -aq -f label=zcbot.product=sandbox)` → `systemctl restart zcbot`。验证:`docker run --rm zcbot-sandbox:latest fc-list :lang=zh` 应列出 Noto/WenQuanYi
dev.html 显示 "load failed" 立刻回登录页	token 过期或 JWT_SECRET 服务端变了。已自动跳登录页,按上次 tab 重登
dev.html 顶栏出现"连接断开,重连中…(N/3)"	SSE 流被切(`--reload` 重启 / nginx 切换 / 网络抖)。客户端自动重连,1s/2s/4s 退避;新进程已 reaper 标 error 则立即收 done + 卡片末尾"请重发"提示;若服务端还活着会继续看后续 delta(断开期间的丢失,broker 不持久化)

关键路径与文件

入口:main.py(web / db / probe / user)→ core/agent_builder.py::build_agent
核心:core/{agent_builder, loop, session, task, llm, memory, paths}.py + core/storage/{engine,models,utils}.py + db/migrations/
工具:tools/{fs, shell, run_python, skill_tool}.py
Web:web/{app.py, auth.py, broker.py, sinks.py} + web/static/dev.html(dev SPA)+ web/static/vendor/(office 预览 jszip/docx-preview/xlsx)
配置:config/agent.yaml + config/models/*.yaml(§3.2 Model Profile)
Skill:skills/{coding,ppt,proposal}/SKILL.md(渐进披露,§3.5)
Workspace(per-user 子树,user_id 来自 JWT sub):
- workspace/users/<user_id>/.memory/{core.md, extended/} — 跨 task 记忆,FS 永久,dotfile 隔离
- workspace/users/<user_id>/<working_dir>/ — 工作目录,用户起名,同 working_dir 多 task 共享

维护约定

改对外行为(CLI 选项 / env / 文件布局)→ 同步本文档。bug 修不动这个,只动 PROGRESS。
故障兜底新增:用过一次的真实坑,写一行,不预测。
跟 DESIGN/PROGRESS 边界:DESIGN 写"为什么",PROGRESS 写"做到哪",RUN 写"怎么跑"。

46 KiB Raw Blame History Unescape Escape