2022年1月11日13:57:45
官方:https://opm.openresty.org/
官方文档:https://opm.openresty.org/docs#table-of-contents
为什么建议使用opm不建议使用luarocks?
http://openresty.org/cn/using-luarocks.html
官方解释:请注意!LuaRocks 并不是 OpenResty 官方推荐的装包方式。LuaRocks 上绝大部分的 Lua 库都可能会阻塞 OpenResty 的事件循环,而让性能急剧下降。推荐使用 OPM。
非常推荐一个本书 如果你要学习openresty 《openresty最佳实践》 https://moonbingbing.gitbooks.io/openresty-best-practices/content/
目录:
- 名称
- 状态
- 概要
- 描述
- 用法
- 安全安装
- 本地安装
- HTTP 代理支持
- 作者工作流程
- dist.ini 文件
- name
- abstract
- version
- author
- license
- requires
- repo_link
- is_original
- lib_dir
- exclude_files
- main_module
- doc_dir
- File .opmrc文件
- github_account
- github_token
- upload_server
- download_server
- 版本号处理
- 安装
- For opm
- 安全注意事项
- 信用
- 待完成
- 作者
- 版权和许可
状态
实验性的.
概要
对于库的用户:
# 显示用法
opm --help
# 使用用户模式“lock”搜索包名称和摘要。
opm search lock
# 使用多种模式“lru”和“cache”搜索包名称和摘要。
opm search lru cache
# 在 some_author 的名称下安装一个名为 lua-resty-foo 的包
opm get some_author/lua-resty-foo
# 获取所有作者下的 lua-resty-foo 包列表。
opm get lua-resty-foo
# 显示由名称指定的已安装包的详细信息。
opm info lua-resty-foo
# 显示所有已安装的软件包。
opm list
# 升级包 lua-resty-foo 到最新版本。
opm upgrade lua-resty-foo
# 将所有已安装的软件包更新到最新版本。
opm update
# 卸载新安装的包
opm remove lua-resty-foo
所有命令都可以跟随 --cwd 选项在当前工作目录(在 ./resty/modules/ 下)而不是系统范围的位置工作。
# 安装到 ./resty_modules/ 而不是系统范围的位置:
opm --cwd get foo/lua-resty-bar
# 检查 ./resty_modules/ 下本地安装的包
opm --cwd list
# 删除 ./resty_modules/ 下本地安装的包
opm --cwd remove lua-resty-bar
对于库的作者:
cd /path/to/lua-resty-foo/
opm build
# optional:
# cd lua-resty-foo-VERSION/ && opm server-build
# 您可能需要编辑 ~/.opmrc 文件来设置您的 github
# 个人访问令牌。 “opm upload”的第一次运行将创建
# 为您提供样板文件 ~/.opmrc 文件。
opm upload
# 清理 opm build 命令的剩余部分。
opm clean dist
描述
opm 是官方的 OpenResty 包管理器,原理上类似于 Perl 的 CPAN 和 NodeJS 的 npm。
我们在此 GitHub 代码存储库中为中央包存储库提供 opm 客户端命令行实用程序和服务器端应用程序。
OpenResty 用户可以使用 opm 命令行实用程序下载在中央 opm 服务器(即 opm.openresty.org)上发布的包。 它还可以用于打包 OpenResty 包并将其上传到服务器,以供包作者和维护者使用。 您可以在 bin/ 目录下找到 opm 的来源。 它目前被实现为独立的 Perl 脚本。
服务器端 Web 应用程序基于 OpenResty 构建并用 Lua 编写。 您可以在 web/ 目录下找到服务器代码。
与许多其他包管理系统(如 cpan、luarocks、npm 或 pip)不同。 我们的 opm 采用了类似于 github 的包命名规则,即每个包名都应该由一个发布者 ID 限定,如 agentzh/lua-resty-foo 其中 agentzh 是发布者 ID 而 lua-resty-foo 是包名 本身。 这种命名要求避免了占用好包名的诱惑,也允许多个同名库共存于同一个中央服务器存储库中。 由用户决定安装哪个库(甚至在她的不同项目中安装同一库的多个分支)。 为简单起见,我们只是将 GitHub 用户 ID 和组织 ID 映射到 opm 的发布者 ID。 出于这个原因,我们使用 GitHub 个人访问令牌(或 oauth 令牌)来验证我们的包发布者。 这也完全消除了 opm 包作者的注册过程。
opm 内置了对 restydoc 工具的支持,即通过 opm 安装的包的文档已经被 restydoc 索引,可以直接在终端上用 restydoc 工具查看。
opm 目前只支持纯 Lua 库,但我们将很快添加对纯 C 或一些 C 组件的 Lua 库的支持。 未来还希望通过 opm 添加对将 3rd-party NGINX C 模块重新分发为动态 NGINX 模块的支持。 OpenResty 世界毕竟由各种不同类型的“模块”组成。
我们还计划允许用户通过特殊用户 ID luarocks 通过 opm 安装 LuaRocks 包。 安装一个与 OpenResty 无关的 Lua 模块会带来风险,该模块会在网络 I/O 上严重阻塞 NGINX 工作进程,但是,作为 opm 的开发人员,我们总是喜欢选择,尤其是那些给我们用户的选择。
Back to TOC
用法
opm [options] command package...
Options:
-h --help 打印此帮助。
--install-dir =PATH 安装到指定的 PATH 目录而不是系统范围内包含此工具的 OpenResty 安装树。
--cwd 安装到 ./resty_modules/ 下的当前工作目录,而不是包含在系统范围内的OpenResty 安装树这个工具。
Commands:
build 从当前工作目录构建一个包 tarball,准备上传到服务器。
clean ARGUMENT ... 做清理工作。目前有效的参数是“dist”,它清理“build”命令创建的临时文件和目录。
info PACKAGE ... 输出指定的详细信息(或元数据)包。像“lua-resty-lock”这样的短包名是可以接受的。
get PACKAGE ... 获取并安装指定的包。完全合格的包装像“openresty/lua-resty-lock”这样的名字是必需的。一个还可以指定版本约束,如“=0.05”和“>=0.01”。
list 列出所有已安装的软件包。包名称和版本被显示。
remove PACKAGE ... 删除(或卸载)指定的包。短包名称像“lua-resty-lock”是可以接受的。
search QUERY ... 在服务器上搜索匹配用户查询的包名称或摘要。可以指定多个查询,并且它们必须同时实现。
server -build 构建最终的包 tarball,准备在服务器上分发。这个命令一般是服务器用来验证上传的包压缩包。
update 将所有已安装的软件包更新到最新版本服务器。
upgrade PACKAGE ... 将名称指定的包升级到最新版本服务器。像“lua-resty-lock”这样的短包名是可以接受的。
upload 将包 tarball 上传到服务器。该命令总是调用在上传之前自动生成命令。
全局安装
要全局安装 opm 包,只需使用 sudo opm get foo/bar 命令。
Back to TOC
本地安装
当您使用 --cwd 选项将软件包安装到 ./resty_modules/ 目录时,您应该将以下行放入您的 nginx.conf 中的 http {} 块内:
lua_package_path "$prefix/resty_modules/lualib/?.lua;;";
lua_package_cpath "$prefix/resty_modules/lualib/?.so;;";
不要自己将 $prefix 更改为硬编码的绝对路径! OpenResty 将在启动时自动解析指令值中的特殊 $prefix 变量。 $prefix 值将被解析为服务器前缀,稍后将通过 openresty 命令行的 -p 选项指定。
然后你应该像这样从当前工作目录启动你的 OpenResty 应用程序:
openresty -p $PWD/
假设您在当前目录中有以下 OpenResty 应用程序目录布局:
logs/
conf/
conf/nginx.conf
resty_modules/
或者,如果您只想使用安装在 ./resty_modules 目录中的 opm 模块的 resty 命令行实用程序,那么您应该只使用 -I ./resty_modules/lualib 选项,如
resty -I ./resty_modules/lualib -e 'require "foo.bar".go()'
Back to TOC
HTTP 代理支持
通过 http_proxy 和 https_proxy 系统环境变量支持 HTTP 代理,如
http_proxy [protocol://]<host>[:port]
Sets the proxy server to use for HTTP.
https_proxy [protocol://]<host>[:port]
Sets the proxy server to use for HTTPS.
Back to TOC
作者工作流程
包作者应该在 Lua 库源代码树的顶层放置一个名为 dist.ini 的元数据文件。 opm build 命令使用此文件来构建库并将其打包成一个 tarball 文件,该文件可以稍后通过 opm upload 命令上传到中央包服务器。
对于 OpenResty 的 lua-resty-core 库,一个示例 dist.ini 文件如下所示:
# opm 打包的分发配置
name = lua-resty-core
abstract = New FFI-based Lua API for the ngx_lua module
author = Yichun "agentzh" Zhang (agentzh)
is_original = yes
license = 2bsd
lib_dir = lib
doc_dir = lib
repo_link = https://github.com/openresty/lua-resty-core
main_module = lib/resty/core/base.lua
requires = luajit, openresty/lua-resty-lrucache >= 0.04
正如我们所见,dist.ini 文件使用流行的 INI 文件格式。 此示例中的大多数字段应该是不言自明的。 有关 dist.ini 中可用字段的详细文档,请查看文件 dist.ini 部分。
opm build 命令还从当前系统用户的主目录(即文件路径 ~/.opmrc)下的配置文件 .opmrc 中读取并提取信息。 如果该文件不存在, opm build 将自动在该路径中生成一个样板文件。 一个示例 ~/.opmrc 文件如下所示。
# 您的 github 帐户名(您拥有的 github 组织的 github 用户名)
github_account=agentzh
# 您可以从 Web UI 生成 github 个人访问令牌:https://github.com/settings/tokens
# 重要的! 您需要将范围“user:email”和“read:org”分配给您的 github 令牌。
# 出于安全考虑,您不应将任何其他范围分配给您的令牌。
github_token=0123456789abcdef0123456789abcdef01234567
# the opm central servers for uploading openresty packages.
upload_server=https://opm.openresty.org
download_server=https://opm.openresty.org
基本上, opm build 命令只需要此文件中的 github_account 设置。尝试将打包的 tarball 上传到远程包服务器的 opm upload 命令需要其他字段。您可以使用自己的 GitHub 登录名(在本例中为 agentzh),也可以使用您拥有的 GitHub 组织名称(即拥有管理员权限)。
opm build 成功在当前工作目录下生成一个.tar.gz 文件后,作者可以使用opm upload 命令将该文件上传到远程服务器。为确保一致性,opm upload 在尝试上传操作之前自动运行 opm build 本身。中央包服务器(本例中为 opm.openresty.org)在后台调用 GitHub API 来验证作者的身份。因此,作者需要在她的 ~/.opmrc 文件中提供他的 GitHub 个人访问令牌。只有 user:email 和 read:org 权限(或 GitHub 术语中的范围)需要分配给这个访问令牌。
Back to TOC
dist.ini 文件
dist.ini 文件指定了包的元数据,并被 opm build 用来生成准备上传到远程包服务器的 tarball。 该文件应位于库或模块源代码树的顶部。
此文件使用 INI 文件格式。 它在默认顶级部分中包含以下键(或属性):
Back to TOC
name
指定包的名称(不包括版本号)。 例如,
name = lua-resty-limit-traffic
名称只能包含字母、数字和短划线 (-)。
此key是强制性的。
Back to TOC
abstract
当前包的摘要。
abstract = New FFI-based Lua API for the ngx_lua module
您可以在此字段值中使用 UTF-8 字符。 但是,无效的 UTF-8 序列会导致 opm build 或 opm server-build 命令出错。
此key是强制性的。
Back to TOC
version
当前包的版本号。
如果指定了这个键,那么这里指定的版本号将自动与从“主模块”文件中提取的版本号进行比较(更多详细信息请参见 main_module 键)。
Example:
version = 1.0.2
有关软件包版本号的更多详细信息,另请参阅版本号处理部分。
该键是可选的。
Back to TOC
author
指定库的一位或多位作者。 例如,
author = Yichun Zhang (agentzh)
多个作者的姓名应以逗号分隔,并带有可选的空格。
author = Yichun Zhang (agentzh), Dejiang Zhu
您可以在此字段值中使用 UTF-8 字符。 但是,无效的 UTF-8 序列会导致 opm build 或 opm server-build 命令出错。
此key是强制性的。
Back to TOC
许可证 (不翻译)
Specifies the license for the library. For example,
license = 3bsd
This assigns the 3-clause BSD license to the current package.
Special IDs for common code licenses are required. For now, the following IDs are supported:
2bsd
BSD 2-Clause "Simplified" or "FreeBSD" license
3bsd
BSD 3-Clause "New" or "Revised" license
apache2
Apache License 2.0
artistic
Artistic License
artistic2
Artistic License 2.0
ccby
Creative Commons Attribution 4.0 International Public License
ccbysa
Creative Commons Attribution-ShareAlike 4.0 International Public License
ccbynd
Creative Commons Attribution-NoDerivatives 4.0 International Public License
ccbync
Creative Commons Attribution-NonCommercial 4.0 International Public License
ccbyncsa
Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
ccbyncnd
Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License
cddl
Common Development and Distribution License
eclipse
Eclipse Public License
gpl
GNU General Public License (GPL)
gpl2
GNU General Public License (GPL) version 2
gpl3
GNU General Public License (GPL) version 3
lgpl
GNU Library or "Lesser" General Public License (LGPL)
mit
MIT license
mozilla2
Mozilla Public License 2.0
proprietary
Proprietary
public
Public Domain
如果您确实需要上面未列出的开源许可证,请告诉我们。
也可以同时指定多个许可证,如
license = gpl2, artistic2
这指定了双重许可:GPLv2 和 Artistic 2.0。
要将包上传到官方的opm包服务器,您至少必须在此处指定一个开源许可。
This key is mandatory.
Back to TOC
依赖
指定此包的运行时依赖项。
多个依赖项用逗号分隔,周围有可选的空格。 如在
requires = foo/lua-resty-bar, baz/lua-resty-blah
在运行 opm get 或 opm build 命令时,必须同时满足此键中指定的所有依赖项约束。
您还可以指定版本号要求,如
requires = foo/lua-resty-bar >= 0.3.5
支持的版本比较运算符是 >=、= 和 >。 它们的语义是不言自明的。
您还可以指定以下特殊依赖项名称:
luajit
需要包用户的 OpenResty 安装(以及包上传器)中的 LuaJIT 组件。 当指定版本号约束时,也会检查 LuaJIT 的版本号。
nginx
需要包用户的 OpenResty 安装(以及包上传器)中的 NGINX 组件。 当指定版本号约束时,也会检查 NGINX 内核的版本号。
openresty
仅当指定了关联的版本号约束时,此依赖关系才有意义。 包用户(以及上传者)的 OpenResty 安装的版本号必须满足这里的版本约束。
ngx_http_lua
需要包用户的 OpenResty 安装(以及包上传者的)中的 ngx_http_lua_module 组件。 当指定版本号约束时,安装的 ngx_http_lua_module 的版本也会被检查。
下面是这样一个例子:
requires = luajit >= 2.1.0, nginx >= 1.11.2, ngx_http_lua = 0.10.6
或者您可以在上面的示例中只指定一个 openresty 版本约束来覆盖它们:
requires = openresty >= 1.11.2.1
该键是可选的。
Back to TOC
repo_link
代码存储库的 URL(通常在 GitHub 上)。 例如,
repo_link = https://github.com/openresty/lua-resty-core
如果存储库位于 GitHub 上,则 opm build 确保在 ~/.opmrc 文件中的 github_account 中指定的名称与 GitHub 存储库 URL 中的帐户匹配。 否则 opm build 会报错。
此key是强制性的。
Back to TOC
is_original
取值 yes or no 来指定此包是否为原创作品(即,不是其他人的另一个包的分支)。
此key是强制性的。
Back to TOC
lib_dir
指定库文件(例如 .lua 文件)的根目录。
不得使用绝对目录路径或包含 .. 作为值的路径。
默认为库。
该键是可选的。
Back to TOC
exclude_files
通过 opm bulid 指定要在打包期间排除的文件的模式。 Unix shell 通配符,如 * 和 ? 支持。
多个模式应该用逗号分隔,周围有可选的空格。
exclude_files=foo*.lua, bar/baz/*/*.lua, lint_config.lua
Back to TOC
main_module
此项指定当前包的“主模块”文件的 PATH。 例如,opm build 命令读取“主模块”文件以提取当前包的版本号。
opm build 使用简单的正则表达式来查找 Lua 代码模式,如下所示:
_VERSION = '1.0.2'
version = "0.5"
version = 0.08
如果未指定此键,则 opm build 将尝试自动查找主模块文件(尽管这可能是错误的)。
您不得使用绝对文件路径或包含 .. 作为值的路径。
This key is optional.
Back to TOC
doc_dir
指定文档文件的根目录。 默认为库。
不得使用绝对目录路径或包含 .. 作为值的路径。
opm build 总是尝试以 Markdown(.md 或 .markdown)或 POD(.pod)格式收集文档文件。
不管这个 doc_dir 键的值是什么, opm build 总是尝试在当前工作目录(应该是当前包的根目录)中收集以下文件:
README.md
,README.markdown
, orREADME.pod
COPYING
COPYRIGHT
Changes.md
,Changes.markdown
, orChanges.pod
您可以在这些文档文件中使用 UTF-8 字符。 必须避免使用其他多字节字符编码。
This key is optional.
Back to TOC
.opmrc 文件
当前系统用户主目录下的 .opmrc 文件为当前系统用户配置各种重要设置。 只有库作者才应该关心这个文件,因为像 opm get、opm search 或 opm list 这样的命令根本不需要这个文件。
与文件 dist-ini 一样,该文件也是 INI 文件格式。 当此文件不存在时,第一次运行 opm build 或 opm upload 命令会自动生成一个样板文件供您以后自己填写。
该文件识别以下键:
Back to TOC
github_account
指定您的 GitHub 帐户名称,您的 GitHub 用户登录名或您拥有的 github 组织。
例如,文档作者的 GitHub 登录名是 agentzh,同时他还拥有 GitHub 组织 openresty。 因此,他可以通过配置此 github_account 密钥,选择使用相同的 GitHub 访问令牌(通过 github_token 密钥定义)在 agentzh 或 openresty 下上传他的包。
This key is required.
Back to TOC
github_token
指定用于包上传的 GitHub 个人访问令牌。
您可以从 GitHub Web UI 生成 GitHub 个人访问令牌。
当您在 GitHub 的网站上生成令牌时,为您的令牌分配正确的权限(或 GitHub 术语中的范围)至关重要。 opm 工具链要求令牌必须包含 user:email 范围。或者,您还可以同时分配 read:org 范围,如果您想以您拥有的组织名称上传 OpenResty 包,则需要这样做。
GitHub 个人访问令牌就像密码一样,因此在处理时要非常小心。永远不要与世界其他地方共享它,否则任何人都可以将包上传到您名下的 OPM 包服务器。
出于安全考虑,包服务器还拒绝过于宽松的 GitHub 个人访问令牌(即,具有比需要更多的范围)。包服务器在自己的数据库中缓存您的令牌的排序哈希,以便服务器在后续上传时不必查询 GitHub。因为令牌是散列的,所以包服务器只能验证您的令牌是否正确,但不能仅从数据库中恢复您的原始令牌。
This key is required.
Back to TOC
upload_server
指定上传包的 OPM 服务器。 默认为 https://opm.openresty.org。 强烈建议使用 https(这是默认设置)来保护通信隐私。
官方的 OPM 包服务器是 https://opm.openresty.org。 但是,您可以将此密钥指向您自己的或任何 第三方服务器(然后您需要自担风险)。
此键可以具有与 download_server 不同的值。
Back to TOC
download_server
指定下载包的 OPM 服务器。 默认为 https://opm.openresty.org。 强烈建议使用 https(这是默认设置)来保护通信隐私。
官方的 OPM 包服务器是 https://opm.openresty.org。 但是,您可以将此密钥指向您自己的或任何 第三方服务器(然后您需要自担风险)。
该键的值可以与upload_server 不同。
Back to TOC
Version Number Handling
OPM 要求所有包版本号仅由数字、点、字母和下划线组成。 只有数字部分是强制性的。
OPM 将所有版本号视为一个或多个由点 (.) 或任何其他非数字字符分隔的整数。 版本号比较是通过按出现的顺序比较每个整数部分来执行的。 例如,以下版本号比较成立:
12 > 10
1.0.3 > 1.0.2
1.1.0 > 1.0.9
0.10.0 > 0.9.2
当您的版本号看起来像十进制数字时,可能会出现一些意外,例如
0.1 < 0.02
这是因为 0.1 被解析为整数对 {0, 1},而 0.02 被解析为 {0, 2},所以后者大于前者。 为避免此类陷阱,请始终指定等长的小数部分,即,将 0.1 写为 0.10,与 0.02 的长度相同。
OPM 尚不支持“候选版本”(RC)或“开发者版本”等特殊版本。 但我们将来可能会增加这样的支持。 为了向前兼容,包作者应避免使用 _2 或 rc1 等后缀的版本号。
Back to TOC
安装
For opm
从 1.11.2.2 开始的 OpenResty 版本已经默认包含并安装了 opm。 所以通常你不需要自己安装opm。
值得注意的是,如果你使用的是官方的 OpenResty 预构建的 linux 包,你应该安装 openresty-opm 包,因为 openresty 二进制包本身不包含 opm。
如果你真的想在代码库中更新到最新版本的 opm,那么只需将存储库中的文件 bin/opm 复制到 <openresty-prefix>/bin/ 其中 <openresty-prefix> 是值 - 构建 OpenResty 时 ./configure 的 -prefix 选项(默认为 /usr/local/openresty/)。
# <openresty-prefix> defaults to `/usr/local/openresty/`
# unless you override it when building OpenResty yourself.
sudo cp bin/opm <openresty-prefix>/bin/
如果您使用的是默认不包含 opm 的旧版本 OpenResty,那么您还应该创建以下目录:
cd <openresty-prefix>
sudo mkdir -p site/lualib site/manifest site/pod
请注意,至少需要 OpenResty 1.11.2.1 才能使 opm 正常工作。
要运行 opm 工具,您只需要 perl、tar 和 curl 即可运行 opm 工具。 确保你的 perl 不是太旧(至少应该是 5.10.1),并且你的 curl 支持 SNI。
Back to TOC
安全注意事项
默认情况下,opm 客户端工具始终使用 HTTPS 与包服务器 opm.openresty.org 通信。 用于包上传和包下载,以及其他元数据的 Web 服务查询。 尽管用户可以通过编辑自己的 ~/.opmrc 文件中的 download_server 和/或 upload_server 键来手动切换到 HTTP 协议。 opm 客户端工具还始终验证远程 OPM 包服务器的 SSL 证书(现在通过 curl)。
同样,OPM 包服务器总是使用 TLS 与 GitHub 和 Mailgun 提供的远程服务进行通信。 这些远程站点的 SSL 证书也始终在服务器端进行验证。 用户无法关闭此功能。
OPM 包服务器使用 PostgreSQL 的 pgcrypto 扩展来加密数据库中作者的 GitHub 个人访问令牌(我们将令牌缓存在我们自己的数据库中,以在 GitHub API 关闭时加快后续上传并提高站点可靠性)。 即使是服务器管理员也无法从数据库中恢复原始访问令牌。 服务器还通过拒绝此类令牌来确保作者的个人令牌不会过于宽松。
opm 工具链和服务器还始终对下载和上传的包文件执行 MD5 校验和验证,以确保通过网络传输时的数据完整性。
Back to TOC
信用
opm 工具的设计灵感来源于各种现有的包管理系统,包括但不限于 Perl 的 cpan 和 Dist::Zilla、RedHat 的 yum、NodeJS 的 npm 和 Mac OS X 的 homebrew。
Back to TOC
待完成
- 添加 opm reinstall 命令以重新安装已安装的模块(在同一版本)。
- 添加 opm doctor 命令检查当前 opm 包安装树是否有不一致的地方。
- 添加 opm files <package> 命令以列出指定包中的所有文件。
- 添加 opm whatprovides <package> 命令来查找指定文件属于哪个包。
- 为 opm build 添加插件机制(类似于 Perl 的 Dist::Zilla 打包框架)。
- 将 opm.openresty.org 变成一个类似于 search.cpan.org 的成熟网站。
- 使用独立的 C 库添加对 Lua C 模块和 LuaJIT FFI 模块的支持。
- 添加对第 3 方 NGINX C 模块的支持(可以编译为 NGINX 动态模块)。
- 通过特殊名称空间 luarocks 添加(有限)对 LuaRocks 的支持,例如,
opm get luarocks/foo
Back to TOC
作者
Yichun Zhang (agentzh) agentzh@gmail.com, OpenResty Inc.
Back to TOC