hyapp-deploly/deploy/tencent_tat/README.md

Tencent TAT Deployment

本目录包含两类 TAT 发布入口：

• deploy_platform_tat_deploy.py：发布当前 deploy-platform 前端项目。
• hyapp_tat_deploy.py：发布 HyApp 后端 Go 微服务；运行态发现使用 TAT 连接 deploy 机器 43.164.75.199，再由 deploy 机器 SSH 读取真实 systemd、Docker、镜像、资源、日志和 YAML。
• hyapp_data_resources.py：数据资源状态。TAT -> deploy；业务服务器配置 SSH 失败后 TAT 兜底。
• validate_rendered_configs.py：校验 HyApp 服务 YAML 字段契约，服务源码默认读取相邻 ../hyapp-server，也可以用 --hyapp-root 指定。

两者使用同一套 TAT/CLB 滚动部署模型：可选 CLB 摘流，TAT 远端更新 docker.env 镜像并重启 systemd unit，健康恢复后恢复权重。

Deploy Platform

脚本只操作以下对象：

• hyapp-deploy-platform systemd unit
• hyapp-deploy-platform Docker 容器
• /etc/hyapp/deploy-platform/docker.env

Prerequisites

1. 目标机已安装 Tencent TAT agent。
2. 目标机已安装 deploy/standalone/systemd/hyapp-deploy-platform.service。
3. 目标机已准备 /etc/hyapp/deploy-platform/docker.env。
4. 发布机安装腾讯云 SDK：

python3 -m pip install tencentcloud-sdk-python

凭据通过环境变量或 --env-file 提供：

export TENCENTCLOUD_SECRET_ID="..."
export TENCENTCLOUD_SECRET_KEY="..."
export TENCENTCLOUD_REGION="me-saudi-arabia"

Inventory

cp deploy/tencent_tat/inventory.prod.example.json deploy/tencent_tat/deploy-platform.inventory.prod.json
vi deploy/tencent_tat/deploy-platform.inventory.prod.json

必须替换：

• hosts.deploy-platform-1.instance_id
• hosts.deploy-platform-1.private_ip
• 如果前面挂 CLB，把 clb.enabled 改成 true，并设置真实 load_balancer_id / listener_ids。

Commands

只看计划，不执行远端动作：

python3 deploy/tencent_tat/deploy_platform_tat_deploy.py plan \
  --inventory deploy/tencent_tat/deploy-platform.inventory.prod.json \
  --services deploy-platform

发现目标机当前状态：

python3 deploy/tencent_tat/deploy_platform_tat_deploy.py discover \
  --env-file /opt/hy-app-monitor/.env \
  --inventory deploy/tencent_tat/deploy-platform.inventory.prod.json \
  --services deploy-platform

滚动更新镜像：

python3 deploy/tencent_tat/deploy_platform_tat_deploy.py deploy \
  --env-file /opt/hy-app-monitor/.env \
  --inventory deploy/tencent_tat/deploy-platform.inventory.prod.json \
  --services deploy-platform \
  --tag 20260514-1800 \
  --yes

只重启，不改镜像：

python3 deploy/tencent_tat/deploy_platform_tat_deploy.py restart \
  --env-file /opt/hy-app-monitor/.env \
  --inventory deploy/tencent_tat/deploy-platform.inventory.prod.json \
  --services deploy-platform \
  --yes

Failure Boundary

如果启用 CLB，脚本会先把当前实例权重改为 0，TAT 重启成功并通过 Docker health 后再恢复权重。重启或健康检查失败时，脚本停止后续步骤，已经摘流的实例保持权重 0，需要人工确认后恢复。

HyApp Services

平台后续接服务端执行器时，直接调用当前仓库内的 HyApp 微服务发布脚本：

python3 deploy/tencent_tat/hyapp_tat_deploy.py plan \
  --inventory deploy/tencent_tat/hyapp-services.inventory.prod.example.json \
  --services gateway-service,room-service,user-service

读取真实运行态和配置 YAML：

python3 deploy/tencent_tat/hyapp_tat_deploy.py discover \
  --env-file /opt/hy-app-monitor/.env \
  --inventory deploy/tencent_tat/hyapp-services.inventory.prod.json \
  --services gateway-service \
  --include-config

discover 的远端链路固定为 TAT -> deploy 机器 -> SSH 业务机器，TAT 入口来自 inventory 的 deploy_server.instance_id / deploy_server.public_ip。 业务机 SSH 默认使用 root 和 deploy 机默认 SSH key；如需指定账号或 key，可在对应 hosts.<name> 上设置 ssh_user / ssh_identity_file，或通过 DEPLOY_SERVICE_SSH_USER / DEPLOY_SERVICE_SSH_KEY 注入。

生产使用时复制成真实 inventory：

cp deploy/tencent_tat/hyapp-services.inventory.prod.example.json deploy/tencent_tat/hyapp-services.inventory.prod.json
vi deploy/tencent_tat/hyapp-services.inventory.prod.json

部署前校验服务配置字段契约：

python3 deploy/tencent_tat/validate_rendered_configs.py \
  --hyapp-root /opt/deploy/sources/hyapp-server \
  --inventory deploy/tencent_tat/hyapp-services.inventory.prod.json

如果已经渲染了生产最终配置，再校验目标 YAML 是否缺字段：

python3 deploy/tencent_tat/validate_rendered_configs.py \
  --hyapp-root /opt/deploy/sources/hyapp-server \
  --inventory deploy/tencent_tat/hyapp-services.inventory.prod.json \
  --rendered-dir /tmp/hyapp-rendered-prod

数据资源状态只读查询：

python3 deploy/tencent_tat/hyapp_data_resources.py resources \
  --env-file /opt/hy-app-monitor/.env \
  --inventory deploy/tencent_tat/hyapp-services.inventory.prod.json

生产 admin-server 固定从 Gitea origin/main 发布，当前运行在 Saudi admin-platform 机器 ins-p11begwe / 10.2.1.2，不是广州独立机。发布链路是 deploy 机本机构建镜像并推送 Harbor，然后用 Tencent TAT 到 ins-p11begwe 更新 Docker env：

docker build -f server/admin/Dockerfile \
  -t 10.2.1.3:18082/hyapp/admin-server:<tag> .
docker push 10.2.1.3:18082/hyapp/admin-server:<tag>

admin-platform 机器已配置 Docker 直拉内网 Harbor：/etc/docker/daemon.json 包含 insecure registry 10.2.1.3:18082，/root/.docker/config.json 包含 Harbor 登录凭据。TAT 到 ins-p11begwe 后只更新 /etc/hyapp/admin-server/docker.env 的 IMAGE，再执行 systemctl restart hyapp-admin-server。

发布后必须验证 systemctl is-active hyapp-admin-server、容器镜像 tag/digest、10.2.1.2:13100 的 /healthz 和 /readyz、yumi-admin-caddy 容器运行、公网 https://admin-acc.global-interaction.com/ 返回 200、未登录 https://admin-acc.global-interaction.com/api/v1/auth/me 返回 401。生产不允许切换到其他分支。

规则：

• MySQL、Redis、MQ 是腾讯云托管资源。
• 读取入口固定为 TAT -> deploy。
• 业务服务器配置优先 SSH；SSH 失败后 TAT 兜底。
• 只读 /etc/hyapp/<service>/config.yaml、docker.env、systemd active。
• 不执行 SQL/Mongo 查询，不修改 MySQL、Redis、MQ。

HyApp Testbox

测试机部署不走生产镜像仓库，也不摘 CLB。当前模式是测试机自己拉取远端 test 分支：

• 后端测试机：43.165.195.39 / 10.11.0.2，实例 lhins-q0m38zc6。
• 代码目录：/opt/hyapp-server-test/source。
• 部署脚本：/opt/hyapp-server-test/bin/deploy.sh。
• 自动轮询：hyapp-server-test-deploy.timer，每分钟检查一次 test 分支。
• 成功条件：Compose 服务全部 healthy 后才写入 /opt/hyapp-server-test/.deployed_commit。
• 后台前端：广州机 172.16.0.10:7001，公网 http://1.14.164.2:7001/。

测试机 Go 服务 YAML 通过只读 TAT 接口读取：

python3 deploy/tencent_tat/hyapp_testbox_config.py configs \
  --env-file /opt/hy-app-monitor/.env \
  --services gateway-service,room-service,admin-server

默认返回会遮罩 secret、password、token、key 等字段；确实需要原始值时，服务端必须显式设置 HYAPP_TESTBOX_CONFIG_ALLOW_RAW=1，并在 API 请求里带 raw=1。

测试服务后台还使用同一个脚本封装固定动作，不开放任意 shell：

• status：读取 test 分支、已部署 commit、timer 和服务状态。
• service --operation update|start|stop|restart：对 Compose 服务或 admin-server systemd 执行固定操作。
• timer --operation start|stop|restart|status：控制 hyapp-server-test-deploy.timer。
• write-config --service <name> --content-base64 <yaml>：写配置前备份旧文件，可选 --restart。
• migrations / migrations-apply：只列出或执行 source/server/admin/migrations/*.sql，不接收页面手写 SQL。