本文說明如何解決 Compute Engine 中繼資料伺服器的問題。
Compute Engine VM 會將中繼資料儲存在中繼資料伺服器。虛擬機器可自動存取中繼資料伺服器 API，而無需其他任何授權。不過，VM 有時可能會因為下列原因而無法存取中繼資料伺服器：
- 無法解析中繼資料伺服器網域名稱
- 下列其中一項因素會封鎖與中繼資料伺服器的連線：
- 作業系統層級的防火牆設定
- 設定 Proxy
- 自訂路徑
如果 VM 無法存取中繼資料伺服器，部分程序可能會失敗。
如要瞭解如何排解 gke-metadata-server 問題，請參閱「排解 GKE 驗證問題」。
事前準備
-
如果尚未設定驗證，請先完成設定。
驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，可以選取下列任一選項，向 Compute Engine 進行驗證：
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI：
gcloud init如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。
- Set a default region and zone.
REST
如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。
安裝 Google Cloud CLI。 安裝完成後，執行下列指令初始化 Google Cloud CLI：
gcloud init如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。
詳情請參閱 Google Cloud 驗證說明文件中的「Authenticate for using REST」。
排解伺服器代碼問題
呼叫 Compute Engine 中繼資料伺服器時，系統會傳回下列伺服器代碼。請參閱本節，瞭解如何回應中繼資料伺服器傳回的每個伺服器代碼。
常見伺服器代碼
這些伺服器代碼經常從中繼資料伺服器傳回。
伺服器程式碼 說明 解決方法 200 OK：要求成功 不適用 400 要求無效：如果要求含有不當的查詢參數，或未滿足端點的要求，系統就會傳回這個錯誤狀態。 查看錯誤訊息，瞭解如何修正錯誤 403 禁止：在下列情況中，系統會傳回這個錯誤狀態： - 專案或執行個體設定已停用要求的端點
- 要求未通過安全檢查。如果伺服器的 TCP 連線在網路層關閉，就可能發生這個問題。
檢查專案和執行個體設定，確認端點已啟用，或檢查網路設定 404 找不到：要求的端點不存在 修正要求路徑 429 要求過多：發生這種情況是因為部分端點使用速率限制，避免後端服務過載。強烈建議您以指數輪詢方式重試。詳情請參閱受速率限制的端點清單。 請稍候片刻，然後重新撥號 503 服務無法使用：中繼資料伺服器尚未準備好提供服務。在下列任一情況下，中繼資料伺服器可能會傳回 Error 503狀態碼：- 中繼資料伺服器仍在啟動
- 中繼資料伺服器正在遷移
- 中繼資料伺服器暫時無法使用
- 主機正在執行維護事件
- 對部分端點進行速率限制時，中繼資料伺服器可能會傳回
503。
503 錯誤是暫時性的，最多幾秒後就會解決。如要解決問題，請稍候幾秒鐘，然後重新撥打電話。 罕見的伺服器代碼
中繼資料伺服器也可能傳回這些伺服器代碼，但機率不高。
伺服器程式碼 說明 解決方法 301 永久移動：適用於有重新導向的路徑 更新要求路徑 405 不允許：如果要求使用不支援的方法，系統會傳回這個錯誤碼。
中繼資料伺服器僅支援GET作業，但可供訪客寫入的中繼資料除外，這類資料允許SET作業。更新要求路徑中的方法 頻率受限的端點錯誤代碼
下列端點設有速率限制，可能會傳回錯誤代碼。如要處理這些傳回的錯誤代碼，請參閱「重試指引」。
端點 狀態碼 說明 oslogin/429使用者、授權和群組要求會共用 OS 登入頻率限制。 instance/service-accounts/identity503身分簽署端點可能會傳回 429或503回應代碼，表示回應受到速率限制。instance/service-accounts/default/token429中繼資料伺服器中的快取權杖沒有速率限制。未快取的權杖會受到頻率限制。 instance/guest-attributes/429、503如果超過 3 QPS 或 10 QPM，系統可能會限制訪客屬性要求。如果發生節流，系統會傳回錯誤代碼 429或503。重試指南
中繼資料伺服器會定期傳回 503 和 429 錯誤代碼。 為確保應用程式的穩定性，建議您為查詢中繼資料伺服器的應用程式實作重試邏輯。此外，我們建議您在指令碼中實作指數輪詢，以因應任何可能的速率限制。
排解中繼資料伺服器要求失敗的問題
如果 VM 無法連線至中繼資料伺服器，可能會發生下列錯誤：
curl: (6) Could not resolve host: metadata.google.internal
postAttribute error: Put "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/guestInventory/ShortName": dial tcp: lookup metadata.google.internal on [::1]:53: read udp [::1]:58319->[::1]:53: read: connection refused
如果 VM 無法存取中繼資料伺服器，請按照下列步驟操作：
Linux
- 連線至 Linux VM。
從 Linux VM 執行下列指令，測試與中繼資料伺服器的連線：
查詢網域名稱伺服器：
nslookup metadata.google.internal輸出內容應如下所示：
Server: 169.254.169.254 Address: 169.254.169.254#53 Non-authoritative answer: Name: metadata.google.internal Address: 169.254.169.254
確認中繼資料伺服器可連線。如要進行確認，請執行下列指令：
ping -c 3 metadata.google.internal輸出內容應如下所示：
PING metadata.google.internal (169.254.169.254) 56(84) bytes of data. 64 bytes from metadata.google.internal (169.254.169.254): icmp_seq=1 ttl=255 time=0.812 ms
ping -c 3 169.254.169.254輸出內容應如下所示：
PING 169.254.169.254 (169.254.169.254) 56(84) bytes of data. 64 bytes from 169.254.169.254: icmp_seq=1 ttl=255 time=1.11 ms
如果上述指令的輸出內容與建議的輸出內容相符，表示 VM 已連線至中繼資料伺服器，無須採取進一步行動。如果指令失敗，請按照下列步驟操作：
確認名稱伺服器已設定為中繼資料伺服器：
cat /etc/resolv.conf輸出內容應如下所示：
domain ZONE.c.PROJECT_ID.internal search ZONE.c.PROJECT_ID.internal. c.PROJECT_ID.internal. google.internal. nameserver 169.254.169.254
如果輸出內容沒有上述幾行，請參閱作業系統說明文件，瞭解如何編輯 DHCP 政策，將名稱伺服器設定保留在
169.254.169.254中。這是因為如果將區域性 DNS 設定套用至專案中的 VM，/etc/resolv.conf的變更會在 1 小時內遭到覆寫。如果專案仍使用全域 DNS，resolv.conf檔案會在 24 小時內還原為預設 DHCP。確認中繼資料伺服器網域名稱與 IP 位址之間的對應關係是否存在：
cat /etc/hosts輸出內容應包含下列這一行：
169.254.169.254 metadata.google.internal # Added by Google
如果輸出內容沒有上述行，請執行下列指令：
echo "169.254.169.254 metadata.google.internal" >> /etc/hosts
Windows
- 連線至 Windows VM。
從 Windows VM 執行下列指令：
查詢網域名稱伺服器：
nslookup metadata.google.internal輸出內容應如下所示：
Server: UnKnown Address: 10.128.0.1 Non-authoritative answer: Name: metadata.google.internal Address: 169.254.169.254
確認中繼資料伺服器可連線。如要驗證，請執行下列指令：
ping -n 3 metadata.google.internal輸出內容應如下所示：
Pinging metadata.google.internal [169.254.169.254] with 32 bytes of data: Reply from 169.254.169.254: bytes=32 time=1ms TTL=255
ping -n 3 169.254.169.254輸出內容應如下所示：
Pinging metadata.google.internal [169.254.169.254] with 32 bytes of data: Reply from 169.254.169.254: bytes=32 time=1ms TTL=255
如果上述指令的輸出內容與建議的輸出內容相符，表示 VM 已連線至中繼資料伺服器，無須採取進一步行動。如果指令失敗，請按照下列步驟操作：
執行下列指令，確認中繼資料伺服器有永久路徑：
route print輸出會包含下列內容：
Persistent Routes: Network Address Netmask Gateway Address Metric 169.254.169.254 255.255.255.255 On-link 1
如果輸出內容沒有前述行，請使用下列指令新增路徑：
$Adapters = Get-NetKVMAdapterRegistry $FirstAdapter = $Adapters | Select-Object -First 1 route /p add 169.254.169.254 mask 255.255.255.255 0.0.0.0 'if' $FirstAdapter.InterfaceIndex metric 1確認中繼資料伺服器網域名稱與 IP 位址之間的對應關係是否存在：
type %WINDIR%\System32\Drivers\Etc\Hosts輸出內容應包含下列這一行：
169.254.169.254 metadata.google.internal # Added by Google
如果輸出內容沒有上述行，請執行下列指令：
echo 169.254.169.254 metadata.google.internal >> %WINDIR%\System32\Drivers\Etc\Hosts
排解使用網路 Proxy 時要求失敗的問題
網路 Proxy 伺服器會防止 VM 直接存取網際網路。從 VM 內傳送的所有查詢都會改由 Proxy 伺服器處理。
使用會從中繼資料伺服器取得憑證 (例如驗證權杖) 的應用程式時，VM 必須直接存取中繼資料伺服器。如果 VM 位於 Proxy 後方，您必須同時設定 IP 位址和主機名稱的
NO_PROXY設定。如果您未設定
NO_PROXY，在執行 Google Cloud CLI 指令或直接查詢中繼資料伺服器時，可能會看到錯誤訊息，因為對metadata.google.internal的呼叫會傳送至 Proxy，而不會在執行個體本身上解析。您可能會看到類似下方的錯誤訊息：
ERROR 403 (Forbidden): Your client does not have permission to get URL
如要解決這個 Proxy 問題，請按照下列步驟，將中繼資料伺服器主機名稱和 IP 位址新增至環境變數
NO_PROXY：Linux
- 連線至 Linux VM。
在 Linux VM 中執行下列指令：
export no_proxy=169.254.169.254,metadata,metadata.google.internal如要儲存變更，請執行下列指令：
echo no_proxy=169.254.169.254,metadata,metadata.google.internal >> /etc/environment
Windows
- 連線至 Windows VM。
從 Windows VM 執行下列指令：
set NO_PROXY=169.254.169.254,metadata,metadata.google.internal如要儲存變更，請執行下列指令：
setx NO_PROXY 169.254.169.254,metadata,metadata.google.internal /m
排解傳送至 HTTPS 中繼資料伺服器端點的要求失敗問題
本節將說明查詢 HTTPS 中繼資料伺服器端點時可能會遇到的錯誤。
使用 cURL 工具查詢時，系統會傳回本節列出的錯誤，但其他工具傳回的錯誤訊息也類似。
用戶端憑證不正確
如果為
-E旗標提供不正確的值，就會發生下列錯誤。curl: (56) OpenSSL SSL_read: error:1409445C:SSL routines:ssl3_read_bytes:tlsv13 alert certificate required, errno 0
curl: (58) unable to set private key file:
curl: (58) could not load PEM client certificate, OpenSSL error error:02001002:system library:fopen:No such file or directory
如要解決這個問題，請提供用戶端身分證明的正確路徑。如要查看用戶端身分識別憑證的位置，請參閱「用戶端身分識別憑證」。
主機名稱有誤
如果憑證上找不到用於存取中繼資料伺服器的主機名稱，就會發生下列錯誤。
curl: (60) SSL: no alternative certificate subject name matches target host name
如要解決這個問題，請確認查詢中的根網址或主機名稱是否為
metadata.google.internal。如要進一步瞭解中繼資料伺服器的根網址，請參閱中繼資料要求的部分。根憑證或用戶端憑證不正確
查詢 HTTPS 中繼資料伺服器端點時，可能會看到以下錯誤訊息：
curl: (77) error setting certificate verify locations:
這可能發生在下列情況：
--cacert標記的路徑可能格式錯誤- 信任存放區可能缺少根憑證
如要解決這個問題，查詢 https 端點時，您需要同時指定根憑證和用戶端憑證。如要瞭解憑證位置，請參閱「憑證儲存位置」。
舉例來說，如要查詢 VM 的開機映像檔，請執行下列查詢：
user@myinst:~$ curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \ -E /run/google-mds-mtls/client.key \ --cacert /run/google-mds-mtls/root.crt \ -H "Metadata-Flavor: Google"排解標頭格式不正確的問題
中繼資料伺服器會執行格式檢查，確保標頭符合標頭格式規範 RFC 7230 第 3.2 節。 如果標頭格式未通過這些檢查，會發生下列情況：
要求已獲准。不過，您會收到建議，指出 VM 向中繼資料伺服器發出要求時，標頭格式不正確。每個 VM 只會收到一次建議。 您可以使用 Google Cloud CLI 或 Recommender REST API 存取這些建議。
套用最佳化建議後，請將最佳化建議狀態設為
succeeded。自 2024 年 1 月 20 日起，中繼資料伺服器會拒絕任何標頭格式不正確的要求。
以下是有效和無效標頭要求格式的範例。
無效：標頭名稱和半形冒號之間含有空白字元
Metadata-Flavor : Google
有效：標頭名稱和冒號之間沒有空白字元，檢查工具會忽略冒號後的空白字元
Metadata-Flavor: Google
有效：標頭中沒有空白字元
Metadata-Flavor:Google
如要進一步瞭解如何查詢中繼資料伺服器，請參閱「存取 VM 中繼資料」。
排解無法取得權杖的問題
查詢中繼資料伺服器時，您可能會看到下列其中一項錯誤：
ERROR: gcloud crashed (MetadataServerException): HTTP Error 401: Unauthorized
curl: (22) The requested URL returned error: 401
如果附加至 VM 的服務帳戶處於停用狀態，就可能發生這些錯誤。如要解決這些錯誤，請啟用服務帳戶或附加其他服務帳戶。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-09-04 (世界標準時間)。
-