164 lines
5.4 KiB
Markdown
164 lines
5.4 KiB
Markdown
# **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 目录下。 |