Email:Service@dogssl.com
中文
中文 繁體 English
CNY
USD CNY
使用Docker时配置自签名证书的详细指南
更新时间：2025-09-24 作者:配置自签名证书

本文将详细介绍Docker中配置自签名证书的完整流程，涵盖证书生成、容器/服务配置、客户端信任设置及常见问题解决，适用于本地开发、Docker Swarm集群及私有仓库等场景。

一、准备工作：工具与环境

在开始配置前，需确保以下工具已安装：

1. Docker Engine：版本≥18.09（支持TLS 1.3及最新安全特性）；

2. OpenSSL：用于生成自签名证书（Linux/macOS预装，Windows需手动安装）；

3. mkcert（可选）：简化本地开发环境证书生成（支持跨平台，自动信任证书）；

4. Docker Compose（可选）：用于快速部署多容器应用（如Nginx+后端服务）。

二、生成自签名证书：两种方式

自签名证书的生成需解决域名/IP匹配（SAN）问题，否则浏览器/客户端会提示“证书不受信任”。以下是两种常用方式：

1. 使用OpenSSL生成基础自签名证书（适合生产环境）

OpenSSL是生成自签名证书的经典工具，需手动指定SAN信息（如域名、IP），适用于Docker Swarm集群或私有仓库的TLS加密。

步骤1：创建证书目录

mkdir -p /etc/docker/certs/{ca,server,client}
cd /etc/docker/certs

步骤2：生成CA（证书颁发机构）证书

CA证书用于签署服务器和客户端证书，是自签名体系的信任根。

# 生成CA私钥（AES256加密，密码设为"Passw0rd!"）
openssl genrsa -aes256 -out ca-key.pem 4096
# 生成CA证书（有效期10年，CN为"Local Docker CA"）
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 3650 -out ca.pem \
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Docker/CN=Local Docker CA"

步骤3：生成服务器证书（用于Docker守护进程或私有仓库）

服务器证书需包含SAN信息（如IP地址、域名），否则客户端会提示“证书中的域名与请求的不匹配”。

# 创建SAN配置文件（san.cnf）
cat > san.cnf <<EOF
[req]
default_bits = 4096
prompt = no
default_md = sha256
distinguished_name = dn

[dn]
C = CN
ST = Shanghai
L = Shanghai
O = Docker
CN = docker-host.example.com  # 替换为你的Docker主机域名或IP

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
IP.1 = 192.168.1.100  # 替换为你的Docker主机IP
DNS.1 = docker-host.example.com  # 替换为你的Docker主机域名
EOF

# 生成服务器私钥
openssl genrsa -out server-key.pem 4096
# 生成证书签名请求（CSR）
openssl req -new -key server-key.pem -out server.csr -config san.cnf
# 签署服务器证书（使用CA证书，有效期1年）
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out server-cert.pem \
  -days 365 -sha256 -extfile san.cnf -extensions v3_req

步骤4：生成客户端证书（用于Docker客户端认证）

若需限制Docker客户端的访问权限（如仅允许特定客户端连接守护进程），需生成客户端证书。

# 生成客户端私钥
openssl genrsa -out client-key.pem 4096
# 生成客户端CSR
openssl req -new -key client-key.pem -out client.csr -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Docker Client/CN=client.example.com"
# 签署客户端证书
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out client-cert.pem \
  -days 365 -sha256

2. 使用mkcert生成本地开发证书（适合本地环境）

mkcert是专为本地开发设计的证书工具，自动信任证书（无需手动导入系统信任库），支持通配符域名（如*.local），适合Nginx、Node.js等容器化应用的HTTPS测试。

步骤1：安装mkcert

  • Linux：sudo apt-get install mkcert（或从GitHub下载二进制文件）；
  • macOS：brew install mkcert；
  • Windows：choco install mkcert（或下载.exe文件）。

步骤2：安装本地CA

mkcert -install

此命令会将mkcert的根证书添加到系统的信任库（Windows的“受信任的根证书颁发机构”、macOS的“钥匙串访问”）。

步骤3：生成域名证书

# 生成通配符证书（支持*.local域名，有效期1年）
mkcert "*.local" localhost 127.0.0.1 ::1

输出示例：

Created a new certificate: local+3.pem
Key file: local+3-key.pem

步骤4：验证证书

mkcert --verify "*.local"

若输出Verified OK，则证书有效。

三、配置Docker守护进程：启用TLS加密

Docker守护进程（dockerd）的TLS配置用于加密远程API调用（如docker -H tcp://host:port命令），防止未授权访问。以下是配置步骤：

1. 修改Docker配置文件（daemon.json）

Docker的配置文件通常位于/etc/docker/daemon.json（Linux）或C:\ProgramData\Docker\config\daemon.json（Windows）。若文件不存在，需手动创建。

添加以下配置（替换为你的证书路径）：

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],  # 监听所有TCP接口（生产环境建议指定IP）
  "tls": true,
  "tlsverify": true,
  "tlscacert": "/etc/docker/certs/ca/ca.pem",          # CA证书路径
  "tlscert": "/etc/docker/certs/server/server-cert.pem",# 服务器证书路径
  "tlskey": "/etc/docker/certs/server/server-key.pem"   # 服务器私钥路径
}

2. 重启Docker服务

配置生效后，需重启Docker服务：

  • Linux：sudo systemctl restart docker；
  • Windows：通过“服务”管理器重启“Docker Desktop”服务。

3. 验证TLS配置

使用以下命令验证Docker守护进程的TLS配置是否生效：

# 使用TLS连接Docker守护进程（替换为你的证书路径）
docker --tlsverify --tlscacert=/etc/docker/certs/ca/ca.pem \
  --tlscert=/etc/docker/certs/client/client-cert.pem \
  --tlskey=/etc/docker/certs/client/client-key.pem \
  version

若输出Docker版本信息（如Client: Docker Engine - Community），则配置成功。

四、配置容器化应用：以Nginx为例

若需为容器化应用（如Nginx）启用HTTPS，需将自签名证书挂载到容器中，并配置Nginx使用该证书。

1. 准备Nginx配置文件（nginx.conf）

创建nginx.conf文件，配置HTTPS监听（端口443）：

server {
  listen 443 ssl;
  server_name localhost *.local;  # 匹配所有*.local域名

  # 证书路径（挂载到容器中的路径）
  ssl_certificate /etc/nginx/ssl/local+3.pem;
  ssl_certificate_key /etc/nginx/ssl/local+3-key.pem;

  # SSL优化配置（可选）
  ssl_protocols TLSv1.2 TLSv1.3;
  ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
  ssl_prefer_server_ciphers on;
  ssl_session_cache shared:SSL:10m;
  ssl_session_timeout 10m;

  # 反向代理到后端服务（可选）
  location / {
    proxy_pass http://backend:8080;  # backend是后端服务的Docker网络别名
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

# 重定向HTTP到HTTPS（可选）
server {
  listen 80;
  server_name localhost *.local;
  return 301 https://$host$request_uri;
}

2. 创建Docker Compose文件（docker-compose.yml）

使用Docker Compose部署Nginx服务，挂载证书和配置文件：

version: '3.9'

services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"   # HTTP端口（重定向到HTTPS）
      - "443:443" # HTTPS端口
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf  # 挂载Nginx配置文件
      - ./ssl:/etc/nginx/ssl                # 挂载证书目录（需提前将mkcert生成的证书复制到此处）
    networks:
      - mynet

  backend:
    image: your-backend-image:latest  # 替换为你的后端服务镜像
    networks:
      - mynet

networks:
  mynet:
    driver: bridge

3. 部署并验证服务

# 创建证书目录（将mkcert生成的证书复制到此处）
mkdir -p ssl
cp ~/.local/share/mkcert/local+3.pem ssl/
cp ~/.local/share/mkcert/local+3-key.pem ssl/

# 启动服务
docker-compose up -d

# 验证HTTPS访问
curl -k https://localhost  # -k忽略证书警告（本地开发环境）

若输出Nginx的欢迎页面，则配置成功。

五、配置私有仓库：以Docker Registry为例

若需搭建私有Docker仓库（如Registry），并使用自签名证书加密访问，需将证书挂载到Registry容器中，并配置客户端信任证书。

1. 配置Registry容器

创建registry.yml文件，部署Registry服务：

version: '3.9'

services:
  registry:
    image: registry:2.8
    ports:
      - "443:443"  # HTTPS端口
    volumes:
      - ./registry-data:/var/lib/registry  # 挂载数据目录
      - ./certs:/certs                       # 挂载证书目录（mkcert生成的证书）
    environment:
      - REGISTRY_HTTP_ADDR=0.0.0.0:443       # 监听443端口
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/local+3.pem  # 证书路径
      - REGISTRY_HTTP_TLS_KEY=/certs/local+3-key.pem      # 私钥路径
    networks:
      - mynet

networks:
  mynet:
    driver: bridge

2. 客户端信任证书

要让Docker客户端信任私有仓库的自签名证书，需将CA证书复制到客户端的/etc/docker/certs.d/<registry-domain>/ca.crt路径（Linux）或C:\ProgramData\Docker\certs.d\<registry-domain>\ca.crt路径（Windows）。

Linux客户端：

# 创建证书目录（替换为你的registry域名）
sudo mkdir -p /etc/docker/certs.d/registry.local:443

# 复制CA证书（mkcert生成的根证书）
sudo cp ~/.local/share/mkcert/rootCA.pem /etc/docker/certs.d/registry.local:443/ca.crt

# 重启Docker服务
sudo systemctl restart docker

Windows客户端：

# 创建证书目录（替换为你的registry域名）
New-Item -ItemType Directory -Path "C:\ProgramData\Docker\certs.d\registry.local:443" -Force

# 复制CA证书（mkcert生成的根证书，重命名为ca.crt）
Copy-Item "$env:USERPROFILE\.local\share\mkcert\rootCA.pem" "C:\ProgramData\Docker\certs.d\registry.local:443\ca.crt"

# 重启Docker Desktop服务
Restart-Service docker

3. 验证私有仓库访问

# 登录私有仓库（替换为你的registry域名）
docker login registry.local:443

# 推送镜像到私有仓库
docker tag nginx:latest registry.local:443/nginx:latest
docker push registry.local:443/nginx:latest

# 拉取镜像
docker pull registry.local:443/nginx:latest

若推送/拉取成功，则配置成功。

六、常见问题与解决方案

1. 客户端提示“证书不受信任”（x509: certificate signed by unknown authority）

原因：客户端未信任自签名证书的CA。  

解决方案：  

  • 将CA证书复制到客户端的系统信任库（如Linux的/usr/local/share/ca-certificates/，Windows的“受信任的根证书颁发机构”）；
  • 使用mkcert生成证书（自动信任，无需手动导入）；
  • 临时禁用证书验证（仅开发环境使用）：docker --tlsverify=false ...。

2. 证书中的域名与请求的不匹配（SSL_ERROR_BAD_CERT_DOMAIN）

原因：证书未包含请求的域名或IP（SAN信息缺失）。  

解决方案：  

  • 生成证书时，确保SAN信息包含所有需要访问的域名或IP（如*.local、192.168.1.100）；
  • 使用mkcert生成证书（自动添加localhost、127.0.0.1等SAN信息）。

3. Docker守护进程无法启动（tls: failed to parse private key）

原因：私钥文件权限不足或格式错误。  

解决方案：  

  • 确保私钥文件的权限为600（仅所有者可读）：chmod 600 server-key.pem；
  • 检查私钥格式是否正确（如RSA私钥以-----BEGIN RSA PRIVATE KEY-----开头）。

4. 私有仓库推送镜像失败（denied: requested access to the resource is denied）

原因：未登录私有仓库或证书配置错误。  

解决方案：  

  • 确保已使用docker login登录私有仓库；
  • 检查客户端是否信任私有仓库的CA证书（参考“配置私有仓库”部分的客户端信任步骤）。

七、最佳实践

1. 生产环境使用CA颁发的证书：自签名证书不适合生产环境，建议使用Let’s Encrypt（免费）或商业证书颁发机构（如DigiCert）的证书；

2. 定期更新证书：自签名证书的有效期建议设置为1年以内，避免过期导致服务中断；

3. 使用mkcert简化本地开发：mkcert自动信任证书，无需手动导入，适合本地开发环境；

4. 限制TLS版本：禁用TLS 1.0和TLS 1.1，仅使用TLS 1.2及以上版本（如Nginx的ssl_protocols TLSv1.2 TLSv1.3;）；

5. 备份证书：定期备份CA证书和服务器证书，避免丢失导致服务无法恢复。

在Docker环境中配置自签名证书，需根据场景选择合适的证书生成方式（OpenSSL或mkcert），并正确配置Docker守护进程、容器化应用或私有仓库。通过本文的步骤，可实现Docker环境的加密通信，保护数据安全。  


Dogssl.com拥有20年网络安全服务经验，提供构涵盖国际CA机构Sectigo、Digicert、GeoTrust、GlobalSign，以及国内CA机构CFCA、沃通、vTrus、上海CA等数十个SSL证书品牌。全程技术支持及免费部署服务，如您有SSL证书需求，欢迎联系!
上一篇:Edge端设备中SSL证书带宽与资源优化策略下一篇:本地开发环境HTTPS与CORS跨域问题调试技巧
相关文档
工具
锐安信DV SSL证书
¥65 /年
  • 锐安信多域名证书最高250个域名
  • 无需提交任何材料，验证域名所有权即可
  • 签发速度5-10分钟
  • 目前价格超群速速选用！
立即抢购
推荐证书
SSL证书品牌
SHECA
vTrus
huace
actalis
WoTrus
CFCA
GlobalSign
Geotrust
Digicert
sslTrus
Sectigo
Positive
SSL证书品类
企业型（OV） 域名型（DV） 增强型（EV） 增强型专业版（EV）
立即加入，让您的品牌更加安全可靠！
申请SSL证书
联系我们
技术咨询：EngineerHelp@dogssl.com
售后咨询：Service@dogssl.com
联系我们

© 2004-2024 DogSSL.com 版权所有 Cookies政策|SSl证书服务协议|用户协议|隐私政策|反馈建议 反馈邮箱:Feedback@dogssl.com

0.105487s