k8s-airflow/infra/registry/091-registry-install-guide-prod.md

Container Registry 部署指南（生產環境 - 帶認證）

生產環境私有 Container Registry 完整部署指南，包含 Basic Authentication 認證保護。

✅ 推薦用於生產環境
測試環境無認證版本請參考：09-registry-install-guide.md

---

環境說明

• 部署節點: 10.10.0.85
• 服務 Port: 50000
• 數據目錄: /srv/registry
• 認證方式: Basic Auth (htpasswd)
• 預設帳號: admin/password (請自行更改密碼)

---

安裝步驟

1. 安裝必要工具

# 在 10.10.0.85 上執行
sudo apt-get update
sudo apt-get install -y apache2-utils

2. 建立目錄與認證檔

# 建立基礎目錄
sudo mkdir -p /srv/registry/auth

# 建立認證檔案（設定密碼）
sudo htpasswd -Bc /srv/registry/auth/htpasswd admin
# 輸入密碼（建議 16+ 字元）

# 驗證檔案
sudo cat /srv/registry/auth/htpasswd
# 應看到: admin:$2y$05$xxxx...

3. 啟動 Registry 容器

sudo podman run -d \
  --name registry \
  --restart=always \
  -p 50000:5000 \
  -v /srv/registry:/var/lib/registry \
  -v /srv/registry/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  docker.io/library/registry:2

4. 驗證服務

# 檢查容器狀態
sudo podman ps | grep registry

# 測試無認證存取（應失敗）
curl http://10.10.0.85:50000/v2/
# 應回傳: {"errors":[{"code":"UNAUTHORIZED",...}]}

# 測試有認證存取（應成功）
curl -u admin:<your-password> http://10.10.0.85:50000/v2/_catalog
# 應回傳: {"repositories":[]}

---

Kubernetes 節點配置

在所有 K8s 節點上 (doris-f01 ~ f03, doris-b01 ~ b04) 執行：

方法 1: 修改 config.toml（推薦）

# 編輯 Containerd 配置檔
sudo vi /etc/containerd/config.toml

# 在檔案最後加入以下內容：
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."10.10.0.85:50000"]
  endpoint = ["http://10.10.0.85:50000"]

# 若需要認證，還需在 configs 區塊加入：
[plugins."io.containerd.grpc.v1.cri".registry.configs."10.10.0.85:50000".auth]
  username = "admin"
  password = "<your-password>"

# 重啟 Containerd
sudo systemctl restart containerd

方法 2: 使用 hosts.toml

sudo mkdir -p /etc/containerd/certs.d/10.10.0.85:50000
sudo tee /etc/containerd/certs.d/10.10.0.85:50000/hosts.toml <<EOF
server = "http://10.10.0.85:50000"

[host."http://10.10.0.85:50000"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true

[host."http://10.10.0.85:50000".auth]
  username = "admin"
  password = "<your-password>"
EOF

sudo systemctl restart containerd

方法 3: 建立 Kubernetes Secret

# 在任一 Master 節點執行
kubectl create secret docker-registry airflow-registry-secret \
  --docker-server=10.10.0.85:50000 \
  --docker-username=admin \
  --docker-password=<your-password> \
  -n airflow

# 驗證 Secret
kubectl get secret airflow-registry-secret -n airflow

在 Pod 中使用：

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: test
    image: 10.10.0.85:50000/airflow-custom:1.0
  imagePullSecrets:
  - name: airflow-registry-secret

---

測試驗證

推送測試映像

# 登入 Registry
podman login 10.10.0.85:50000 --tls-verify=false
# Username: admin
# Password: <your-password>

# 標記映像
podman tag alpine:latest 10.10.0.85:50000/test-alpine:secure

# 推送映像
podman push 10.10.0.85:50000/test-alpine:secure --tls-verify=false

# 驗證
curl -u admin:<your-password> http://10.10.0.85:50000/v2/_catalog
# 應回傳: {"repositories":["test-alpine"]}

從 K8s 節點拉取

# 在任一 K8s 節點上
sudo crictl pull 10.10.0.85:50000/test-alpine:secure

# 檢查映像列表
sudo crictl images | grep 10.10.0.85

---

進階配置

啟用 HTTPS/TLS

# 生成自簽證書
sudo mkdir -p /srv/registry/certs
sudo openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout /srv/registry/certs/domain.key \
  -x509 -days 365 \
  -out /srv/registry/certs/domain.crt \
  -subj "/CN=10.10.0.85"

# 重新啟動 Registry 啟用 TLS
sudo podman stop registry
sudo podman rm registry

sudo podman run -d \
  --name registry \
  --restart=always \
  -p 50000:5000 \
  -v /srv/registry:/var/lib/registry \
  -v /srv/registry/auth:/auth \
  -v /srv/registry/certs:/certs \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  docker.io/library/registry:2

啟用垃圾回收

sudo podman stop registry
sudo podman rm registry

sudo podman run -d \
  --name registry \
  --restart=always \
  -p 50000:5000 \
  -v /srv/registry:/var/lib/registry \
  -v /srv/registry/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -e "REGISTRY_STORAGE_DELETE_ENABLED=true" \
  docker.io/library/registry:2

---

維護操作

更換密碼

# 更新密碼
sudo htpasswd -B /srv/registry/auth/htpasswd admin

# 重啟 Registry
sudo podman restart registry

# 更新 K8s 節點配置
# 在每個節點上更新 /etc/containerd/certs.d/10.10.0.85:50000/hosts.toml
# 然後執行: sudo systemctl restart containerd

添加新使用者

# 添加新使用者
sudo htpasswd -B /srv/registry/auth/htpasswd developer

# 重啟 Registry
sudo podman restart registry

備份與恢復

# 備份數據
sudo tar -czf /backup/registry-$(date +%Y%m%d).tar.gz \
  /srv/registry/docker \
  /srv/registry/auth

# 恢復
sudo tar -xzf /backup/registry-20260130.tar.gz -C /
sudo podman restart registry

垃圾回收

# 執行垃圾回收（需先啟用 STORAGE_DELETE_ENABLED）
sudo podman exec registry bin/registry garbage-collect \
  /etc/docker/registry/config.yml

# 查看清理效果
du -sh /srv/registry/docker/registry/v2/*

---

常見問題

認證失敗

# 檢查認證檔案
sudo cat /srv/registry/auth/htpasswd

# 測試認證
curl -u admin:<password> http://10.10.0.85:50000/v2/_catalog

# 重新建立認證
sudo htpasswd -Bc /srv/registry/auth/htpasswd admin
sudo podman restart registry

節點無法拉取映像

# 檢查節點配置
sudo cat /etc/containerd/certs.d/10.10.0.85:50000/hosts.toml

# 確認密碼正確
grep password /etc/containerd/certs.d/10.10.0.85:50000/hosts.toml

# 重啟 Containerd
sudo systemctl restart containerd

# 手動測試
sudo crictl pull 10.10.0.85:50000/test-alpine:latest

檢查容器日誌

# 查看 Registry 日誌
sudo podman logs registry | tail -50

# 查看認證相關日誌
sudo podman logs registry | grep -i auth

---

安全性建議

1. 使用強密碼: 建議 16+ 字元隨機密碼

   # 生成隨機密碼
   openssl rand -base64 24
   

2. 定期更換密碼: 每 90 天更換一次

3. 啟用 HTTPS: 生產環境務必使用 TLS

4. 限制網路訪問:

   # 設定防火牆
   sudo ufw allow from 10.10.0.0/24 to any port 50000
   sudo ufw deny 50000
   

5. 定期備份: 自動化備份腳本

6. 監控磁碟空間: 設定告警

7. 審計日誌: 定期檢查存取日誌

---

升級與遷移

從無認證版本升級

# 1. 停止舊容器
sudo podman stop registry
sudo podman rm registry

# 2. 建立認證檔案
sudo mkdir -p /srv/registry/auth
sudo htpasswd -Bc /srv/registry/auth/htpasswd admin

# 3. 啟動新容器（帶認證）
sudo podman run -d \
  --name registry \
  --restart=always \
  -p 50000:5000 \
  -v /srv/registry:/var/lib/registry \
  -v /srv/registry/auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  docker.io/library/registry:2

# 4. 更新所有 K8s 節點配置
# 在每個節點上添加認證資訊到 hosts.toml