> ## Documentation Index
> Fetch the complete documentation index at: https://hilt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新工作流

> 自动更新代理的分步更新流程与回滚步骤。

## 更新代理脚本逻辑

代理容器运行的脚本遵循以下流程：

**1. 读取当前的 image\_tag**

**2. 从 Hilt 发布 ECR 列出可用标签**

**3. 按 UPDATE\_POLICY 过滤标签**

**4. 没有符合条件的更新？**

Exit 0（无需执行任何操作）。

**5. 验证候选标签在全部 6 个仓库中均存在**

确保 Hilt 发布的是完整版本，而非部分推送。

**6. 镜像同步**

```bash theme={null}
docker pull 297433793776.dkr.ecr.us-east-1.amazonaws.com/${repo}:${NEW_TAG}
docker tag  ... ${CUSTOMER_ECR}/${prefix}${repo}:${NEW_TAG}
docker push ${CUSTOMER_ECR}/${prefix}${repo}:${NEW_TAG}
```

**7. 更新 ECS 任务定义**

**8. 强制 ECS 重新部署**

```bash theme={null}
aws ecs update-service --cluster collector \
  --service collector-service --force-new-deployment
aws ecs update-service --cluster dashboard \
  --service dashboard-frontend-service --force-new-deployment
aws ecs update-service --cluster dashboard \
  --service dashboard-backend-service --force-new-deployment
aws ecs update-service --cluster dashboard \
  --service dashboard-query-service --force-new-deployment
```

**9. 重启 EKS 部署**

```bash theme={null}
kubectl rollout restart deployment/enrichment-app \
  deployment/dag-classification -n default
# 启用 GNN 的站点还有一个校准部署。它与 dag-classification 使用同一镜像，
# 并与其交换校准记录，因此两者必须始终保持相同的标签。
kubectl rollout restart deployment/dag-calibration -n default 2>/dev/null || true
```

**10. 等待稳定**

```bash theme={null}
aws ecs wait services-stable --cluster collector --services collector-service
aws ecs wait services-stable --cluster dashboard \
  --services dashboard-frontend-service dashboard-backend-service \
             dashboard-query-service
kubectl rollout status deployment/enrichment-app --timeout=300s
kubectl rollout status deployment/dag-classification --timeout=300s
kubectl rollout status deployment/dag-calibration --timeout=300s 2>/dev/null || true
```

**11. 健康检查**

```bash theme={null}
curl -sf http://dashboard-backend-service:8080/healthz
curl -sf http://dashboard-query-service:8080/healthz
```

**12. 用新标签更新 ConfigMap**

```bash theme={null}
kubectl patch configmap dag-release -p '{"data":{"image_tag":"NEW_TAG"}}'
```

**13. 发送 webhook 通知**

向 `POST $WEBHOOK_URL` 发送 JSON 负载：

```json theme={null}
{
  "text": "Hilt auto-update: v2026.04.27 → v2026.04.28 applied successfully",
  "previous_tag": "v2026.04.27",
  "new_tag": "v2026.04.28",
  "services_updated": [
    "collector",
    "enrichment",
    "classification",
    "dashboard-frontend",
    "dashboard-backend",
    "dashboard-query"
  ],
  "status": "success"
}
```

**14. 镜像同步后发生失败时**

* 发送失败 webhook。
* **不要**更新 ConfigMap（下次运行将重试）。
* Exit 1（CronJob 会在 Kubernetes 事件中记录失败）。

## 回滚

如果某次更新引发问题，运维人员可以手动回退：

```bash theme={null}
# Point back to the previous tag
kubectl patch configmap dag-release -n default \
  -p '{"data":{"image_tag":"v2026.04.27"}}'

# Force rollout to previous images (already in customer ECR)
./scripts/rollout-services.sh
```

> [!WARNING]
>
> **请勿使用 `kubectl rollout undo` 回滚检测相关的部署。**
>
> 从引入检测横向扩展的版本开始，`dag-classification` 以**只读**方式挂载其状态卷，
> 并将每主机状态保存在 Kafka 中。仅回滚镜像标签会让旧镜像无法写入该卷：它仍会运行，
> 但每 300 秒告警一次，并在下次重启时从种子时刻的卷内容冷启动。
>
> 请按前进时的方式回滚：重新应用上一个版本的 Terraform，它会同时恢复镜像及其所需的
> 卷与环境配置：
>
> ```bash theme={null}
> # 在要回退到的版本目录中执行
> terraform apply
> ```
>
> `dag-calibration` 使用同一镜像并与 `dag-classification` 交换校准记录，
> 因此二者必须一起回滚，切勿只回滚其中之一。没有状态卷的部署
> （`enrichment-app`、各 dashboard 服务）仍可通过上面的标签修改方式回退。

自动更新代理在下次运行时不会重新应用有问题的标签，因为它只会向前推进。如果运维人员将 ConfigMap 标签改回旧值，代理会再次将其视为“新”标签并尝试更新。为防止这种情况，请在 `terraform.tfvars` 中设置 `auto_update_enabled = false` 或 `auto_update_dry_run = true` 并重新应用。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.