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.3.1，于 2025 年 12 月 08 日发布。

nginx-acme

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

该模块实现了以下规范：

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

入门

检出、配置并构建 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     admin@example.test;
    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 挑战是有版本的。如果指定了未版本化的名称，模块将自动选择最新实现的版本。

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

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

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 仓库中找到此模块的其他配置提示和文档。