跳转至

Agent Portal — 03-18~20 Dashboard v3与历史模式重构

关键产品决策

  • Dad 决策：Dashboard 历史模式拆分
  • 历史查看模式下，bot 和 server 不应混合展示，否则数据会错乱
  • Dashboard 重构为 tab-based information architecture：Bot Fleet + Server Fleet

  • 历史模式需要明显的视觉语义：整体背景带"历史感"的大框、透明但不深色

  • Dad 决策：dev 预览规范

  • 以后未明确要求前，不要直接发生产版本
  • 先在本地改，用固定 dev 域名预览：portal.dev.dora.restry.cn

  • 本地调试优先，先跑起来再看效果

  • Dad 决策：可用性优化要求

  • 不要只 audit，要真正改：修复 unused imports/vars，补 aria-*、focus-visible、按钮语义
  • 卡片点击区域要更大，提升桌面和移动端命中率
  • 加入"保守型动效"，定位为研究工作台风格，不花哨，只提升顺滑感

技术问题与根因分析

构建产物被误纳入 Git

  • 现象：Git 出现大量脏文件（70 个）
  • 根因：前端构建产物本应先产出到 dist/，但项目里有一批生成文件落在 public/
  • 解决方案：更新 .gitignore，忽略相关 public 产物
  • 结论：Portal 前端构建目录规范应为 dist/，public/ 只放静态源文件

生产站故障与端口问题

  • 现象：Dad 在生产站与机器对话时"没反应"，dev 环境页面数据显示为 0
  • 根因链条：
  • Git 历史中的 server.js 端口是 3019，但运行环境里出现 18820，存在本地改动未提交
  • Vite proxy 仍指向 localhost:3019，但本地 server 已运行在 3002
  • Docker 映射关系是 host 3002 -> container 3019，而容器内环境变量又给了 PORT=3002，导致容器内监听端口与映射端口不一致
  • 解决方案： 
    process.env.PORT || 3002
  • 修复验证：Bot 卡片、Server Fleet 数据恢复加载

历史 Bot 数量统计错误

  • 现象：bots 数量显示错误，显示成 60+
  • 根因：前端把 botPoints 当成 bot 数量，实际上它只是每次检查的时间点，统计成了"检查次数"
  • Dad 要求：以后写代码不能糊弄，要用第一性原理处理问题
  • 解决方案：
  • 直接改后端 /api/dashboard/history，为每个时间点返回真实的 bot/server 数量 summary
  • 使用单个 SQL + CTE + LEFT JOIN，在 DB 层完成计数，避免 JS↔DB 时间格式不匹配
  • 结果：历史 summary 恢复为真实值，如 7 bots / 20-22 servers

Bot 架构/实现决策

Dashboard 前端重构

  • 架构决策：Dashboard 拆分为：
  • Bot Fleet（bot 状态与任务）
  • Server Fleet（服务器资源状态）
  • 历史查看组件按 tab 上下文展示不同数据
  • 选型理由：历史模式下 bot/server 数据模型不同，混合会导致统计口径和 UI 语义混乱

端口与部署链路统一

  • 端口规范：Portal server 从 18820 改为 3002
  • 部署方式：
  • 后端：server.cjs 跑在 3002
  • 前端：pm2 serve dist 跑在 3013
  • Caddy 路由拆分：API → 3002，静态前端 → 3013
  • 选型理由：前后端职责清晰，便于后续鉴权、SSE、静态资源缓存与独立重启

数据模型时光机化

  • 现状问题：当前 collector 把数据堆进一个大 JSON 字段，不利于支持时光机和灵活展示
  • 改造方案：改造后端 API，让 GET /api/dashboard 从新表读取，保持 API response 字段名兼容
  • 架构升级：从"大 JSON"向可时光机化结构演进，支持历史状态回溯

里程碑

  1. 前后端分离完成：Caddy 路由拆分，API 与静态前端分离部署
  2. Dashboard v3 架构完成：tab-based 信息架构，bot/server 数据拆分展示
  3. 开发预览流程确立：dev 域名预览机制建立，避免直接上生产
  4. 可用性大幅提升：补齐 a11y、触控区域、动效优化，研究工作台风格确立
  5. 历史数据准确性修复：从"检查次数"修正为"真实数量"，数据统计第一性原理落地
  6. 生产部署链路修复：端口映射、容器配置、Caddy 反代完整打通

关键配置线索

  • 开发域名：portal.dev.dora.restry.cn
  • 端口配置：后端 3002，前端 3013，原 18820 废弃
  • 容器映射：host 3002 -> container 3019（需要修正）
  • 构建产物：dist/ 目录，不再使用 public/
  • 时光机：新表结构支持历史状态查询

这一阶段确立了 Agent Portal 的现代架构基础：前后端分离、tab-based 信息架构、历史回溯能力和开发预览机制。