在实际生产环境中，OpenResty 的版本升级和第三方模块管理是运维工作的重要内容。本文将从两个实际案例出发：如何在已安装的 OpenResty 中新增 LDAP 认证模块，以及如何将 OpenResty 打包成 RPM 以便批量部署。

版本说明

本文基于多篇历史文章合并整理，包含 2020-06（LDAP 模块添加）和 2021-10（RPM 打包）两部分的实践内容。合并后版本写于 2026-09。

1. 为 OpenResty 新增 LDAP 认证模块

1.1 背景说明

在一些企业内部系统中，需要对公共服务添加 LDAP 认证以实现统一身份管理。Nginx 结合 LDAP 认证模块可以方便地实现这一需求，但默认安装的 OpenResty 不包含此模块，需要手动编译添加。

1.2 准备工作

首先下载与当前 OpenResty 版本一致的源码包：

wget https://openresty.org/download/openresty-1.13.6.2.tar.gz

下载所需的 LDAP 认证模块：

cd /opt  # 注意拉取代码存放位置
git clone https://gitee.com/eryajf/nginx-auth-ldap.git

安装编译依赖：

yum -y install gcc gcc-c++ pcre pcre-devel openldap-devel lua-devel systemtap-sdt-devel openssl-devel openssl

1.3 编译安装

坑与边界

踩坑记录：编译并不能在 OpenResty 根目录进行，否则将会失败。需要在 bundle/nginx-版本号/ 目录下进行编译。

tar xf openresty-1.13.6.2.tar.gz
cd openresty-1.13.6.2/bundle/nginx-1.13.6/

配置编译选项，添加 LDAP 模块：

./configure --prefix=/usr/local/openresty/nginx \
  --with-cc-opt='-O2 -DNGX_LUA_ABORT_AT_PANIC -I/usr/local/openresty/zlib/include -I/usr/local/openresty/pcre/include -I/usr/local/openresty/openssl/include' \
  --add-module=../ngx_devel_kit-0.3.0 \
  --add-module=../echo-nginx-module-0.61 \
  --add-module=../xss-nginx-module-0.06 \
  --add-module=../ngx_coolkit-0.2rc3 \
  --add-module=../set-misc-nginx-module-0.32 \
  --add-module=../form-input-nginx-module-0.12 \
  --add-module=../encrypted-session-nginx-module-0.08 \
  --add-module=../srcache-nginx-module-0.31 \
  --add-module=../ngx_lua-0.10.13 \
  --add-module=../ngx_lua_upstream-0.07 \
  --add-module=../headers-more-nginx-module-0.33 \
  --add-module=../array-var-nginx-module-0.05 \
  --add-module=../memc-nginx-module-0.19 \
  --add-module=../redis2-nginx-module-0.15 \
  --add-module=../redis-nginx-module-0.3.7 \
  --add-module=../ngx_stream_lua-0.0.5 \
  --with-ld-opt='-Wl,-rpath,/usr/local/openresty/luajit/lib -L/usr/local/openresty/zlib/lib -L/usr/local/openresty/pcre/lib -L/usr/local/openresty/openssl/lib -Wl,-rpath,/usr/local/openresty/zlib/lib:/usr/local/openresty/pcre/lib:/usr/local/openresty/openssl/lib' \
  --with-pcre-jit --with-stream --with-stream_ssl_module --with-http_v2_module \
  --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module \
  --with-http_stub_status_module --with-http_realip_module --with-http_addition_module \
  --with-http_auth_request_module --with-http_secure_link_module \
  --with-http_random_index_module --with-http_gzip_static_module --with-http_sub_module \
  --with-http_dav_module --with-http_flv_module --with-http_mp4_module \
  --with-http_gunzip_module --with-threads --with-file-aio --with-dtrace-probes \
  --with-http_image_filter_module --with-stream --with-stream_ssl_module --with-http_ssl_module \
  --add-module=/opt/nginx-auth-ldap

坑与边界

常见错误：如果在一个已经安装过 OpenResty 的环境中新增模块，需要先把原来的安装包移走，否则 make 时会报如下错误：

/bin/ld: warning: libssl.so.10, needed by /usr/lib/gcc/x86_64-redhat-linux/4.8.5/../../../../lib64/libldap.so, may conflict with libssl.so.1.1
/bin/ld: objs/src/event/ngx_event_openssl.o: undefined reference to symbol 'SSL_CTX_get_ex_new_index@@libssl.so.10'
collect2: error: ld returned 1 exit status
make[1]: *** [objs/nginx] Error 1

编译并安装：

make
make install

重新软链 nginx 主程序：

ln -snf /usr/local/openresty/nginx/sbin/nginx /usr/sbin/

1.4 LDAP 认证配置

配置示例：

http {
    ldap_server ldap_server1 {
        url ldap://192.0.2.10:389/dc=example,dc=com?uid?sub?(&(objectClass=posixAccount));
        bindn "cn=admin,dc=example,dc=com";
        binddn "cn=proxy,dc=example,dc=com";
        bindpw "proxy_password";
        group_attribute memberuid;
        group_attribute_is_dn off;
        require valid_user;
    }
    
    server {
        location / {
            auth_ldap "Restricted Access";
            auth_ldap_servers ldap_server1;
        }
    }
}

---

2. 将 OpenResty 打包成 RPM

2.1 为什么需要 RPM 包

源码包有源码包的灵活，RPM 包有 RPM 包的方便。在企业生产环境中，如果需要批量部署 OpenResty，使用 RPM 包可以：

• 通过 yum/yum 仓库统一管理版本
• 简化批量安装和卸载流程
• 利用 RPM 签名确保软件完整性
• 便于与其他系统（监控、备份）集成

2.2 准备物料

• OpenResty 官网 (opens new window)
• openresty-packaging (opens new window)：官方维护的 RPM 构建基础文件
• 自定义 RPM 构建项目：rpmbuild (opens new window)

官方提供的包大多使用默认配置，不大适合生产直接使用，因此可以借鉴官方包进行调整改造。

2.3 自定义调整

主要调整内容包括：

替换 nginx.conf 配置

• 调整日志格式为 JSON
• 调整路径配置

error_log /data/log/error.log;
access_log /data/log/tmp.log json;

• 调整支持传递带有下划线的 header

创建软链便于维护

ln -snf /usr/local/openresty/nginx/sbin/nginx /usr/sbin/nginx
ln -snf /usr/local/openresty/nginx/conf /etc/nginx

添加日志清理策略

/data/log/tmp.log
/data/log/error.log
{
    daily
    dateext
    missingok
    rotate 7
    notifempty
    create 755 www
    sharedscripts
    postrotate
        [ -f /var/run/nginx.pid ] && kill -USR1 `cat /var/run/nginx.pid`
    endscript
}

预装常用模块

• LDAP 认证模块
• upsync 模块（基于 Consul 做配置中心）

2.4 打包步骤

以下基于 CentOS 7 进行操作：

首先克隆项目到 root 目录（rpmbuild 基于家目录工作）：

git clone https://github.com/carry00/rpmbuild.git

配置阿里云和 OpenResty 的 yum 源：

yum -y install yum-utils
yum-config-manager --add-repo http://mirrors.aliyun.com/repo/Centos-7.repo
yum-config-manager --add-repo https://openresty.org/package/centos/openresty.repo

安装基础构建工具：

yum -y install rpm-build redhat-rpm-config rpmdevtools

安装项目编译依赖：

yum -y install gcc gcc-c++ systemtap-sdt-devel openresty-zlib-devel openresty-openssl-devel openresty-pcre-devel gd-devel openresty-openssl111-devel ccache

下载 spec 中定义的源码文件：

cd /root/rpmbuild/SPECS/openresty/
spectool -g -R openresty.spec

执行打包命令：

rpmbuild -ba openresty.spec

当返回值为 0 时，构建成功。构建好的 RPM 包位于 /root/rpmbuild/RPMS 目录。

查看包信息：

cd /root/rpmbuild/RPMS/x86_64
rpm -qpi openresty-1.19.9.1-1.eryajf.el7.x86_64.rpm

---

3. 版本选择与模块兼容性

3.1 OpenResty 版本演进

版本	发布时间	主要特性
1.13.6.2	2018-06	LuaJIT 2.1，新一代 NGINX 1.13.x 核心
1.19.9.1	2020-10	更好的性能，OpenSSL 1.1.1 支持

选择版本时需要考虑：

• OpenSSL 版本（老系统可能只有 OpenSSL 1.0，需要选择对应版本）
• Lua 库兼容性（部分第三方库可能在特定版本上有问题）
• 业务依赖（某些模块可能需要特定版本才能工作）

3.2 模块编译顺序

在编译 OpenResty 时，模块的添加顺序可能影响编译结果。建议遵循以下顺序：

1. 先添加 ngx_devel_kit（很多模块依赖它）
2. 再添加其他第三方模块
3. 最后添加官方模块

3.3 升级时的平滑迁移策略

在生产环境中升级 OpenResty 需要格外谨慎，推荐以下步骤：

步骤一：备份配置

# 备份整个 OpenResty 目录
cp -r /usr/local/openresty /usr/local/openresty.backup.$(date +%Y%m%d)
# 备份配置文件
cp -r /usr/local/openresty/nginx/conf /etc/nginx.backup.$(date +%Y%m%d)

步骤二：灰度测试

在新服务器或测试环境编译新版本，验证业务功能正常后再在生产环境部署。

步骤三：热更新

利用 nginx 的热加载机制，平滑切换版本：

# 优雅重启
nginx -s reload
# 或者完全停止再启动
systemctl stop openresty
systemctl start openresty

步骤四：回滚预案

# 快速回滚
rm -rf /usr/local/openresty
cp -r /usr/local/openresty.backup.$(date +%Y%m%d) /usr/local/openresty
nginx -s reload

---

4. 总结

场景	方法	适用情况
新增单个模块	重新编译添加 --add-module	少量服务器，紧急修复
批量部署	打包成 RPM	多服务器，标准化运维
版本升级	RPM 升级 or 重新打包	版本跨度大，推荐重新打包

无论是新增模块还是版本升级，核心思路是：准备好编译环境 → 下载源码和依赖 → 配置编译参数 → 执行编译 → 验证安装。

关键踩坑点：

1. 编译目录必须在 bundle/ 下，不能在根目录
2. 原有 OpenResty 环境要先移走安装包
3. 依赖库版本要匹配（特别是 OpenSSL）

4.1 更多模块添加案例

除了 LDAP 模块，常见的还需要添加以下模块：

upsync 模块（基于 Consul/Etcd 做配置中心）

--add-module=../nginx-upsync-module

lua-resty-kafka 模块（Kafka 客户端）

--add-module=../lua-resty-kafka

nginx-http-concat 模块（静态资源合并）

--add-module=../nginx-http-concat

添加新模块的通用流程：

1. 克隆模块源码到 bundle/ 目录外
2. 在 configure 参数中添加 --add-module=路径
3. 重新编译 make
4. 升级包或替换 nginx 二进制文件

---

5. 常见问题汇总

Q1：编译时提示缺少依赖怎么办？

A：使用 yum 安装对应-devel 包，例如 yum install pcre-devel openssl-devel zlib-devel。

Q2：原有配置是否需要修改？

A：通常不需要。但建议在升级前检查配置文件与新版本的兼容性。

Q3：RPM 安装后如何查看版本？

A：openresty -v 或 nginx -v。

Q4：如何确定哪些模块已经安装？

A：nginx -V 会列出所有编译进去的模块。

Q5：LDAP 连接失败如何排查？

A：首先检查 LDAP 服务器连通性 ping ldap_server，然后检查防火墙规则 iptables -L -n，最后查看 Nginx 错误日志 /var/log/nginx/error.log。

Q6：RPM 包签名如何添加？

A：使用 rpmsign 命令添加签名，确保客户端可以验证包完整性。

Q7：如何回滚 OpenResty 版本？

A：使用 yum history 或手动卸载后安装旧版本 RPM。生产环境建议保留上一版本的 RPM 包。

---

6. 参考

• nginx-auth-ldap 模块 (opens new window)
• OpenResty 官方打包工具 (opens new window)

{
  "article_title": "OpenResty 版本升级与模块管理：从 1.13 到 1.19 的实践",
  "date": "2020-06-06 11:17:48",
  "category": "Linux笔记/Nginx",
  "tags": ["安全加固", "Nginx", "OpenResty", "Linux"],
  "version_block": true,
  "principle": true,
  "pitfall": true,
  "verification": true,
  "merged_from": [
    "16.OpenResty-1-13-6-2-新增ldap模块儿.md",
    "18.制作OpenResty-1-19-9-1的RPM包.md"
  ]
}