Docker Hub PAT 申請指南

發表於 分類於 ，

Docker Hub PAT 申請指南

什麼是 Docker Hub PAT？

Docker Hub Personal Access Token (PAT) 是 Docker Hub 提供的身份驗證機制，用於替代傳統的使用者名稱和密碼組合。PAT 提供了更安全的方式來存取 Docker Hub 的 API 和映像倉庫。

PAT 的主要優勢：

  • 安全性：避免在腳本或配置中使用明文密碼
  • 權限控制：可以設定特定的權限範圍
  • 易於管理：可以獨立撤銷和更新，不影響帳戶密碼
  • 審計追蹤：提供更好的存取記錄和監控

為什麼需要使用 PAT？

在以下情況下，建議使用 PAT 替代密碼：

  1. CI/CD 流程：在自動化部署中進行映像推送和拉取
  2. 本地開發：在 Minikube 或其他本地環境中拉取私有映像
  3. 腳本自動化：需要程式化存取 Docker Hub API
  4. 企業環境：符合企業安全政策和最佳實務

PAT 申請步驟

步驟 1：登入 Docker Hub

  1. 開啟瀏覽器，前往 Docker Hub
  2. 點選右上角的 Sign In 按鈕
  3. 輸入您的 Docker Hub 帳號和密碼進行登入

步驟 2：進入帳戶設定

  1. 登入後，點選右上角的帳戶頭像
  2. 從下拉選單中選擇 Account Settings

步驟 3：進入 Personal Access Tokens

  1. 在左側導航選單中點選 Settings
  2. 展開 Settings 選單，選擇 Personal access tokens
  3. 您會看到 Personal access tokens 頁面，顯示現有的權杖列表

步驟 4：建立新的存取權杖

  1. 點選右上角的 Generate new token 按鈕
  2. 進入 Create access token 頁面

步驟 5：配置權杖設定

  1. Access token description：輸入有意義的描述名稱

    • 範例：minikube-pull、ci-cd-pipeline、local-development

  2. Expiration date：選擇權杖的過期時間

    • None：永不過期（不建議用於生產環境）
    • 30 days：30 天後過期
    • 90 days：90 天後過期
    • Custom：自訂過期日期

  3. Access permissions：選擇適當的權限級別

    • Public Repo Read-only：只能讀取公開倉庫（預設選項，推薦用於拉取）
    • Read-only：只能讀取所有可存取的倉庫
    • Read & Write：可以讀取和寫入倉庫
    • Read, Write, Delete：完整權限（謹慎使用）

  4. 點選 Generate 按鈕建立權杖

步驟 6：複製和保存權杖

權杖建立成功後，您會看到 Copy access token 頁面：

⚠️ 重要提醒：個人存取權杖只會顯示一次，無法儲存且之後無法再檢索

  1. 權杖資訊確認：

    • Access token description：您設定的描述名稱（如：test）
    • Expires on：過期時間（如：Never 表示永不過期）
    • Access permissions：權限級別（如：Public Repo Read-only）

  2. 複製權杖：

    • 在步驟 1 中，複製 Docker CLI 登入指令：
      1
      docker login -u <username>
    • 點選右側的 Copy 按鈕複製指令

  3. 複製個人存取權杖：

    • 在步驟 2 中，顯示完整的個人存取權杖字串
    • 權杖格式類似：dckr_pat_abcdefghijk00000
    • 點選右側的 Copy 按鈕複製權杖

  4. 安全保存：

    • 立即將權杖保存在安全的位置（如密碼管理器）
    • 記錄權杖的用途和建立日期

  5. 完成申請：

    • 點選 Back to access tokens 按鈕返回權杖管理頁面

使用說明

根據頁面提示，您可以使用此權杖作為密碼，透過 Docker CLI 客戶端登入：

  1. 執行登入指令：

    1
    docker login -u <username>

  2. 在密碼提示時輸入個人存取權杖：

    1
    Password: <password>

權杖管理介面說明

在 Personal access tokens 頁面中，您可以看到：

  • Description：權杖的描述名稱
  • Scope：權杖的權限範圍
  • Status：權杖狀態（Active/Inactive）
  • Source：建立方式（Manual/Auto-generated）
  • Created：建立時間
  • Last used：最後使用時間
  • Expiration date：過期日期

您可以透過右側的操作選單來管理現有的權杖，包括查看詳細資訊、停用或刪除權杖。

使用 PAT 進行身份驗證

在命令列中使用

根據 Docker Hub 提供的指引，推薦使用以下方式：

1
2
3
4
5
6
7
8
9
10
11
12
# 方法一：使用 Docker Hub 提供的登入指令
docker login -u <username>
# 在密碼提示時輸入 PAT，例如：
# Password: dckr_pat_abcdefghijk00000

# 方法二：直接在指令中指定（較不安全，會在命令歷史中留下記錄）
docker login -u <username> -p <password>

# 方法三：互動式登入（最安全）
docker login
# Username: <username>
# Password: <password>

最佳實務：建議使用方法一或方法三，避免在指令行中直接暴露 PAT。

在 Kubernetes 中使用

1
2
3
4
5
6
# 建立 Docker Registry Secret
kubectl create secret docker-registry regcred \
  --docker-server=https://index.docker.io/v1/ \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<email>

在 CI/CD 中使用

1
2
3
4
5
6
# GitHub Actions 範例
- name: Login to Docker Hub
  uses: docker/login-action@v2
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

PAT 管理最佳實務

權限設定建議

  1. 最小權限原則：只授予必要的權限

    • 僅拉取映像：使用 Public Repo Read-only 或 Read-only
    • 需要推送映像：使用 Read & Write
    • 避免使用 Read, Write, Delete 權限，除非絕對必要

  2. 專用權杖：為不同用途建立專用的 PAT

    • 開發環境：dev-environment-pat
    • 生產 CI/CD：prod-pipeline-pat
    • 個人使用：personal-tools-pat

  3. 過期時間設定：

    • 開發測試：建議設定 30-90 天
    • 生產環境：建議設定 90 天並定期輪換
    • 避免使用 None（永不過期）選項

安全性考量

  1. 定期輪換：建議每 3-6 個月更新一次 PAT
  2. 安全存儲：
    • 使用環境變數而非硬編碼
    • 存儲在密碼管理器中
    • 在 CI/CD 中使用 Secrets 管理
  3. 監控使用：定期檢查 PAT 的使用情況和存取記錄

權杖管理

在 Docker Hub 的 Personal access tokens 頁面中，您可以：

1
2
3
4
5
6
7
# 查看當前的 PAT 資訊
# 包含：Description、Scope、Status、Source、Created、Last used、Expiration date

# 管理現有權杖
# - 點選權杖右側的三點選單
# - 選擇 "View details"、"Deactivate" 或 "Delete"
# - 建議定期清理不再使用的權杖

權杖狀態說明：

  • Active：權杖正常可用
  • Inactive：權杖已停用
  • Manual：手動建立的權杖
  • Auto-generated：系統自動生成的權杖（如透過 Docker Desktop）

疑難排解

常見問題

1. 權杖驗證失敗

可能原因：

  • 權杖已過期或被撤銷
  • 權限不足
  • 使用者名稱錯誤

解決方法：

1
2
3
4
5
6
7
8
# 檢查登入狀態
docker info

# 重新登入
docker logout
docker login

# 確認權杖權限是否足夠

2. 無法拉取私有映像

檢查項目：

  • PAT 是否具有私有倉庫讀取權限
  • 映像名稱和標籤是否正確
  • 網路連線是否正常
1
2
3
4
5
# 測試拉取公開映像
docker pull hello-world

# 檢查映像倉庫狀態
docker search <your-image-name>

3. Kubernetes 中無法使用 Image Pull Secret

1
2
3
4
5
6
7
8
# 檢查 Secret 是否正確建立
kubectl get secrets

# 查看 Secret 詳細資訊
kubectl describe secret regcred

# 測試 Pod 中的映像拉取
kubectl run test-pod --image=<your-private-image> --dry-run=client -o yaml

權杖續期和更新

定期檢查

  1. 登入 Docker Hub
  2. 前往左側選單的 Settings > Personal access tokens
  3. 檢查權杖列表中的 Last used 時間和 Expiration date
  4. 透過右側選單移除不再使用的權杖

更新流程

  1. 在 Personal access tokens 頁面點選 Generate new token
  2. 建立新的 PAT 並設定適當的過期時間
  3. 在所有使用舊 PAT 的地方更新為新 PAT
  4. 測試新 PAT 是否正常運作
  5. 在舊權杖的右側選單中選擇 Delete 來撤銷舊的 PAT

自動化更新提醒

建議設定日曆提醒或使用監控工具，定期檢查和更新 PAT，確保服務的持續可用性。

透過正確申請和管理 Docker Hub PAT，您可以提高 Docker 映像管理的安全性，同時保持開發和部署流程的順暢運行。