# 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 或长连接串。