5.4 KiB
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 目录下。