HTTPS-PORTAL

HTTPS-PORTAL 是一款由 Nginx、Let's Encrypt 和 Docker 驱动的全自动 HTTPS 服务器。通过使用它，您可以让任何现有 Web 应用通过 HTTPS 运行，仅需额外一行配置。SSL 证书将自动从 Let's Encrypt 获取并续期。

Docker Hub 页面：[***]

目录

• 镜像概述与主要用途
• 前提条件
• 快速上手
• 核心功能与特性
  • 本地测试
  • 重定向配置
  • 自动容器发现
  • 与非 Docker 应用的混合部署
  • 多域名支持
  • 多上游服务（负载均衡）
  • 静态网站托管
  • 证书共享
  • HTTP 基本认证
  • 访问限制
  • 日志配置
  • 调试模式
  • 其他配置
• 高级用法
  • 通过环境变量配置 Nginx
  • 覆盖 Nginx 配置文件
• 工作原理
• 关于 Let's Encrypt 的速率限制
• 故障排除
• 鸣谢

镜像概述与主要用途

HTTPS-PORTAL 是一款轻量级 Docker 镜像，旨在为 Web 应用提供全自动的 HTTPS 支持。其核心功能包括：

• 自动从 Let's Encrypt 获取和续期 SSL/TLS 证书
• 通过 Nginx 实现 HTTP 到 HTTPS 的强制重定向
• 支持多域名、多上游服务、静态网站托管等场景
• 提供灵活的访问控制和认证机制

主要用途：快速为现有 Web 应用（无论是否基于 Docker）添加 HTTPS 支持，无需手动配置 Nginx 和 SSL 证书。

前提条件

HTTPS-PORTAL 以 Docker 镜像形式分发，使用前需确保目标 Linux 主机（本地或远程）满足以下条件：

• 80 和 443 端口可用且已开放（需允许外部访问）
• 已安装 Docker Engine，推荐同时安装 Docker Compose（本文示例主要基于 Docker Compose 格式）
• 所有使用的域名已解析到该主机的 IP 地址

快速上手

基础示例

创建 docker-compose.yml 文件：

https-portal:
  image: steveltn/https-portal:1
  ports:
    - '80:80'
    - '443:443'
  environment:
    DOMAINS: 'example.com'  # 替换为您的域名
    # STAGE: 'production'  # 测试通过前不要使用生产环境，默认使用 Let's Encrypt 测试服务器

在同一目录下执行 docker-compose up，片刻后即可通过 [***] 访问默认欢迎页面。

真实场景示例（对接 WordPress）

https-portal:
  image: steveltn/https-portal:1
  ports:
    - '80:80'
    - '443:443'
  links:
    - wordpress
  restart: always
  environment:
    DOMAINS: 'wordpress.example.com -> [***]  # 域名 -> 上游服务（WordPress 容器）
    # STAGE: 'production'  # 测试稳定后启用生产环境证书

wordpress:
  image: wordpress
  links:
    - db:mysql

db:
  image: mariadb
  environment:
    MYSQL_ROOT_PASSWORD: '安全密码'  # 替换为实际密码

执行 docker-compose up -d（-d 表示后台运行），访问 [***] 即可使用 HTTPS 加密的 WordPress。

核心功能与特性

本地测试

无需公网域名即可本地测试配置，使用自签名证书：

https-portal:
  # ... 其他配置 ...
  environment:
    STAGE: local  # 使用本地自签名证书
    DOMAINS: 'example.com'  # 测试域名

注意：本地测试需确保 example.com 解析到 Docker 主机，可通过修改 /etc/hosts 文件（如 127.0.0.1 example.com）或配置 DNSMasq 实现。

重定向配置

支持域名间重定向（使用 => 分隔符）：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: '[***] => [***]  # www 域名重定向到主域名

所有路径将自动跟随，例如 [***] 会重定向到 [***]（301 永久重定向）。

自动容器发现

警告：此功能需挂载 Docker 套接字（/var/run/docker.sock），本质上授予容器主机 root 权限，除非必要否则不建议使用。

通过 Docker API 自动发现同一主机上的其他容器，无需手动配置 DOMAINS：

1. 配置 HTTPS-PORTAL 挂载 Docker 套接字：

version: '2'
services:
  https-portal:
    # ... 其他配置 ...
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro  # 只读挂载 Docker 套接字

2. 在目标应用容器中设置 VIRTUAL_HOST 环境变量：

version: '2'
services:
  my-app:
    image: nginx  # 示例应用
    environment:
      VIRTUAL_HOST: example.com  # 告诉 HTTPS-PORTAL 为该域名配置代理
    expose:
      - 80  # 暴露内部端口（无需映射到主机）

注意：应用容器需与 HTTPS-PORTAL 在同一 Docker 网络中。若应用暴露多个端口，可通过 VIRTUAL_PORT 指定上游端口（如 VIRTUAL_PORT: 8080）。

与非 Docker 应用的混合部署

对于直接运行在主机上的非 Docker 应用，可通过 host.docker.internal 访问（支持 Docker Desktop）：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: 'example.com -> [***]  # 代理到主机的 8080 端口

防火墙设置：若主机启用 UFW，需允许 HTTPS-PORTAL 容器访问主机端口：

# 获取 Docker 网络网关 IP（假设网络名为 default）
DOCKER_HOST_IP=$(docker network inspect default --format='{{(index .IPAM.Config 0).Gateway}}')
# 获取 HTTPS-PORTAL 容器 IP
HTTPS_PORTAL_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <容器名>)
# 允许访问主机 8080 端口
ufw allow from $HTTPS_PORTAL_IP to $DOCKER_HOST_IP port 8080

多域名支持

通过逗号分隔多个域名配置：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: 'blog.example.com -> [***] git.example.com -> [***]

支持为每个域名单独指定证书环境（覆盖全局 STAGE）：

DOMAINS: 'blog.example.com -> [***] #local, git.example.com #staging'  # blog 使用本地证书，git 使用测试证书

多上游服务（负载均衡）

通过 | 分隔多个上游服务，实现负载均衡：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: 'app.example.com -> [***]|[***][weight=2 max_conns=100]'

• weight=2：app2 权重为 2（接收 2/3 请求）
• max_conns=100：限制到 app2 的并发连接数为 100

支持 Nginx 上游模块的所有参数（详见 Nginx 文档）。

静态网站托管

直接托管静态文件（无需上游服务）：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: 'static.example.com'  # 仅指定域名，无需上游
  volumes:
    - /path/to/static/files:/var/www/vhosts/static.example.com  # 挂载静态文件目录

HTTPS-PORTAL 会自动在 /var/www/vhosts 下创建与域名对应的子目录，静态文件需放在该目录下（如 index.html）。

证书共享

将证书目录挂载到主机，供其他应用使用：

https-portal:
  # ... 其他配置 ...
  volumes:
    - /host/path/to/certs:/var/lib/https-portal  # 证书存储路径

证书文件结构：/host/path/to/certs/[域名]/fullchain.pem（证书链）和 privkey.pem（私钥）。

HTTP 基本认证

为域名添加 HTTP 基本认证（格式：用户名:密码@域名 -> 上游）：

https-portal:
  # ... 其他配置 ...
  environment:
    DOMAINS: 'admin:*** -> [***]  # 访问 example.com 需输入用户名 admin、密码 secret

访问限制

通过 IP 地址限制访问，支持全局或按域名配置：

• 全局限制（允许 1.2.3.0/24 网段和 4.3.2.1 IP）：

https-portal:
  environment:
    ACCESS_RESTRICTION: "1.2.3.4/24 4.3.2.1"  # 空格分隔多个 IP/网段

• 按域名限制：

DOMAINS: "[1.2.3.4/24] app.example.com -> [***] [4.3.2.1] api.example.com"

支持 CIDR 网段（如 192.168.1.0/24）和单个 IP（如 1.2.3.4）。

日志配置

默认不记录访问日志，错误日志输出到 stdout（Docker 日志），可通过环境变量自定义：

• 输出到标准流：

https-portal:
  environment:
    ERROR_LOG: stdout  # 错误日志到 stdout
    ACCESS_LOG: stderr  # 访问日志到 stderr

• 输出到文件（需挂载日志目录）：

https-portal:
  environment:
    ERROR_LOG: default  # 默认路径 /var/log/nginx/error.log
    ACCESS_LOG: default  # 默认路径 /var/log/nginx/access.log
  volumes:
    - /host/logs:/var/log/nginx  # 挂载日志目录到主机

• 自定义日志路径：

https-portal:
  environment:
    ERROR_LOG: /var/log/custom/error.log
    ACCESS_LOG: /var/log/custom/access.log
  volumes:
    - /host/custom/logs:/var/log/custom

其他日志相关环境变量：

• ACCESS_LOG_BUFFER: 访问日志缓冲区大小（如 16k）
• ERROR_LOG_LEVEL: 错误日志级别（默认 error，可选 debug/info 等）

调试模式

设置 DEBUG=true 输出域名解析等调试信息：

https-portal:
  environment:
    DEBUG: 'true'  # 启用调试模式

其他配置

• 证书续期时间：默认提前 30 天续期，可通过 RENEW_MARGIN_DAYS 调整（如 RENEW_MARGIN_DAYS=15）。
• 强制续期证书：设置 FORCE_RENEW: 'true' 强制重新获取证书（用于解决证书链问题）。

高级用法

通过环境变量配置 Nginx

支持通过环境变量修改 Nginx 核心参数，默认值如下：

示例：启用 HSTS 和 WebSocket：

https-portal:
  environment:
    HSTS_MAX_AGE: 31536000  # HSTS 有效期 1 年
    WEBSOCKET: 'true'       # 启用 WebSocket 代理

覆盖 Nginx 配置文件

通过挂载自定义 ERB 模板覆盖默认 Nginx 配置：

• 单域名配置：挂载 <域名>.conf.erb（HTTP 配置）和 <域名>.ssl.conf.erb（HTTPS 配置）：

https-portal:
  volumes:
    - ./example.com.conf.erb:/var/lib/nginx-conf/example.com.conf.erb:ro  # HTTP 配置
    - ./example.com.ssl.conf.erb:/var/lib/nginx-conf/example.com.ssl.conf.erb:ro  # HTTPS 配置

• 全局默认配置：覆盖 default.conf.erb 或 default.ssl.conf.erb 影响所有域名：

https-portal:
  volumes:
    - ./custom.default.ssl.conf.erb:/var/lib/nginx-conf/default.ssl.conf.erb:ro  # 全局 HTTPS 模板

模板语法参考 ERB，可使用环境变量动态生成配置。

工作原理

1. 证书获取：启动时检查证书是否存在/过期，若不存在或即将过期（默认提前 30 天），通过 ACME 协议向 Let's Encrypt 申请/续期证书。
2. Nginx 配置生成：根据 DOMAINS 或自动发现的容器生成 Nginx 配置，包含 HTTPS 监听、SSL 证书路径、上游代理规则等。
3. 服务启动：启动 Nginx 服务，并通过 cron 任务每周检查证书续期。

关于 Let's Encrypt 的速率限制

Let's Encrypt 为防止滥用设置了速率限制，主要包括：

• 每注册域名每周最多 50 张证书
• 每小时最多 5 次验证失败
• 每周最多 5 次重复证书申请

HTTPS-PORTAL 默认使用 Let's Encrypt 测试服务器（STAGE=staging），生成的证书不受浏览器信任，但无严格速率限制。测试稳定后，通过 STAGE=production 切换到生产服务器，生成可信证书。

故障排除

• 证书链不完整：设置 FORCE_RENEW: 'true' 强制续期证书，重新获取完整证书链。
• 域名解析失败：确保域名已正确解析到主机 IP，可通过 nslookup example.com 验证。
• 端口占用：确保 80/443