Debian 安装 OpenResty 详细教程

环境要求

项目	要求
操作系统	Debian 11 / Debian 12，推荐 Debian 12
架构	x86_64 / amd64
内存	>= 1 GB
权限	root 或具备 sudo 权限的用户
网络	能访问 OpenResty 官方软件源

本文以 Debian 12 为例。Debian 11 操作方式基本一致。

---

一、安装前检查

1.1 查看系统版本

cat /etc/os-release

正常会看到类似：

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
VERSION_CODENAME=bookworm

1.2 查看系统架构

dpkg --print-architecture

常见输出：

amd64

1.3 确认当前用户权限

如果当前是 root 用户，可以直接执行后续命令：

whoami

如果不是 root 用户，请在命令前加 sudo，或者切换 root：

su -

---

二、安装基础依赖

更新软件包索引：

apt update

安装 OpenResty 软件源需要用到的基础工具：

apt install -y curl gnupg2 ca-certificates lsb-release debian-archive-keyring

依赖说明：

软件包	作用
curl	下载 GPG Key 和软件源配置
gnupg2	处理 GPG 签名
ca-certificates	HTTPS 证书校验
lsb-release	获取 Debian 版本代号
debian-archive-keyring	Debian 官方仓库 Key

---

三、添加 OpenResty 官方 APT 源

3.1 创建 keyrings 目录

install -d -m 0755 /usr/share/keyrings

3.2 导入 OpenResty GPG Key

curl -fsSL https://openresty.org/package/pubkey.gpg \
  | gpg --dearmor -o /usr/share/keyrings/openresty.gpg

设置权限：

chmod 644 /usr/share/keyrings/openresty.gpg

3.3 添加 OpenResty Debian 软件源

echo "deb [signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/debian $(lsb_release -sc) openresty" \
  > /etc/apt/sources.list.d/openresty.list

查看是否写入成功：

cat /etc/apt/sources.list.d/openresty.list

Debian 12 正常应类似：

deb [signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/debian bookworm openresty

3.4 更新软件源

apt update

如果没有 GPG 或 404 报错，说明软件源添加成功。

---

四、安装 OpenResty

安装 OpenResty 主程序和常用工具：

apt install -y openresty openresty-resty openresty-opm

软件包说明：

包名	说明
openresty	OpenResty 核心程序，包含 Nginx 和 LuaJIT
openresty-resty	resty 命令行工具，可直接运行 Lua 脚本
openresty-opm	OpenResty 包管理器，用于安装 Lua 扩展包

---

五、确认安装结果

5.1 查看 OpenResty 版本

/usr/local/openresty/bin/openresty -v

示例输出：

nginx version: openresty/1.27.1.1

5.2 查看编译参数

/usr/local/openresty/bin/openresty -V

该命令可以查看 OpenResty 编译模块、OpenSSL 版本、LuaJIT 等信息。

5.3 查看安装目录

ls -lah /usr/local/openresty

常见目录结构如下：

/usr/local/openresty/
├── bin/
│   └── openresty
├── luajit/
├── lualib/
├── nginx/
│   ├── conf/
│   ├── html/
│   ├── logs/
│   └── sbin/
├── opm/
└── site/

---

六、OpenResty 目录说明

路径	说明
/usr/local/openresty/bin/openresty	OpenResty 启动命令
/usr/local/openresty/nginx/conf/nginx.conf	主配置文件
/usr/local/openresty/nginx/conf/conf.d/	推荐的站点配置目录，需要手动创建
/usr/local/openresty/nginx/html/	默认静态页面目录
/usr/local/openresty/nginx/logs/	默认日志目录
/usr/local/openresty/lualib/	OpenResty 内置 Lua 库
/usr/local/openresty/bin/resty	Lua 脚本运行工具
/usr/local/openresty/bin/opm	OpenResty 包管理器

---

七、基础配置

7.1 创建站点配置目录

OpenResty 默认配置中通常没有 conf.d 目录，建议手动创建：

mkdir -p /usr/local/openresty/nginx/conf/conf.d

7.2 备份主配置文件

修改前建议先备份：

cp /usr/local/openresty/nginx/conf/nginx.conf \
   /usr/local/openresty/nginx/conf/nginx.conf.bak.$(date +%F_%H%M%S)

7.3 修改主配置文件

编辑主配置文件：

vi /usr/local/openresty/nginx/conf/nginx.conf

在 http {} 块末尾、最后一个 } 之前添加：

include conf.d/*.conf;

示例结构如下：

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    # 引入站点配置
    include conf.d/*.conf;
}

---

八、创建测试站点

创建一个最小可用的 OpenResty 测试配置：

cat > /usr/local/openresty/nginx/conf/conf.d/default.conf << 'EOF'
server {
    listen 80;
    server_name _;

    access_log /usr/local/openresty/nginx/logs/default.access.log;
    error_log  /usr/local/openresty/nginx/logs/default.error.log;

    location / {
        default_type text/plain;
        content_by_lua_block {
            ngx.say("OpenResty is running on Debian.")
        }
    }

    location /health {
        default_type application/json;
        content_by_lua_block {
            ngx.say('{"status":"ok"}')
        }
    }
}
EOF

检查配置语法：

/usr/local/openresty/bin/openresty -t

正常输出类似：

nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful

---

九、启动 OpenResty 并设置开机自启

9.1 启动服务

systemctl start openresty

9.2 设置开机自启

systemctl enable openresty

9.3 查看服务状态

systemctl status openresty

正常状态应包含：

Active: active (running)

---

十、验证访问

10.1 本机验证

curl http://127.0.0.1

期望输出：

OpenResty is running on Debian.

验证健康检查接口：

curl http://127.0.0.1/health

期望输出：

{"status":"ok"}

10.2 查看监听端口

ss -tunlp | grep ':80'

应看到 OpenResty 或 nginx 进程监听 0.0.0.0:80。

10.3 浏览器访问

如果服务器 IP 是 192.168.1.100，浏览器访问：

http://192.168.1.100

---

十一、防火墙放行端口

Debian 常见防火墙可能是 ufw 或云服务器安全组。

11.1 ufw 放行 80 和 443

如果系统启用了 ufw：

ufw status

放行 HTTP / HTTPS：

ufw allow 80/tcp
ufw allow 443/tcp
ufw reload

11.2 云服务器安全组

如果部署在云服务器，还需要在云平台安全组中放行：

端口	协议	说明
80	TCP	HTTP
443	TCP	HTTPS

---

十二、配置反向代理示例

OpenResty 常用于代理云枢或其他后端服务。以下示例将所有请求代理到 127.0.0.1:8080。

cat > /usr/local/openresty/nginx/conf/conf.d/cloudpivot-proxy.conf << 'EOF'
upstream cloudpivot_backend {
    server 127.0.0.1:8080;
    keepalive 64;
}

server {
    listen 80;
    server_name example.com;

    client_max_body_size 200m;

    access_log /usr/local/openresty/nginx/logs/cloudpivot.access.log;
    error_log  /usr/local/openresty/nginx/logs/cloudpivot.error.log;

    location / {
        proxy_pass http://cloudpivot_backend;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}
EOF

检查配置并重载：

/usr/local/openresty/bin/openresty -t
systemctl reload openresty

注意：如果 default.conf 和 cloudpivot-proxy.conf 都监听 80 且都使用 _ 或相同域名，可能会产生默认站点冲突。生产环境建议删除测试配置或改成实际域名。

---

十三、配置 HTTPS 示例

如果已经有证书文件，例如：

/etc/ssl/cloudpivot/fullchain.pem
/etc/ssl/cloudpivot/privkey.pem

可以创建 HTTPS 配置：

cat > /usr/local/openresty/nginx/conf/conf.d/cloudpivot-https.conf << 'EOF'
upstream cloudpivot_backend {
    server 127.0.0.1:8080;
    keepalive 64;
}

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate     /etc/ssl/cloudpivot/fullchain.pem;
    ssl_certificate_key /etc/ssl/cloudpivot/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    client_max_body_size 200m;

    access_log /usr/local/openresty/nginx/logs/cloudpivot-https.access.log;
    error_log  /usr/local/openresty/nginx/logs/cloudpivot-https.error.log;

    location / {
        proxy_pass http://cloudpivot_backend;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_connect_timeout 60s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }
}
EOF

检查并重载：

/usr/local/openresty/bin/openresty -t
systemctl reload openresty

---

十四、常用管理命令

操作	命令
启动	systemctl start openresty
停止	systemctl stop openresty
重启	systemctl restart openresty
平滑重载	systemctl reload openresty
查看状态	systemctl status openresty
开机自启	systemctl enable openresty
取消自启	systemctl disable openresty
检查配置	/usr/local/openresty/bin/openresty -t
查看版本	/usr/local/openresty/bin/openresty -v

---

十五、日志查看

15.1 查看 systemd 服务日志

journalctl -u openresty -f

15.2 查看访问日志

tail -f /usr/local/openresty/nginx/logs/access.log

如果使用了本文的测试站点配置：

tail -f /usr/local/openresty/nginx/logs/default.access.log

15.3 查看错误日志

tail -f /usr/local/openresty/nginx/logs/error.log

如果使用了本文的测试站点配置：

tail -f /usr/local/openresty/nginx/logs/default.error.log

---

十六、Lua 功能验证

OpenResty 的核心能力是 Nginx + Lua。可以创建一个 Lua 测试接口：

cat > /usr/local/openresty/nginx/conf/conf.d/lua-test.conf << 'EOF'
server {
    listen 8081;
    server_name _;

    location /lua {
        default_type text/plain;
        content_by_lua_block {
            ngx.say("hello from lua")
            ngx.say("time: ", ngx.localtime())
        }
    }
}
EOF

检查并重载：

/usr/local/openresty/bin/openresty -t
systemctl reload openresty

访问验证：

curl http://127.0.0.1:8081/lua

期望输出：

hello from lua
time: 2026-xx-xx xx:xx:xx

---

十七、常见问题处理

17.1 apt update 提示 GPG 签名错误

错误类似：

The following signatures couldn't be verified because the public key is not available

处理方式：

rm -f /usr/share/keyrings/openresty.gpg
curl -fsSL https://openresty.org/package/pubkey.gpg \
  | gpg --dearmor -o /usr/share/keyrings/openresty.gpg
chmod 644 /usr/share/keyrings/openresty.gpg
apt update

17.2 apt update 提示仓库 404

先检查 Debian 版本代号：

lsb_release -sc

再检查源文件：

cat /etc/apt/sources.list.d/openresty.list

如果版本代号不正确，重新生成：

echo "deb [signed-by=/usr/share/keyrings/openresty.gpg] http://openresty.org/package/debian $(lsb_release -sc) openresty" \
  > /etc/apt/sources.list.d/openresty.list
apt update

17.3 80 端口被占用

查看占用端口的进程：

ss -tunlp | grep ':80'

如果是 Nginx 或 Apache 占用，可按实际情况停止：

systemctl stop nginx
systemctl disable nginx

或：

systemctl stop apache2
systemctl disable apache2

然后重新启动 OpenResty：

systemctl restart openresty

17.4 配置检查失败

执行：

/usr/local/openresty/bin/openresty -t

根据报错行号修改对应配置文件。常见问题包括：

• 少写分号 ;
• 花括号 {} 不匹配
• server_name 重复不是致命错误，但容易造成访问结果不符合预期
• 证书路径不存在
• 日志目录不存在或权限不足

17.5 浏览器无法访问

按顺序检查：

# 1. 服务是否运行
systemctl status openresty

# 2. 本机是否可访问
curl http://127.0.0.1

# 3. 是否监听 80
ss -tunlp | grep ':80'

# 4. 防火墙是否放行
ufw status

# 5. 云服务器安全组是否放行 80 / 443

---

十八、卸载 OpenResty

如果需要卸载 OpenResty：

systemctl stop openresty
systemctl disable openresty
apt remove -y openresty openresty-resty openresty-opm

如果确认不再需要配置和日志，可以删除安装目录：

rm -rf /usr/local/openresty
rm -f /etc/apt/sources.list.d/openresty.list
rm -f /usr/share/keyrings/openresty.gpg
apt update

注意：删除 /usr/local/openresty 会清理站点配置、日志和静态文件。生产环境请先备份。

---

十九、生产环境建议

1. 不要直接使用测试站点配置，生产环境请按实际域名配置 server_name。
2. 反向代理云枢时建议配置 client_max_body_size，避免附件上传失败。
3. 修改配置后先执行：

/usr/local/openresty/bin/openresty -t

4. 配置正确后再重载：

systemctl reload openresty

5. HTTPS 证书建议统一放在 /etc/ssl/业务名/ 或 /etc/letsencrypt/live/域名/。
6. 建议按站点拆分日志文件，方便排查问题。
7. 建议定期备份：

/usr/local/openresty/nginx/conf/
/usr/local/openresty/nginx/html/
/etc/ssl/

---

二十、安装完成检查清单

安装完成后建议逐项检查：

/usr/local/openresty/bin/openresty -v
/usr/local/openresty/bin/openresty -t
systemctl status openresty
curl http://127.0.0.1
curl http://127.0.0.1/health

如果以上命令均正常，说明 Debian OpenResty 安装完成。