> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Hub

> Kết nối Docker Hub để agent kiểm kê repository, so sánh lượt pull và tuổi lần push, kiểm tra tag và cập nhật mô tả

Kết nối Docker Hub để các agent CloudThinker liệt kê repository trong các namespace của bạn, so sánh chế độ hiển thị, lượt pull và tuổi lần push gần nhất, đồng thời kiểm tra tag của từng repository. Kết nối dùng username Docker Hub và một personal access token (PAT), và mặc định ở chế độ chỉ đọc.

## Điều kiện tiên quyết

* Một tài khoản Docker có quyền truy cập các repository cá nhân và tổ chức mà bạn muốn agent kiểm tra.
* Username Docker Hub của bạn: tên tài khoản, không phải địa chỉ email hay tên tổ chức.
* Với repository của tổ chức: một tài khoản Docker là thành viên của tổ chức đó. Dùng một tài khoản riêng cho CloudThinker để tách token khỏi thông tin đăng nhập của một cá nhân.

## Thiết lập

**1. Tạo personal access token**

Trong Docker Home, chọn avatar, rồi **Account settings → Personal access tokens** ([app.docker.com/settings/personal-access-tokens](https://app.docker.com/settings/personal-access-tokens)), và nhấn **Generate new token**. Đặt:

* **Access token description**: `cloudthinker`
* **Expiration date**: thời hạn phù hợp với chính sách xoay vòng của bạn
* **Access permissions**: **Repo Read-only**. Chỉ chọn **Repo Read, Write, Delete** nếu bạn muốn agent cập nhật mô tả repository (xem [Quyền ghi](#quyền-ghi)).

Đừng giữ giá trị mặc định **Repo Public Read-only**. Quyền này không đọc được repository private, nên agent sẽ bỏ sót mọi repository private trong các namespace của bạn.

Nhấn **Generate** và sao chép token. Docker chỉ hiển thị token một lần.

**2. Thêm kết nối**

Mở **More → Workspace settings → Connections**, ở lại tab **Builtin Connections** và chọn **Docker Hub**. Điền:

* **Docker Hub username**: tài khoản đã tạo PAT, chẳng hạn `myuser`.
* **Personal access token**: PAT. Không phải mật khẩu Docker Hub.

Nhấn **Connect**. CloudThinker đăng nhập và đọc namespace cá nhân của bạn.

**Trạng thái thành công:** kết nối hiển thị **Connected**, với thông báo như `Connected to Docker Hub namespace myuser (12 repositories)`.

## Chi tiết kết nối

| Trường | Mô tả | Ví dụ |
| - | - | - |
| **Docker Hub username** | Tài khoản sở hữu PAT. Chỉ gồm chữ cái, chữ số, `.`, `-` và `_` | `myuser` |
| **Personal access token** | PAT từ cài đặt tài khoản Docker | |

Không có trường namespace. Namespace cá nhân chính là username của bạn, và agent tự phát hiện các namespace tổ chức từ token.

## Quyền yêu cầu

| Quyền PAT | Cho phép gì |
| - | - |
| **Repo Public Read-only** (mặc định của Docker) | Chỉ repository public. Repository private không hiển thị. |
| **Repo Read-only** | Mọi thao tác đọc: namespace, repository, chế độ hiển thị, lượt pull, star, tuổi lần push và tag, bao gồm cả repository private |
| **Repo Read, Write, Delete** | Mọi thao tác đọc, cộng thêm cập nhật mô tả ngắn và phần overview của repository |

Docker Hub từ chối cập nhật mô tả từ PAT **Repo Read & Write**, nên mức quyền đó không cho agent thêm gì.

> [!TIP]
>
> Bắt đầu với PAT **Repo Read-only**. Chỉ chuyển sang **Repo Read, Write, Delete** cho workspace cần agent sửa văn bản repository.

## Quyền ghi

Kết nối ở chế độ chỉ đọc khi bạn thêm vào. Để cho phép agent cập nhật mô tả repository:

1. Kết nối lại với PAT **Repo Read, Write, Delete**.
2. Trong **More → Workspace settings → Connections**, chọn **Docker Hub** và bật công tắc **Allow writes** trên bảng chi tiết của kết nối.

Khi đó mỗi lần cập nhật đều đi qua [Rules](https://docs.cloudthinker.io/vi/guide/approvals/rules.md) và [Approval mode](https://docs.cloudthinker.io/vi/guide/approvals/approval-mode.md) của bạn. Agent hiển thị văn bản hiện tại và chính xác văn bản mới trước khi hỏi.

Ngay cả khi bật ghi, agent chỉ thay đổi được mô tả ngắn và overview của repository. Agent không thể push, pull, xóa hoặc đổi tên image, thay đổi chế độ hiển thị, tạo hoặc xóa repository, hay quản lý thành viên và token.

> [!WARNING]
>
> CloudThinker giới hạn những gì agent làm với token, không giới hạn những gì token làm được. PAT **Repo Read, Write, Delete** có thể xóa repository nếu bị lộ. Chỉ dùng loại này khi bạn cần sửa mô tả, và đặt thời hạn ngắn.

## Khả năng của agent

| Khả năng | Agent làm được gì |
| - | - |
| **Khám phá tài khoản** | Xác định namespace cá nhân và các namespace tổ chức mà token truy cập được |
| **Kiểm kê repository** | Liệt kê repository theo namespace với chế độ hiển thị, tổng lượt pull, star, số ngày kể từ lần push gần nhất và trạng thái Docker Hub (active hoặc inactive) |
| **Kiểm tra tag** | Hiển thị số tag, kích thước nén, nền tảng, ngày push và pull cho một repository |
| **Văn bản repository** | Đọc mô tả repository, và cập nhật mô tả ngắn hoặc overview khi bật ghi |

Đọc các con số theo cách Docker Hub báo cáo:

* **Pulls** là tổng từ trước đến nay. Chúng không thể hiện xu hướng hay đột biến.
* **Sizes** là kích thước layer đã nén, không phải dung lượng lưu trữ đã dùng hay mức chiếm dụng khi chạy.
* **Days since last push** chỉ là tuổi lần push. Docker Hub không báo cáo thứ gì đang chạy image, nên con số này không chứng minh được một repository không còn được dùng.
* **Inactive** là dấu hiệu riêng của Docker Hub cho việc không có push hoặc pull nào trong một tháng.

Kết nối này không báo cáo chi phí lưu trữ, lỗ hổng bảo mật hay chữ ký image.

### Xác minh kết nối

```text theme={null}
Discover my Docker Hub account and list each namespace with its repository count
```

Kết quả mong đợi là namespace cá nhân của bạn và các namespace tổ chức, mỗi namespace kèm số repository private và public.

### Ví dụ prompt

```text theme={null}
List repositories in the acme namespace sorted by last push, with visibility and lifetime pulls
Inspect the tags of acme/api and show compressed size, platforms, and push and pull dates
```

## Khắc phục sự cố

> **Invalid Docker Hub username**
>
> Bạn đã nhập địa chỉ email hoặc tên tổ chức. Hãy nhập tên tài khoản đã tạo PAT.

> **Authentication failed**
>
> PAT sai, đã hết hạn, bị vô hiệu hóa hoặc bị xóa. Tạo PAT mới và kết nối lại với cùng username.

> **Thiếu một namespace tổ chức**
>
> Docker Hub từ chối một phần danh sách tổ chức đối với đăng nhập bằng PAT. Điều đó không có nghĩa là bạn không có tổ chức nào. Hãy yêu cầu agent kiểm tra namespace theo tên, chẳng hạn `acme`, và xác nhận tài khoản của PAT là thành viên. Nếu thành công, agent sẽ liệt kê các repository của namespace đó.

> **Không tìm thấy một repository private**
>
> Kiểm tra tên đầy đủ, `NAMESPACE/NAME`. Docker Hub cũng trả về "not found" khi tài khoản của PAT không đọc được một repository private.

> **Cập nhật mô tả bị từ chối**
>
> Kiểm tra ba điều theo thứ tự. Công tắc **Allow writes** trên bảng chi tiết của kết nối phải được bật. PAT phải là **Repo Read, Write, Delete**; PAT **Repo Read & Write** bị từ chối. Không được có Rule nào trong [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) từ chối thao tác cập nhật.

> **429 rate limited**
>
> Docker Hub đã giới hạn số request. Chờ vài phút, rồi hỏi về từng namespace hoặc repository một.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Ưu tiên Repo Read-only**: PAT **Repo Read-only** bao gồm mọi thao tác đọc. Ngay cả PAT **Repo Read, Write, Delete** cũng chỉ thay đổi được văn bản repository qua kết nối này.
- **Rà soát PAT**: đặt thời hạn và kiểm tra ngày dùng gần nhất trong **Account settings → Personal access tokens**. Vô hiệu hóa các token bạn không còn cần.

## Liên quan

> **[CircleCI](https://docs.cloudthinker.io/vi/guide/connections/circleci.md)**
>
> Trạng thái pipeline, log lỗi, test chập chờn và chạy lại có kiểm soát phê duyệt.

> **[Tổng quan kết nối](https://docs.cloudthinker.io/vi/guide/connections/overview.md)**
>
> Cách thông tin xác thực, Allow writes và Approvals phối hợp với nhau.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.