部署与配置

↻script/startup.sh

封装 docker compose up -d --build，随后做 60 × 0.5s 的健康探测，并给宿主目录 chmod。日常起停用这个。

■script/shutdown.sh

对应的停止入口（封装 docker compose down），避免遗留 provisioner 容器占住 8002。

▤script/sandbox_local.sh

在宿主机直接跑 provisioner（不经容器），用于调试；script/run/ 是运行产物目录（当前只有 provisioner.log，未被 git 跟踪），不是镜像构建输入。

A入口一 · /api/system/config

GET 登录用户可读，POST 与 POST /update 需 admin。 这一组读写的是 system_options 单条记录里的 5 个字段（上表）。 来源：docs/08-configuration.md 第 3 节、routers/system_router.py。

B入口二 · /api/system/config/options/{key}

GET /options 与 PUT /options/{key} 均为 admin，读写 OPTION_DEFINITIONS 里的其它选项； list_options() 显式排除 system_options，所以这组接口不会返回上面那 5 个字段。两组入口互不覆盖。

◈RBAC 与资源级权限

角色三档：superadmin / admin / user（users.role）。 守卫实现是逐路由 FastAPI 依赖注入，没有全局中间件：get_required_user（登录且已绑部门，否则 400）→ get_admin_user → get_superadmin_user。 资源权限由 share_config（JSON）定义 read / manage scope，可授 global / department / user 级，角色上限 role_ceiling 约束可达范围；部门是 departments 树。 来源：zhiwu/permissions/resource_permission.py、docs/11-security.md「已确认结论」。

✋工具审批 human-in-the-loop

敏感工具集合固定 SENSITIVE_BACKEND_TOOLS = {write_file, edit_file, execute}； 按用户 tool_approval_mode（default / always / never）启用 HumanInTheLoopMiddleware。 命中时 Run 进入 interrupted，前端 approve / edit / reject 后以 run_type=resume 从 checkpoint 续跑。 当前 Project workdir 内的写入豁免审批；子智能体默认禁用敏感工具与 install_skill。

▣沙箱边界

• CompositeBackend 路径守卫：readable / writable roots + 虚拟路径 /home/gem/*，越界直接拒
• 文件工具七件套没有 delete（agents/backends/composite.py）
• 技能投影 fail-closed：同步异常时清空投影而不是留旧内容
• 远程 Skill 安装：一次性沙箱执行 npx skills add + 域名白名单 + draft 两段确认，且 inherit_env=False（不继承宿主环境变量）
• MCP：用户配置仅 sse / streamable_http，stdio 强制仅内置（启动时自动禁用历史用户的 stdio），杜绝任意命令执行面

⚑密钥管理现状

• 三项密钥 lifespan 硬校验（≥32 字符、无首尾空白、彼此不等）；API_KEY_DERIVATION_SECRET 与 SANDBOX_PROVISIONER_TOKEN 在所有环境缺失都是启动硬失败
• 生产应接部署平台的 secret 管理注入，不要把 backend/.env 打进镜像（该文件未被 git 跟踪，仓内亦无 .env.example）
• ⚠ 已知待收敛项：MCP env / headers 与模型供应商 api_key 在管理端接口明文返回，只靠 get_admin_user 角色守卫，无字段级打码；普通用户走字段白名单
• ⚠ /docs 与 /openapi.json 未按 ZHIWU_ENV 关闭
• 暴破防护三层：内存滑窗（60s / 每 IP 10 次）+ Redis 滑窗（600s，IP+账号 10 次、单 IP 全局 30 次）+ 账号锁定（5 次 / 300s，返 423 + X-Lock-Remaining）。客户端 IP 优先取 X-Forwarded-For 首段，生产必须由反向代理覆盖 / 剥离 XFF，否则可伪造绕过限速

⌁调试入口

• 终端日志带 [T:trace_id]；在线查 GET /api/system/logs
• LANGFUSE_ENABLED=true 后按 Run 看完整 trace（/api/agent/runs/{id}/langfuse）
• LangGraph 状态：GET /api/chat/thread/{tid}/state 直查 checkpoint
• Swagger：/api/docs（开发环境）

◇API 兼容性与 CLI

URL 无版本号，兼容性靠响应字段增量演进。GET /api/system/discovery（公开）返回 name / version / api_prefix、capabilities.features.knowledge 与 12 个 CLI 能力字段 （min_cli_version + browser_login、api_key_auth、remote_config、agent_list、kb_* 等）。 这些值是硬编码字面量，不随配置或运行状态变化；CLI 执行前读它校验版本（要求 ≥ 0.1.0）与能力标志， 不满足直接报 ServerCompatibilityError 退出。加端点时记得同步 routers/__init__.py 与 docs/06-api.md。

1启动即报安全密钥缺失 / 相同

症状：进程秒退，日志提示密钥校验失败。
原因：JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET、SANDBOX_PROVISIONER_TOKEN 任一为空、短于 32 字符、带首尾空白或彼此相等；开发环境只对 JWT_SECRET_KEY 自动生成临时值，另两项任何环境缺失都是硬失败。
处置：配三个互不相同的 ≥ 32 字符强随机值（openssl rand -hex 32）。

2启动报存储根目录错误

症状：lifespan 阶段 RuntimeError。
原因：ZHIWU_USER_DATA_DIR 等三个目录是相对路径或空值。
处置：改成绝对路径；顺带把 ZHIWU_RUNTIME_DIR 也固定下来，否则日志散落在带 pid 的临时目录里。

3schema 版本不兼容拒绝启动

症状：应用进程启动时校验 schema 失败。
原因：应用只校验兼容、不建表不改表，迁移归 storage-migrator。
处置：先跑一次性迁移（仓内 uv run python -m zhiwu.storage_migration，镜像由部署方自打），再起 api / worker。

4423 登录被锁定，连已登录页面也报错

症状：登录返 423 + X-Lock-Remaining，其他鉴权接口也 423。
原因：连续 5 次密码错 → 锁 300s；且锁定检查在 get_current_user 的 JWT 分支，作用于所有鉴权请求。
处置只能等自然过期——仓内没有任何管理端解锁 / 重置端点，阈值也没有环境变量入口。紧急旁路：API Key 分支提前 return，不经过锁定检查。

5429 登录受限

症状：登录接口返 429。
原因：两层 IP 滑窗——内存层 60s / 每 IP 10 次，Redis 层 600s（IP+账号 10 次、单 IP 全局 30 次）。
处置：等窗口过期；无清除端点，必要时直接删 zhiwu:login-failure:ip:* / …:ipacct:* key。生产要确认反代已覆盖 XFF，否则限速按代理 IP 计数。

6消息一直 queued / Run 卡 running

症状：提交后无输出。
原因：Worker 没跑或队列堆积；或同线程已有活跃 Run（部分唯一索引）；Run 卡住多为 Worker 崩溃后租约未过期。
处置：查 Redis health key 是否每 5s 刷新、GET /api/agent/thread/{tid}/active_run、agent_run_attempts.heartbeat_at / lease_expires_at 是否停更；等租约过期会被其他实例接管。等 Run 时用 Last-Event-ID 重连 SSE 续传。

7沙箱创建超时 / 工作目录不同步

症状：execute 或文件工具失败，或沙箱里看不到刚写的文件。
原因：provisioner 不可达（两套 compose 抢了同一个 8002）、/var/run/docker.sock 权限、镜像缺失、两端 token 不一致；不同步多为宿主 bind 源反查失败。
处置：GET :8002/health → 看 provisioner 日志 → 核对 SANDBOX_PROVISIONER_URL 与 token → 确认 compose 里 user-data / skill-projections 相对挂载路径与真实宿主目录一致 → 用 SANDBOX_WORKDIR_PROBE 打开探测；重试次数看 SANDBOX_PROVISIONER_CREATE_ATTEMPTS。

8文档停在 error_parsing / 检索无结果

症状：KB 不索引，或查询空返回。
原因：OCR / 解析引擎不可用（MinerU、PaddleOCR 服务地址或密钥未配、超时）；检索侧是状态未到 indexed、相似度阈值过滤或 search_mode 选择不当。
处置：GET /api/system/ocr/health，把 default_ocr_engine 先换回本地 rapid_ocr；用 /databases/{kb_id}/query-test 调试、调 query-params；换 embed 模型导致维度不符时新建 KB 重索引。

9技能工具不可见 / 头像加载失败

症状：模型说没有某技能，或前端图片 404。
原因：技能需模型先 read_file SKILL.md 才激活，未激活就不放依赖工具；投影 fail-closed 会在同步异常时清空 skill-projections/<uid>/。头像 404 多为宿主机直跑没设 VITE_MINIO_URL，代理仍去打 http://minio:9000。
处置：检查 prompt 摘要是否含该技能、重新触发同步、补 VITE_MINIO_URL=http://127.0.0.1:9000。

10日志查不到 / MCP 用户 stdio 消失

症状：/api/system/logs 返回空或只有旧内容；历史用户配置的 stdio MCP 不见了。
原因：该端点只读当前 API 进程自己 的日志文件（文件名按当天固化），Worker 未共享 ZHIWU_RUNTIME_DIR 时写在另一个带 pid 的目录；stdio 是启动策略强制禁用的安全迁移。
处置：进容器 tail 文件，或让两侧共用同一 ZHIWU_RUNTIME_DIR（会互相混写）；MCP 改用 sse / streamable_http 形态。

⌗自定义域名与预览

• Pages：项目 Settings → Custom domains 添加域名，Cloudflare 会写 CNAME 并在托管 zone 内自动开代理；*.pages.dev 子域默认存在，可用 Branch settings 控制生产分支。
• Workers：在 Worker 的 Triggers → Custom domains 绑定，或在 wrangler.jsonc 里声明 routes 后随部署生效。
• 两种路线都保留免费的 pages.dev / workers.dev 域名，预览部署不会覆盖生产。

!部署前要自己确认的两件事

• wrangler.jsonc 的 name 与 Pages 的 --project-name 必须与实际 Cloudflare 账号下的项目名一致；不一致时 pages deploy 会新建项目、wrangler deploy 会新建 Worker，容易留下孤儿。
• 先 npx wrangler login（或提供 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID）。本站是公开内容，不需要 secrets；若后续给 Worker 加鉴权，密钥走 wrangler secret put，不要写进 wrangler.jsonc。