51 lines
3.5 KiB
Markdown
51 lines
3.5 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`，密钥字段保持脱敏。
|
||
|
||
## 测试 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 与预期一致。
|