openresty采坑笔记

2022年6月15日11:02:14

推荐一个博客：https://yxudong.github.io/categories/OpenResty/
因为lua和luajit差别有点大，想要写好高性能的luajit代码，需要非常多的经验

OpenResty 完全开发指南
https://wiki.shileizcc.com/confluence/pages/viewpage.action?pageId=47415930

openresty最佳实践
https://moonbingbing.gitbooks.io/openresty-best-practices/content/

openresty RHEL 安装

官方文档：http://openresty.org/cn/linux-packages.html#rhel

你可以在你的 RHEL 系统中添加 openresty 仓库，这样就可以便于未来安装或更新我们的软件包（通过 yum check-update 命令）。添加仓库，运行下面的命令（对于 RHEL 8 或以上版本，应将下面的 yum 都替换成 dnf）：

add the yum repo:

wget https://openresty.org/package/rhel/openresty.repo
sudo mv openresty.repo /etc/yum.repos.d/

update the yum index:

sudo yum check-update

添加了包仓库之后就可以像下面这样安装软件包，比如 openresty：

sudo yum install -y openresty

如果你想安装命令行工具 resty，那么可以像下面这样安装 openresty-resty 包：

sudo yum install -y openresty-resty

命令行工具 opm 在 openresty-opm 包里，而 restydoc 工具在 openresty-doc 包里头。

列出所有 openresty 仓库里头的软件包：

sudo yum --disablerepo="*" --enablerepo="openresty" list available

我们的包仓库中有某些包，比如 perl-Test-Nginx 和 perl-Lemplate，依赖开启一些可选的 RHEL 标准包仓库。比如 在 RHEL 6 和 RHEL 7 上，需要启用 RHEL 官方的 Optional RPM 包仓库。在 RHEL 7 上可以运行这条命令：

sudo subscription-manager repos --enable rhel-7-server-optional-rpms

在 RHEL 6 上则是这样的：

sudo subscription-manager repos --enable rhel-6-server-optional-rpms

而在 RHEL 8 上则需要开启 RHEL 官方的 CodeReady 仓库：

sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms

安装opm

yum install openresty-opm

opm官网
https://opm.openresty.org/

在 OpenResty RPM 包 页面能看到这些包更多的细节。

请注意在 RHEL 8 上面缺少 perl-Lemplate 这个 RPM 包，这是因为 RHEL 8 相比 RHEL 7 从其标准仓库中移除了 perl-Template-Toolkit 这样的 Perl 模块包。

对于 RHEL 8 及更新版本，我们只需要将上面的 yum 命令都替换成 dnf 即可。

项目目录

drwxr-xr-x.  2 root root    123 Jun  8 18:18 bin                    可执行文件目录
-rw-r--r--.  1 root root  22924 May 18 03:15 COPYRIGHT
drwxr-xr-x.  6 root root     56 Jun  8 17:59 luajit                 luajit目录
drwxr-xr-x.  5 root root    105 Jun  8 17:59 lualib                 lua的引用库目录
drwxr-xr-x. 11 root root    151 Jun  8 18:00 nginx                   nginx目录
drwxr-xr-x.  4 root root     28 Jun  8 17:59 openssl111              openssl目录
drwxr-xr-x.  3 root root     17 Jun  8 17:59 pcre                    Perl的库
drwxr-xr-x. 47 root root   4096 Jun  8 18:18 pod                     基本是一些文档
-rw-r--r--.  1 root root 235463 May 18 03:15 resty.index
drwxr-xr-x.  5 root root     66 Jun  8 18:38 site
drwxr-xr-x.  3 root root     17 Jun  8 17:59 zlib                      zlib库

更重要的是bin目录下的一些东西

-rwxr-xr-x. 1 root root 19185 May 18 03:15 md2pod.pl
-rwxr-xr-x. 1 root root 15994 May 18 03:15 nginx-xml2pod
lrwxrwxrwx. 1 root root    37 Jun  8 17:59 openresty -> /usr/local/openresty/nginx/sbin/nginx      nginx可执行文件
-rwxr-xr-x. 1 root root 63510 May 18 03:15 opm                                                     包管理工具opm
-rwxr-xr-x. 1 root root 36623 May 18 03:15 resty                                                   OpenResty CLI的命令行
-rwxr-xr-x. 1 root root 14957 May 18 03:15 restydoc                                                文档查看工具，就是看pod里面的 这个很重要，开发的时候全靠这个
-rwxr-xr-x. 1 root root  8873 May 18 03:15 restydoc-index                                           文档索引

OpenResty 附带了非常完善的用户参考手册 restydoc，提供与 UNIX 手册 man 相同的功能，可以检索 OpenResty 里所有组件的帮助文档，包括但不限于：

    OpenResty 各个组件的介绍和用法；
    OpenResty 指令和功能接口的用法；
    Nginx 介绍、用法、基本工作原理；
    Lua/LuaJIT 语法要素。

下面示范了一些 restydoc 的用法，其中的 “-s” 参数用来指定搜索手册里的小节名：
# Nginx 的说明
$ /usr/local/openresty/bin/restydoc nginx
# LuaJIT 的说明
$ /usr/local/openresty/bin/restydoc luajit
# 包管理工具 opm 说明
$ /usr/local/openresty/bin/restydoc opm
# 命令行工具 resty 的说明
$ /usr/local/openresty/bin/restydoc resty-cli
# ngx_echo 组件的说明
$ /usr/local/openresty/bin/restydoc ngx_echo
# ngx_lua 的说明
$ /usr/local/openresty/bin/restydoc ngx_lua
#  stream_lua 说明
$ /usr/local/openresty/bin/restydoc stream_lua
# lua-cjson 说明
$ /usr/local/openresty/bin/restydoc lua-cjson
# 反向代理指令 proxy_pass 的说明
$ /usr/local/openresty/bin/restydoc -s proxy_pass
# content_by_lua_block 指令的说明
$ /usr/local/openresty/bin/restydoc -s content_by_lua_block
# 功能接口 ngx.say 的说明
$ /usr/local/openresty/bin/restydoc -s ngx.say
# lua 函数 concat 的说明
$ /usr/local/openresty/bin/restydoc -s concat

对于使用 opm 安装的组件，需要使用 “-r” 参数指定安装目录，例如：
$ /usr/local/openresty/bin/restydoc -r /usr/local/openresty/site -s lua-resty-http


OpenResty 命令行工具

OpenResty 在 bin 目录下提供一个命令行工具 resty（注意命令不是 resty-cli）。可以把它作为 Lua 语言的解释器（但运行在 OpenResty 环境里）代替标准的 Lua 5.x，写出类似 Perl、Python 那样易用的脚本，是测试/运维工程师的利器。

resty 的工作原理是启动了一个 “无服务” 的 Nginx 示例，禁用了 daemn 等大多数指令，也没有配置监听端口，只是在 worker 集成里用定时器让 Lua 代码在 Nginx 里执行。

使用 “-e” 参数可以在命令行里直接执行 Lua 代码，例如：
$ resty -e "print('hello OpenResty')"
hello OpenResty

这种方式只适合执行很小的代码片段，更好的方式是利用 UNIX 的 “Shebang” (#!)，在脚本文件里的一行指定 resty 作为解释器，能够书写任意长度和复杂度的代码，而且更利于管理维护。

刚才的命令行用法可以改成写成下面的脚本文件：
hello.lua
#!/usr/local/openresty/bin/resty
 
local n = #arg
print("args count = ", n)
 
for i = i,n do
    print("arg ", i , ": ", arg[i])
end

使用参数执行脚本 hello.lua 结果是：
$ chmod +x hello.lua
$ ./hello.lua FireEmblem Heroes

resty 工具还有很多选项用于配置行为，非常灵活，“-e” 之外较常用的有：

    -c：指定最大并发连接数（默认值是 64）；
    -I：指定 Lua 库的搜索路径；
    -l：指定加载某个 Lua 库；
    --http-conf：定制在 http 域里的指令；
    --main-include：定制在 main 域里的指令；
    --shdict：定制使用的共享内存。
    --resolve-upv6：允许解析 ipv6 的地址。
	
	
	OpenResty 变量

"变量" 是 Nginx 内部保存的运行时 HTTP/TCP 请求相关数据，可以在编写配置文件时任意引用，使得编写 Nginx 配置文件更像编写程序（但注意不要与编程语言里的变量概念混淆，两者是完全不同的）。

在配置文件里使用变量需要以 “$” 开头，例如 $request_method、$args、$uri 等（这与 Shell 和 Perl 是一样的）。变量的用法很多，例如记录访问日志，设置反向代理的参数，或者传递给 Lua 程序获取各种运行时信息。

    $uri：当前请求的 URI，但不包含 “?” 后的参数。
    $args：当前请求的参数，及 “?” 后的字符串。
    $arg_xxx：当前请求里的某个参数，“arg_” 后就是参数名。
    $http_xxx：当前请求里的 xxx 头部对应的值。
    $sent_http_xxx：返回给客户端的相应头部对应的值。
    $remote_addr：客户端 IP 地址。

如果执行下面的 curl 命令：
$ curl 'http://localhost/index.html?a=1&b=2' -H 'hello: world'

变量对应的值为：
$uri = /index.html
$args = a=1&b=2
$arg_a = 1
$arg_b = 2
$http_hello = world
$sent_http_server = openresty/1.13.6.2
$remote_addr = 127.0.0.1

Nginx 内置的变量非常多，详细的列表可以参考官方文档。此外，Nginx 也允许使用指令自定义变量，最常用的就是 Set，例如：
set $max_size 10000;  # 定义变量 $max_size="10000"


OpenResty 组件管理工具

很多开发语言/环境都会提供配套的包管理工具，例如 npm/Node.js、cpan/Perl、gem/Ruby 等，它们可以方便地安装功能组件，辅助用户的开发工作，节约用户的时间和经理。OpenResty 也有功能类似的工具，名叫 opm。

OpenResty 维护一个官方组件库（opm.openresty.org）,opm 就是库的客户端，可以把组件库里的组件下载到本地，并管理本地的组件列表。

opm 的用法很简单，常用的命令有：

    search：以关键字搜索关键的组件。
    get：安装功能组件（注意不是 install）。
    info：显示已安装组件的详细信息。
    list：列出所有本地已经安装的组件。
    upgrad：更新某个已安装组件。
    update：更新所有已安装组件。
    remove：移除某个已安装组件。

opm 默认的操作目录是 “/usr/local/openresty/site”，但是也可以在命令行参数 “--install-dir=PATH” 安装到其他目录，或者用参数 “–cwd” 安装到当前目录的 "./resty_module/" 目录里。

下面的命令示范了 opm 的部分用法：
# 搜索关键字 http
$ opm search http
openresty/lua-resty-upload                        Streaming reader and parser for HTTP file uploading based on ngx_lua cosocket
dailymotion/lua-nginx-guard-jwt                   Map JWT claims values to HTTP Headers request. Could specify a custom mapping.
mycsj/lua-resty-rx-test                           Yet Another HTTP library for OpenResty
tokers/lua-resty-requests                         Yet Another HTTP library for OpenResty
bungle/lua-resty-reqargs                          HTTP Request Arguments and File Uploads Helper
fffonion/lua-resty-shdict-server                  A HTTP and Redis protocol compatible interface for debugging ngx.shared API
hamishforbes/lua-resty-consul                     Library to interface with the consul HTTP API
hamishforbes/ledge                                An RFC compliant and ESI capable HTTP cache for Nginx / OpenResty, backed by Redis
lilien1010/lua-resty-s3uploader                   an http s3 client for openresty
antonheryanto/lua-resty-post                      Openresty utility for parsing HTTP POST data
duhoobo/lua-resty-smtp                            A http to smtp bridge library for the ngx_lua module
duhoobo/lua-resty-auth                            A Lua resty module for HTTP Authentication (both basic and digest scheme supported, referring to RFC 2617)
p0pr0ck5/lua-resty-cookie                         Lua library for HTTP cookie manipulations for OpenResty/ngx_lua
pintsized/lua-resty-http                          Lua HTTP client cosocket driver for OpenResty/ngx_lua
agentzh/lua-resty-http                            Lua HTTP client cosocket driver for OpenResty/ngx_lua
# 搜索关键字 kafka
$ opm search kafka
doujiang24/lua-resty-kafka                        Lua kafka client driver for the Openresty based on the cosocket API
# 安装组件，注意需要 sudo
$ opm get agentzh/lua-resty-http
* Fetching agentzh/lua-resty-http
  Downloading https://opm.openresty.org/api/pkg/tarball/agentzh/lua-resty-http-0.09.opm.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 16385  100 16385    0     0  39111      0 --:--:-- --:--:-- --:--:-- 39105
Package agentzh/lua-resty-http 0.09 installed successfully under /usr/local/openresty/site/ .
# 显示组件的版本，作者等信息。
$ opm info agentzh/lua-resty-http
Name             : lua-resty-http
Version          : 0.09
Abstract         : Lua HTTP client cosocket driver for OpenResty/ngx_lua
Author           : James Hurst
Account          : agentzh
Code Repo        : https://github.com/agentzh/lua-resty-http/tree/agentzh
License          : BSD 2-Clause "Simplified" or "FreeBSD" license
Original Work    : no
# 移除组件，同样需要 sudo
$ opm remove  agentzh/lua-resty-http
Package agentzh/lua-resty-http 0.09 removed successfully.

安装组件：
$ opm --install-dir=/opt get xxx
$ opm --cwd get xxx

需要注意的是 opm 里组件的名字，使用的是类似 GitHub 的格式，即 “作者名/组件名”，允许一个组件有多个不同的作者和版本，方便组件开发者 “百家争鸣”，由客户来评估决定使用哪一个。

由于 opm 在 OpenResty 里出现的较晚（2016年），目前库里可用的组件还不多，希望假以时日能够丰富壮大。

设置package包的搜索路径

package.path = '/usr/local/share/lua/5.1/?.lua;/usr/local/openresty/lualib/resty/?.lua;/usr/local/openresty/lualib/?.lua;'
package.cpath = '/usr/local/lib/lua/5.1/?.so;'
local cjson = require "cjson"

lua_package_path "lua/?.lua;app/?.lua";
lua_code_cache off;
-- 打印目前的包搜索的路径
ngx.say(package.path)

打印结果
/usr/local/openresty/site/lualib/?.ljbc;/usr/local/openresty/site/lualib/?/init.ljbc;/usr/local/openresty/lualib/?.ljbc;/usr/local/openresty/lualib/?/init.ljbc;/usr/local/openresty/site/lualib/?.lua;/usr/local/openresty/site/lualib/?/init.lua;/usr/local/openresty/lualib/?.lua;/usr/local/openresty/lualib/?/init.lua;./?.lua;/usr/local/openresty/luajit/share/luajit-2.1.0-beta3/?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/openresty/luajit/share/lua/5.1/?.lua;/usr/local/openresty/luajit/share/lua/5.1/?/init.lua

把prel的 pod文档文件转成html

 C:\Strawberry\perl\bin> .\pod2html.bat D:\openresty\pod\lua-5.1.5\lua-5.1.5.pod > D:\openresty\pod\lua-5.1.5\lua-5.1.5.html

可以直接转成html

openresty的注释

lua的注释是 // /**/ #

openresty 的注释

--