騰訊雲快速開戶 騰訊雲 TCR 鏡像倉庫配置跨帳號拉取鏡像，提示 `Unauthorized` 排查

先看懂 Unauthorized 代表什麼

在騰訊雲 TCR 做跨帳號拉取鏡像時，最常見的報錯之一就是 Unauthorized。很多人一看到這個字樣，第一反應是登入失敗，但實際上它的含義更寬：可能是沒拿到正確憑證，也可能是拿到了憑證，卻沒有對應倉庫的拉取權限，還可能是連到錯的地域、錯的實例，或是 K8s 取到的密鑰已經過期。

這類問題的麻煩之處在於，表面上都叫 Unauthorized，但根因卻完全不同。如果排查順序不對，很容易在網路、鏡像格式、節點環境之間來回打轉。最有效的方法，是先把跨帳號拉取這件事拆成四個環節：倉庫地址是否正確、登入憑證是否有效、目標倉庫是否授權、拉取環境是否真的在使用這組憑證。只要按這個順序查，通常都能很快縮小範圍。

第一步：先確認鏡像地址和實例沒有弄錯

騰訊雲快速開戶 地域、實例、命名空間要對得上

跨帳號拉取最容易忽略的不是權限，而是地址。TCR 的鏡像地址通常和地域、實例綁得很緊。如果源帳號和目標帳號不在同一個 TCR 實例，或者你把地域寫錯了，系統回傳的錯誤有時候不會很直白，最後也可能表現成 Unauthorized。

排查時先確認三件事：第一，拉取用的鏡像地址是否來自正確的 TCR 實例；第二，地址中的地域是否與倉庫實際所在地域一致；第三，命名空間和倉庫名是否完全一致。很多團隊在測試環境與正式環境共用相似命名，結果把測試環境的地址拿去正式環境拉，或反過來，這種錯誤一旦發生，授權再怎麼配也沒有用。

先用最小路徑驗證

如果不確定哪裡有問題，先不要急著在 Kubernetes 或 CI 裡排查，最好直接在一台乾淨的機器上，手動執行登入與拉取。先用最簡單的方式確認：能不能登進對應的 TCR，再能不能拉到指定鏡像。只要手動這一步通了，就表示問題多半不在倉庫本身，而在後面的自動化環節。

第二步：確認跨帳號授權是否真的生效

授權對象不能只看人，還要看角色

跨帳號拉取不是把兩個帳號都變成管理員就結束了。TCR 的授權通常關注的是對方帳號下的某個 RAM 主體，例如子帳號、角色、或某個服務所使用的身份。也就是說，你不是單純把「帳號 A」給了權限，而是要把「帳號 A 底下實際發起拉取動作的那個身份」授權給它。

這裡很容易出現一個錯誤：控制台裡看起來已經加了授權，但 CI/CD 實際使用的卻是另一個角色；或者你授權給了子帳號，但真正執行拉取的是節點上的服務角色。這種情況下，界面上看起來一切正常，到了執行時還是 Unauthorized。因此排查時要先明確：到底是哪一個身份在拉鏡像。

確認授權範圍是否包含 pull

授權不只要「有權限」，還要「有對的權限」。有些人為了保守，只開了查看、列舉之類的能力，卻沒有給拉取鏡像所需的讀取權限；也有人把權限加在實例層，但實際倉庫或命名空間層還有限制。結果就是，登入看似成功，真正拉鏡像時被拒絕。

一個實用判斷方式是：如果登入成功但拉取失敗，通常更像是倉庫或命名空間權限不足；如果連登入都失敗，則更可能是憑證、身份、地域或地址不對。這兩種情況不要混在一起看。

第三步：檢查登入憑證是否過期或用錯

臨時密碼和長期密碼不是一回事

TCR 的登入常常依賴臨時憑證或專用密碼。很多人第一次配置成功後，過幾天就突然拉不下來，原因不是倉庫變了，而是之前保存的密碼已經失效。尤其是在自動化環境裡，密鑰寫死在配置文件中，一旦過期，就會集體報 Unauthorized。

所以排查時，先不要假設登入信息還有效。重新生成一次可用憑證，再手動執行登入，確認能成功，然後再去看自動化流程是否同步更新。如果手動登入可以，但系統還是不行，通常是自動化環節仍在使用舊密碼，或 secret 沒有更新到正確位置。

登錄主機和鏡像地址要完全匹配

登入時使用的 registry 地址，必須和拉取時使用的地址一致。比如你在登入時登的是 A 地域的私有地址，拉取時卻用了 B 地域的公開地址，或者地址中帶了不同的實例名稱，系統會把它當成兩個不同的倉庫來源。這種情況常被誤判為授權問題，其實只是憑證沒有打到正確的地址上。

建議每次排查都把登入命令和鏡像地址放在一起看，確認兩者完全一致，連地域和前綴都不要差一個字元。

第四步：檢查倉庫和命名空間的權限層級

不是授權到實例就一定能拉到所有倉庫

有些團隊以為只要對 TCR 實例開了跨帳號授權，底下所有倉庫就都能拉，實際上未必如此。TCR 通常還會涉及命名空間、倉庫級別的控制。若某個倉庫本身是私有可見，或者僅對特定主體可讀，即使實例層已經放行，最後還是可能被拒絕。

因此，當你看到 Unauthorized 時，不要只看實例級別的設定，也要確認倉庫所在命名空間的可見性，以及倉庫本身的讀取策略。有些問題表面像跨帳號失敗，其實只是你對了實例，卻沒有對到倉庫。

同一個命名空間下的倉庫不要想當然

在實際運維中，命名空間經常被當成整理容器，但權限配置並不會因為名稱相似而自動繼承。某個倉庫能拉，不代表同命名空間下的另一個倉庫也能拉。尤其是多人協作時，常有人複製了一個可用倉庫地址，改了倉庫名，結果卻忘了把對應權限一起補上。

如果你最近只是新增了一個倉庫，老倉庫正常、新倉庫報錯，那幾乎可以直接把重點放在新倉庫的授權和可見性上。

第五步：別忽略網路和接入方式

內網、公網與 VPC 容易混用

在企業環境裡，TCR 可能同時存在內網地址和公網地址。若你的節點部署在 VPC 裡，卻使用了外部可見地址，有時候能連通、有時候不能，最後表現也可能被包裝成 Unauthorized 或類似的認證失敗。雖然這看起來像授權問題，但本質上可能是接入方式不一致，導致你打到的不是預期服務。

尤其在跨帳號、跨環境部署時，最好固定一種接入方式，不要今天用內網，明天用公網。環境一多，排查成本會快速上升。

Kubernetes 環境最容易卡在 secret

如果鏡像拉取發生在 K8s 中，重點就不只是你在本機能不能登錄，而是節點或 Pod 是否拿到了正確的 imagePullSecret。很多時候，本地測試完全正常，但集群裡就是拉不下來，原因往往是 secret 沒綁到對應的 namespace，或者 serviceAccount 沒有引用它。

還有一種常見情況是 secret 已經更新了，但工作負載還在使用舊配置。這時候需要重新掛載或重建 Pod，讓它拿到新的憑證。否則你在控制台看見的已經是最新值，實際拉取時卻還在用舊 token，錯誤自然會一直存在。

第六步：從錯誤現象反推根因

不同報錯，優先看不同方向

雖然大家最後都會統稱為拉取失敗，但其實不同報錯有不同的排查方向。若是直接報 Unauthorized，大多先看登入憑證和權限；若是 no basic auth credentials，優先看 secret 或登入流程是否根本沒生效；若是 denied 類型，通常更像倉庫層級授權不足；若是連不上地址，則先回頭查地域、DNS、網路和 endpoint。

騰訊雲快速開戶 把錯誤分型的好處，是能避免每個問題都從頭查一遍。實務上，先把身份認證和倉庫授權排掉，剩下的通常就不是大問題了。

看日誌時要盯住關鍵字

無論是 Docker、containerd，還是 K8s 的事件日誌，真正有用的不是整段輸出，而是其中幾個關鍵字：登錄失敗、認證失敗、權限拒絕、倉庫不存在、命名空間不匹配。把這些關鍵字和你的授權配置對照，基本就能知道問題落在哪一層。

很多人習慣把日誌從頭到尾貼出來看，結果越看越亂。其實只要抓住錯誤發生的那一瞬間，通常就能知道是登入前出錯、登入時出錯，還是拉取時出錯。

一套好用的排查順序

先手動，再自動；先身份，再網路

面對 TCR 跨帳號拉取鏡像的 Unauthorized，最實用的順序可以記成一句話：先確認地址，再確認身份，接著確認授權，最後看自動化環節。具體做法如下：

• 騰訊雲快速開戶 確認鏡像地址、地域、實例、命名空間是否正確。
• 用正確的身份重新登入一次，排除密碼過期。
• 確認授權對象就是實際拉取鏡像的那個 RAM 主體。
• 核對倉庫級別與命名空間級別的讀取權限。
• 如果在 K8s 中拉取，再檢查 secret、serviceAccount、namespace 是否一致。
• 最後才回頭看網路、DNS、內外網地址和節點接入方式。

這個順序看似簡單，但能幫你避開很多無效排查。尤其是跨帳號場景，常見問題並不是某一項配置完全沒有做，而是做了其中一半，另一半留在了另一個帳號、另一個角色，或者另一個環境裡。

結語：把問題拆小，Unauthorized 就不難查

跨帳號拉取鏡像出現 Unauthorized，本質上不是一個難題，而是一個容易被混淆的題目。它把身份、權限、地址、憑證、環境幾種問題混在一起，讓人誤以為是單點故障。真正高效的做法，不是盲目重試，也不是一次改很多配置，而是把鏈路拆開，一段一段驗證。

只要你先確認地址是否正確，再核對實際拉取身份，接著檢查跨帳號授權和倉庫可讀性，最後排除 secret 過期、K8s 掛載錯誤和內外網混用，大多數 Unauthorized 都能找到明確原因。對運維和平台團隊來說，這套思路比記住某個單一配置更重要，因為它能應付的，不只是今天這個問題，而是之後所有相似的鏡像拉取故障。