admin/hyapp-deploly
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
hyapp-deploly/AGENTS.md
zhx f441fd49c0 Add lucky gift deployment support
2026-07-08 22:33:12 +08:00

7.9 KiB
Raw Permalink Blame History

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 与预期一致。