跳到主要内容
前往申请免费HTTPS证书

一、介绍​

Docker - NGINX 类型的部署节点用于实现将OHTTPS中申请的证书自动化部署至nginx容器中。

如果官方镜像不满足需求，可以查看 [Docker 自定义] 文档，通过在构建自定义容器的Dockerfile中引入我们官方提供的push-node二进制包，实现证书的自动化部署。

二、使用方法​

使用 Docker - NGINX 类型的部署节点，需要使用我们官方提供的nginx容器镜像ohttps/ohttps-nginx。
该镜像是基于nginx官方稳定版镜像nginx:1.16构建，添加了证书更新服务后生成的。ohttps/ohttps-nginx镜像内的其他内容和使用方式和nginx官方镜像完全一致，请放心使用。

拉取镜像命令为:

 docker pull ohttps/ohttps-nginx

使用该镜像时，需要设置以下两个环境变量：

  • PUSH_NODE_ID：即为部署节点创建完成后系统生成的部署节点的ID，部署节点的ID都是以push开头的，样例：push-53ejqm8p60gd7no9
  • PUSH_NODE_TOKEN：即为创建部署节点时，通过点击生成按钮生成的32位令牌，样例：6b2440b1e3f180a3c9453f9d7766a565

在使用该镜像的容器首次启动时，会根据配置的PUSH_NODE_ID和PUSH_NODE_TOKEN从OHTTPS服务器拉取最新版证书，如果PUSH_NODE_ID对应的部署节点被多个证书配置为部署节点，则会同时拉取多个证书，拉取到的证书文件被存放在容器内/etc/nginx/certificates文件夹下，然后按照证书ID为子文件夹进行存放（证书ID为创建证书完成后系统生成的证书的ID，证书的ID都是以cert开头的，样例：cert-2enm4pr1q09g3x5z），则证书文件的全路径为：

  • 私钥文件cert.key（PEM格式）：
`/etc/nginx/certificates/${证书ID}/cert.key`
  • 证书文件fullchain.cer（PEM格式）：
`/etc/nginx/certificates/${证书ID}/fullchain.cer`

把上面路径中'${证书ID}'部分换成您的证书ID即为对应文件在容器中的存放路径。注意在容器启动前，请先完成证书部署节点的配置，将证书和部署节点关联，否则会导致容器无法成功启动。


三、最佳实践​

  这里我们会举个例子来说明具体如何使用 Docker - NGINX 类型的部署节点。例如我们创建了一个 Docker - NGINX 类型的部署节点，PUSH_NODE_ID和PUSH_NODE_TOKEN的值为：

  • PUSH_NODE_ID：push-53ejqm8p60gd7no9
  • PUSH_NODE_TOKEN：6b2440b1e3f180a3c9453f9d7766a565

我们为域名www.example.com申请了一个有单域名证书，这个证书的证书ID为cert-2enm4pr1q09g3x5z，然后我们在证书配置中将我们刚创建的节点配置为该证书的部署节点之一，那么该证书的证书文件在容器内的路径为：

  • 私钥文件cert.key（PEM格式）：/etc/nginx/certificates/cert-2enm4pr1q09g3x5z/cert.key
  • 证书文件fullchain.cer（PEM格式）：/etc/nginx/certificates/cert-2enm4pr1q09g3x5z/fullchain.cer

我们的nginx配置文件nginx.conf的内容为：

user  nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    server {
        listen              443 ssl;
        server_name         www.example.com;
        ssl_certificate     /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/fullchain.cer;
        ssl_certificate_key /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/cert.key;

        include /etc/nginx/default.d/*.conf;

        location / {
            root   /usr/share/nginx/html;
            index  index.html;
        }
    }
}

对应的Dockerfile为：

FROM ohttps/ohttps-nginx
WORKDIR /etc/nginx
COPY ./nginx.conf /etc/nginx/nginx.conf
ENV PUSH_NODE_ID='push-53ejqm8p60gd7no9'
ENV PUSH_NODE_TOKEN='6b2440b1e3f180a3c9453f9d7766a565'

根据上面的Dockerfile生成我们自己的镜像即可。


四、常见问题​

1、容器启动后，容器日志内一直显示：“certificates loading ...”​

遇到这种情况，需要依次检查以下两点：

  • 请在OHTTPS中检查部署节点是否已和证书绑定，部署节点只有绑定证书才能自动拉取到相应的证书
  • 请检查容器内的环境变量 PUSH_NODE_ID 以及 PUSH_NODE_TOKEN 是否设置正确并生效，可以使用以下命令检查
# 下方命令中的nginx为容器名称，需要替换为你实际创建的容器名称
# 下方命令会打开容器内的shell执行环境，用以执行echo命令检查环境变量
docker exec -it nginx bash

# 在打开的容器shell执行环境中执行下方两条命令，以检查环境变量是否在容器内存在且和OHTTPS中的一致
# 如果下方两条命令执行结果为空或与OHTTPS中的不一致，则环境变量没有生效或设置不正确，请检查容器启动命令或者docker-compose.yml文件中是否正确设置了这两个环境变量
echo $PUSH_NODE_ID
echo $PUSH_NODE_TOKEN

如果以上两项都没有问题且问题依然存在，则请联系客服解决