hink/https-portal

HTTPS-PORTAL

HTTPS-PORTAL是一个由http://nginx.org、https://letsencrypt.org和https://www.docker.com驱动的全自动HTTPS服务器。使用它，您可以通过HTTPS运行任何现有的Web应用，只需添加一行额外配置。SSL证书会从Let's Encrypt自动获取并续期。

Docker Hub页面：https://hub.docker.com/r/steveltn/https-portal/

目录

• HTTPS-PORTAL
  • 前提条件
  • 快速体验
  • 快速开始
  • 功能特性
    • 本地测试
    • 自动容器发现
    • 与非Docker化应用的混合设置
    • 多域名支持
    • 静态网站服务
    • 与其他应用共享证书
  • 高级用法
    • 通过环境变量配置Nginx
    • 覆盖Nginx配置文件
  • 工作原理
  • 关于Let's Encrypt的速率限制
  • credits

前提条件

HTTPS-PORTAL以Docker镜像形式提供。使用前，您需要一台Linux机器（本地或远程主机），满足：

• 80和443端口可用且已开放。
• 已安装https://docs.docker.com/engine/installation/。此外，强烈推荐安装https://docs.docker.com/compose/，它能简化操作。本文档中的示例主要使用Docker Compose格式。
• 您将在示例中使用的所有域名已解析到该主机。

尽管了解Docker会有帮助，但使用HTTPS-PORTAL并不要求必须掌握Docker知识。

快速体验

在任意目录创建docker-compose.yml文件，内容如下：

yaml
https-portal:
  image: docker.xuanyuan.run/steveltn/https-portal:1.0.0
  ports:
    - '80:80'
    - '443:443'
  environment:
    DOMAINS: 'example.com'
    # STAGE: 'production'（生产环境，默认是staging测试环境）

在同一目录运行docker-compose up命令。片刻后，您将在[***]看到欢迎页面。

快速开始

以下是更贴近实际场景的示例：在另一个目录创建docker-compose.yml文件：

yaml
https-portal:
  image: docker.xuanyuan.run/steveltn/https-portal:1.0.0
  ports:
    - '80:80'
    - '443:443'
  links:
    - wordpress
  restart: always
  environment:
    DOMAINS: 'wordpress.example.com -> http://wordpress'
    # STAGE: 'production'（生产环境，默认是staging测试环境）
    # FORCE_RENEW: 'true'（强制续期证书）

wordpress:
  image: docker.xuanyuan.run/wordpress
  links:
    - db:mysql

db:
  image: docker.xuanyuan.run/mariadb
  environment:
    MYSQL_ROOT_PASSWORD: '<安全密码>'

运行docker-compose up -d命令。片刻后，WordPress将在[***]上运行。

在上述示例中，只有https-portal部分的环境变量是HTTPS-PORTAL的特定配置。这次我们添加了-d参数，它会让Docker Compose在后台运行docker-compose.yml中定义的应用。

注意：STAGE默认值为staging，这会从Let's Encrypt获取测试（不受信任）证书。

功能特性

本地测试

您可以在本地测试HTTPS-PORTAL与应用栈的配合。

yaml
https-portal:
  # ...
  environment:
    STAGE: local
    DOMAINS: 'example.com'

这样配置后，HTTPS-PORTAL会创建自签名证书。该证书可能不被浏览器信任，但可用于测试您的docker-compose文件，确保它与应用栈正常工作。

注意，HTTPS-PORTAL仅监听您在compose文件中指定的example.com。为了让HTTPS-PORTAL响应您的连接，您需要：

• 修改hosts文件，将example.com解析到Docker主机，

或

• 在您的计算机/路由器上设置DNSMasq，此方法更灵活。

测试完成后，您可以将应用栈部署到服务器。

自动容器发现

只要容器内可访问Docker API套接字，HTTPS-PORTAL就能发现同一主机上运行的其他Docker容器。

要实现这一点，使用以下docker-compose.yml启动HTTPS-PORTAL：

注意：目前容器发现不支持compose v2语法，因为新的网络接口与docker-gen不兼容。

yaml
https-portal:
  # ...
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro

然后启动一个或多个Web应用：

yaml
a-web-application:
  # ...
  ports:
    - '8080:80'
  environment:
    # 告诉HTTPS-PORTAL设置"example.com"
    VIRTUAL_HOST: example.com

注意，无需将Web服务链接到HTTPS-PORTAL，也不应在HTTPS-PORTAL的DOMAINS环境变量中添加example.com。

此功能允许您在同一主机上部署多个Web应用，添加/删除Web应用时无需重启HTTPS-PORTAL或中断其他应用。

如果您的Web服务暴露了多个端口（注意端口可能在Web服务的Dockerfile中暴露），使用环境变量VIRTUAL_PORT指定接受HTTP请求的端口：

yaml
a-multi-port-web-application:
  # ...
  ports:
    - '8080:80'
    - '2222:22'
  environment:
    VIRTUAL_HOST: example.com
    VIRTUAL_PORT: '8080'

当然，容器发现可以与通过环境变量指定的域结合使用：

yaml
https-portal:
  # ...
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
  environment:
    DOMAINS: 'example.com -> http://upstream'

与非Docker化应用的混合设置

直接在主机上运行（而非Docker容器中）的Web应用可通过dockerhost访问。

例如，如果某个应用在主机的8080端口接受HTTP请求，您可以这样启动HTTPS-PORTAL：

yaml
https-portal:
  # ...
  environment:
    DOMAINS: 'example.com -> http://dockerhost:8080'

多域名支持

您可以通过逗号分隔指定多个域名：

yaml
https-portal:
  # ...
  environment:
    DOMAINS: 'wordpress.example.com -> http://wordpress, gitlab.example.com -> http://gitlab'

您还可以为每个站点指定阶段（local、staging或production），注意单个站点的阶段会覆盖全局阶段：

yaml
DOMAINS: 'wordpress.example.com -> http://wordpress #local, gitlab.example.com #production'

静态网站服务

除了将请求转发到Web应用，HTTPS-PORTAL还可以直接提供（多个）静态网站服务：

yaml
https-portal:
  # ...
  environment:
    DOMAINS: 'hexo.example.com, octopress.example.com'
  volumes:
    - /data/https-portal/vhosts:/var/www/vhosts

HTTPS-PORTAL启动后，会在主机的/data/https-portal/vhosts目录中为每个虚拟主机创建相应的子目录：

/data/https-portal/vhosts
├── hexo.example.com
│  └── index.html
└── octopress.example.com
    └── index.html

您可以在此目录结构中放置自己的静态文件，它们不会被覆盖。需要index.html作为首页。

与其他应用共享证书

您可以将任意主机目录挂载为/var/lib/https-portal的数据卷（https://docs.docker.com/engine/userguide/dockervolumes/）。

例如：

yaml
https-portal:
  # ...
  volumes:
    - /data/ssl_certs:/var/lib/https-portal

现在，证书将在主机的/data/ssl_certs目录中可用。

高级用法

通过环境变量配置Nginx

有几个额外的环境变量可用于配置Nginx，它们对应您通常在nginx.conf中提供的配置选项。以下是带有默认值的配置键：

WORKER_PROCESSES=1
WORKER_CONNECTIONS=1024
KEEPALIVE_TIMEOUT=65
GZIP=on
SERVER_TOKENS=off
SERVER_NAMES_HASH_MAX_SIZE=512
SERVER_NAMES_HASH_BUCKET_SIZE=32        # 根据CPU默认是32或64
CLIENT_MAX_BODY_SIZE=1M                 # 0表示禁用请求体大小检查
PROXY_BUFFERS="8 4k"                    # 根据平台是4k或8k
PROXY_BUFFER_SIZE="4k"                  # 根据平台是4k或8k
RESOLVER="自定义解析器字符串"
PROXY_CONNECT_TIMEOUT=60;
PROXY_SEND_TIMEOUT=60;
PROXY_READ_TIMEOUT=60;

您还可以添加：

WEBSOCKET=true

使HTTPS-PORTAL代理WEBSOCKET连接。

覆盖Nginx配置文件

您可以通过提供包含有效server块的nginx.conf配置片段来覆盖默认Nginx设置。自定义Nginx配置是ERB模板，使用前会被渲染。

例如，要覆盖my.example.com的HTTPS和HTTP设置，您可以这样启动HTTPS-PORTAL：

yaml
https-portal:
  # ...
  volumes:
    - /path/to/http_config:/var/lib/nginx-conf/my.example.com.conf.erb:ro
    - /path/to/https_config:/var/lib/nginx-conf/my.example.com.ssl.conf.erb:ro

https://github.com/SteveLTN/https-portal/blob/master/fs_overlay/var/lib/nginx-conf/default.conf.erb和https://github.com/SteveLTN/https-portal/blob/master/fs_overlay/var/lib/nginx-conf/default.ssl.conf.erb是HTTPS-PORTAL使用的默认配置文件。您可以从复制这些文件开始进行修改。

另一个示例可在这里找到。

如果您想创建所有站点都使用的Nginx配置，可以覆盖/var/lib/nginx-conf/default.conf.erb或/var/lib/nginx-conf/default.ssl.conf.erb。如果未提供站点特定的配置文件，这两个文件将应用于每个站点。

工作原理

它的工作流程：

• 从https://letsencrypt.org为每个子域名获取SSL证书。
• 配置Nginx使用HTTPS（并通过将HTTP重定向到HTTPS强制使用HTTPS）。
• 设置 cron 任务，每周检查证书，若证书将在30天内过期则自动续期。

关于Let's Encrypt的速率限制

Let's Encrypt目前处于公开测试阶段。根据https://community.letsencrypt.org/t/public-beta-rate-limits/4772和https://community.letsencrypt.org/t/public-beta-rate-limits/4772/42，速率限制如下：

• 每IP每3小时10次注册。
• 每域名（非子域名）每7天5个证书。

前者通常不成问题，但后者可能在您为单个域名的多个子域名申请证书时造成困扰。Let's Encrypt支持SAN证书，但需要仔细规划且难以自动化。因此HTTPS-PORTAL仅处理CN证书。

HTTPS-PORTAL将证书存储在数据卷中，若找到有效证书，将在过期前30天才重新签名（您可以使用FORCE_RENEW: 'true'环境变量强制续期证书）。但如果您频繁调试镜像，可能会达到限制。这就是为什么STAGE默认是staging，即使用Let's Encrypt的测试服务器。当您完成实验并确认一切正常后，可以切换到生产模式：STAGE: 'production'。

根据Let's Encrypt的说明，这些限制会随着时间逐渐放宽。

Credits

• https://github.com/diafygi/acme-tiny by Daniel Roesler.
• https://github.com/jwilder/docker-gen by Jason Wilder.
• https://github.com/just-containers/s6-overlay.