77 lines
7.9 KiB
Markdown
77 lines
7.9 KiB
Markdown
# 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:<tag>`，再通过 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:<tag>`，通过 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 与预期一致。
|