feat: support ECS RAM role backups

docs/offsite-backup.md

@@ -8,7 +8,7 @@
 
 ## 2. 当前环境状态
 
-目标ECS已安装并校验`ossutil 2.3.0`，客户端压缩包使用阿里云文档公布的Linux x86_64 SHA-256验证。当前实例没有绑定RAM角色，也没有配置OSS Bucket，因此：
+目标ECS已安装并校验`ossutil 2.3.0`，客户端压缩包使用阿里云文档公布的Linux x86_64 SHA-256验证。2026-08-26通过IMDSv2实测实例地域为`cn-hangzhou`，RAM角色元数据返回404；当前实例没有绑定RAM角色，也没有配置OSS Bucket，因此：
 
 - `OFFSITE_BACKUP_ENABLED=false`；
 - 定时器已安装并保持活动，但任务只记录`disabled/not_enabled`；
@@ -53,7 +53,7 @@ systemctl list-timers platform-offsite-backup.timer --no-pager
 2. 优先给ECS绑定最小权限实例RAM角色，避免长期AccessKey落盘；
 3. 授权该角色仅能向指定Bucket前缀上传、读取和查询备份对象；
 4. 如需地域级灾备，为目标Bucket配置跨区域复制；
-5. 使用ossutil交互配置或RAM角色模式生成`/etc/data-terminal-cloud/ossutilconfig`，权限必须为`0600 root:root`。
+5. 推荐直接使用脚本的`ecs_ram_role`模式；该模式通过IMDSv2确认角色存在，再让ossutil自动取得短期STS凭据，不需要AccessKey或ossutil凭据文件。
 
 当前脚本需要上传后回读，因此至少要具备指定前缀的写入和读取权限。Bucket创建、RAM授权和跨区域复制属于云资源变更，不能通过服务器root账号替代完成。
 
@@ -66,9 +66,14 @@ OFFSITE_BACKUP_ENABLED=true
 OFFSITE_BACKUP_REQUIRED=true
 OFFSITE_OSS_BUCKET=your-private-backup-bucket
 OFFSITE_OSS_PREFIX=data-terminal-cloud/121.41.46.238
+OFFSITE_OSS_AUTH_MODE=ecs_ram_role
+OFFSITE_OSS_REGION=cn-hangzhou
+OFFSITE_OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
 OFFSITE_OSS_CONFIG_FILE=/etc/data-terminal-cloud/ossutilconfig
 ```
 
+`OFFSITE_OSS_CONFIG_FILE`只在`OFFSITE_OSS_AUTH_MODE=config`时读取，用于兼容受控配置文件或隔离测试；阿里云ECS正式路径使用`ecs_ram_role`。脚本强制通过IMDSv2获取元数据令牌，不回退IMDSv1。角色缺失时任务以`ecs_ram_role_missing`失败，不会继续读取本机归档或尝试匿名访问OSS。
+
 然后执行：
 
 ```bash
@@ -89,7 +94,11 @@ systemctl start platform-health-monitor.service
 | 原因 | 含义 |
 |---|---|
 | `ossutil_missing` | 官方客户端未安装 |
+| `curl_missing` | ECS RAM角色模式缺少IMDSv2请求客户端 |
 | `oss_config_missing` | 身份配置不可读 |
+| `ecs_metadata_v2_unavailable` | 无法取得IMDSv2元数据令牌 |
+| `ecs_ram_role_missing` | ECS未绑定实例RAM角色或角色名称无效 |
+| `invalid_oss_region` / `invalid_oss_endpoint` | OSS地域或端点配置不合法 |
 | `local_backup_missing` | 没有本机加密备份 |
 | `local_checksum_failed` | 本机归档已损坏 |
 | `archive_upload_failed` | OSS归档上传失败 |
@@ -105,6 +114,8 @@ systemctl start platform-health-monitor.service
 - 禁用状态：任务成功记录`disabled/not_enabled`，不访问OSS；
 - 隔离兼容目标：上传归档和摘要、回读并复算，状态为`verified`且远端有2个文件；
 - 缺身份配置：退出4并记录`failed/oss_config_missing`；
+- ECS RAM角色缺失：在目标阿里云实例通过IMDSv2实测退出4并记录`failed/ecs_ram_role_missing`；
+- 兼容配置模式：隔离OSS替身完成上传、摘要上传、双回读和三方摘要一致校验；
 - 健康门禁：设为必需但缺远端状态时退出1并记录`offsite_backup=critical/status_missing`。
 
 隔离兼容目标只验证脚本控制流与摘要闭环，不是阿里云真实Bucket证据。真实门禁必须在配置RAM角色和私有Bucket后重新执行。