hy-app-monitor/AGENTS.md

hy-app-monitor Agent Guide

项目目标

• 这是部署在 deploy 机器上的轻量监控面板。
• 页面端口固定走 2026，不要再改回 6666 一类浏览器 unsafe port。
• 服务健康检查直接走各业务机器的 HTTP 接口。
• 主机 CPU / 内存 / 磁盘 / 进程数 统一走 TAT 远程采集，不额外安装 agent。
• Nacos 和 MongoDB 指标优先走 deploy 机直连，不需要额外 agent。

配置约定

• 项目根目录 .env 是运行时唯一配置源。
• .env 必须保留在本地和远端项目目录里，但不能提交到 Git。
• .env.example 只作为模板，不能写真实密钥。
• TENCENT_SECRET_ID / TENCENT_SECRET_KEY / DEPLOY_REGION 从 .env 读取。
• NACOS_BASE_URL / NACOS_NAMESPACE_ID / MONGO_URI 也从 .env 读取。
• config/targets.json 里的 instanceId 不能删，TAT 主机采集依赖它。

运行约定

• 正式运行优先使用 systemd。
• scripts/install_systemd.sh 负责安装 unit 并启用开机自启。
• scripts/start.sh / stop.sh / restart.sh / status.sh 在检测到 unit 后应直接转调 systemctl。
• scripts/run_foreground.sh 只给 systemd 用，不要把它改成后台模式。

部署约定

• 远端路径固定为 /opt/hy-app-monitor。
• 部署入口是 ops/deploy_via_tat.py。
• 该脚本需要把本地项目根目录 .env 同步到远端项目根目录 .env。
• 远端 Python 运行时优先使用项目内 .venv。
• requirements-ops.txt 里的依赖既服务于部署脚本，也服务于运行时 TAT 指标采集。
• Python 代码按模块维护，核心目录是 monitor/，server.py 只保留入口。

修改原则

• 不要把 TAT 采集替换成 agent 方案，除非用户明确要求。
• 不要把密钥写进版本库。
• 不要删除页面里的主机指标区块。
• Python 文件保持高注释密度，优先写清楚每个步骤在做什么。
• Python 文件顶部的 import 区域不写包用途注释。

视觉约定

• 前端默认视觉风格固定为“浅色工业控制台”。
• 设计上下文以项目根目录 .impeccable.md 为准，后续前端对话和改动先读取它。
• 页面保持冷静、可靠、可操作，不回退到玻璃拟态、霓虹渐变、大 Hero 的 demo 风。
• 页面文案只保留必要标签和动作，不添加无意义描述。
• 首页默认是状态总览，不把配置编辑和发布表单继续堆在同一条长页面里。
• 服务视图优先使用状态矩阵，主机视图优先使用紧凑条带，基础设施视图承接 Nacos / Mongo 详情。
• 首页首屏默认收敛为顶部导航、工具条、紧凑摘要条、服务矩阵，不额外插入大块最近异常横幅。
• 最近异常进入可折叠详情侧栏顶部，不独立占据首页主宽度。
• 服务矩阵按业务分组切成子矩阵，异常排序前置，表头和第一列保持 sticky。
• 首页主机区只展示业务主机；基础设施主机放到基础设施或主机视图承接。
• 主机指标使用单行短文本，正常态降饱和，红橙色保留给异常和告警。
• 监控筛选条只属于 总览 / 服务 / 主机；发布 / 配置 / 基础设施 必须使用各自专用工具条和页内导航。
• 发布 页按“构建参数 -> 更新目标 -> 执行日志 -> 滚动重启”组织，更新与重启目标都优先用紧凑表格，不再回退到大卡片流。
• 配置 页按 Nacos / Go Env / 历史版本 tabs 组织，编辑器必须提供 sticky 工具条、metadata strip 和 源码 / Diff 切换。
• 基础设施 页按 状态总览 / Nacos 服务 / Mongo 指标 / TAT 二级导航组织，Nacos 服务默认折叠实例，Mongo 次要指标默认折叠。
• 长文本默认缩写并提供复制或展开，不直接在主列表铺完整 digest、路径、长 ID 或长连接串。