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

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

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

---

## 環境說明

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

---

## 安裝步驟

### 1. 安裝必要工具

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

### 2. 建立目錄與認證檔

```bash
# 建立基礎目錄
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 容器

```bash
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. 驗證服務

```bash
# 檢查容器狀態
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（推薦）

```bash
# 編輯 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

```bash
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

```bash
# 在任一 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 中使用：

```yaml
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
```

---

## 測試驗證

### 推送測試映像

```bash
# 登入 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 節點拉取

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

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

---

## 進階配置

### 啟用 HTTPS/TLS

```bash
# 生成自簽證書
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
```

### 啟用垃圾回收

```bash
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
```

---

## 維護操作

### 更換密碼

```bash
# 更新密碼
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
```

### 添加新使用者

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

# 重啟 Registry
sudo podman restart registry
```

### 備份與恢復

```bash
# 備份數據
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
```

### 垃圾回收

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

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

---

## 常見問題

### 認證失敗

```bash
# 檢查認證檔案
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
```

### 節點無法拉取映像

```bash
# 檢查節點配置
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
```

### 檢查容器日誌

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

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

---

## 安全性建議

1. **使用強密碼**: 建議 16+ 字元隨機密碼
   ```bash
   # 生成隨機密碼
   openssl rand -base64 24
   ```

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

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

4. **限制網路訪問**: 
   ```bash
   # 設定防火牆
   sudo ufw allow from 10.10.0.0/24 to any port 50000
   sudo ufw deny 50000
   ```

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

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

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

---

## 升級與遷移

### 從無認證版本升級

```bash
# 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
```