# AGENTS.md ## Working agreements 1. 做任何事情之前不要猜测，先看代码和现有链路。 2. 找最直接的方案解决问题。 3. 所有解决的问题都要验证。 4. 修改时碰到已有改动无需询问，继续修改，不回滚无关改动。 ## 数据资源 1. MySQL、Redis、MQ 都是腾讯云托管资源。 2. 数据资源状态入口：`GET /deploy/api/hyapp/resources?remote=1`。 3. 读取链路：Tencent TAT -> deploy 机器。 4. 业务服务器配置优先用 deploy 机器 SSH 读取。 5. 业务服务器 SSH 失败时，对对应 CVM 使用 TAT 兜底读取。 6. 禁止把 MySQL、Redis、MQ 当服务器 SSH。 7. 禁止开放生产 SQL、Mongo 查询入口。 8. TAT 未返回前，页面保持加载状态。 ## 微服务 1. 微服务列表和详情必须使用 `GET /deploy/api/hyapp/discover?remote=1` 的真实数据。 2. 禁止用静态假数据兜底展示微服务运行态。 3. 配置 YAML 只在列表右侧三点和详情配置区展示。 4. 读取 YAML 时使用 `includeConfig=1`，密钥字段保持脱敏。 ## CDN 刷新 1. CDN 刷新入口是 `/cdn-refresh`。 2. EdgeOne URL 刷新 API 是 `POST /deploy/api/edgeone/purge-url`。 3. 默认 EdgeOne 站点是 `global-interaction.com`，ZoneId 是 `zone-3qwew52ihaj2`。 4. 默认只允许刷新 `h5.global-interaction.com`，新增域名必须通过 `EDGEONE_ALLOWED_HOSTS` 配置。 5. 真实刷新必须带 `confirmed=true`；验证以 EdgeOne 返回的 `jobId`、`status`、`tasks` 为准。 6. 禁止把 CDN 刷新页面做成任意域名、任意动作执行入口。 ## 生产特殊服务 1. `admin-server` 不在标准 prod inventory 的滚动服务清单里；它部署在 Saudi `admin-platform` 机器 `ins-p11begwe`，公网 `43.164.70.49`，内网 `10.2.1.2`。 2. `admin-server` 的 systemd 是 `hyapp-admin-server`，容器是 `hyapp-admin-server`，配置是 `/etc/hyapp/admin-server/config.yaml`，Docker env 是 `/etc/hyapp/admin-server/docker.env`，migration 目录是 `/opt/hyapp/admin-server/migrations`，监听 `10.2.1.2:13100`。 3. 更新 `admin-server` 必须只发布 `origin/main`：deploy 机从 Gitea 拉取 `git@gitea.haiyihy.com:hy/hyapp-server.git` 的 `origin/main`，构建并推送 `10.2.1.3:18082/hyapp/admin-server:`，再通过 Tencent TAT 到 `ins-p11begwe` 修改 `/etc/hyapp/admin-server/docker.env` 的 `IMAGE` 后重启 `hyapp-admin-server`。 4. `admin-platform` 机器已经配置 Docker 直拉内网 Harbor：`/etc/docker/daemon.json` 包含 insecure registry `10.2.1.3:18082`，`/root/.docker/config.json` 包含 Harbor 登录凭据；如果 `docker pull 10.2.1.3:18082/...` 失败，优先检查这两处。 5. 更新 `admin-server` 后必须验证：`systemctl is-active hyapp-admin-server`、容器镜像 tag/digest、`ss -lntp | grep 13100`、`curl http://10.2.1.2:13100/healthz`、`curl http://10.2.1.2:13100/readyz`、Caddy 容器 `yumi-admin-caddy` 运行、公网 `https://admin-acc.global-interaction.com/` 返回 `200`、未登录 `https://admin-acc.global-interaction.com/api/v1/auth/me` 返回 `401`。 6. Saudi `admin-platform` 机器同时承接两个 5 秒轮询的前端 watcher：`chatapp3-admin-watch.service` 和 `hyapp-admin-platform-watch.service`。它们只在远端 commit 变化或静态目录缺失时构建，不应每 5 秒重复 build。 7. `chatapp3-admin-watch.service` 使用 `/opt/chatapp3-admin/bin/watch-build.sh`，部署脚本是 `/opt/chatapp3-admin/bin/deploy-once.sh`，仓库是 `git@gitea.haiyihy.com:hy/chatapp3-admin.git` 的 `main`，构建后写入 `/opt/yumi-admin/frontend-admin/site/yumiadmin-acc`，公网入口是 `https://yumiadmin-acc.global-interaction.com`。前端 API 配置必须是 `https://yumiadmin-acc.global-interaction.com/console`，Caddy 的 `/console/*` 通过 Saudi 内网 CLB `https://10.2.1.12` 回源，并保持上游 Host/SNI 为 `jvapi.haiyihy.com`。 8. `hyapp-admin-platform-watch.service` 使用 `/opt/hyapp-admin-platform/bin/watch-build.sh`，部署脚本是 `/opt/hyapp-admin-platform/bin/deploy-once.sh`，仓库是 `https://gitea.haiyihy.com/hy/hyapp-admin-platform.git` 的 `main`，构建后写入 `/opt/yumi-admin/frontend-admin/site/hyapp-admin-platform`，公网入口是 `https://admin-acc.global-interaction.com`。前端 API 配置必须保持同源 `/api`，Caddy 的 `/api/*` 回源到 `10.2.1.2:13100`。 9. 更新或排查这两个 Saudi 前端 watcher 后必须验证：`systemctl is-active chatapp3-admin-watch hyapp-admin-platform-watch`、对应 `.last_built_commit` / `.deployed_commit`、`journalctl -u ...` 或 `/opt/*/logs/deploy.log`，以及公网首页 `200`、未登录 API `401`。 10. HyApp `cron-service` 当前部署在 Saudi 主服务机器 `new-app-1`，实例 `ins-fi5zufpk`，内网 `10.2.1.4`。 11. `cron-service` 的 systemd 是 `hyapp-cron-service`，容器是 `hyapp-cron-service`，配置是 `/etc/hyapp/cron-service/config.yaml`，Docker env 是 `/etc/hyapp/cron-service/docker.env`，监听 `13007`。 12. `cron-service` 当前不在标准 prod inventory 的 `services` 清单里；更新时构建并推送 `10.2.1.3:18082/hyapp/cron-service:`，通过 Tencent TAT 到 `new-app-1` 修改 docker env 的 `IMAGE` 后重启 `hyapp-cron-service`。 13. 更新 `cron-service` 后必须验证镜像 tag、Docker health、systemd `active` 和 `13007` 监听。 14. 腾讯云 `ap-singapore` 的实例名 `cron` 机器是 `ins-nt6bsay0` / `10.3.1.14`；当前没有 HyApp `hyapp-cron-service`，不要把它当成 HyApp `cron-service` 发布目标。 ## 测试 server / testbox 1. 测试 server 指 HyApp 后端测试机 testbox：`43.165.195.39` / `10.11.0.2`，实例 `lhins-q0m38zc6`，区域 `ap-jakarta`。 2. 测试机根目录固定为 `/opt/hyapp-server-test`，代码目录为 `/opt/hyapp-server-test/source`。 3. 测试机部署不走生产镜像仓库，不摘 CLB；当前模式是测试机拉取远端 `test` 分支。 4. 自动更新由 `hyapp-server-test-deploy.timer` 每分钟触发，部署脚本为 `/opt/hyapp-server-test/bin/deploy.sh`。 5. 只有 Compose 服务全部 healthy 后，才认为部署成功并写入 `/opt/hyapp-server-test/.deployed_commit`。 6. 测试服务页面必须通过 `GET /deploy/api/hyapp/testbox/status` 读取真实状态，禁止静态假数据兜底。 7. 测试服务操作必须走固定 API 和 `deploy/tencent_tat/hyapp_testbox_config.py`，禁止在页面开放任意 shell。 8. 服务操作只允许 `update/start/stop/restart`，timer 操作只允许 `start/stop/restart/status`。 9. 测试机配置读取默认脱敏；除非服务端显式设置 `HYAPP_TESTBOX_CONFIG_ALLOW_RAW=1` 且请求带 `raw=1`，否则不得返回原始密钥。 10. 保存配置前必须备份旧文件；包含 `***` 脱敏占位符的配置禁止保存。 11. 测试库 migration 只允许列出或执行测试机仓库 `source/server/admin/migrations/*.sql`，禁止页面手写 SQL。 ## 测试 server 日志 debug 1. Debug 前先用 `GET /deploy/api/hyapp/testbox/status` 或 `python3 deploy/tencent_tat/hyapp_testbox_config.py status --env-file /opt/hy-app-monitor/.env` 确认真实状态。 2. 页面或 API 异常时，先查 deploy-platform 自身：`journalctl -u hyapp-deploy-platform -n 200 --no-pager` 和 `docker logs --tail=200 hyapp-deploy-platform`。 3. 测试机自动部署异常时，查 `hyapp-server-test-deploy.timer` 和 `hyapp-server-test-deploy.service` 的 `journalctl`。 4. 业务服务异常时，在测试机 `/opt/hyapp-server-test/source` 下查 Docker Compose 项目 `hyapp-test` 的 `ps`、`logs`、`inspect`。 5. 如果 `/opt/hyapp-server-test/docker-compose.testbox.yml` 不存在，Compose 命令只能使用 `source/docker-compose.yml`。 6. Debug 过程可以通过 SSH 或腾讯云 TAT 执行只读命令；不要新增生产 SQL、Mongo 查询入口，不要把 MySQL、Redis、MQ 当服务器 SSH。 7. 修复后必须验证：刷新测试服务页、调用 status API，或直接运行 `hyapp_testbox_config.py status`，确认 commit、timer、服务 health 与预期一致。