Docker基础教程（233）私有仓库之添加认证服务：别再让你的Docker仓库“裸奔”！手把手教你给私有库穿上“认证”的金钟罩

引言：从一场“惊悚”的想象开始

兄弟们，程序员们，运维侠客们！请大家跟我一起做个深呼吸，想象这样一个场景：

你呕心沥血，花了几个星期打包好了公司最核心的微服务应用镜像，满心欢喜地把它推送到内网搭建的私有Docker仓库（registry:5000）。感觉良好，世界和平。但突然，某个新来的实习生小哥，只是因为IP段猜对了，一句简单的 docker pull registry:5000/my-company/core-app:latest，就把你的“毕生心血”轻松拽到了他的本地。

刺激吗？后背发凉吗？这不亚于你把家门钥匙插在锁孔上，然后出门度假去了。

这个场景的核心问题就在于：你正在使用一个“裸奔”的Docker私有仓库。默认搭建的Docker Registry服务是没有任何认证机制的，这意味着只要网络能通，任何人都可以随意推送（push）和拉取（pull）镜像。在稍微严肃点的开发或生产环境中，这简直是灾难性的。

所以，今天咱们不整虚的，就来一场彻彻底底的“穿衣”行动，给咱们的私有仓库穿上最坚固的“认证”盔甲。

第一章：认证的必要性——不只是“防小人”

为啥要给私有仓库加认证？答案看似显而易见——“为了安全呗”。但让我们深入一层，看看安全背后具体意味着什么：

1. 权限隔离（Authorization）：不是所有开发者都需要推送权限。运维团队可以推送基础镜像和线上镜像，开发团队可能只有推送测试镜像到特定项目的权限，而测试团队可能只有拉取权限。认证是实现精细权限管理的基础。
2. 审计与追溯（Audit）：谁在什么时候推送了哪个镜像？出了问题得能找到责任人。有了认证，每一次操作都能关联到一个具体的用户身份。
3. 防止意外操作：没有认证，网络内的任何机器（比如一台中病毒的CI/CD服务器）都可能无意间覆盖掉重要镜像。认证就像一道安全门，过滤掉非法的请求。
4. 合规要求：在很多行业（如金融、医疗），数据安全和访问控制是硬性规定。一个“裸奔”的仓库绝对无法通过安全审计。

所以，添加认证远不止是“防黑客”，更是现代软件工程中团队协作和规范流程的基石。

第二章：技术选型——为何是“Nginx + htpasswd”这套经典组合拳？

给Docker Registry添加认证有多种方式，比如官方的Token认证（更复杂，适合大规模集群）、集成第三方认证服务等。但我们今天选择 Nginx反向代理 + htpasswd基础认证 这套方案，原因是：

• 简单粗暴：概念清晰，配置直观，非常适合中小团队和个人项目。
• 久经考验：Nginx是世界上最流行的Web服务器之一，其稳定性毋庸置疑。htpasswd是Apache和Nginx通用的标准密码文件生成工具。
• 功能强大：Nginx不仅能做认证，还能轻松配置TLS/SSL加密（HTTPS），这是Docker客户端强制要求的安全通信方式。
• 学习成本低：理解了这个最经典的方案，再去看更复杂的方案会更容易上手。

工作原理简析：
我们不直接让Docker客户端连接Registry服务，而是在Registry前面套一个Nginx服务器。所有客户端的请求都先发给Nginx，由Nginx进行用户名密码验证（认证），验证通过后，Nginx再把请求转发给后端的Registry服务。这样，Registry本身依然保持“无状态”，而繁重的安全工作交给了专业的Nginx。

第三章：实战！手把手搭建带认证的私有仓库

好了，口水话少说，亮代码！我们假设你已经在服务器上安装好了Docker和Docker Compose。

我们的目标：在一台Linux服务器（IP假设为 192.168.1.100）上，搭建一个可通过 https://registry.mycompany.com 访问的、带认证的私有仓库。

步骤一：创建项目结构

首先，创建一个工作目录，并组织好文件结构。

mkdir -p ~/secure-docker-registry/{auth,certs,data}
cd ~/secure-docker-registry

• auth/：存放密码文件
• certs/：存放SSL证书文件
• data/：映射给Registry容器，用于持久化存储镜像数据
• （根目录）：存放 docker-compose.yml 文件

步骤二：创建用户密码文件

我们使用 htpasswd 工具来创建密码文件。如果系统没有，可以通过安装 apache2-utils 包获得。

# 在宿主机上安装 htpasswd (以Ubuntu/Debian为例)
sudo apt-get update && sudo apt-get install -y apache2-utils

# 进入auth目录，创建第一个用户，比如用户名为 'registry-user'
# -B 表示使用 bcrypt 加密（更安全）
# -c 表示创建新文件，如果文件已存在，想添加新用户时不要加 -c 参数，否则会覆盖！
cd auth
htpasswd -B -c .htpasswd registry-user

执行后，会提示你输入密码并确认。这样，.htpasswd 文件就生成了，里面包含着加密后的密码。

步骤三：准备SSL证书（至关重要！）

Docker客户端要求与仓库的通信必须是HTTPS。有两种选择：

1. 使用受信任的CA签发的证书（如Let‘s Encrypt）：最佳实践，适用于有公网域名的生产环境。
2. 使用自签名证书：适用于内网测试或开发环境。

这里我们以自签名证书为例进行演示：

# 进入certs目录
cd ../certs

# 生成私钥和自签名证书
# 将 `registry.mycompany.com` 替换为你实际访问的域名或IP（如果是IP，需要额外参数，建议用域名）
openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key -x509 -days 365 -out domain.crt

在执行过程中，会提示你填写一些信息。特别注意：Common Name 这一项必须填写你访问仓库时使用的域名（如 registry.mycompany.com），否则客户端会报证书错误。

步骤四：配置Docker客户端信任自签名证书（仅在用自签名证书时需要）

为了让你的Docker客户端（以及服务器本机的Docker客户端）能信任这个自签名证书，你需要将 domain.crt 文件复制到指定位置。

# 在客户端机器上（如果和服务器是同一台，就本地操作）
sudo mkdir -p /etc/docker/certs.d/registry.mycompany.com:5000
# 将上一步生成的 domain.crt 文件复制到这个目录
sudo cp path/to/your/domain.crt /etc/docker/certs.d/registry.mycompany.com:5000/ca.crt

# 重启Docker服务使配置生效
sudo systemctl restart docker

步骤五：编写Docker Compose文件

这是整个系统的核心编排文件 docker-compose.yml。

version: '3.8'

services:
  registry:
    image: registry:2
    container_name: private-registry
    restart: always
    volumes:
      - ./data:/var/lib/registry
    networks:
      - registry-net
    # 注意：Registry本身不暴露端口，只通过内部网络与Nginx通信
    environment:
      - REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry

  nginx:
    image: nginx:alpine
    container_name: registry-nginx
    restart: always
    ports:
      - "5000:443" # 将宿主机的5000端口映射到Nginx容器的443端口
    volumes:
      - ./auth:/etc/nginx/auth
      - ./certs:/etc/nginx/certs
      - ./nginx.conf:/etc/nginx/nginx.conf
    networks:
      - registry-net
    depends_on:
      - registry

networks:
  registry-net:

步骤六：编写Nginx配置文件

创建 nginx.conf 文件，这是认证逻辑所在。

events {
    worker_connections 1024;
}

http {
    # 设置日志格式，方便排查问题
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    # 配置上游的Docker Registry服务
    upstream docker-registry {
        server registry:5000;
    }

    server {
        listen 443 ssl;
        server_name registry.mycompany.com;

        # SSL证书配置
        ssl_certificate /etc/nginx/certs/domain.crt;
        ssl_certificate_key /etc/nginx/certs/domain.key;

        # 推荐的安全套件配置
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!MD5;

        # 禁用客户端展示Nginx版本号
        server_tokens off;

        # 配置Docker Registry的代理和认证
        location /v2/ {
            # 首先进行认证
            auth_basic "Docker Registry Authentication Required";
            auth_basic_user_file /etc/nginx/auth/.htpasswd;

            # 代理设置
            proxy_pass http://docker-registry;
            proxy_set_header Host $http_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 特定的代理设置
            client_max_body_size 0; # 禁用文件大小限制，用于推送大镜像
            chunked_transfer_encoding on;
        }

        # 可以添加一个健康检查端点
        location /v2/ {
            return 200;
            add_header Content-Type text/plain;
        }
    }
}

步骤七：启动所有服务

万事俱备，只欠东风！

# 在项目根目录 (~/secure-docker-registry) 下执行
docker-compose up -d

用 docker-compose ps 检查两个容器是否都正常启动。

第四章：测试！看看我们的“金钟罩”是否坚固

现在，是时候检验我们的劳动成果了。

登录仓库：

docker login registry.mycompany.com:5000

输入之前创建的用户名（registry-user）和密码。看到 Login Succeeded 就成功了一半！

给现有镜像打标签：

docker tag nginx:alpine registry.mycompany.com:5000/my-nginx:v1

推送镜像：

docker push registry.mycompany.com:5000/my-nginx:v1

如果推送成功，恭喜你！认证仓库搭建完成！

1. 拉取镜像：
   可以先 docker rmi 删除本地镜像，然后尝试拉取，同样需要先登录。
2. 测试未认证访问：
   尝试不登录直接拉取，或者用错误的密码登录，Nginx会返回 401 Unauthorized 错误。看，我们的“金钟罩”生效了！

第五章：常见问题与进阶思考

• 问题：客户端一直报 x509: certificate signed by unknown authority

• • 解答：99%的原因是步骤四没做对，客户端不信任你的自签名证书。请仔细检查证书放置的路径和文件名是否正确，并重启Docker服务。

• 进阶1：使用更安全的Token认证

• • 当用户和项目非常多时，htpasswd文件难以管理。可以考虑使用Docker官方的 registry:2 镜像自带的Token认证，它可以与第三方认证服务（如GitLab， OAuth2）集成。

• 进阶2：与CI/CD集成

• • 在Jenkins、GitLab CI等工具中，通常可以通过在Pipeline的environment块或withCredentials指令中设置用户名密码变量，来实现非交互式登录。

结语

瞧，从“裸奔”到穿上“金钟罩”，我们只用了几步配置和一个Docker Compose文件。安全并不是一件遥不可及、高大上的事情，它往往就藏在这些基础而关键的配置里。

现在，你的私有镜像再也不是堆在公共走廊的“私房钱”了，而是被妥善保管在装有密码锁和监控探头的金库里。赶紧去给你的仓库“穿好衣服”，享受这份踏实的安全感吧！

---

免责声明：本文示例基于自签名证书，适用于内网测试和学习。在生产环境中，请务必使用由受信任证书颁发机构（CA）签发的SSL证书。