Skip to content

附录 F:关键链路时序(照着读代码) ​

每个链路给出真实参数(窗口、超时、阈值),都从源码里取,不是估计值。

F.1 后台登录 ​

浏览器 POST /api/admin/auth/login {username, password, totpCode?}
  │
  ├─ ① IP 限流:RateLimiter.tryAcquire("login:ip:"+ip, 600s, 20 次)
  │      超限 → code 20014「提交过于频繁,请稍后再试」
  ├─ ② 账号锁定:10 分钟窗口内失败 ≥ 5 次 → code 10102「账号已临时锁定」
  ├─ ③ 口令校验:BCrypt(>72 字节直接判失败,避免异常变 500)
  │      失败 → 写 sys_login_log(status=0) → 返回「用户名或密码错误」
  ├─ ④ 两步验证(已开启时):先验 6 位 TOTP;失败再试 10 位一次性恢复码(命中即消耗)
  ├─ ⑤ 签发 JWT:HS512,有效期 24h(cosmos.jwt.expire-hours),载荷含 userId/username/tv
  ├─ ⑥ 写 sys_login_log(status=1),成功告警(若开启)通过通知通道发送
  └─ 返回 { token, userInfo }

前端:token 存 localStorage['vite-cosmos-token'];request.ts 每次请求带 Authorization: Bearer; 收到 code 10002 清 token 并跳 /admin/login。

F.2 请求鉴权(后台 / Agent / internal) ​

请求 ──▶ AuthInterceptor(后台)
          ├─ 无有效 JWT → code 10002
          ├─ JWT 的 tv(token version)与库中 sys_user.token_version 不一致 → 失效(改密码即踢下线)
          └─ 通过 → 写 request attribute(当前用户)

请求 ──▶ AgentAuthInterceptor(/api/agent/**)
          ├─ Authorization: Bearer cosmos_agent_xxx → 查 sys_agent_token
          ├─ 校验 enabled / expires / ip_allow / rate_limit(进程内滑动窗口)
          └─ 更新 last_used_at;通过记 scope

请求 ──▶ AgentCapabilityController(/api/internal/agent-capability)
          ├─ X-Run-Token + runId → ExtensionRunTokenService.validate(runId, token)
          └─ 一次性令牌:用完即失效;失败返回 { ok:false, error:"run_token_invalid" }

另外 AdminIpGuardInterceptor 按 site.security.admin-ip-whitelist 拦后台接口(空值=不限制)。

F.3 AI 对话一轮(SSE) ​

前端 GET /api/admin/ai/chat/stream?conversationId=..&requestId=..&content=..
  │  (SseEmitter 超时 540s)
  ├─ beginOrResume(conversationId, requestId)         ← 幂等:同 requestId 复用
  │    └─ 状态 queued → 建/复用 user 消息
  ├─ 状态 running,phase=thinking
  ├─ 调用 DSH 网关(流式),逐块 write 给前端
  │    ├─ 工具调用:phase=tool(能力经扩展平台/白名单)
  │    └─ 终态整理:phase=finalizing
  ├─ 成功 → status=completed,写 assistant 消息,finished_at
  └─ 失败 → status=failed,error_code/error_detail(脱敏)
       前端可用同 requestId 重试;服务重启时 StaleJobLogReconciler 把遗留 running 改写为失败

没有取消:状态机里没有 cancelled(见 §九)。

F.4 采集上报(Agent → 后端) ​

采集器 POST /api/agent/ingest  Authorization: Bearer cosmos_agent_xxx
  ├─ 校验令牌(scope=agent:ingest、IP、速率)
  ├─ 按 (sessionId, lineNo) 去重 → 追加 agent_session_raw / agent_session
  ├─ 更新 agent_ingest_log(lastLineNo、ingestedLines、status)与 agent_heartbeat
  └─ 触发记忆流水线(若开启):ai_hs_operation 入队 → HindsightIngestJob 异步 ingest
  • 采集器与本机的 DSH 会话文件绑定,只增量读新行(lastLineNo 之后)。
  • 心跳单独走 /api/agent/heartbeat,健康监控据此判断采集是否活着。

F.5 扩展触发 → 效果 ​

ExtensionTriggerScheduler(每分钟扫到期触发器)
  └─ 命中 → 创建 extension_run(queued)
       ├─ 策略:ExtensionPolicyService → extension_policy_decision(allow/deny/needs_approval)
       │    ├─ deny → run 状态 skipped,**记跳过原因**
       │    └─ needs_approval → extension_approval(pending),人工批准后继续
       ├─ 预算:extension_budget_ledger 扣减;超预算 → skipped(预算耗尽)
       ├─ 执行:沙箱内跑扩展代码(sandbox 目录),过程事件写 extension_run_event
       │    能力调用 → extension_capability_call(出网受 EgressGate 约束)
       ├─ 效果:EffectApplier 落 extension_effect(幂等键防重复应用)
       └─ 通知:extension_message → extension_message_delivery(失败重试)

F.6 记忆写入与检索 ​

写入:对话/事件 → HindsightIngestService
       ├─ 组 batch(幂等键 session+lineNo 或 event+version)
       ├─ HindsightClient.retain() → 成功记 ai_hs_usage;失败写 ai_hs_operation 待重试
       └─ HindsightOperationJob 定时重试(指数退避,超过上限标记失败)

检索:memory_search → HindsightClient.query()
       ├─ 结果按隐私等级过滤(私密内容不出现在给模型/访客的结果里)
       └─ 覆盖度不足时明确标注「只能说没记到,不能推断没做」(ai_mem_coverage)

F.7 发布(后端容器) ​

deploy-server.sh
  ├─ mvn package(或用 --no-build 的已有 jar,校验 jar 新于源码)
  ├─ docker build -t vite-cosmos-app:prod-<时间戳>
  ├─ 改写 compose 使用的镜像标签 → docker compose up -d
  ├─ 等待 /api/health/ready 通过(超时则失败退出,旧容器仍在)
  └─ 清理非 prod-* 旧镜像

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。