# **Debian 私有 Docker 仓库 (Registry \+ UI \+ HTTPS) 部署手册**

本文档详细说明了如何在 Debian 系统上构建一个支持域名访问、HTTPS 加密、用户认证以及图形化管理界面的私有 Docker 仓库。

## **1\. 基础环境准备**

### **1.1 系统更新与防火墙**

确保服务器已开启 80 (HTTP) 和 443 (HTTPS) 端口。

sudo apt update && sudo apt upgrade \-y  
\# 如果开启了 ufw 防火墙  
sudo ufw allow 80/tcp  
sudo ufw allow 443/tcp

### **1.2 安装 Docker 与 Docker Compose**

使用 Docker 官方源安装最新版本。

sudo apt install ca-certificates curl gnupg lsb-release \-y  
sudo install \-m 0755 \-d /etc/apt/keyrings  
curl \-fsSL \[https://download.docker.com/linux/debian/gpg\](https://download.docker.com/linux/debian/gpg) | sudo gpg \--dearmor \-o /etc/apt/keyrings/docker.gpg  
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb \[arch=$(dpkg \--print-architecture) signed-by=/etc/apt/keyrings/docker.gpg\] \[https://download.docker.com/linux/debian\](https://download.docker.com/linux/debian) $(lsb\_release \-cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list \> /dev/null

sudo apt update  
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin \-y

## **2\. 仓库服务配置 (Registry & UI)**

### **2.1 创建项目目录与认证文件**

我们将使用 htpasswd 为仓库添加登录限制。

mkdir \-p \~/docker-registry/auth && cd \~/docker-registry

\# 创建用户名为 admin，密码为 your\_password 的认证文件  
\# 请务必修改下方的 your\_password  
docker run \--entrypoint htpasswd httpd:2 \-Bbn admin your\_password \> auth/htpasswd

### **2.2 编写 docker-compose.yml**

该配置包含仓库核心服务和可视化 UI 服务。

version: '3.8'

services:  
  registry:  
    image: registry:2  
    container\_name: registry-server  
    restart: always  
    environment:  
      REGISTRY\_AUTH: htpasswd  
      REGISTRY\_AUTH\_HTPASSWD\_REALM: Registry Realm  
      REGISTRY\_AUTH\_HTPASSWD\_PATH: /auth/htpasswd  
      REGISTRY\_HTTP\_SECRET: some\_random\_secret  
      REGISTRY\_HTTP\_CORS\_ENABLED: "true"  
      REGISTRY\_HTTP\_CORS\_ALLOWEDMETHODS: "\[HEAD,GET,OPTIONS,DELETE\]"  
      REGISTRY\_HTTP\_CORS\_ALLOWEDORIGINS: "\['\[https://docker.aizhangz.top\](https://docker.aizhangz.top)'\]"  
      REGISTRY\_STORAGE\_DELETE\_ENABLED: "true"  
    volumes:  
      \- ./data:/var/lib/registry  
      \- ./auth:/auth  
    ports:  
      \- "127.0.0.1:5000:5000"

  ui:  
    image: joxit/docker-registry-ui:latest  
    container\_name: registry-ui  
    restart: always  
    environment:  
      \- REGISTRY\_TITLE=My Private Registry  
      \- NGINX\_PROXY\_PASS\_URL=http://registry:5000  
      \- SINGLE\_REGISTRY=true  
      \- DELETE\_IMAGES=true  
    ports:  
      \- "127.0.0.1:8080:80"

启动容器：

docker compose up \-d

## **3\. Nginx 反向代理与 SSL 证书**

### **3.1 安装 Nginx 与 Certbot**

sudo apt install nginx certbot python3-certbot-nginx \-y

### **3.2 申请证书**

\# 请将 docker.aizhangz.top 替换为您实际解析好的域名  
sudo certbot \--nginx \-d docker.aizhangz.top

### **3.3 修改 Nginx 配置文件**

编辑 /etc/nginx/sites-available/default，将 HTTPS 核心块修改为如下代理逻辑。

server {  
    listen 443 ssl;  
    server\_name docker.aizhangz.top;

    \# SSL 证书路径（由 Certbot 自动生成）  
    ssl\_certificate /etc/letsencrypt/live/docker.aizhangz.top/fullchain.pem;  
    ssl\_certificate\_key /etc/letsencrypt/live/docker.aizhangz.top/privkey.pem;  
    include /etc/letsencrypt/options-ssl-nginx.conf;  
    ssl\_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    \# 允许上传大型镜像文件  
    client\_max\_body\_size 0;  
    chunked\_transfer\_encoding on;

    \# 1\. 路由 Docker API 请求 (命令行操作及 UI 后台通讯)  
    location /v2/ {  
        proxy\_pass \[http://127.0.0.1:5000\](http://127.0.0.1:5000);  
        proxy\_set\_header Host $host;  
        proxy\_set\_header X-Real-IP $remote\_addr;  
        proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;  
        proxy\_set\_header X-Forwarded-Proto $scheme;  
        proxy\_read\_timeout 900;  
    }

    \# 2\. 路由浏览器访问请求 (UI 界面)  
    location / {  
        proxy\_pass \[http://127.0.0.1:8080\](http://127.0.0.1:8080);  
        proxy\_set\_header Host $host;  
        proxy\_set\_header X-Real-IP $remote\_addr;  
        proxy\_set\_header X-Forwarded-For $proxy\_add\_x\_forwarded\_for;  
        proxy\_set\_header X-Forwarded-Proto $scheme;  
    }  
}

重启 Nginx：

sudo nginx \-t && sudo systemctl restart nginx

## **4\. 客户端使用指南**

### **4.1 登录仓库**

在任意客户端机器（Windows/Linux/Mac）执行：

docker login docker.aizhangz.top  
\# 输入步骤 2.1 中设置的用户名(admin)和密码

### **4.2 推送镜像**

\# 以 busybox 为例  
docker pull busybox  
docker tag busybox docker.aizhangz.top/my-busybox:v1  
docker push docker.aizhangz.top/my-busybox:v1

### **4.3 访问 Web 界面**

在浏览器打开：https://docker.aizhangz.top

输入账号密码后即可可视化管理镜像。

## **5\. 维护说明**

* **查看容器状态**：docker compose ps  
* **查看日志**：docker compose logs \-f  
* **证书续期**：Certbot 会自动处理，可手动测试：sudo certbot renew \--dry-run  
* **存储位置**：所有镜像物理文件存储在 \~/docker-registry/data 目录下。