标签归档:Lua

微服务 API 网关 Kong 命令行中文文档

原文链接: https://docs.konghq.com/1.0.x/cli/
(如有翻译的不准确或错误之处,欢迎留言指出)

介绍

提供的CLI(命令行界面Command Line Interface)允许启动,停止和管理Kong实例。CLI可以管理本地节点(如在当前计算机上)。

如果您还没有使用,我们建议您阅读配置参考

通用标志参数

所有命令都将一组特殊的可选标志作为参数:

  • --help:打印此命令的帮助信息
  • --v:启用详细模式
  • --vv:启用调试模式(很多输出)

可用命令

kong check

Usage: kong check <conf>

检查给定Kong配置文件的有效性。

<conf> (default /etc/kong/kong.conf) 配置文件

kong health

Usage: kong health [OPTIONS]

验证Kong 的服务组件是否正常运行

Options:
 -p,--prefix      (可选参数) Kong运行位置的前缀

kong migrations

Usage: kong migrations COMMAND [OPTIONS]

管理数据库迁移。

可用的命令如下:
  bootstrap                         引导数据库并运行全部迁移(初始化)。

  up                                运行新迁移。

  finish                            完成正在等待中的迁移命令,在执行`up`后。

  list                              列出已执行的迁移。

  reset                             重置数据库。

Options(可选):
 -y,--yes                           假设提示“yes”,并运行非交互模式

 -q,--quiet                         忽略所有输出

 -f,--force                         依旧执行迁移,即使数据库报告已经执行过了。

 --db-timeout     (default 60)      超时时间,以秒为单位,所有数据库操作通用(包括Cassandra的schema consensus)。

 --lock-timeout   (default 60)      超时时间,以秒为单位, 节点等待领导节点迁移完成。

 -c,--conf        (optional string) 配置文件。

kong prepare

此命令用来准备Kong前缀文件夹及其子文件夹和文件。

Usage: kong prepare [OPTIONS]

在配置的前缀目录中准备Kong前缀。这个命令可以用于从nginx二进制文件启动Kong而不使用`kong start`命令。

Example usage:
  kong migrations up
  kong prepare -p /usr/local/kong -c kong.conf
  nginx -p /usr/local/kong -c /usr/local/kong/nginx.conf

Options:
  -c,--conf       (optional string) 配置文件
  -p,--prefix     (optional string) 覆盖前缀目录
  --nginx-conf    (optional string) 自定义Nginx配置模板

kong quit

Usage: kong quit [OPTIONS]

优雅地退出一个正在运行的Kong节点(Nginx和其他节点)在给定的前缀目录中配置的服务。

此命令将会向Nginx发送SIGQUIT信号,表示全部请求将在关闭之前完成处理。
如果达到超时延迟,则该节点将被强制执行停止(SIGTERM)

Options:
 -p,--prefix      (optional string) kong正在运行的前缀
 -t,--timeout     (default 10) 强制停止前的超时

kong reload

Usage: kong reload [OPTIONS]

重新加载Kong节点(并启动其他已配置的服务)在给定的前缀目录中。

此命令将HUP信号发送到Nginx,它将生成workers(告知account配置变更),当他们处理完成当前的请求后就停止旧的。

Options:
  -c,--conf       (optional string) 配置文件
  -p,--prefix     (optional string) 覆盖前缀目录
  --nginx-conf    (optional string) 自定义Nginx配置模板

kong restart

Usage: kong restart [OPTIONS]

重新启动Kong节点(以及其他配置的服务,如Serf)在给定的前缀目录中。

这个命令相当于同时执行`kong stop`和`kong start`。

Options:
 -c,--conf        (optional string)   配置文件
 -p,--prefix      (optional string)   Kong运行的前缀
 --nginx-conf     (optional string)   自定义Nginx配置模板
 --run-migrations (optional boolean)  可选地在DB上运行迁移
 --db-timeout     (default 60)
 --lock-timeout   (default 60)

kong start

Usage: kong start [OPTIONS]

在配置中启动Kong(Nginx和其他配置的服务)。

Options:
 -c,--conf        (optional string)   配置文件。

 -p,--prefix      (optional string)   覆盖前缀目录。

 --nginx-conf     (optional string)   自定义Nginx配置模板。

 --run-migrations (optional boolean)  在开始之前运行迁移。

 --db-timeout     (default 60)      超时时间,以秒为单位,所有数据库操作通用(包括Cassandra的schema consensus)。

 --lock-timeout   (default 60)      超时时间,以秒为单位, 节点等待领导节点迁移完成。

kong stop

Usage: kong stop [OPTIONS]

停止给定的正在运行的Kong节点(Nginx和其他已配置的服务)在指定的前缀目录。

此命令将SIGTERM信号发送到Nginx。

Options:
 -p,--prefix      (optional string) Kong运行的前缀

kong version

Usage: kong version [OPTIONS]

打印kong的版本。
使用-a选项,将打印所有底层依赖项的版本。

Options:
 -a,--all         获取所有依赖项的版本

微服务 API 网关 Kong File Log 插件中文文档

原文链接: https://docs.konghq.com/hub/kong-inc/file-log
(如有翻译的不准确或错误之处,欢迎留言指出)

将请求和响应数据写入磁盘上的日志文件中。不建议在生产中使用此插件,在生产环境下,最好使用另一个日志插件,例如syslog。由于系统限制,此插件使用阻塞文件i/o,将会损害性能,因此是Kong安装的反面模式。
注意:此插件的功能与0.10.2之前的Kong版本捆绑在一起,与此处记录的不同。 有关详细信息,请参阅CHANGELOG

配置

在服务上启用插件

通过发出以下请求在服务上配置此插件:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=file-log"  \
    --data "config.path=/tmp/file.log"

service:此插件配置将绑定的服务的ID或名称。

在路由上启用插件

Route上配置此插件:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=file-log"  \
    --data "config.path=/tmp/file.log"

route_id:此插件配置将绑定的路由的ID。

在Consumer上启用插件

您可以使用 http://localhost:8001/plugins 端点在特定的Consumers上启用此插件:

$ curl -X POST http://kong:8001/plugins \
    --data "name=file-log" \
    --data "consumer_id={consumer_id}"  \
    --data "config.path=/tmp/file.log"

其中,consumer_id是我们想要与此插件关联的消费者的ID。您可以组合consumer_idservice_id。在同一个请求中,进一步缩小插件的范围。

全局插件

可以使用http://kong:8001/plugins/ 配置所有插件。与任何服务,路由或消费者(或API,如果您使用旧版本的Kong)无关的插件被视为“全局”,并将在每个请求上运行。有关更多信息,请阅读插件参考插件优先级部分。

参数

以下是可在此插件配置中使用的所有参数的列表:

参数名称 默认值 描述
name 要使用的插件的名称,在本例中为file-log
service_id 此插件将关联的服务的ID。
route_id 此插件将关联的路由的ID。
enabled true 是否将应用此插件。
consumer_id 此插件将定位的绑定的id。
config.path 输出日志文件的文件路径。
如果该文件尚不存在,该插件将创建该文件。
确保Kong对此文件具有写入权限。
config.reopen false 在kong0.10.2引入。确定是否关闭日志文件并在每个请求时重新打开。 如果文件未重新打开,并且已被删除/循环,则插件将继续写入过时的文件描述符,从而丢失信息。

日志格式

每个请求将分别记录在由新行\n分隔的JSON对象中,格式如下:

{
    "request": {
        "method": "GET",
        "uri": "/get",
        "url": "http://httpbin.org:8000/get",
        "size": "75",
        "querystring": {},
        "headers": {
            "accept": "*/*",
            "host": "httpbin.org",
            "user-agent": "curl/7.37.1"
        }
    },
    "upstream_uri": "/",
    "response": {
        "status": 200,
        "size": "434",
        "headers": {
            "Content-Length": "197",
            "via": "kong/0.3.0",
            "Connection": "close",
            "access-control-allow-credentials": "true",
            "Content-Type": "application/json",
            "server": "nginx",
            "access-control-allow-origin": "*"
        }
    },
    "tries": [
        {
            "state": "next",
            "code": 502,
            "ip": "127.0.0.1",
            "port": 8000
        },
        {
            "ip": "127.0.0.1",
            "port": 8000
        }
    ],
    "authenticated_entity": {
        "consumer_id": "80f74eef-31b8-45d5-c525-ae532297ea8e",
        "id": "eaa330c0-4cff-47f5-c79e-b2e4f355207e"
    },
    "route": {
        "created_at": 1521555129,
        "hosts": null,
        "id": "75818c5f-202d-4b82-a553-6a46e7c9a19e",
        "methods": null,
        "paths": [
            "/example-path"
        ],
        "preserve_host": false,
        "protocols": [
            "http",
            "https"
        ],
        "regex_priority": 0,
        "service": {
            "id": "0590139e-7481-466c-bcdf-929adcaaf804"
        },
        "strip_path": true,
        "updated_at": 1521555129
    },
    "service": {
        "connect_timeout": 60000,
        "created_at": 1521554518,
        "host": "example.com",cuowu
        "id": "0590139e-7481-466c-bcdf-929adcaaf804",
        "name": "myservice",
        "path": "/",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
        "retries": 5,
        "updated_at": 1521554518,
        "write_timeout": 60000
    },
    "workspaces": [
        {
            "id":"b7cac81a-05dc-41f5-b6dc-b87e29b6c3a3",
            "name": "default"
        }
    ],
    "consumer": {
        "username": "demo",
        "created_at": 1491847011000,
        "id": "35b03bfc-7a5b-4a23-a594-aa350c585fa8"
    },
    "latencies": {
        "proxy": 1430,
        "kong": 9,
        "request": 1921
    },
    "client_ip": "127.0.0.1",
    "started_at": 1433209822425
}

关于上述JSON对象的一些注意事项:

  • request 包含有关客户端发送的请求的属性
  • response 包含有关发送到客户端的响应的属性
  • tries 包含负载均衡器为此请求进行的(重新)尝试(成功和失败)列表
  • route 包含有关所请求的特定路线的Kong属性
  • service 包含与所请求的路线相关联的服务的Kong属性
  • authenticated_entity 包含有关经过身份验证的凭据的Kong属性(如果已启用身份验证插件)
  • workspaces 包含与请求的路由关联的工作空间的Kong属性。仅限Kong Enterprise版本> = 0.34
  • consumer 包含经过身份验证的使用者(如果已启用身份验证插件)
  • latencies 包含一些有关延迟的数据:
    • proxy 是最终服务处理请求所花费的时间
    • kong 是运行所有插件所需的内部Kong延迟
    • request 是从客户端读取的第一个字节之间以及最后一个字节发送到客户端之间经过的时间。用于检测慢速客户端。
  • client_ip 包含原始客户端IP地址
  • started_at 包含开始处理请求的UTC时间戳。

Kong执行错误

此日志记录插件仅记录HTTP请求和响应数据。 如果您正在寻找Kong进程错误文件(这是nginx错误文件),那么您可以在以下路径找到它:{prefix}/logs/error.log

微服务 API 网关 Kong 1.0.0 升级指南

原文地址:https://docs.konghq.com/1.0.x/upgrading/#2-deprecation-notices (不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

注意:以下是1.0.x的升级指南。 如果您要升级到Kong的早期版本,请阅读Kong repo中的UPGRADE.md文件。

本指南将告知您在升级时应了解的重大更改,并指导您完成正确的步骤,以便在不同的升级方案中获得不需要停止服务的迁移。

升级到 1.0.0

此版本(1.0.0) 是Kong的主要版本,包括许多新功能以及重大变化。
这个版本中引入了新的插件架构格式,Admin API 终端的更改,数据库迁移,Nginx配置更改以及已删除的配置属性。
在此版本中,将删除 API 及其相关的Admin API 终端。
本节将重点介绍在升级之前需要注意的重大更改,并将介绍建议的升级路径。我们建议您查阅完整的1.0.0更新日志,以获取更改和新功能的完整列表。

1.突破性修改

依赖

  • 所需的OpenResty版本是1.13.6.2,但是对于完整的功能集,包括具有相互TLS的流路由和服务网格功能,您需要Kong的openresty-patches
  • 所需的最低OpenSSL版本为1.1.1。如果您手动构建,请确保使用相同的OpenSSL版本编译所有依赖项(包括LuaRocks模块)。如果您从我们的某个分发包中安装Kong,则不会受此更改的影响。

配置

  • 删除了custom_plugins 指令(自0.14.0起不推荐使用)。请改用plugin,您不仅可以使用插件来启用自定义插件,还可以禁用自带的捆绑插件。
  • cassandra_lb_policy的默认值从Round Robin更改为Request Round Robin
  • Kong为其流路由生成了一个新的模板文件nginx-kong-stream.conf,该文件包含在其顶级Nginx配置文件的stream块中。如果您使用自定义Nginx配置并希望使用流路由,则可以使用kong prepare生成此文件。
  • Nginx配置文件已更改,这意味着如果使用自定义模板,则需要更新它:
diff --git a/kong/templates/nginx_kong.lua b/kong/templates/nginx_kong.lua
index d4e416bc..8f268ffd 100644
--- a/kong/templates/nginx_kong.lua
+++ b/kong/templates/nginx_kong.lua
@@ -66,7 +66,9 @@ upstream kong_upstream {
     balancer_by_lua_block {
         Kong.balancer()
     }
+> if upstream_keepalive > 0 then
     keepalive $;
+> end
 }

 server {
@@ -85,7 +87,7 @@ server {
 > if proxy_ssl_enabled then
     ssl_certificate $;
     ssl_certificate_key $;
-    ssl_protocols TLSv1.1 TLSv1.2;
+    ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;
     ssl_certificate_by_lua_block {
         Kong.ssl_certificate()
     }
@@ -200,7 +202,7 @@ server {
 > if admin_ssl_enabled then
     ssl_certificate $;
     ssl_certificate_key $;
-    ssl_protocols TLSv1.1 TLSv1.2;
+    ssl_protocols TLSv1.1 TLSv1.2 TLSv1.3;

     ssl_session_cache shared:SSL:10m;
     ssl_session_timeout 10m;

核心

  • 将删除API实体和相关概念,例如/apis终端。自0.13.0起,这些已被弃用。而是使用Routes配置终端,Services以配置上游服务。
  • 删除旧的DAO实现(kong.dao),其中包括旧的模式验证库。这对插件开发人员有影响,如下所示。
    • 转换为新DAO实现的最后剩余实体是Plugins,Upstreams和Targets。这会对下面列出的Admin API产生影响。

插件

kong 1.0.0标志着插件开发套件(PDK)1.0.0版的推出。与版本0.14相比,PDK没有进行重大更改,但现在可以删除一些可能由自定义插件使用的较旧的非PDK功能。

  • 插件现在使用新DAO实现引入的新模式格式,用于插件模式(在schema.lua中)和自定义DAO实体(daos.lua)。为了简化插件的转换,1.0中的插件加载器包含了一个为schema.lua的自动转换器,对于许多插件来说应该足够了(在1.0.0rc1中,我们的自带捆绑插件使用了自动转换器;它们们现在使用的是新格式)。
    • 如果您在schema.lua中使用旧格式的插件无法加载,请检查自动转换器生成的消息的错误日志。如果无法自动转换字段,则可以通过向格式的字段表转换添加new_type条目来逐步转换模式文件。例如,请参阅1.0.0rc1中的key-auth架构new_type注释被Kong 0.x忽略。
    • 如果您的自定义插件使用自定义DAO对象(如果它包含daos.lua文件),则需要将其转换为新格式。代码也需要相应调整,用kong.db代替singletons.daokong.dao的使用(注意,这个模块暴露了与旧DAO实现不同的API)。
  • 现已删除了在0.14.0中由PDK替换其功能的ome Kong模块:
    • kong.tools.ip:改为用PDK中的kong.ip
    • kong.tools.public:由PDK的各种功能取代。
    • kong.tools.responses:由PDK中的kong.response.exit取代。您可能还使用kong.log.err来记录内部服务器错误。
  • kong.api.crud_helpers模块已被删除。如果需要自定义自动生成的终端,请使用kong.api.endpoints

Admin API

  • 删除API实体后,将删除/apis终端;因此,接受api_id的其他终端不再这样做。请改用Routes和Services。
  • 现在,所有实体终端都使用新的Admin API实现。这意味着他们的请求和响应现在使用相同的语法,该语法已在终端(例如/routes/services)中使用。
    • 所有端点现在使用相同的语法将其他实体作为/routes引用(例如,“service”:{“id”:“...”}而不是“service_id”:“...”),包括请求和响应。
      • 此更改会影响/plugins以及特定于插件的终端。
    • 数组类型的值不再指定为以逗号分隔的列表。必须将其指定为JSON数组或使用新Admin API实现的url-formencoded数组表示法支持的各种格式(a[1]=x&a[2]=y, a[]=x&a[]=y, a=x&a=y
      • 此更改会影响/upstreams终端的属性。
    • 更新终端的错误响应使用新的标准化格式。
    • 由于被移动到新的Admin API实现,支持PUT的所有终端都使用适当的语义。
    • 有关更多详细信息,请参阅Admin API参考

2.弃用通知

此版本中没有弃用通知。

3.建议的升级路径

初步检查

如果您的群集运行的版本低于0.14,则需要先升级到0.14.1。不支持从0.14之前的群集直接升级到Kong 1.0。如果您仍然使用已弃用的API实体来配置终端和上游服务(通过/apis),而不是使用路由Routes(通过’/routes’)和服务Service(通过/services),现在是时候这样做了。如果您在数据存储区中使用/apis配置了任何实体,则kong 1.0将拒绝运行迁移。创建等效的路由和服务并删除您的API。请注意,Kong不会自动执行此操作,因为为每个API创建一对路由和服务这样天真的操作将错过路由和服务带来的改进点;路由和服务的理想映射取决于您的微服务架构。

如果您使用除与Kong自带捆绑的插件以外的其他插件,请确保在升级之前它们与Kong 1.0兼容。有关插件兼容性的信息,请参阅上面有关插件的部分。

从0.14开始逐步迁移

Kong 1.0引入了一个新的,改进的迁移框架。它支持无停机,蓝/绿迁移模型,可从0.14.x升级。完整迁移现在分为两个步骤,这两个步骤通过命令kong migrations upkong migrations finish完成。

对于从0.14群集到1.0群集的无停机时间迁移,我们建议采用以下一系列步骤:

  • 第一步:下载1.0,并将其配置为指向与0.14群集相同的数据存储。执行kong migrations up
  • 第二步:现在,0.14和1.0节点都可以在同一数据存储上同时运行。开始配置1.0节点,但是先不要使用其Admin API。更好的操作是向0.14节点发出Admin API请求。
  • 第三步:逐渐将流量从0.14节点转移到1.0集群中。监控您的流量,确保一切顺利。
  • 第四步:当您的流量完全迁移到1.0群集时,停用0.14节点。
  • 第五步:从1.0集群中,运行:kong migrations finish。从现在开始,将无法再启动指向同一数据存储区的0.14个节点。仅在您确信迁移成功时才运行此命令。从现在开始,您可以安全地向1.0节点发出Admin API请求。

在任何一步,您都可以运行kong migrations list来获取迁移状态的报告。它将列出是否缺少迁移,如果有待处理的迁移(已经在kong迁移步骤中启动,之后需要在kong迁移完成步骤中完成)或者是否有新的迁移可用。流程的状态代码也会相应更改:

  • 0 - 迁移是最新的
  • 1 - 检查迁移状态失败(例如数据库已关闭)
  • 3 - 数据库需要引导:你应该运行kong migrations bootstrap来安装在新的数据存储上。
  • 4 - 有待处理的迁移:一旦您的旧群集被解除,您应该运行kong迁移完成(上面的步骤5)。
  • 5 - 有新的迁移:您应该开始迁移序列(从上面的步骤1开始)。

从1.0 Release Candidates迁移

该过程与上面列出的0.14升级过程相同,但在第1步中,您应该运行kong migrations --force。

补丁版本的升级路径

同一次要版本的Kong的当前或未来补丁版本之间的升级没有迁移(例如1.0.0到1.0.1,1.0.1到1.0.4等)。

假设Kong已在您的系统上运行,请从任何可用的安装方法获取最新版本并继续安装它,覆盖以前的安装。

如果您计划对配置进行修改,那么这是一个好时机。然后,运行迁移以升级数据库模式

$ kong migrations up [-c configuration_file]

如果命令成功,并且没有运行迁移(没有输出),那么您只需要重新加载Kong

$ kong reload [-c configuration_file]

提醒:kong reload利用ngnix的reload来无缝启动一个新的worker。在那些旧worker被终止之前接管旧的worker。通过这种方式,Kong将通过新配置提供新请求,而不会丢弃现有的服务连接。

在新数据存储上安装1.0

为了在新的数据存储上安装,Kong 1.0引入了kong migrations bootstrap命令。可以运行以下命令从新数据存储区准备新的1.0集群:

$ kong migrations bootstrap [-c config]
$ kong start [-c config]

微服务 API 网关 Kong 插件开发套件PDK 中文文档

原文地址:https://docs.konghq.com/1.0.x/pdk/(不能保证所有的翻译都是准确无误的,所有如有翻译的不准确或错误之处,请一定记得查看原文,并欢迎留言指出)。

插件开发工具包 Plugin Development Kit(或“PDK”)是一组Lua函数和变量,插件可以使用这些函数和变量来实现自己的逻辑。PDK是一个语义版本的组件,最初在Kong 0.14.0中发布。PDK将保证从1.0.0版本开始向前兼容。

截至本版本,PDK尚未达到1.0.0,但插件作者已经可以依赖它来使用安全可靠的方式进行请求、响应或者做一些核心组件。

可以从kong全局变量访问插件开发工具包,并在此表下命名各种功能,例如kong.requestkong.log等…

kong.version

一个可以直观阅读的字符串,包含当前正在运行的节点的版本号。

用法

print(kong.version) -- "0.14.0"
Back to TOC

kong.version_num

表示当前运行节点的版本号的整数,用于比较和特征存在检查。

用法

if kong.version_num < 13000 then -- 000.130.00 -> 0.13.0
  -- no support for Routes & Services
end

kong.pdk_major_version

表示当前PDK主要版本的数字(例如1)。 对于作为PDK用户的特征存在检查或向后兼容行为很有用。

用法

if kong.pdk_version_num < 2 then
  -- PDK is below version 2
end
Back to TOC

kong.pdk_version

一个可以直观阅读的字符串,包含当前PDK的版本号。

用法

print(kong.pdk_version) -- "1.0.0"

kong.configuration

包含当前Kong节点配置的只读表,基于配置文件和环境变量。 有关详细信息,请参阅kong.conf.default。 该文件中以逗号分隔的列表将被提升为此表中的字符串数组。

用法

print(kong.configuration.prefix) -- "/usr/local/kong"
-- this table is read-only; the following throws an error:
kong.configuration.prefix = "foo"

kong.db

Kong的DAO实例(kong.db模块)。 包含各种实体的访问者对象。

用法

kong.db.services:insert()
kong.db.routes:select()

将来可以提供有关此DAO和新模式定义的更全面的文档。

kong.dns

Kong的DNS解析器实例,来自lua-resty-dns-c模块的客户端对象。 注意:此模块的使用目前保留给核心或高级用户。

kong.worker_events

Kong的IPC模块实例,用于来自lua-resty-worker-events模块的员工间通信。 注意:此模块的使用目前保留给核心或高级用户。

kong.cluster_events

用于节点间通信的Kong的集群事件模块的实例。 注意:此模块的使用目前保留给核心或高级用户。 回到TOC

kong.cache

来自kong.cache模块的Kong数据库缓存对象的实例。 注意:此模块的使用目前保留给核心或高级用户。

Openresty 第三方库 Lua_resty_http 使用教程

lua_resty_http是一个第三方 openresty 库,基于 Openresty/ngx_lua 的HTTP客户端,支持POST方法上传数据,刚好项目中用到需要从网关中发起请求,于是就用到这个库,把使用方式在这里分享一下。

安装第三方库lua_resty_http

第一步

首先找到项目地址:https://github.com/pintsized/lua-resty-http

第二步

然后将 lua-resty-http/lib/resty/ 目录下的 http.lua  http_headers.lua 两个文件拷贝到 /usr/local/openresty/lualib/resty 目录下即可,OpenResty 安装目录为 /usr/local/openresty)。不需要重启。(少数需要清空 Openresty shared_dict 数据的情况需要重启 )。

代码示例

local function HttpUtil(jwt_data)
    -- 引入第三方库
    local http = require "resty.http"
    local httpc = http.new()
    -- 需要post的参数
    local str = "aaa=1&bbb=2%ccc=3"
    -- 请求地址
    local url = "http://wwww.xxxxxxx.com"
    local res, err = httpc:request_uri(url, {
        method = "POST",
        body = str,
        headers = {
            ["Content-Type"] = "application/x-www-form-urlencoded",
            ["Content-Length"] = #str,
        }
    })

    -- 返回值
    ngx.say(res.body)
    ngx.say(res.status)
    ngx.say(res.headers)

    return res.body,res.status
end

参数详解

请求参数

参数名 描述
version HTTP版本号,目前支持1.0或1.1
method HTTP方法
path 路径
query 查询字符串,表示为文字字符串或Lua table
headers 请求 header table
body 请求体作为字符串或迭代器函数(请参阅get_client_body_reader)。
ssl_verify 验证SSL证书是否与主机名匹配

返回参数

请求成功后,res将包含以下字段:

参数名 描述
status 状态码
reason 状态原因短语
headers headers 类型是table ,相同名称的header会合并成一个table
has_body bool值,指示是否有要读取的正文
body_reader 迭代器函数,用于以流方式读取正文。
read_body 一种将整个主体读入字符串的方法。
read_trailers 读取正文后,合并标题下trailers的方法。

参考链接

Nginx API for Lua 汇总

Nginx API for Lua 一览

常量列表

常量 说明
Core constants 核心常量 ngx.OK (0) 
ngx.ERROR (-1)
ngx.AGAIN (-2)
ngx.DONE (-4)
ngx.DECLINED (-5)
ngx.nil
HTTP method constants HTTP方法常量 ngx.HTTP_GET
ngx.HTTP_HEAD
ngx.HTTP_PUT
ngx.HTTP_POST
ngx.HTTP_DELETE
ngx.HTTP_OPTIONS
ngx.HTTP_MKCOL
ngx.HTTP_COPY
ngx.HTTP_MOVE
ngx.HTTP_PROPFIND
ngx.HTTP_PROPPATCH
ngx.HTTP_LOCK
ngx.HTTP_UNLOCK
ngx.HTTP_PATCH
ngx.HTTP_TRACE
HTTP status constants HTTP 状态常量 ngx.HTTP_OK (200)
ngx.HTTP_CREATED (201)
ngx.HTTP_SPECIAL_RESPONSE (300)
ngx.HTTP_MOVED_PERMANENTLY (301)
ngx.HTTP_MOVED_TEMPORARILY (302)
ngx.HTTP_SEE_OTHER (303)
ngx.HTTP_NOT_MODIFIED (304)
ngx.HTTP_BAD_REQUEST (400)
ngx.HTTP_UNAUTHORIZED (401)
ngx.HTTP_FORBIDDEN (403)
ngx.HTTP_NOT_FOUND (404)
ngx.HTTP_NOT_ALLOWED (405)
ngx.HTTP_GONE (410)
ngx.HTTP_INTERNAL_SERVER_ERROR (500)
ngx.HTTP_METHOD_NOT_IMPLEMENTED (501)
ngx.HTTP_SERVICE_UNAVAILABLE (503)
ngx.HTTP_GATEWAY_TIMEOUT (504)
Nginx log level constants nginx日志级别常量 ngx.STDERR
ngx.EMERG
ngx.ALERT
ngx.CRIT
ngx.ERR
ngx.WARN
ngx.NOTICE
ngx.INFO
ngx.DEBUG

Api一览

Nginx Api name 描述
ngx.arg 指令参数,如跟在content_by_lua_file后面的参数
ngx.var.VARIABLE 变量,ngx.var.VARIABLE引用某个变量
print 等价于 ngx.log(ngx.NOTICE, …)
ngx.ctx 这个 Lua 表可以用来存储基于请求的 Lua 环境数据,其生存周期与当前请求相同 (类似 Nginx 变量)。
ngx.location.capture 发布一个子请求
ngx.location.capture_multi 发布多个子请求
ngx.status 响应码
ngx.header.HEADER 响应头,ngx.header.HEADER引用某个头
ngx.resp.get_headers 获取响应头
ngx.req.is_internal 返回一个布尔值,指示当前请求是否是“内部请求”,即从当前nginx服务器内部而不是从客户端侧发起的请求
ngx.req.start_time 请求的开始时间
ngx.req.http_version 请求的HTTP版本号
ngx.req.raw_header 请求头(包括请求行)
ngx.req.get_method 请求方法
ngx.req.set_method 请求方法重载
ngx.req.set_uri 请求URL重写
ngx.req.set_uri_args 通过args参数重写当前请求的URI查询参数。
ngx.req.get_uri_args 获取请求参数
ngx.req.get_post_args 获取请求表单
ngx.req.get_headers 获取请求头
ngx.req.set_header 将当前请求的名为header_name的请求标头设置为值header_value,覆盖任何现有的
ngx.req.clear_header 清除当前请求的名为header_name的请求标头。当前请求的现有子请求都不会受到影响,但随后发起的子请求将默认继承该更改。
ngx.req.read_body 读取请求体
ngx.req.discard_body 扔掉请求体
ngx.req.get_body_data 检索内存中的请求正文数据。它返回一个Lua字符串,而不是一个包含所有已解析查询参数的Lua表。如果需要Lua表,请使用ngx.req.get_post_args函数。
ngx.req.get_body_file 检索文件内请求正文数据的文件名。如果请求正文尚未被读取或已被读入内存,则返回nil。
ngx.req.set_body_data 使用data参数指定的内存数据设置当前请求的请求主体。
ngx.req.set_body_file 使用file_name参数指定的文件内数据设置当前请求的请求正文。
ngx.req.init_body 为当前请求创建一个新的空白请求主体,并通过ngx.req.append_body和ngx.req.finish_body API将缓冲区用于以后的请求正文数据写入。
ngx.req.append_body 将data_chunk参数指定的新数据块附加到由ngx.req.init_body调用创建的现有请求主体上。
ngx.req.finish_body 完成由ngx.req.init_body和ngx.req.append_body调用创建的新请求正文的构造过程。
ngx.req.socket 返回包装下游连接的只读cosocket对象。此对象仅支持receive和receiveuntil方法。
ngx.exec 是否使用args将内部重定向到uri,并且类似于echo-nginx-module的echo_exec指令。
ngx.redirect 向uri发出HTTP 301或302重定向
ngx.send_headers 发送响应头
ngx.headers_sent 响应头是否已发送
ngx.print 输出响应
ngx.say 输出响应,自动添加’\n’
ngx.log 输出到error.log
ngx.flush 刷新响应
ngx.exit 结束请求
ngx.eof 明确指定响应输出流的结束。在HTTP 1.1分块编码输出的情况下,它只会触发Nginx核心发送“last chunk”。
ngx.sleep 无阻塞的休眠(使用定时器实现)
ngx.escape_uri 字符串的url编码
ngx.unescape_uri 字符串url解码
ngx.encode_args 将table编码为一个参数字符串
ngx.decode_args 将参数字符串编码为一个table
ngx.encode_base64 字符串的base64编码
ngx.decode_base64 字符串的base64解码
ngx.crc32_short 字符串的crs32_short哈希
ngx.crc32_long 字符串的crs32_long哈希
ngx.hmac_sha1 字符串的hmac_sha1哈希
ngx.md5 返回16进制MD5
ngx.md5_bin 返回2进制MD5
ngx.sha1_bin 返回2进制sha1哈希值
ngx.quote_sql_str SQL语句转义
ngx.today 返回当前日期
ngx.time 返回UNIX时间戳
ngx.now 返回当前时间
ngx.update_time 刷新时间后再返回
ngx.localtime 返回nginx缓存时间的当前时间戳(格式为yyyy-mm-dd hh:mm:ss)(与Lua的os.date函数不同,不涉及系统调用)
ngx.utctime 返回nginx缓存时间的当前时间戳(格式为yyyy-mm-dd hh:mm:ss)(与Lua的os.date函数不同,不涉及系统调用)
ngx.cookie_time 返回的时间可用于cookie值
ngx.http_time 返回的时间可用于HTTP头
ngx.parse_http_time 解析HTTP头的时间
ngx.is_subrequest 当前请求是否是子请求
ngx.re.match 使用Perl兼容的正则表达式正则表达式与可选选项匹配主题字符串。
ngx.re.find
ngx.re.gmatch
ngx.re.sub
ngx.re.gsub
ngx.shared.DICT
ngx.shared.DICT.get
ngx.shared.DICT.get_stale
ngx.shared.DICT.set
ngx.shared.DICT.safe_set
ngx.shared.DICT.add
ngx.shared.DICT.safe_add
ngx.shared.DICT.replace
ngx.shared.DICT.delete
ngx.shared.DICT.incr
ngx.shared.DICT.lpush
ngx.shared.DICT.rpush
ngx.shared.DICT.lpop
ngx.shared.DICT.rpop
ngx.shared.DICT.llen
ngx.shared.DICT.ttl
ngx.shared.DICT.expire
ngx.shared.DICT.flush_all
ngx.shared.DICT.flush_expired
ngx.shared.DICT.get_keys
ngx.shared.DICT.capacity
ngx.shared.DICT.free_space
ngx.socket.udp
udpsock:setpeername
udpsock:send
udpsock:receive
udpsock:close
udpsock:settimeout
ngx.socket.stream
ngx.socket.tcp
tcpsock:connect
tcpsock:sslhandshake
tcpsock:send
tcpsock:receive
tcpsock:receiveany
tcpsock:receiveuntil
tcpsock:close
tcpsock:settimeout
tcpsock:settimeouts
tcpsock:setoption
tcpsock:setkeepalive
tcpsock:getreusedtimes
ngx.socket.connect
ngx.get_phase
ngx.thread.spawn
ngx.thread.wait
ngx.thread.kill
ngx.on_abort 注册client断开请求时的回调函数
ngx.timer.at 注册定时器事件
ngx.timer.every
ngx.timer.running_count
ngx.timer.pending_count
ngx.config.subsystem
ngx.config.debug 编译时是否有 –with-debug选项
ngx.config.prefix 编译时的 – -prefix选项
ngx.config.nginx_version 返回nginx版本号
ngx.config.nginx_configure 返回编译时 ./configure的命令行选项
ngx.config.ngx_lua_version 返回ngx_lua模块版本号
ngx.worker.exiting 当前worker进程是否正在关闭(如reload、shutdown期间)
ngx.worker.pid 返回当前worker进程的pid
ngx.worker.count
ngx.worker.id
ngx.semaphore
ngx.balancer 提供了一个Lua API,允许在纯Lua中定义完全动态的负载均衡器。
ngx.ssl
ngx.ocsp
ndk.set_var.DIRECTIVE
coroutine.create
coroutine.resume
coroutine.yield
coroutine.wrap
coroutine.running
coroutine.status