CVM 实例元数据使用实践：超时、版本、多网卡与失败处理

结论：把实例身份作为运行时数据，不要写死在镜像里

同一份镜像部署到不同地域后，日志里仍然带着制作镜像时的实例 ID；多网卡机器把 eth0 的地址误当成业务网卡地址；初始化脚本遇到元数据请求失败，却把空值写进配置。这些问题都不是“能不能 curl 通”能单独解决的。

腾讯云 CVM 提供实例元数据接口，可以在实例内部读取实例 ID、地域、可用区等信息。正确的使用边界是：明确读取字段、限制请求等待时间、识别失败，并且只在必要字段全部获取成功后交给下游。下面以 Linux CVM 的启动前检查为例，不涉及临时凭证读取，也不修改云资源。

一、先确认访问位置与版本

在目标 CVM 内执行，而不是在本地电脑、CloudShell 或另一台服务器上替它查询：

curl --noproxy metadata.tencentyun.com \
  --connect-timeout 2 --max-time 5 --fail --silent --show-error \
  http://metadata.tencentyun.com/latest/meta-data/instance-id

其中，连接超时 2 秒、单次请求最长 5 秒是本文示例选择的客户端等待上限，不是产品 SLA。--fail 让 HTTP 4xx/5xx 变为命令失败；--silent --show-error 隐藏进度条但保留错误信息。

显式使用 --noproxy，是为了避免环境里的 HTTP 代理变量让请求绕到代理服务器。不要为了排查而把全部代理配置删掉，也不需要把元数据域名暴露成公网服务。

官方文档列出了 1.0、2017-09-19、latest 等版本入口，并说明不指定版本默认访问 1.0。尤其是 placement 的返回数据存在版本差异。本文统一使用 /latest/meta-data/；长期依赖固定响应结构的程序，应按官方版本说明选择并验证所需版本，不要混用旧示例与新路径。

二、必要字段全部成功后再输出

下面脚本需要 Bash 与 curl。保存为 instance-context.sh，执行 bash instance-context.sh。它只读取三个明确字段，不递归遍历元数据目录，也不会读取角色凭证或用户数据。

#!/usr/bin/env bash
set -euo pipefail

base='http://metadata.tencentyun.com/latest/meta-data'

get_meta() {
  local value
  if ! value=$(curl --noproxy metadata.tencentyun.com \
    --connect-timeout 2 --max-time 5 \
    --fail --silent --show-error "$base/$1"); then
    printf 'metadata request failed: %s\n' "$1" >&2
    return 1
  fi
  if [[ -z "$value" || "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then
    printf 'metadata response invalid: %s\n' "$1" >&2
    return 1
  fi
  printf '%s' "$value"
}

instance_id=$(get_meta 'instance-id')
region=$(get_meta 'placement/region')
zone=$(get_meta 'placement/zone')

printf 'instance_id=%s\nregion=%s\nzone=%s\n' \
  "$instance_id" "$region" "$zone"

脚本只在三个请求全部成功后写标准输出；诊断信息进入标准错误。这样，下游不会把“读到实例 ID，但地域读取失败”的半成品当成成功结果。三个请求串行执行，5 秒并不是整个脚本的总超时。

单行、非空检查只是最基本的结构校验，不是对响应真实性的证明。这份输出用于身份核对或日志标签；不要直接 source 或 eval。如果要生成应用配置，应使用对应格式的序列化工具，并在成功后原子替换目标文件；不能用直接重定向覆盖正在使用的配置，因为 shell 会先截断文件。

三、不要把内网 IP 与公网 IP 当成同一种身份

官方文档说明，local-ipv4 在实例存在多张网卡时返回 eth0 的网络地址。它不等于“业务流量一定使用的地址”，也不能替代路由检查。

如果程序需要指定网卡的信息，先查询网卡目录：

curl --noproxy metadata.tencentyun.com \
  --connect-timeout 2 --max-time 5 --fail --silent --show-error \
  http://metadata.tencentyun.com/latest/meta-data/network/interfaces/macs/

再根据返回的 MAC 目录，查询该网卡的 primary-local-ipv4、vpc-id 或 subnet-id。路径大小写敏感，应沿用实际返回的内容，不要自行改变 MAC 的大小写。公网地址适合描述网络入口，实例 ID 更适合区分实例；二者不要混作同一个主键。

四、把失败分成三类处理

• 解析失败或连接超时：先确认命令确实在目标 CVM 内执行，检查域名解析、代理环境和本机网络策略。不要无限重试来掩盖启动依赖失败。
• HTTP 404：官方文档明确，不存在的资源返回 404。核对字段拼写、版本和资源条件；404 不能自动转换成空字符串再当成有效配置。
• 返回成功但值不符合业务预期：把实例 ID、地域和可用区与控制台实例详情核对。多网卡场景再检查实际路由，不要只看顶层 local-ipv4。

验收时至少检查正常执行的退出码、三个字段与控制台的一致性，以及失败时是否停止产生成功输出。可以在脚本副本中把 instance-id 改成明确不存在的路径，检查非零退出码与标准错误；不要通过关闭整台机器的网络来制造故障。

五、元数据不是“内网所以安全”

官方文档提醒，元数据虽然只能从实例内部访问，但并未被加密保护。元数据还可能包含实例角色临时凭证；用户数据也不适合作为明文密码仓库。

应用提供 URL 抓取、图片代理或回调检测功能时，要防范 SSRF 让外部请求间接访问本机可达的内部接口。不要把元数据目录完整打印到工单、流水线日志或公网诊断页面。生产使用应限制查询字段，并按应用需要配置最小权限。

本文命令依据官方接口文档编写，未展示真实 CVM 的运行结果。上线前应在自己的实例中完成上述验收，不要把文档示例值当作环境事实。

参考文档

• 腾讯云：查看实例元数据，包含访问范围、版本、字段、404 行为与安全说明。