flnxi-Wu/docs/guides/SELF_HOSTED_REGISTRY.md

在现有服务器上搭建 Docker Registry

概述

在现有的素材网服务器上搭建私有 Docker Registry，完全避免依赖外部服务，部署更快更安全。

方案选择

方案 1：Docker Registry（简单，推荐 ⭐）

优点：

• ✅ 轻量级，资源占用少（< 500MB RAM）
• ✅ 配置简单，5 分钟完成
• ✅ 无需额外数据库
• ✅ 适合单服务器场景

缺点：

• ❌ 功能简单（无 Web UI）
• ❌ 无镜像扫描、安全策略

方案 2：Harbor（功能完整）

优点：

• ✅ 功能完整（Web UI、镜像扫描、安全策略）
• ✅ 支持多租户
• ✅ 企业级功能

缺点：

• ❌ 资源占用大（> 2GB RAM）
• ❌ 配置复杂
• ❌ 需要数据库（PostgreSQL）

推荐方案：Docker Registry + Nginx 反向代理

架构设计

客户端 → Nginx (443) → Docker Registry (5000)

资源需求

• CPU：1 核心（足够）
• 内存：500MB（Registry）+ 现有服务
• 磁盘：镜像存储空间（建议至少 20GB）
• 网络：需要域名或 IP 访问

实施步骤

步骤 1：创建 Registry 配置目录

在服务器上执行：

mkdir -p /root/deploy/registry/{data,config}
cd /root/deploy/registry

步骤 2：创建 docker-compose.registry.yml

创建文件 /root/deploy/registry/docker-compose.registry.yml：

version: '3.8'

services:
  registry:
    image: registry:2.8
    container_name: docker-registry
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt
      - REGISTRY_HTTP_TLS_KEY=/certs/domain.key
      # 启用删除功能
      - REGISTRY_STORAGE_DELETE_ENABLED=true
      # 启用清单删除
      - REGISTRY_STORAGE_MAINTENANCE_DELETEENABLED=true
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs
    networks:
      - registry-network

networks:
  registry-network:
    driver: bridge

步骤 3：生成 SSL 证书（HTTPS）

选项 A：使用自签名证书（快速，适合内网）

cd /root/deploy/registry
mkdir -p certs

# 生成自签名证书
openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout certs/domain.key \
  -x509 -days 365 \
  -out certs/domain.crt \
  -subj "/C=CN/ST=State/L=City/O=Organization/CN=registry.45.249.208.118"

选项 B：使用 Let's Encrypt（推荐，适合公网）

如果有域名，可以使用 Let's Encrypt：

# 安装 certbot
apt-get update
apt-get install -y certbot

# 申请证书（需要域名）
certbot certonly --standalone -d registry.yourdomain.com

# 复制证书到 registry 目录
cp /etc/letsencrypt/live/registry.yourdomain.com/fullchain.pem certs/domain.crt
cp /etc/letsencrypt/live/registry.yourdomain.com/privkey.pem certs/domain.key

步骤 4：配置 Nginx 反向代理（可选但推荐）

创建 /etc/nginx/sites-available/registry：

server {
    listen 80;
    server_name registry.45.249.208.118;  # 或你的域名
    
    # 重定向到 HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name registry.45.249.208.118;  # 或你的域名
    
    ssl_certificate /root/deploy/registry/certs/domain.crt;
    ssl_certificate_key /root/deploy/registry/certs/domain.key;
    
    # SSL 配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    
    client_max_body_size 0;  # 允许上传大文件
    
    location / {
        proxy_pass http://localhost: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;
        
        # 支持 Docker Registry API
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
}

启用配置：

ln -s /etc/nginx/sites-available/registry /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

步骤 5：启动 Registry

cd /root/deploy/registry
docker compose -f docker-compose.registry.yml up -d

步骤 6：配置认证（可选但推荐）

创建认证文件 /root/deploy/registry/config/htpasswd：

# 安装 htpasswd
apt-get install -y apache2-utils

# 创建用户（用户名：admin，会提示输入密码）
htpasswd -Bbn admin your-password > config/htpasswd

# 添加更多用户
htpasswd -Bbn user1 password1 >> config/htpasswd

更新 docker-compose.registry.yml：

services:
  registry:
    # ... 其他配置 ...
    environment:
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
    volumes:
      - ./data:/var/lib/registry
      - ./certs:/certs
      - ./config:/auth  # 添加认证配置

重启 Registry：

docker compose -f docker-compose.registry.yml restart

步骤 7：测试 Registry

# 测试连接
curl -k https://registry.45.249.208.118/v2/

# 登录（如果配置了认证）
docker login https://registry.45.249.208.118 -u admin -p your-password

# 测试推送
docker tag hello-world:latest registry.45.249.208.118/hello-world:latest
docker push registry.45.249.208.118/hello-world:latest

修改部署脚本

更新根目录下的 一键镜像部署.ps1，使用自建 Registry：

# 使用自建 Registry
.\一键镜像部署.ps1 `
    -Server 45.249.208.118 `
    -Username root `
    -Password "your-ssh-password" `
    -RegistryHost "registry.45.249.208.118" `
    -RegistryNamespace "youyidian" `
    -RegistryImage "3d-material" `
    -RegistryUser "admin" `
    -RegistryPassword "your-registry-password" `
    -Tag "latest"

简化版（无 HTTPS，仅内网使用）

如果只是内网使用，可以简化配置：

1. 修改 docker-compose.registry.yml

version: '3.8'

services:
  registry:
    image: registry:2.8
    container_name: docker-registry
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry
      - REGISTRY_STORAGE_DELETE_ENABLED=true
    volumes:
      - ./data:/var/lib/registry
    networks:
      - registry-network

networks:
  registry-network:
    driver: bridge

2. 配置 Docker 允许不安全的 Registry

在服务器上配置 /etc/docker/daemon.json：

{
  "insecure-registries": ["45.249.208.118:5000"]
}

重启 Docker：

systemctl restart docker

3. 在本地也配置（如果需要从本地推送）

Windows：在 Docker Desktop 设置中添加：

45.249.208.118:5000

资源占用

Registry 服务

• 内存：~200-500MB
• CPU：几乎无占用（推送/拉取时短暂使用）
• 磁盘：取决于镜像数量（每个镜像约 100-500MB）

总资源需求

• 当前服务：PostgreSQL + MinIO + App
• Registry：+500MB RAM
• 总计：建议服务器至少 4GB RAM

优势

1. ✅ 完全控制：不依赖外部服务
2. ✅ 速度快：内网传输，速度极快
3. ✅ 免费：无需额外费用
4. ✅ 安全：私有仓库，代码不泄露
5. ✅ 灵活：可以自定义配置

维护

清理旧镜像

# 进入 Registry 容器
docker exec -it docker-registry sh

# 查看存储使用情况
registry garbage-collect /etc/docker/registry/config.yml

# 或使用工具自动清理
# 可以设置定时任务清理超过 30 天的镜像

备份

# 备份 Registry 数据
tar -czf registry-backup-$(date +%Y%m%d).tar.gz /root/deploy/registry/data

故障排查

问题 1：无法推送镜像

Error: Get https://registry.45.249.208.118/v2/: x509: certificate signed by unknown authority

解决：配置 Docker 允许不安全的 Registry，或使用正确的证书

问题 2：推送时提示认证失败

Error: unauthorized: authentication required

解决：检查用户名和密码，确保已登录

问题 3：磁盘空间不足

Error: no space left on device

解决：清理旧镜像，或增加磁盘空间

下一步

1. ✅ 搭建 Registry（5 分钟）
2. ✅ 测试推送/拉取（2 分钟）
3. ✅ 修改部署脚本使用 Registry（5 分钟）
4. ✅ 切换到新方案（1 分钟）

总计：约 15 分钟即可完成迁移