NGINX ACME 模块使用指南

jetsung

NGINX ACME 模块使用指南

ngx_http_acme_module 是一个由 NGINX 官方（F5, Inc.）开发的基于 Rust 的动态模块，用于实现 ACMEv2 协议（RFC 8555）的自动化证书管理。它支持 HTTP-01 和 TLS-ALPN-01 验证方式。

1. 模块加载

由于该模块是作为动态模块编译的，必须在 nginx.conf 的最顶部（全局块）加载：

load_module modules/ngx_http_acme_module.so;

2. 基础配置示例

以下是一个使用 Let's Encrypt 获取证书并在 443 端口使用的完整示例：

# 加载模块
load_module modules/ngx_http_acme_module.so;

events {
    worker_connections 1024;
}

http {
    # 必须配置解析器以解析 ACME 服务器域名
    # 使用 Google 或 Cloudflare 的公共 DNS，或者使用 Docker 内部 DNS (127.0.0.11)
    resolver 8.8.8.8 1.1.1.1 valid=300s;
    resolver_timeout 5s;

    # 【重要】如果是在 Docker 内部，也可以尝试使用 Docker 的内置解析器
    # resolver 127.0.0.11 ipv6=off;

    # 定义共享内存区域，用于存储证书和状态（建议 1M 或更多）
    acme_shared_zone zone=ngx_acme_shared:1M;

    # 定义 ACME 发行者
    acme_issuer letsencrypt {
        uri https://acme-v02.api.letsencrypt.org/directory;
        state_path /var/cache/nginx/acme_letsencrypt;
        accept_terms_of_service;
        contact mailto:admin@example.com;
    }

    server {
        listen 80;
        server_name example.com;

        # HTTP-01 验证需要监听 80 端口，模块会自动处理 /.well-known/acme-challenge/
        location / {
            return 301 https://$host$request_uri;
        }
    }

    server {
        listen 443 ssl;
        server_name example.com;

        # 关联发行者并请求证书
        acme_certificate letsencrypt;

        # 使用模块提供的嵌入式变量加载证书和密钥
        ssl_certificate     $acme_certificate;
        ssl_certificate_key $acme_certificate_key;

        # 推荐：启用证书缓存以提高性能
        ssl_certificate_cache max=10;

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

3. 指令详解

`acme_issuer`

上下文: http
作用: 定义一个证书发行者配置块。
子指令:
- uri: ACME 服务器的目录 URL（必须）。
- account_key: 指定账户私钥。格式为算法（ecdsa:256/rsa:2048）或现有密钥路径。默认为 ecdsa:256。
- challenge: 验证方式。可选 http-01 (默认) 或 tls-alpn-01。
- state_path: 证书和账户数据在磁盘上的持久化路径。
- contact: 联系方式，通常为 mailto:email@address。
- accept_terms_of_service: 自动同意服务条款。
- external_account_key: 配置外部账户绑定 (EAB)，用于 ZeroSSL 或 Google Trust Services 等。

`acme_certificate`

上下文: server
用法: acme_certificate issuer_name [identifiers...];
作用: 为当前虚拟主机请求证书。如果不指定标识符，将自动使用 server_name 指令中的域名。

`acme_shared_zone`

上下文: http
用法: acme_shared_zone zone=name:size;
作用: 分配共享内存以在所有工作进程间同步证书数据。

4. 高级用法

TLS-ALPN-01 验证

如果您无法开启 80 端口，可以使用 TLS-ALPN-01 方式（必须在 443 端口进行）：

acme_issuer cloud_issuer {
    uri https://...;
    challenge tls-alpn-01;
    state_path /etc/nginx/acme;
}

server {
    listen 443 ssl;
    server_name example.com;
    acme_certificate cloud_issuer;
    ...
}

嵌入式变量

模块提供了两个只读变量，直接用于 ssl_certificate 系列指令：

$acme_certificate: 获取当前 server 块签发的证书内容（PEM 格式）。
$acme_certificate_key: 获取对应的私钥内容。

5. 注意事项

权限: 确保 NGINX 工作进程对 state_path 目录具有读写权限。
限速: 第一次启动时，模块会发起注册和签发请求。如果域名过多，请注意 ACME 服务器的速率限制。
域名解析: 必须配置 resolver 指令，否则模块无法连接到 ACME 发行者。
IP 证书: 该模块支持申请 IP 证书（RFC 8738），只需将 IP 放入 server_name 或 acme_certificate 参数中。

模块仓库：https://github.com/nginx/nginx-acme
官方文档：http://nginx.org/en/docs/http/ngx_http_acme_module.html

jetsung

更多配置

解耦模式

nginx.conf

主配置需要增加

include extend/acme.conf;

extend/acme.sh

Docker 模式

# 必须配置解析器以解析 ACME 服务器域名
# 使用 Google 或 Cloudflare 的公共 DNS，或者使用 Docker 内部 DNS (127.0.0.11)
# resolver 8.8.8.8 1.1.1.1 valid=300s;
resolver 8.8.8.8 1.1.1.1 valid=300s ipv6=off;

# 如果是在 Docker 内部，也可以尝试使用 Docker 的内置解析器
# resolver 127.0.0.11 ipv6=off;

# 定义共享内存区域，用于存储证书和状态（建议 1M 或更多）
acme_shared_zone zone=ngx_acme_shared:1M;

# 定义 ACME 发行者
acme_issuer letsencrypt {
    uri https://acme-v02.api.letsencrypt.org/directory;
    state_path /etc/nginx/acme/letsencrypt;
    accept_terms_of_service;
    contact mailto:admin@example.com;
}

acme_issuer zerossl {
    uri https://acme.zerossl.com/v2/DV90;
    state_path /etc/nginx/acme/zerossl;
    accept_terms_of_service;
    contact mailto:admin@example.com;
    external_account_key <EAB_ID> data:<EAB_HMAC_KEY>;
}

acme_issuer google {
    uri https://dv.acme-v02.api.pki.goog/directory;
    state_path /etc/nginx/acme/google;
    accept_terms_of_service;
    contact mailto:admin@example.com;
    external_account_key <EAB_ID> data:<EAB_HMAC_KEY>;
}

wildcard/acme.conf

通用配置（不同的提供商可以共用）

# wildcard/acme.conf
include extend/ssl.conf;

# 关联发行者并请求证书
# acme_certificate zerossl;
# acme_certificate letsencrypt;

# 使用模块提供的嵌入式变量加载证书和密钥
ssl_certificate     $acme_certificate;
ssl_certificate_key $acme_certificate_key;

# 推荐：启用证书缓存以提高性能
ssl_certificate_cache max=10;

extend/ssl.conf

SSL 通用配置（手动签名也可以共用）

# extend/ssl.conf
#listen [::]:443 ssl ipv6only=off reuseport;
#listen [::]:443 quic reuseport ipv6only=off;

listen 443 ssl;
listen 443 quic;
listen [::]:443 ssl;
listen [::]:443 quic;

# 监听 IPv4 和 IPv6 的 443 端口，启用 SSL
http2 on;
http3 on;

# 仅启用 TLSv1.3
ssl_protocols TLSv1.2 TLSv1.3;

# 默认密码套件
ssl_ciphers DEFAULT;

# 优先使用服务器指定的密码套件
ssl_prefer_server_ciphers on;

# 启用 SSL 会话缓存，提高性能
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;

# 设置 SSL 缓冲区大小，优化性能
ssl_buffer_size 1400;

# 设置 HSTS 头部，强制客户端使用 HTTPS
add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload";

# Alt-Svc 指示浏览器支持 HTTP/3
add_header Alt-Svc 'h3=":443"; ma=86400';

# 启用 OCSP  stapling，提高证书验证效率
ssl_stapling off;
ssl_stapling_verify off;

# 错误页重定向，HTTP 1.1 协议的 401 Unauthorized 状态码已被废弃，使用 403 Forbidden
error_page 403 https://$host$request_uri;

conf.d/example.com.conf

域名配置入口主配置

# conf.d/example.com.conf
server {
    listen 80;
    listen  [::]:80;

    server_name example.com;

    include extend/http_to_https.conf;
}

server {
    server_name example.com;

    acme_certificate letsencrypt;
    include wildcard/acme.conf;
}

extend/http_to_https.conf

HTTP 强制跳转至 HTTPS

# extend/http_to_https.conf
if ($skip_https_redirect = 1) {
    return 301 https://$host$request_uri;
}

extend/maps.conf

禁止 ClaudeBot 爬虫、设置 HTTP 跳转 HTTPS 参数

# extend/maps.conf
map $http_user_agent $bad_bot {
    default 0;
    "~*ClaudeBot" 1;
}

map $host $skip_https_redirect {
    default 1;                     # 默认要重定向
}

extend/robots_disallow.conf

禁止所有爬虫

# extend/robots_disallow.conf
location = /robots.txt {
    add_header Content-Type text/plain;
    return 200 "User-agent: *\nDisallow: /\n";
}

在 conf.d/example.com.conf 需要使用禁止爬虫的域名配置中追加

# conf.d/example.com.conf
server {
    include extend/robots_disallow.conf;
}

扩展

反向代理

# conf.d/example.com.conf
server {
    location / {
        proxy_pass http://ntfy;
        proxy_http_version 1.1;

        proxy_set_header Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;

        proxy_connect_timeout 3m;
        proxy_send_timeout 3m;
        proxy_read_timeout 3m;

        client_max_body_size 0; # Stream request body to backend
    }
}

上游文件

# extend/upstreams.conf
upstream server1 {
    server 127.0.0.1:8080;
}

upstream server2 {
    server host.docker.internal:9120;
}

upstream server3 {
    server other_server:8989;
}