71 lines
5.7 KiB
Markdown
71 lines
5.7 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 的滚动服务清单里；它部署在独立机器 `134.175.160.86` / `172.16.0.6`。
|
||
2. `admin-server` 的 systemd 是 `hyapp-admin-server`，二进制是 `/opt/hyapp/admin-server/admin-server`，配置是 `/etc/hyapp/admin-server/config.yaml`，监听 `172.16.0.6:13100`。
|
||
3. 更新 `admin-server` 必须通过 deploy 平台触发；由 deploy 机器 `43.164.75.199` 在 `/opt/deploy/sources/hyapp-server` 拉取 Gitea `git@gitea.haiyihy.com:hy/hyapp-server.git` 的 `origin/main`，构建 Linux 二进制，上传到 `134.175.160.86` 替换 `/opt/hyapp/admin-server/admin-server` 后重启 `hyapp-admin-server`。线上只允许发布 `origin/main`；发布后必须验证 systemd `active`、`13100` 监听和 `healthz/readyz`。
|
||
4. HyApp `cron-service` 当前部署在 Saudi 主服务机器 `new-app-1`，实例 `ins-fi5zufpk`，内网 `10.2.1.4`。
|
||
5. `cron-service` 的 systemd 是 `hyapp-cron-service`，容器是 `hyapp-cron-service`，配置是 `/etc/hyapp/cron-service/config.yaml`，Docker env 是 `/etc/hyapp/cron-service/docker.env`，监听 `13007`。
|
||
6. `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`。
|
||
7. 更新 `cron-service` 后必须验证镜像 tag、Docker health、systemd `active` 和 `13007` 监听。
|
||
8. 腾讯云 `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 与预期一致。
|