acme: NGINX 的自动证书管理 (ACMEv2) 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-acme

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-acme

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用模块：

load_module modules/ngx_http_acme_module.so;

本文档描述了 nginx-module-acme v0.4.1，于 2026 年 5 月 01 日发布。

nginx-acme

nginx-acme 是一个 NGINX 模块，实现了自动证书管理 (ACMEv2) 协议。

该模块实现了以下规范：

RFC8555 (自动证书管理环境) 的限制：
- 仅支持 HTTP-01 挑战类型
RFC8737 (ACME TLS 应用层协议协商 (ALPN) 挑战扩展)
RFC8738 (ACME IP 标识符验证扩展)
RFC9773 (ACME 续订信息 (ARI) 扩展)
draft-ietf-acme-profiles (ACME 配置文件扩展，版本 01)

入门

检出、配置并构建 NGINX 在 ../nginx

cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release

结果将位于 `target/release/libnginx_acme.so`。

另一种方法是使用提供的配置脚本：

```sh
# 在 NGINX 源代码目录中
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

结果将位于 objs/ngx_http_acme_module.so。

目前此方法生成的库稍大，因为我们没有指示链接器执行 LTO 并删除未使用的代码。

测试

该仓库包含基于 nginx-tests 的集成测试套件。以下命令将构建模块并运行测试：

# nginx 源代码检出的路径，如果未指定，默认为 ../nginx。
export NGINX_SOURCE_DIR=$(realpath ../nginx)
# nginx-tests 检出的路径；如果未指定，默认为 ../nginx/tests。
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

大多数测试需要在路径中或通过 TEST_NGINX_PEBBLE_BINARY 环境变量指定的位置中包含 pebble 测试服务器二进制文件。

如何使用

将模块添加到 NGINX 配置中，并按以下描述进行配置。请注意，此模块需要在 http 块中配置 resolver。

示例配置

resolver 127.0.0.1:53;

acme_issuer example {
    uri         https://acme.example.com/directory;
    # contact     [email protected];
    state_path  /var/cache/nginx/acme-example;
    accept_terms_of_service;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    listen 443 ssl;
    server_name  .example.test
                 192.0.2.1      # 某些 ACME 服务器不支持
                 2001:db8::1    # 某些 ACME 服务器不支持
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # 不要在每个请求中解析证书
    ssl_certificate_cache max=2;
}

server {
    # 需要在 80 端口上监听以处理 ACME HTTP-01 挑战
    listen 80;

    location / {
        return 404;
    }
}

指令

[!重要] 以下参考反映了当前开发版本。请查看 ngx_http_acme_module 文档以获取最新发布版本。

acme_issuer

语法: acme_issuer name { ... }

默认: -

上下文: http

定义一个 ACME 证书颁发者对象。

uri

语法: uri uri

默认: -

上下文: acme_issuer

ACME 服务器的目录 URL。此指令是必需的。

account_key

语法: account_key alg[:size] | file

默认: -

上下文: acme_issuer

用于请求身份验证的帐户私钥。

接受的值：

ecdsa:256/384/521 用于 ES256、ES384 或 ES512 JSON Web 签名算法
rsa:2048/3072/4096 用于 RS256。
使用上述算法之一的现有密钥的文件路径。

生成的帐户密钥在重新加载时会被保留，但在重启时会丢失，除非配置了 state_path。

challenge

语法: challenge type

默认: http-01

上下文: acme_issuer

此指令在版本 0.2.0 中出现。

指定用于颁发者的 ACME 挑战类型。

接受的值：

http-01 (http)
tls-alpn-01 (tls-alpn)

ACME 挑战是有版本的。如果指定了未版本化的名称，模块会自动选择最新实现的版本。

common_name_in_csr

语法: common_name_in_csr on | off

默认: off

上下文: acme_issuer

此指令在版本 0.4.0 中出现。

如果启用，将证书请求中的主题通用名称设置为提供的第一个 DNS 名称或第一个 IP 地址。

请注意，启用此选项可能会导致证书请求被拒绝。

contact

语法: contact URL

默认: -

上下文: acme_issuer

设置 ACME 服务器可以用来联系客户端的 URL 数组，以解决帐户问题。除非明确指定，否则将使用 mailto: 方案。

external_account_key

语法: external_account_key kid file

默认: -

上下文: acme_issuer

此指令在版本 0.2.0 中出现。

指定一个密钥标识符 kid 和一个包含 MAC 密钥的 file 用于外部帐户授权。

可以指定值 data:key 代替 file，该值直接从配置加载密钥，而不使用中间文件。

在这两种情况下，密钥应以 base64url 编码。

preferred_chain

语法: preferred_chain name

默认: -

上下文: acme_issuer

此指令在版本 0.3.0 中出现。

指定首选证书链。

如果 ACME 服务器提供多个证书链，则优先选择由主题通用名称 name 颁发的最上面的证书链。如果没有匹配项，将使用默认链。

profile

语法: profile name [require]

默认: -

上下文: acme_issuer

此指令在版本 0.3.0 中出现。

请求来自 ACME 服务器的证书配置文件 name。

如果服务器不支持指定的配置文件，require 参数将导致证书续订失败。

ssl_trusted_certificate

语法: ssl_trusted_certificate file

默认: 系统 CA 包

上下文: acme_issuer

指定一个 file，其中包含用于验证 ACME 服务器证书的受信任 CA 证书，格式为 PEM。

ssl_verify

语法: ssl_verify on | off

默认: on

上下文: acme_issuer

启用或禁用对 ACME 服务器证书的验证。

state_path

语法: state_path path | off

默认: acme_<name>

上下文: acme_issuer

定义一个目录，用于存储可以跨重启持久化的模块数据。这可以通过跳过某些启动时的请求来提高加载时间，并避免触及 ACME 服务器的请求速率限制。

该目录包含敏感内容，例如帐户密钥、已颁发的证书和私钥。

off 参数 (0.2.0) 禁用在磁盘上存储帐户信息和已颁发证书。

在版本 0.2.0 之前，状态目录默认不会创建。

accept_terms_of_service

语法: accept_terms_of_service

默认: -

上下文: acme_issuer

同意使用 ACME 服务器的服务条款。某些服务器要求在注册帐户之前接受服务条款。条款通常在 ACME 服务器的网站上提供，如果需要，URL 将打印到错误日志中。

acme_shared_zone

语法: acme_shared_zone zone=name:size

默认: zone=ngx_acme_shared:256k

上下文: http

允许增加模块的内存存储大小。共享内存区域将用于存储所有配置的证书颁发者的已颁发证书、密钥和挑战数据。

默认区域大小足以容纳大约 50 个 ECDSA prime256v1 密钥或 35 个 RSA 2048 密钥。

acme_certificate

语法: acme_certificate issuer [identifier ...] [key=alg[:size]]

默认: -

上下文: server

定义一个证书，包含从颁发者 issuer 请求的 identifiers 列表。

可以省略显式的标识符列表。在这种情况下，标识符将从同一 server 块中的 server_name 指令中获取。并非所有在 server_name 中接受的值都是有效的证书标识符：不支持正则表达式和通配符。

key 参数设置生成的私钥类型。支持的密钥算法和大小： ecdsa:256 (默认)、ecdsa:384、ecdsa:521、 rsa:2048、rsa:3072、rsa:4096。

嵌入变量

ngx_http_acme_module 模块支持嵌入变量，在 acme_certificate 指令的 server 块中有效：

`$acme_certificate`

可以传递给 ssl_certificate 的 SSL 证书。

`$acme_certificate_key`

可以传递给 ssl_certificate_key 的 SSL 证书私钥。

GitHub

您可以在 nginx-module-acme 的 GitHub 仓库中找到有关此模块的其他配置提示和文档。