開啟 GitLab Container Registry 功能

發表於 2026-08-05 分類於 gitlab

GitLab 除了可以管理 Git repository、Merge Request 與 CI/CD，也內建 Container Registry 功能。開啟後，每個專案都可以擁有自己的映像檔倉庫，讓團隊把 Docker image 與程式碼放在同一個 GitLab 專案中管理，後續也能搭配 GitLab CI/CD 自動 build、push 與部署。

本文會示範如何在 GitLab Self-Managed 環境中開啟 Container Registry，並透過 Docker CLI 完成登入、build、tag、push 與 GitLab Web UI 驗證。範例環境使用 inner.gitlab.dev 作為 GitLab 網域，並使用 5050 作為 Container Registry 對外連接埠。

前置需求

開始設定前，請先確認環境符合以下條件：

已經安裝 GitLab Self-Managed，並可正常登入 GitLab Web UI
可以使用具備 sudo 權限的帳號登入 GitLab 主機
GitLab 主機的網域名稱或 IP 可以被 Docker client 解析與連線
Docker client 已安裝 Docker Engine 或 Docker Desktop
防火牆、VM port forwarding、安全群組或上層網路設備已開放 Container Registry 使用的連接埠

如果 GitLab 是正式環境，建議搭配 HTTPS 與正式憑證使用；如果只是內網測試環境，也可以先使用 HTTP，但 Docker client 端通常需要額外設定 insecure registry，否則會因為未使用 TLS 而拒絕連線。

設定 registry_external_url

GitLab Omnibus 的主要設定檔位於 /etc/gitlab/gitlab.rb。要開啟 Container Registry，最重要的是設定 registry_external_url，讓 GitLab 知道 Registry 對外提供服務的網址。

先開啟設定檔：

1	sudo nano /etc/gitlab/gitlab.rb

如果要讓 Container Registry 使用和 GitLab 相同的網域，但改用 5050 連接埠，可以加入或修改以下設定：

1	registry_external_url 'http://inner.gitlab.dev:5050'

請把 inner.gitlab.dev 換成自己的 GitLab 網域或主機名稱。如果正式環境已經準備好 HTTPS 憑證，建議改用：

1	registry_external_url 'https://inner.gitlab.dev:5050'

設定完成後，儲存檔案並離開編輯器。

重新套用 GitLab 設定

修改 /etc/gitlab/gitlab.rb 後，需要執行 gitlab-ctl reconfigure，GitLab 才會依照新的設定產生 Nginx、Registry 與相關服務設定。

1	sudo gitlab-ctl reconfigure

完成後可以檢查 GitLab 服務狀態：

1	sudo gitlab-ctl status

如果防火牆使用 ufw，也要開放 Registry 對外使用的連接埠：

1	sudo ufw allow 5050/tcp

如果 GitLab 架在 VirtualBox、VMware、Proxmox、雲端 VM 或公司內網環境，也要確認外層網路有把 5050 連接埠轉發或開放到 GitLab 主機。

設定 Docker insecure registry

若 registry_external_url 使用 HTTP，例如 http://inner.gitlab.dev:5050，Docker client 預設會拒絕連線。這時需要在 Docker client 端把該位址加入 insecure registry。

在 Linux 環境中，可以編輯 Docker daemon 設定檔：

1	sudo nano /etc/docker/daemon.json

加入以下內容：

1
2
3

{
	"insecure-registries": ["inner.gitlab.dev:5050"]
}

如果檔案中原本已經有其他 Docker daemon 設定，請把 insecure-registries 合併到既有 JSON 物件中，不要建立第二個最外層 {}。

儲存後重新啟動 Docker：

1	sudo systemctl restart docker

如果使用 Docker Desktop，可以到 Docker Desktop 的設定頁面中調整 Docker Engine JSON 設定，加入相同的 insecure-registries 欄位後重新啟動 Docker Desktop。

正式環境建議改用 HTTPS 憑證，避免帳號密碼與 token 在未加密連線中傳輸。

登入 GitLab Container Registry

設定完成後，可以先使用 Docker CLI 登入 Registry：

1	docker login inner.gitlab.dev:5050

輸入 GitLab 使用者名稱與密碼後，如果看到 Login Succeeded，代表 Docker client 已經可以成功連到 GitLab Container Registry。

如果 GitLab 帳號有開啟 Two-factor authentication，不能直接使用帳號密碼登入 Registry，需要改用 Personal Access Token 或 Project Access Token。Token 權限至少需要包含 read_registry 與 write_registry，才能完成 pull 與 push 操作。

建立測試 Docker image

接著準備一個可以 build 的 Docker 專案，並建立測試 image。以下範例會使用目前目錄中的 dockerfile，把 image 建成 docker-test:latest：

1	docker build -f dockerfile -t docker-test:latest .

如果 build 成功，可以使用 docker images 檢查本機是否已經有 docker-test:latest。這個 image 目前只存在本機，還沒有上傳到 GitLab Container Registry。

標記 image repository

要把 image 推送到 GitLab Container Registry，image tag 必須符合 GitLab 專案的 Registry 路徑格式。格式通常是：

1	<registry-host>/<namespace>/<project>:<tag>

以上面的範例來說，Registry 位址是 inner.gitlab.dev:5050，GitLab 使用者或 namespace 是 pcion123，專案名稱是 docker-test，tag 是 latest，因此可以執行：

1	docker tag docker-test:latest inner.gitlab.dev:5050/pcion123/docker-test:latest

這個步驟不會重新 build image，只是替既有 image 增加一個符合 Registry 路徑的名稱，讓 Docker 知道要推送到哪一個遠端倉庫。

推送 image 到 GitLab

完成 tag 後，就可以把 image 推送到 GitLab Container Registry：

1	docker push inner.gitlab.dev:5050/pcion123/docker-test:latest

如果看到每個 layer 都完成上傳，最後出現 digest 與 size，代表 image 已經成功推送到 GitLab Container Registry。

在 GitLab Web UI 查看 image

回到 GitLab 專案頁面後，可以從左側選單進入 Deploy > Container registry。如果 push 成功，就會看到剛才上傳的 image repository 與 tag。

展開 tag 後，可以看到 published time、manifest digest、manifest media type 與 supported platforms 等資訊。這些資訊可以用來確認實際被推送上來的 image 版本，也方便後續在部署環境中鎖定特定 digest。

查看與清除 Docker 登入資訊

Docker login 成功後，登入資訊會被保存在使用者家目錄下的 Docker 設定檔中。Linux 環境常見位置是 ~/.docker/config.json。

1	cat ~/.docker/config.json

這個檔案可能包含 Registry 登入憑證或 credential helper 設定，不建議截圖公開，也不要提交到 Git repository。

如果只是測試環境，測試完成後可以登出 Registry，移除本機保存的登入資訊：

1	docker logout inner.gitlab.dev:5050

常見問題排查

設定 Container Registry 時，最常遇到的問題通常和網址、連接埠、憑證或權限有關。可以依照以下方向檢查：

問題	檢查方向
`docker login` 連不上	確認 DNS、`5050` 連接埠、防火牆與 VM port forwarding 是否正確
Docker 顯示 HTTP 不安全	若使用 HTTP，確認 Docker client 已加入 `insecure-registries`
登入失敗	確認帳號密碼、Personal Access Token 或 Project Access Token 是否正確
push 被拒絕	確認使用者對專案是否具備寫入 Registry 的權限
GitLab UI 看不到 image	確認 image tag 是否使用正確的 `<registry-host>/<namespace>/<project>:<tag>` 格式
修改設定後沒有生效	確認已執行 `sudo gitlab-ctl reconfigure`，必要時再檢查 `sudo gitlab-ctl status`

如果需要查看 GitLab Registry 相關 log，可以使用：

1	sudo gitlab-ctl tail registry

也可以搭配 GitLab Nginx log 檢查是否有反向代理或憑證錯誤：

1	sudo gitlab-ctl tail nginx

小結

開啟 GitLab Container Registry 的核心設定是 registry_external_url。在 GitLab 主機上設定好 Registry 對外網址、重新執行 gitlab-ctl reconfigure，並確認防火牆與 Docker client 端設定後，就可以透過 docker login、docker tag 與 docker push 把 image 上傳到 GitLab 專案中。

如果是內網測試環境，使用 http://inner.gitlab.dev:5050 搭配 insecure registry 可以快速驗證流程；如果要放到正式環境，建議改用 HTTPS、妥善管理 token 權限，並搭配 GitLab CI/CD 自動化 build 與 push，讓 image 管理流程更穩定也更容易追蹤。