.

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

驗證遠端存放區，以上游 Docker Hub 來源為準

Artifact Registry 可讓您向 Docker Hub 驗證遠端存放區。雖然提取公開映像檔不需要驗證，但驗證可提高下載頻率限制。如要驗證，請使用 Docker Hub 使用者名稱和儲存為密鑰的個人存取權杖，設定遠端存放區。

事前準備

確認符合下列規定：

您已建立 Artifact Registry Docker 遠端存放區
您有 Docker Hub 帳戶。

必要的角色

如要取得設定遠端存放區 Docker Hub 驗證所需的權限，請要求管理員授予您專案的下列 IAM 角色：

Artifact Registry 管理員 (roles/artifactregistry.admin)
Secret Manager 管理員 (roles/secretmanager.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

建立 Docker Hub 個人存取權杖

登入 Docker Hub。
建立具有唯讀權限的個人存取權杖。
複製存取權杖。

警告： 存取權杖只會顯示一次。如果關閉視窗，就無法擷取，必須建立新的存取權杖。
將存取權杖儲存至本機或 Cloud Shell 的文字檔。

警告： 請將存取權杖視為密碼，妥善保管。

將個人存取權杖儲存為密鑰版本

在 Secret Manager 中建立密鑰。
將 Docker Hub 個人存取權杖儲存為密鑰版本。

授予 Artifact Registry 服務帳戶存取密鑰的權限

與 Google Cloud 服務互動時，Artifact Registry 服務代理會代表 Artifact Registry 執行操作。如要允許服務代理使用儲存在 Secret Manager 中的密鑰，您必須授予服務代理查看密鑰版本的權限。

服務代理 ID 如下：

service-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com

PROJECT-NUMBER 是執行 Artifact Registry 的 Google Cloud 專案編號。

如要將 Secret Manager 密鑰存取者角色授予 Artifact Registry 服務代理，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Secret Manager」頁面。

前往「Secret Manager」頁面
在「Secret Manager」頁面，勾選 Secret 名稱旁的核取方塊。
若面板尚未開啟，請按一下「Show Info Panel」(顯示資訊面板) 以開啟面板。
在資訊面板中，按一下「Add Principal」(新增主體)。
在「New principals」(新增主體) 文字區域中，輸入要新增的成員電子郵件地址。
在「Select a role」(請選擇角色) 下拉式選單中，依序選擇「Secret Manager」和「Secret Manager Secret Accessor」(Secret Manager 密鑰存取者)。

gcloud

$ gcloud secrets add-iam-policy-binding secret-id \
    --member="member" \
    --role="roles/secretmanager.secretAccessor"

其中 member 是 IAM 成員，例如使用者、群組或服務帳戶。

C#

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


using Google.Cloud.SecretManager.V1;
using Google.Cloud.Iam.V1;

public class IamGrantAccessSample
{
    public Policy IamGrantAccess(
      string projectId = "my-project", string secretId = "my-secret",
      string member = "user:foo@example.com")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretName secretName = new SecretName(projectId, secretId);

        // Get current policy.
        Policy policy = client.GetIamPolicy(new GetIamPolicyRequest
        {
            ResourceAsResourceName = secretName,
        });

        // Add the user to the list of bindings.
        policy.AddRoleMember("roles/secretmanager.secretAccessor", member);

        // Save the updated policy.
        policy = client.SetIamPolicy(new SetIamPolicyRequest
        {
            ResourceAsResourceName = secretName,
            Policy = policy,
        });
        return policy;
    }
}

Go

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
)

// iamGrantAccess grants the given member access to the secret.
func iamGrantAccess(w io.Writer, name, member string) error {
	// name := "projects/my-project/secrets/my-secret"
	// member := "user:foo@example.com"

	// Create the client.
	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Get the current IAM policy.
	handle := client.IAM(name)
	policy, err := handle.Policy(ctx)
	if err != nil {
		return fmt.Errorf("failed to get policy: %w", err)
	}

	// Grant the member access permissions.
	policy.Add(member, "roles/secretmanager.secretAccessor")
	if err = handle.SetPolicy(ctx, policy); err != nil {
		return fmt.Errorf("failed to save policy: %w", err)
	}

	fmt.Fprintf(w, "Updated IAM policy for %s\n", name)
	return nil
}

Java

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.iam.v1.Binding;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

public class IamGrantAccess {

  public static void iamGrantAccess() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String secretId = "your-secret-id";
    String member = "user:foo@example.com";
    iamGrantAccess(projectId, secretId, member);
  }

  // Grant a member access to a particular secret.
  public static void iamGrantAccess(String projectId, String secretId, String member)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      // Build the name from the version.
      SecretName secretName = SecretName.of(projectId, secretId);

      // Request the current IAM policy.
      Policy currentPolicy =
          client.getIamPolicy(
              GetIamPolicyRequest.newBuilder().setResource(secretName.toString()).build());

      // Build the new binding.
      Binding binding =
          Binding.newBuilder()
              .setRole("roles/secretmanager.secretAccessor")
              .addMembers(member)
              .build();

      // Create a new IAM policy from the current policy, adding the binding.
      Policy newPolicy = Policy.newBuilder().mergeFrom(currentPolicy).addBindings(binding).build();

      // Save the updated IAM policy.
      client.setIamPolicy(
          SetIamPolicyRequest.newBuilder()
              .setResource(secretName.toString())
              .setPolicy(newPolicy)
              .build());

      System.out.printf("Updated IAM policy for %s\n", secretId);
    }
  }
}

Node.js

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const name = 'projects/my-project/secrets/my-secret';
// const member = 'user:you@example.com';
//
// NOTE: Each member must be prefixed with its type. See the IAM documentation
// for more information: https://cloud.google.com/iam/docs/overview.

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function grantAccess() {
  // Get the current IAM policy.
  const [policy] = await client.getIamPolicy({
    resource: name,
  });

  // Add the user with accessor permissions to the bindings list.
  policy.bindings.push({
    role: 'roles/secretmanager.secretAccessor',
    members: [member],
  });

  // Save the updated IAM policy.
  await client.setIamPolicy({
    resource: name,
    policy: policy,
  });

  console.log(`Updated IAM policy for ${name}`);
}

grantAccess();

PHP

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;

// Import the Secret Manager IAM library.
use Google\Cloud\Iam\V1\Binding;
use Google\Cloud\Iam\V1\GetIamPolicyRequest;
use Google\Cloud\Iam\V1\SetIamPolicyRequest;

/**
 * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId  Your secret ID (e.g. 'my-secret')
 * @param string $member Your member (e.g. 'user:foo@example.com')
 */
function iam_grant_access(string $projectId, string $secretId, string $member): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the secret.
    $name = $client->secretName($projectId, $secretId);

    // Get the current IAM policy.
    $policy = $client->getIamPolicy((new GetIamPolicyRequest)->setResource($name));

    // Update the bindings to include the new member.
    $bindings = iterator_to_array($policy->getBindings());
    $bindings[] = new Binding([
        'members' => [$member],
        'role' => 'roles/secretmanager.secretAccessor',
    ]);
    $policy->setBindings($bindings);

    // Build the request.
    $request = (new SetIamPolicyRequest)
        ->setResource($name)
        ->setPolicy($policy);

    // Save the updated policy to the server.
    $client->setIamPolicy($request);

    // Print out a success message.
    printf('Updated IAM policy for %s', $secretId);
}

Python

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

Ruby

如要向 Artifact Registry 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

# project_id = "YOUR-GOOGLE-CLOUD-PROJECT"  # (e.g. "my-project")
# secret_id  = "YOUR-SECRET-ID"             # (e.g. "my-secret")
# member     = "USER-OR-ACCOUNT"            # (e.g. "user:foo@example.com")

# Require the Secret Manager client library.
require "google/cloud/secret_manager"

# Create a Secret Manager client.
client = Google::Cloud::SecretManager.secret_manager_service

# Build the resource name of the secret.
name = client.secret_path project: project_id, secret: secret_id

# Get the current IAM policy.
policy = client.get_iam_policy resource: name

# Add new member to current bindings
policy.bindings << Google::Iam::V1::Binding.new(
  members: [member],
  role:    "roles/secretmanager.secretAccessor"
)

# Update IAM policy
new_policy = client.set_iam_policy resource: name, policy: policy

# Print a success message.
puts "Updated IAM policy for #{secret_id}"

API

注意：與其他範例不同，這會取代整個 IAM 政策。

$ curl "https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id:setIamPolicy" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"policy\": {\"bindings\": [{\"members\": [\"member\"], \"role\": \"roles/secretmanager.secretAccessor\"}]}}"

如要進一步瞭解如何授予或撤銷密鑰存取權，請參閱「管理密鑰存取權」。

將 Docker Hub 憑證新增至遠端存放區

如要使用 Docker Hub 憑證更新遠端存放區，請按照下列步驟操作：

控制台

在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

開啟「存放區」頁面
在存放區清單中，選取存放區，然後按一下「Edit Repository」(編輯存放區)。
在「Remote repository authentication mode」(遠端存放區驗證模式) 區段中，更新或新增 Docker Hub 使用者名稱，以及含有 Docker Hub 存取權杖的密鑰版本。

gcloud CLI

如要使用 Docker Hub 憑證更新遠端存放區，請執行下列指令：

gcloud artifacts repositories update REPOSITORY \
    --project=PROJECT_ID \
    --location=LOCATION \
    --remote-username=USERNAME \
    --remote-password-secret-version=projects/SECRET_PROJECT_ID/secrets/SECRET_ID/versions/SECRET_VERSION

更改下列內容：

REPOSITORY：Artifact Registry 遠端存放區的名稱。
PROJECT_ID：您的 Google Cloud 專案 ID。
LOCATION：存放區的區域或多區域位置。如果您設定了預設值，則可省略這個旗標。如要查看支援的位置清單，請執行 gcloud artifacts locations list 指令。
USERNAME：您的 Docker Hub 使用者名稱。
SECRET_PROJECT_ID：您建立 Secret 的Google Cloud 專案 ID。
SECRET_ID：您為密鑰指定的名稱。
SECRET_VERSION：儲存 Docker Hub 存取權杖的密鑰版本。

下次遠端存放區要求上游來源的構件時，就會使用您的憑證。

後續步驟

進一步瞭解 Artifact Registry 存放區。
使用 Docker 提取映像檔。
完成 Docker Hub 遠端存放區快速入門導覽課程。

除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。

上次更新時間：2026-10-30 (世界標準時間)。