7.9.3 OpenResty安装与编译管理

本节聚焦 OpenResty 的安装方式、编译参数规划与版本管理策略，确保在不同场景下实现可控、可复现的构建与升级。

原理草图：从源码到运行时的构建与加载链路

文章图片

1. 安装方式选择与场景定位（含示例）#

  • 系统包安装：适合快速验证与标准化环境，维护成本低，但模块灵活性受限。
  • 源码编译：适合生产环境与定制化需求，可灵活选择 Nginx 核心版本、第三方模块与编译优化参数。
  • 容器镜像：适合云原生与 CI/CD 流水线，保证构建一致性与快速回滚。

示例：基于包管理器快速安装（Ubuntu）

# 更新索引
sudo apt update

# 安装 OpenResty 官方仓库（示例）
sudo apt install -y curl gnupg2 lsb-release
curl -fsSL https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg
echo "deb [signed-by=/usr/share/keyrings/openresty.gpg] https://openresty.org/package/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/openresty.list

# 安装
sudo apt update
sudo apt install -y openresty

# 验证版本
openresty -V

命令解释：
- openresty -V：输出编译参数、内置模块和 LuaJIT 版本，用于确认安装信息。

2. 源码编译前置准备（含示例）#

依赖安装与目录规划示例（CentOS 7）

# 依赖库
sudo yum install -y gcc make pcre pcre-devel zlib zlib-devel openssl openssl-devel perl

# 目录规范
sudo mkdir -p /opt/openresty/{src,build}
sudo mkdir -p /data/openresty/{conf,logs,temp}

命令解释：
- pcre：用于正则匹配模块
- openssl：用于 HTTPS
- zlib：用于 gzip 压缩
- /data/openresty：独立保存配置与日志，避免升级覆盖

3. 编译参数规划（核心点）与完整编译示例#

完整可执行编译流程（含注释）

# 进入源码目录
cd /opt/openresty/src

# 下载源码（示例版本）
curl -O https://openresty.org/download/openresty-1.25.3.2.tar.gz
tar -xzf openresty-1.25.3.2.tar.gz
cd openresty-1.25.3.2

# 配置编译参数
./configure \
  --prefix=/opt/openresty/1.25.3.2 \
  --conf-path=/data/openresty/conf/nginx.conf \
  --pid-path=/data/openresty/logs/nginx.pid \
  --error-log-path=/data/openresty/logs/error.log \
  --http-log-path=/data/openresty/logs/access.log \
  --http-client-body-temp-path=/data/openresty/temp/client_body \
  --http-proxy-temp-path=/data/openresty/temp/proxy \
  --http-fastcgi-temp-path=/data/openresty/temp/fastcgi \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-stream \
  --with-stream_ssl_module \
  --with-threads \
  --with-file-aio

# 编译与安装
make -j$(nproc)
sudo make install

参数解释：
- --prefix：安装路径，便于多版本并行
- --conf-path：配置文件路径，和二进制分离
- --with-http_ssl_module：启用 HTTPS
- --with-stream：支持 TCP/UDP 代理
- --with-threads、--with-file-aio：提升 IO 性能

4. 第三方模块集成管理（含示例）#

示例：集成第三方模块（动态模块）

# 下载模块（示例）
cd /opt/openresty/src
git clone https://github.com/openresty/echo-nginx-module.git

# 重新配置，加入动态模块
cd /opt/openresty/src/openresty-1.25.3.2
./configure \
  --prefix=/opt/openresty/1.25.3.2 \
  --add-dynamic-module=/opt/openresty/src/echo-nginx-module

make -j$(nproc)
sudo make install

加载动态模块示例

# /data/openresty/conf/nginx.conf
load_module modules/ngx_http_echo_module.so;

events {}
http {
  server {
    listen 8080;
    location /hello {
      echo "hello openresty";
    }
  }
}

验证

/opt/openresty/1.25.3.2/bin/openresty -t
/opt/openresty/1.25.3.2/bin/openresty -s reload
curl http://127.0.0.1:8080/hello

预期效果：输出 hello openresty

5. 编译后的安装与验证流程（含示例）#

# 查看编译参数
/opt/openresty/1.25.3.2/bin/openresty -V

# 语法检查
/opt/openresty/1.25.3.2/bin/openresty -t

# 启动与监听检查
/opt/openresty/1.25.3.2/bin/openresty
ss -lntp | grep 80

命令解释：
- -t：语法检查
- ss -lntp：确认监听端口

6. 版本管理与升级策略（含示例）#

并行安装与软链切换

# 假设已安装 1.25.3.2 与 1.21.4.1
sudo ln -sfn /opt/openresty/1.25.3.2 /opt/openresty/current

# 统一入口命令
/opt/openresty/current/bin/openresty -V

回滚示例

sudo ln -sfn /opt/openresty/1.21.4.1 /opt/openresty/current
/opt/openresty/current/bin/openresty -s reload

要点：配置目录与日志目录固定在 /data/openresty，升级不改动配置。

7. 常见编译问题与排查（含示例）#

问题 1：缺少依赖库

# 报错示例：
# ./configure: error: the HTTP rewrite module requires the PCRE library.

# 解决：
sudo yum install -y pcre pcre-devel

问题 2：模块冲突

# 报错示例：duplicate module "ngx_http_headers_more_filter_module"
# 解决：确保同一模块只添加一次，检查 configure 参数与模块列表
/opt/openresty/1.25.3.2/bin/openresty -V

问题 3：动态模块未加载

# 报错示例：
# [emerg] dlopen() "/opt/openresty/1.25.3.2/modules/ngx_http_echo_module.so" failed
# 解决：确认模块路径与 load_module 配置
ls /opt/openresty/1.25.3.2/modules/

8. 运维建议与自动化编译脚本（含示例）#

自动化编译脚本

#!/usr/bin/env bash
set -e

VER="1.25.3.2"
PREFIX="/opt/openresty/${VER}"
CONF="/data/openresty/conf/nginx.conf"

cd /opt/openresty/src
curl -O https://openresty.org/download/openresty-${VER}.tar.gz
tar -xzf openresty-${VER}.tar.gz
cd openresty-${VER}

./configure \
  --prefix=${PREFIX} \
  --conf-path=${CONF} \
  --pid-path=/data/openresty/logs/nginx.pid \
  --error-log-path=/data/openresty/logs/error.log \
  --http-log-path=/data/openresty/logs/access.log \
  --with-http_ssl_module \
  --with-stream

make -j$(nproc)
make install

预期效果：在 /opt/openresty/${VER} 生成可用二进制与模块。

练习#

  1. 使用源码方式编译 OpenResty，开启 --with-http_v2_module，并验证 openresty -V 输出包含该模块。
  2. 新增一个动态模块（如 echo 模块），编译并在 nginx.conf 中加载，访问 /hello 输出自定义文本。
  3. 模拟依赖缺失：卸载 pcre-devel 后重新执行 ./configure，记录报错并修复。