<ph type="x-smartling-placeholder"></ph>
您正在查看 Apigee Edge 文档。
转到
Apigee X 文档。 信息
Edge Microgateway v. 3.0.x
本主题介绍如何管理和配置 Edge Microgateway。
如果您有互联网连接,则升级 Edge Microgateway
本部分介绍如何升级现有安装的 Edge Microgateway。 如果您在没有互联网连接的情况下操作,请参阅 我可以在没有互联网连接的情况下安装 Edge Microgateway 吗?。
Apigee 建议您使用 在升级生产环境之前使用新版本。
- 执行以下
npm
命令以升级到最新版本的 Edge Microgateway:npm upgrade edgemicro -g
要升级到特定版本的 Edge Microgateway,您需要指定版本 号。如果您不指定版本号, 系统会安装最新版本例如,要升级到版本 3.0.2,请使用 以下命令:
npm upgrade edgemicro@3.0.2 -g
- 检查版本号。例如,如果您安装的是版本 3.0.2:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.0.2
- 最后,升级到最新版本的 edgemicro-auth 代理:
edgemicro upgradeauth -o org_name -e env_name -u username
更改配置
您需要了解的配置文件包括:
- 默认系统配置文件
- 新初始化的 Edge Microgateway 实例的默认配置文件
- 用于正在运行的实例的动态配置文件
本节讨论这些文件以及关于更改它们需要了解的信息。
默认系统配置 文件
安装 Edge Microgateway 时,默认系统配置文件位于此处:
prefix/lib/node_modules/edgemicro/config/default.yaml
其中 prefix 是 npm
前缀目录。请参阅
如果找不到 Edge Microgateway 的安装位置,
如果您更改系统配置文件,则必须重新初始化、重新配置并重启 Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
新初始化的 Edge Microgateway 实例的默认配置文件
运行 edgemicro init
时,系统配置文件(描述
default.yaml
)会放在 ~/.edgemicro
目录中。
如果您更改 ~/.edgemicro
中的配置文件,则必须重新配置并重启
Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
动态 用于运行实例的
当您运行 edgemicro configure [params]
时,
在 ~/.edgemicro
中创建配置文件。该文件的命名依据如下
格式:org-env-config.yaml
,其中 org 和
env是
您的 Apigee Edge 组织和环境名称。您可以使用此文件
然后重新加载它们,无需停机例如,如果您添加并配置一个插件,
您可以重新加载配置,而不会导致任何停机,具体如下所述。
如果 Edge Microgateway 正在运行(零停机选项):
- 重新加载 Edge Microgateway 配置:
edgemicro reload -o org_name -e env_name -k key -s secret
其中:
- org_name 是您的 Edge 组织名称(您必须是组织) 管理员)。
- env_name 是贵组织中的一种环境(例如“test”或 “prod”)。
- key 是 configure 命令之前返回的键。
- secret 是 configure 命令之前返回的键。
例如:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
如果 Edge Microgateway 已停止:
- 重启 Edge Microgateway:
edgemicro start -o org_name -e env_name -k key -s secret
其中:
- org_name 是您的 Edge 组织名称(您必须是组织) 管理员)。
- env_name 是贵组织中的环境(例如“test”或 “prod”)。
- key 是 configure 命令之前返回的键。
- secret 是 configure 命令之前返回的键。
例如:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
下面是一个配置文件示例。如需详细了解配置文件设置,请参阅 Edge Microgateway 配置参考文档。
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
设置环境变量
需要 Edge 组织和 启动 Edge Microgateway 所需的密钥和密钥可以存储在 环境变量:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
设置这些变量是可选的。如果设置了这些参数,则无需指定它们的值 当您使用命令行界面 (CLI) 配置和启动 Edge Microgateway 时。
在 Edge Microgateway 上配置 SSL 服务器
观看以下视频,了解如何在 Apigee Edge Microgateway 中配置 TLS:
视频 | 说明 |
---|---|
配置单向北向 TLS | 了解如何在 Apigee Edge Microgateway 中配置 TLS。 此视频简要介绍了 TLS 及其重要性,并介绍了 TLS 以及如何配置北向单向 TLS。 |
配置双向北向 TLS | 这是有关在 Apigee Edge Microgateway 中配置 TLS 的第二个视频。这个 视频介绍了如何配置北向双向 TLS。 |
配置单向和双向 TLS 传输层安全协议 | 第三个视频介绍了如何在 Apigee Edge Microgateway 中配置 TLS 介绍了 如何配置南向单向 TLS 和双向 TLS。 |
您可以将 Microgateway 服务器配置为使用 SSL。例如,配置 SSL 后 可以使用“https”通过 Edge Microgateway 调用 API协议,如下所示:
https://localhost:8000/myapi
如需在 Microgateway 服务器上配置 SSL,请按以下步骤操作:
- 使用 openssl 实用程序或您喜欢的任何方法生成或获取 SSL 证书和密钥。
- 将
edgemicro:ssl
属性添加到 Edge Microgateway 配置文件。有关 选项列表,请参阅下表。例如:
edgemicro: ssl: key: <absolute path to the SSL key file> cert: <absolute path to the SSL cert file> passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2 requestCert: true
- 重启 Edge Microgateway。请按照 更改配置 是默认文件或运行时配置文件。
下面是一个使用 SSL 的配置文件的 edgemicro
部分的示例
已配置:
edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth ssl: key: /MyHome/SSL/em-ssl-keys/server.key cert: /MyHome/SSL/em-ssl-keys/server.crt passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2
以下是所有支持的服务器选项的列表:
选项 | 说明 |
---|---|
key |
ca.key 文件的路径(PEM 格式)。 |
cert |
ca.cert 文件的路径(PEM 格式)。 |
pfx |
包含私钥、证书和 CA 证书的 pfx 文件的路径
采用 PFX 格式 |
passphrase |
包含私钥或 PFX 密码的字符串。 |
ca |
指向包含 PEM 格式的可信证书列表的文件的路径。 |
ciphers |
用于描述要使用的密码的字符串,以“:”分隔。 |
rejectUnauthorized |
如果为 true,则根据提供的 CA 列表验证服务器证书。如果 则会返回错误。 |
secureProtocol |
要使用的 SSL 方法。例如,使用 SSLv3_method 将 SSL 强制使用版本 3。 |
servername |
SNI(服务器名称指示)TLS 扩展的服务器名称。 |
requestCert |
如果是双向 SSL,则为 true;false(对于单向 SSL) |
使用客户端 SSL/TLS 选项
您可以将 Edge Microgateway 在连接到目标时配置为 TLS 或 SSL 客户端 端点。在 Microgateway 配置文件中,使用 targets 元素设置 SSL/TLS 选项。
以下示例提供了将应用于所有主机的设置:
edgemicro: ... targets: ssl: client: key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
在此示例中,这些设置仅应用于指定的主机:
edgemicro: ... targets: - host: 'myserver.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
以下是 TLS 的示例:
edgemicro: ... targets: - host: 'myserver.example.com' tls: client: pfx: /Users/myname/twowayssl/ssl/client.pfx passphrase: admin123 rejectUnauthorized: true
下面列出了所有支持的客户端选项:
选项 | 说明 |
---|---|
pfx |
包含私钥、证书和 CA 证书的 pfx 文件的路径
采用 PFX 格式 |
key |
ca.key 文件的路径(PEM 格式)。 |
passphrase |
包含私钥或 PFX 密码的字符串。 |
cert |
ca.cert 文件的路径(PEM 格式)。 |
ca |
指向包含 PEM 格式的可信证书列表的文件的路径。 |
ciphers |
用于描述要使用的密码的字符串,以“:”分隔。 |
rejectUnauthorized |
如果为 true,则根据提供的 CA 列表验证服务器证书。如果 则会返回错误。 |
secureProtocol |
要使用的 SSL 方法。例如,使用 SSLv3_method 将 SSL 强制使用版本 3。 |
servername |
SNI(服务器名称指示)TLS 扩展的服务器名称。 |
自定义 Edgemicro-auth 代理
默认情况下,Edge Microgateway 使用 Apigee Edge 上部署的代理进行 OAuth2 身份验证。
此代理会在您首次运行 edgemicro configure
时部署。您可以更改
此代理的默认配置,用于向 JSON 网络令牌添加自定义声明
(JWT)、配置令牌到期时间并生成刷新令牌。如需了解详情,请参阅 GitHub 中的 edgemicro-auth 页面。
使用自定义身份验证服务
默认情况下,Edge Microgateway 使用 Apigee Edge 上部署的代理进行 OAuth2 身份验证。
此代理会在您首次运行 edgemicro configure
时部署。默认情况下,
代理的网址在 Edge Microgateway 配置文件中指定,如下所示:
authUri: https://myorg-myenv.apigee.net/edgemicro-auth
如果您希望使用自己的自定义服务来处理身份验证,请将
authUri
值,以指向您的服务。例如,您可能有
一项使用 LDAP 验证身份的服务。
管理日志文件
Edge Microgateway 会记录每个请求和响应的相关信息。日志文件会提供 调试和问题排查信息。
日志文件的存储位置
默认情况下,日志文件存储在 /var/tmp
中。
如何更改默认日志 文件目录
存储日志文件的目录在 Edge Microgateway 配置中指定 文件。另请参阅进行配置 更改。
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
更改 dir 值以指定其他日志文件目录。
将日志发送到控制台
您可以配置日志记录,以便将日志信息发送到标准输出,而不是
日志文件。将 to_console
标志设置为 true,如下所示:
edgemicro: logging: to_console: true
如果使用此设置,日志将发送至“标准输出”。目前,您不能同时向两者发送日志 标准输出和日志文件。
如何设置日志记录级别
您可以设置以下日志级别:info、warn 和 错误。建议使用信息级别。它会记录所有 API 请求和响应 这是默认值
如何更改日志时间间隔
您可以在 Edge Microgateway 配置文件中配置这些时间间隔。另请参阅更改配置。
可配置的属性包括:
- stats_log_interval:(默认值:60)显示统计数据时的时间间隔(以秒为单位) 将写入 API 日志文件。
- rotate_interval:(默认值:24)日志文件的间隔时间(以小时为单位) 旋转。例如:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
日志文件维护的良好做法
随着日志文件数据随时间的积累,Apigee 建议您采用以下做法 做法:
- 由于日志文件会变得非常大,因此请确保日志文件目录 空间充足。请参阅下面的日志文件的存储位置和如何更改默认日志文件 目录。
- 每周至少删除一次日志文件,或将日志文件移至单独的存档目录。
- 如果您的政策是删除日志,可以使用 CLI 命令
edgemicro log -c
移除(清理)较旧的日志。
日志文件命名惯例
每个 Edge Microgateway 实例会生成三种类型的日志文件:
- api - 记录流经 Edge 的所有请求和响应 Microgateway。API 计数器(统计数据)和错误也会记录到该文件中。
- err - 记录发送到 stderr 的任何内容。
- out - 记录发送到 stdout 的所有内容。
以下是命名惯例:
edgemicro-<Host Name>-<Instance ID>-<Log Type>.log
例如:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log
关于日志文件内容
添加此模块的版本:v2.3.3
默认情况下,日志记录服务会忽略下载的代理、产品的 JSON 和 JSON
网络令牌 (JWT)。如果要将这些对象输出到日志文件,请将
DEBUG=*
(在您启动 Edge Microgateway 时)。例如:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
“API”的内容日志文件
“API”日志文件包含有关请求和响应流的详细信息 通过 Edge Microgateway 访问 Wi-Fi。“API”日志文件的名称如下所示:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
对于发送到 Edge Microgateway 的每个请求,“api”中会捕获四个事件日志 文件:
- 来自客户端的传入请求
- 向目标发出的传出请求
- 来自目标的响应
- 对客户端的传出响应
这些单独的条目均以简写表示法表示 让文件更加紧凑以下是四个示例条目,分别代表这四个事件。在日志中 它们将如下所示(行号仅供在文档中参考,不会出现 记录)。
(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0 (2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0 (3) 1436403888672 info tres s=200, d=7, i=0 (4) 1436403888676 info res s=200, d=11, i=0
下面我们将逐一介绍:
1. 来自客户端的传入请求示例:
1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
- 1436403888651 - Unix 日期戳
- info - 取决于上下文。可以是信息、警告或错误 具体取决于日志级别可以是统计数据记录的统计信息、出现警告时显示警告, 出错。
- req - 标识事件。在这种情况下,请从 客户端。
- m - 请求中使用的 HTTP 动词。
- u - 网址中基本路径之后的部分。
- h - Edge Microgateway 所在的主机和端口号 。
- r - 客户端请求所在的远程主机和端口 来源。
- i - 请求 ID。所有四个事件条目都将共用此 ID。每个 系统会为请求分配一个唯一的请求 ID按请求 ID 关联日志记录可以 可让您了解目标延迟时间的宝贵数据洞见
- d - 自从 SDK 收到请求后的持续时间(以毫秒为单位) Edge Microgateway。在上面的示例中,收到了目标对请求 0 的响应 7 毫秒之后(第 3 行),并且在额外 4 次请求后, 毫秒(第 4 行)。换句话说,总请求延迟时间为 11 毫秒, 目标占用了 7 毫秒,Edge Microgateway 占用了 4 毫秒 本身。
2. 向目标发出的传出请求的示例:
1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
- 1436403888651 - Unix 日期戳
- info - 取决于上下文。可以是信息、警告或错误 具体取决于日志级别可以是统计数据记录的统计信息、出现警告时显示警告, 出错。
- treq - 标识事件。在本示例中,目标请求。
- m - 目标请求中使用的 HTTP 动词。
- u - 网址中基本路径之后的部分。
- h - 后端目标的主机和端口号。
- i - 日志条目的 ID。这四个活动条目将会共享 ID。
3. 来自目标的传入响应示例
1436403888672 info tres s=200, d=7, i=0
1436403888651 - Unix 日期戳
- info - 取决于上下文。可以是信息、警告或错误 具体取决于日志级别可以是统计数据记录的统计信息、出现警告时显示警告, 出错。
- tres - 标识事件。在本示例中,目标回复。
- s - HTTP 响应状态。
- d - 时长(以毫秒为单位)。调用 API 所用的时间 目标。
- i - 日志条目的 ID。这四个活动条目将会共享 ID。
4. 发送至客户端的传出响应示例
1436403888676 info res s=200, d=11, i=0
1436403888651 - Unix 日期戳
- info - 取决于上下文。可以是信息、警告或错误 具体取决于日志级别可以是统计数据记录的统计信息、出现警告时显示警告, 出错。
- res - 标识事件。在这种情况下,对 客户端。
- s - HTTP 响应状态。
- d - 时长(以毫秒为单位)。这是总时间 由 API 调用触发,包括目标 API 花费的时间和 Edge 花费的时间 Microgateway 本身。
- i - 日志条目的 ID。这四个活动条目将会共享 ID。
日志文件时间安排
日志文件按 rotate_interval 指定的间隔定期轮替 配置属性。参评申请将继续添加到 同一个日志文件,直到轮替间隔过期。不过,每次 重新启动后,设备会接收新的 UID,并使用此 UID 创建一组新的日志文件。另请参阅 良好的日志文件维护 做法。
错误消息
部分日志条目包含错误消息。为帮助确定错误的发生位置和原因 请参阅 Edge Microgateway 错误 参考。
Edge Microgateway 配置参考文档
的 配置文件
本部分介绍的配置属性位于 Edge Microgateway 配置文件另请参阅进行配置 更改。
Edge_config 属性
这些设置用于配置 Edge Microgateway 实例和 Apigee Edge。
- bootstrap:(默认值:无)指向 Edge 的网址
在 Apigee Edge 上运行的 Microgateway 专用服务。Edge Microgateway 使用此服务
与 Apigee Edge 进行通信当您执行相应命令以生成
公钥/私钥对:
edgemicro genkeys
。请参阅有关设置 和配置 Edge Microgateway。 - jwt_public_key:(默认值:无)指向 Edge Microgateway 的网址 部署在 Apigee Edge 上的代理此代理可用作以下账号的身份验证端点: 向客户端颁发已签名的访问令牌。当您执行命令以 部署代理:edgemicro configure。请参阅有关设置 和配置 Edge Microgateway。
- quotaUri:设置此配置
属性(如果您想通过
edgemicro-auth
代理) 部署到您的组织如果未设置此属性 配额端点默认为内部 Edge Microgateway 端点。edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
要使用此功能,您必须先部署 3.0.5 版或更高版本的 贵组织的
edgemicro-auth
代理。有关详情,请参阅 <ph type="x-smartling-placeholder"></ph> 升级 Edgemicro-auth 代理。
Edgemicro 属性
这些设置会配置 Edge Microgateway 进程。
- port:(默认值:8000)Edge Microgateway 所在的端口号 进程监听
- max_connections:(默认值:-1)指定
Edge Microgateway 可以接收的并发传入连接数。如果此数字为
系统将返回以下状态:
res.statusCode = 429; // Too many requests
- max_connections_hard:(默认值:-1)并发的最大数量 在关闭连接之前 Edge Microgateway 可以接收的请求。此设置 旨在阻止拒绝服务攻击。通常,将其设置为大于 max_connections.
-
logging:
<ph type="x-smartling-placeholder">
- </ph>
-
level:(默认值:error)
<ph type="x-smartling-placeholder">
- </ph>
- info - 记录流经 Edge Microgateway 实例。
- warn - 仅记录警告消息。
- error - 仅记录错误消息。
- dir:(默认值:/var/tmp)日志文件所在的目录 存储的数据。
- stats_log_interval:(默认值:60)显示统计数据时的时间间隔(以秒为单位) 将写入 API 日志文件
- rotate_interval:(默认值:24)日志文件的间隔时间(以小时为单位) 旋转。
-
level:(默认值:error)
<ph type="x-smartling-placeholder">
- 插件:插件用于向 Edge Microgateway 添加功能。了解详情 如需了解如何开发插件,请参阅开发自定义插件。
- dir:从 ./gateway 目录到 ./plugins 目录或绝对路径。
- sequence:要添加到 Edge Microgateway 的插件模块列表 实例。模块将按此处指定的顺序执行。
-
debug :在 Edge Microgateway 进程中添加远程调试。
- port:要监听的端口号。例如,设置 IDE 调试程序 在此端口上进行监听。
- args:调试进程的参数。例如:
args --nolazy
- config_change_poll_interval:(默认值:600 秒)Edge Microgateway
定期加载新配置,并在发生更改时执行重新加载。轮询
提取在 Edge 上所做的任何更改(产品更改、可感知微网关的代理等),
以及对本地配置文件所做的更改
- disable_config_poll_interval:(默认值:false)设置为 设置为 true 可关闭自动更改轮询。
- request_timeout:为目标请求设置超时。超时时间是在 。如果发生超时,Edge Microgateway 会返回 504 状态代码。(已添加 v2.4.x)
标头属性
这些设置用于配置某些 HTTP 标头的处理方式。
- x-forwarded-for:(默认值:true)设置为 false 可防止 x-forwarded-for 要传递给目标的标头。请注意,如果 x-forwarded-for 标头 ,那么其值将设置为 Edge Analytics 中的 client-ip 值。
- x-forwarded-host:(默认值:true)设置为 false 可防止 要传递给目标的 x-forwarded-host 标头。
- x-request-id:(默认值:true)设置为 false 可防止 要传递给目标的 x-request-id 标头。
- x-response-time:(默认值:true)设置为 false 以防止 要传递给目标的 x-response-time 标头。
- via:(默认值:true)设置为 false 可阻止通过标头 传递给目标。
OAuth 属性
这些设置用于配置 Edge Microgateway 如何强制执行客户端身份验证。
- allowNoAuthorization:(默认值:false)如果设置为 true,则会执行 API 调用 允许在没有任何授权标头的情况下通过 Edge Microgateway。将此项设为 false 表示需要使用授权标头(默认)。
- allowInvalidAuthorization:(默认值:false)如果设置为 true,则会执行 API 调用 在 Authorization 标头中传递的令牌无效或过期时允许传递。设置此项 设置为 false 则要求有效令牌(默认)。
- authorization-header:(默认值: Authorization: Bearer)用于 将访问令牌发送到 Edge Microgateway。如果遇到这种情况,您可能需要更改 目标需要使用 Authorization 标头来实现其他目的。
- api-key-header:(默认值:x-api-key)标头或查询的名称 参数,用于将 API 密钥传递给 Edge Microgateway。另请参阅使用 API 密钥。
- keep-authorization-header:(默认值:false)如果设为 true,则授权标头 会传递到目标(会得到保留)。
- allowOAuthOnly - 如果设置为 true,则每个 API 都必须带有授权 带有不记名访问令牌的标头。允许您仅允许 OAuth 安全模型(而 保持向后兼容性)。(添加了 2.4.x)
- allowAPIKeyOnly - 如果设置为 true,则每个 API 都必须带有 带有 API 密钥的 x-api-key 标头(或自定义位置)。允许您允许 仅 API 密钥安全模型(同时保持向后兼容性)。(添加了 2.4.x)
- gracePeriod - 此参数有助于防止由于轻度 系统时钟与“不早于”(nbf) 或颁发时间 (iat) 时间之间存在差异 指定 JWT 授权令牌。将此参数设置为允许的秒数 处理这些差异。(添加了 2.5.7)
插件专用 属性
要详细了解每个插件的可配置属性,请参阅“使用插件”。
过滤代理
您可以过滤 Edge Microgateway 实例将处理哪些 microgateway 感知代理。
Edge Microgateway 启动时,会下载
组织。使用以下配置来限制
microgateway 将对其进行处理。例如,此配置限制了 microgateway
将处理为三个:edgemicro_proxy-1
、edgemicro_proxy-2
、
和 edgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
配置 Google Analytics 推送频率
使用以下配置参数来控制 Edge Microgateway 发送的频率 导出到 Apigee:
- bufferSize(可选):读取广告 缓冲区可以在开始删除最早的记录之前持有。默认值:10000
- batchSize(可选):一批分析记录的大小上限 发送到 Apigee 的平台默认值:500
- flushInterval(可选):每次刷新间隔的毫秒数 将一批分析记录发送到 Apigee。默认值:5000
例如:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
遮盖分析数据
以下配置可防止请求路径信息显示在 Edge 中 分析。将以下内容添加到 microgateway 配置,以遮盖请求 URI 和/或 请求路径。请注意,URI 包含请求的主机名和路径部分。
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
在 Edge Analytics 中隔离 API 调用
您可以将分析插件配置为隔离特定的 API 路径,使其显示为 在 Edge Analytics 信息中心内使用单独的代理。例如,您可以 在信息中心内隔离健康检查 API,以免与实际的 API 代理调用混淆。在 Analytics 信息中心内,独立代理遵循以下命名模式:
edgemicro_proxyname-health
下图显示了 Google Analytics 信息中心内的两个独立代理:edgemicro_hello-health
和
edgemicro_mock-health
:
使用这些 参数,将 Google Analytics 信息中心内的相对路径和绝对路径隔离为单独的代理:
- relativePath(可选):指定要在
Analytics 信息中心。例如,如果您指定
/healthcheck
,则包含该路径的所有 API 调用/healthcheck
在信息中心内将显示为edgemicro_proxyname-health
。请注意,此标志会忽略代理基本路径。 如需根据完整路径(包括基本路径)进行隔离,请使用proxyPath
标志。 - proxyPath(可选):指定完整的 API 代理路径,包括代理
基本路径,在分析信息中心内隔离出来。例如,如果您指定
/mocktarget/healthcheck
, 其中/mocktarget
是代理基本路径,路径为/mocktarget/healthcheck
的所有 API 调用都将 在信息中心内显示为edgemicro_proxyname-health
。
例如,在以下配置中,包含 /healthcheck
的任何 API 路径都将
与分析插件隔离开来这意味着,/foo/healthcheck
和 /foo/bar/healthcheck
将在 Google Analytics 信息中心内被隔离为名为 edgemicro_proxyname-health
的单独代理。
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
在以下配置中,任何具有代理路径 /mocktarget/healthcheck
的 API
将被隔离为名为edgemicro_proxyname-health
的单独代理
查看分析信息中心
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
在 公司防火墙
支持的 v2.4.x
如果 Edge Microgateway 安装在防火墙后面,则网关可能无法 与 Apigee Edge 进行通信在这种情况下,您可以考虑以下两种选择:
选项 1:
第一个选项是在 microgateway 配置文件:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: true
当 proxy_tunnel 为 true 时,Edge Microgateway 会使用 HTTP CONNECT 方法,通过单一 TCP 连接传输 HTTP 请求。 (如果用于配置代理的环境变量启用了 TLS,也是如此)。
选项 2:
第二个选项是指定代理并将 microgateway 配置文件。例如:
edge_config: proxy: http://10.224.16.85:3128 proxy_tunnel: false
在这种情况下,您可以设置以下变量来控制每个 HTTP 的主机 或哪些主机不应处理 Edge Microgateway 代理: HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。
您可以将 NO_PROXY 设置为 Edge 的用英文逗号分隔的网域列表 Microgateway 不应代理到。例如:
export NO_PROXY='localhost,localhost:8080'
将 HTTP_PROXY 和 HTTPS_PROXY 设置为 HTTP 代理 端点 Edge Microgateway 可以向其发送消息。例如:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
如需详细了解这些变量,请参阅 https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
另请参阅
<ph type="x-smartling-placeholder"></ph> 如何在 Apigee 社区中设置公司防火墙后面的 Edge Microgateway。
在 Microgateway 感知中使用通配符 个指标
您可以使用一个或多个“*”或包含通配符
edgemicro_*(可感知 Microgateway)代理。例如,
/team/*/members 允许客户调用
https://[host]/team/blue/members 和
https://[host]/team/green/members,而无需创建新的 API 代理
为新团队提供支持请注意,不支持 /**/
。
重要提示:Apigee 不支持使用通配符“*”用作
基本路径的第一个元素。例如,不支持:/*/
搜索。
轮替 JWT 密钥
在最初生成 JWT 之后的某个时间,您可能需要更改 存储在 Edge 加密 KVM 中的公钥/私钥对。生成新密钥的过程 称为密钥轮替。
Edge Microgateway 如何使用 JWT
JSON 网络令牌 (JWT) 是 RFC7519 中所述的令牌标准。JWT 提供了对一组声明进行签名的方式 且可由 JWT 接收方进行可靠的验证。
Edge Microgateway 使用 JWT 作为 OAuth 安全性的不记名令牌。生成 是 Edge Microgateway 的 OAuth 令牌,您会收到一个 JWT。然后,您可以使用 API 调用的授权标头。例如:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
生成新的 JWT
您可以使用 edgemicro token
命令或
API。例如:
edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
此命令要求 Apigee Edge 生成 JWT,然后可用于验证 API
调用。-i
和 -s
参数是开发者应用中的消费者 ID 和密钥值
您的 Apigee Edge 组织。
或者,您也可以使用 Management API 生成 JWT:
curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "your consumer key", "client_secret": "your consumer secret", "grant_type": "client_credentials" }'
其中:
- org 是您的 Edge 组织名称(您必须是组织管理员)。
- env 是贵组织中的环境(例如“test”或“prod”)。
- client_id 是您之前创建的开发者应用中的消费者 ID。
- client_secret 是您创建的开发者应用中的使用方 Secret 。
什么是密钥轮替?
在最初生成 JWT 之后的某个时间,您可能需要更改 存储在 Edge 加密 KVM 中的公钥/私钥对。生成新密钥的过程 称为密钥轮替。当您轮替密钥时,系统会生成新的私钥/公钥对, 存储在“microgateway”您的 Apigee Edge 组织/环境中的 KVM。此外, 旧公钥及其原始密钥 ID 值会保留下来。
为了生成 JWT,Edge 会使用存储在加密 KVM 中的信息。答
在您最初设置(配置)时创建并填充了名为 microgateway
的 KVM,
Edge Microgateway。KVM 中的密钥用于对 JWT 进行签名和加密。
KVM 密钥包括:
-
private_key - 用于签名的最新(最近创建)RSA 私钥 JWT。
-
public_key - 用于验证 JWT 的最新(最近创建)证书 使用 private_key 进行签名。
-
private_key_kid - 最新(最近创建的)私钥 ID。此密钥 ID 与 private_key 值相关联,用于支持密钥轮替。
-
public_key1_kid - 最新(最近创建的)公钥 ID。此键为 与 public_key1 值相关联,用于支持密钥轮替。此值 与私钥小区相同。
-
public_key1 - 最新(最近创建的)公钥。
执行密钥轮替时,系统会替换映射中的现有密钥值, 密钥以保留旧的公钥。例如:
-
public_key2_kid - 旧的公钥 ID。此键与 public_key2 值,用于支持密钥轮替。
-
public_key2 - 旧的公钥。
将使用新的公钥对呈现以供验证的 JWT 进行验证。如果 验证失败,系统将使用旧公钥,直至公钥过期(30 分钟后)。在 通过这种方式,您可以密钥,而不会立即中断 API 流量。
如何进行密钥轮替
本部分介绍了如何执行密钥轮替。
如果您的 Edge Microgateway 实例低于 2.5.2 版
如果您在 2.5.2 之前的版本中配置了 Edge Microgateway 实例,则必须运行 使用以下两个命令升级 KVM 和身份验证政策:
upgradekvm -o org -e env -u username
有关此命令的详细信息,请参阅升级 KVM。
下一个命令会升级已部署到的 edgemicro-oauth 代理 Apigee 组织。此代理提供 生成词元。
upgradeauth -o org -e env -u username
有关此命令的详细信息,请参阅升级 Edgemicro-auth 代理。
轮替密钥
将以下代码行添加到 ~/.edgemicro/org-env-config.yaml
文件中,
指定您配置微网关所使用的同一组织和环境:
jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'
运行密钥轮替命令以轮替密钥。(有关此命令的详细信息,请参阅 轮替密钥。)
edgemicro rotatekey -o org -e env -u username -k kid_value
例如:
edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2 current nodejs version is v12.5.0 current edgemicro version is 3.0.2 password: Checking if private key exists in the KVM... Checking for certificate... Found Certificate Generating New key/cert pair... Extract new public key Key Rotation successfully completed!
-k
参数会指定密钥 ID (kid)。此 ID 用于匹配特定键。
Edge Microgateway 在密钥轮替期间使用此值在一组密钥中进行选择。有关
详情请参阅
JSON Web Key 规范。
密钥轮替后,Edge 会将多个密钥返回到 Edge Microgateway。备注 例如,每个键都有一个唯一的“kid”(键 ID)值。然后,微网关会使用 密钥来验证授权令牌。如果令牌验证失败,则微网关会向 查看键集中是否有较旧的键,并尝试该键。该 返回的密钥是 JSON 网络密钥 (JWK)。您可以在 RFC 7517 中了解此格式。
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
过滤下载的代理
默认情况下,Edge Microgateway 会下载 Edge 组织中的所有代理 名称前缀“edgemicro_”开头的应用了您可以更改此默认设置以下载代理 其名称与某个模式匹配。
- 打开 Edge Micro 配置文件:
~/.edgemicro/org-env-config.yaml
- 在 Edge_config 下添加 proxyPattern 元素。例如,以下格式
下载 Edgemicro_foo、edgemicro_fast 和 edgemicro_first 等代理。
edge_config: … proxyPattern: edgemicro_f*
指定没有 API 代理的产品
在 Apigee Edge 中,您可以创建不包含任何 API 代理的 API 产品。 此产品配置允许与该产品关联的 API 密钥用于任何 部署了代理从 2.5.4 版开始,Edge Microgateway 支持此产品 配置。
调试和问题排查
连接到调试程序
您可以使用调试程序(例如 node-inspector)运行 Edge Microgateway。这对于 自定义插件的问题排查和调试。
- 在调试模式下重启 Edge Microgateway。为此,请将
DEBUG=*
添加到start
命令的开头。例如:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
- 启动调试程序,并将其设置为监听调试过程的端口号。
- 现在,您可以逐步执行 Edge Microgateway 代码、设置断点、监视表达式, 依此类推。
您可以指定与调试模式相关的标准 Node.js 标志。例如:
--nolazy
有助于调试异步代码。
检查日志文件
如果您遇到问题,请务必检查日志文件以获取执行详情和错误 信息。有关详情,请参阅管理日志文件。
使用 API 密钥安全性
API 密钥提供了一种简单的机制,用于对向 Edge 发出请求的客户端进行身份验证 Microgateway。您可以通过复制使用方密钥(也称为“客户端 ID”)值来获取 API 密钥 。
缓存键
API 密钥交换为已缓存的不记名令牌。您可以通过将
发送到 Edge 的传入请求中的 Cache-Control: no-cache
标头
Microgateway。
使用 API 密钥
您可以在 API 请求中将 API 密钥作为查询参数或标头传递。默认情况下
标头和查询参数名称均为 x-api-key
。
查询参数示例:
curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz
标头示例:
curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
配置 API 密钥名称
默认情况下,x-api-key
是 API 密钥标头和查询参数使用的名称。
如更改配置中所述,您可以在配置文件中更改此默认设置。例如,要更改
apiKey:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
在此示例中,查询参数和标头名称均更改为 apiKey
。通过
无论是哪种情况,名称“x-api-key
”都将不再有效。另请参阅
更改配置。
例如:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
有关将 API 密钥用于代理请求的详细信息,请参阅 Secure Edge Microgateway。
启用上行响应代码
默认情况下,如果存在以下情况,oauth
插件仅返回 4xx 错误状态代码
该响应不是 200 状态。您可以更改此行为,
根据错误返回确切的 4xx 或 5xx 代码。(在版本 3.0.7 中发布)
如需启用此功能,请添加 oauth.useUpstreamResponse: true
属性添加到 Edge Microgateway 配置。例如:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
使用 OAuth2 令牌安全性
本部分介绍了如何获取 OAuth2 访问令牌和刷新令牌。访问令牌用于 确保 API 调用的安全性。刷新令牌用于获取新的访问令牌。
如何获取访问令牌
本部分介绍了如何使用 edgemicro-auth
代理获取访问令牌。
您还可以使用 edgemicro token
CLI 命令获取访问令牌。
如需详细了解 CLI,请参阅管理令牌。
API 1:将凭据作为正文参数发送
替换网址中的组织和环境名称,并 请替换从 Apigee 上的开发者应用获取的使用方 ID 和使用方密钥值 client_id 和 client_secret 正文参数的 Edge:
curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \ -d '{"grant_type": "client_credentials", "client_id": "your_client_id", \ "client_secret": "your_client_secret"}' -H "Content-Type: application/json"
API 2:在基本身份验证标头中发送凭据
将客户端凭据作为基本身份验证标头发送,
grant_type
作为表单参数。关于此命令格式
RFC 6749:OAuth 2.0 授权框架。
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
输出示例
API 会返回 JSON 响应。请注意,token
和
access_token
属性。您可以使用其中任何一个。
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": "108000" }
如何获取刷新令牌
要获取刷新令牌,请对/token
edgemicro-auth
代理。您必须使用 password
进行此 API 调用
授权类型。您可以按照以下步骤操作。
- 通过
/token
API 获取访问令牌和刷新令牌。请注意, 授权类型为password
:curl -X POST \ https://your_organization-your_environment.apigee.net/edgemicro-auth/token \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq", "client_secret":"bUdDcFgv3nXffnU", "grant_type":"password", "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq", "password":"bUdD2FvnMsXffnU" }'
该 API 会返回一个访问令牌和一个刷新令牌。响应类似于 :
{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": "108000", "refresh_token": "your-refresh-token", "refresh_token_expires_in": "431999", "refresh_token_issued_at": "1562087304302", "refresh_token_status": "approved" }
- 现在,您可以调用
同一 API 的
/refresh
端点。例如:curl -X POST \ https://willwitman-test.apigee.net/edgemicro-auth/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq", "client_secret":"bUdDc2Fv3nMXffnU", "grant_type":"refresh_token", "refresh_token":"your-refresh-token" }'
API 会返回一个新的访问令牌。响应类似于以下内容:
{ "token": "your-new-access-token" }
永久监控
Forever是一种 Node.js 工具 在进程停止或出现错误时,自动重启 Node.js 应用。边缘 Microgateway 包含一个 forever.json 文件,您可以配置该文件来控制 Edge Microgateway 需要重启的时间以及间隔时间。此文件将 名为 forever-monitor 的永久服务,用于永久管理 以编程方式
您可以在 Edge Microgateway 根安装中找到 forever.json 文件 目录。请参阅 Edge Microgateway 的安装位置。有关配置选项的详细信息,请参阅 forever-monitor 文档。
edgemicro forever
命令包含一些标志,可用于指定
forever.json
文件(-f
标志),以及启动/停止“永久”监控
进程(-a
标志)。例如:
edgemicro forever -f ~/mydir/forever.json -a start
如需了解详情,请参阅 CLI 参考文档中的永久监控。
指定配置文件端点
如果您运行多个 Edge Microgateway 实例,您可能希望管理其配置 。为此,您可以指定一个 HTTP 端点 下载其配置文件使用以下命令启动 Edge Micro 时,您可以指定此端点: -u 标志。
例如:
edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key
其中,mgconfig 端点会返回配置文件的内容。这就是文件
该属性默认位于 ~/.edgemicro
中,并采用以下命名惯例:
org-env-config.yaml
。
停用 TCP 连接数据缓冲
您可以使用 nodelay
配置属性为以下内容停用数据缓冲:
Edge Microgateway 使用的 TCP 连接。
默认情况下,TCP 连接使用 Nagle
算法在发送数据之前缓冲数据。正在将 nodelay
设置为 true
,
停用此行为(每次
调用 socket.write()
)。另请参阅 Node.js
文档了解详情。
如需启用 nodelay
,请按如下方式修改 Edge Micro 配置文件:
edgemicro: nodelay: true port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
在独立模式下运行 Edge Microgateway
您可以运行与任何设备完全断开连接的 Edge Microgateway Apigee Edge 依赖项。这种场景称为独立模式,可让您运行和测试 Edge Microgateway 无法连接互联网。
在独立模式下,以下功能无法运行,因为它们需要连接到网络 迁移到 Apigee Edge:
- OAuth 和 API 密钥
- 配额
- 分析
另一方面,自定义插件和高峰控制可以正常工作,因为它们
需要连接到 Apigee Edge。此外,借助一个名为 extauth
的新插件,
在独立模式下使用 JWT 授权对微网关的 API 调用。
配置和启动网关
如需在独立模式下运行 Edge Microgateway,请执行以下操作:
- 请确保您已安装 Edge Microgateway 3.0.1 或更高版本。否则,您必须
执行以下命令以升级到最新版本:
npm install -g edgemicro
如果您需要帮助,请参阅安装 Edge Microgateway。
- 创建一个名为
$HOME/.edgemicro/
org_name-
env_name-config.yaml
的配置文件例如:
vi $HOME/.edgemicro/foo-bar-config.yaml
- 将以下代码粘贴到此文件中:
edgemicro: port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - extauth - spikearrest headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true extauth: publickey_url: https://www.googleapis.com/oauth2/v1/certs spikearrest: timeUnit: second allow: 10 buffersize: 0
- 导出以下值为“1”的环境变量:
export EDGEMICRO_LOCAL=1
- 执行以下
start
命令,您可以在其中提供值以实例化 本地代理:edgemicro start -o org_name -e environment_name -a local_proxy_name \ -v local_proxy_version -t target_url -b base_path
其中:
- your_org 是“组织”您在配置文件名称中使用的名称
- your_environment 是“env”您在配置文件中使用的 名称。
- local_proxy_name 是将创建的本地代理的名称。您可以使用 随意命名。
- local_proxy_version 是代理的版本号。
- target_url 是代理目标的网址。(目标是 (由代理调用的服务)。
- base_path 是该代理的基本路径。此值必须以正向开头 斜杠。对于根基本路径,只需指定正斜杠;例如“/”。
例如:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- 测试配置。
curl http://localhost:8000/echo { "error" : "missing_authorization" }
由于
extauth
插件位于foo-bar-config.yaml
文件中,因此您需要 获取“missing_authorization”错误。此插件用于验证授权中必须包含的 JWT API 调用的标头。在下一部分中,您将获取允许 API 调用的 JWT 以确保整个过程不会出现错误
示例:获取授权令牌
以下示例展示了如何从 Apigee Edge 上的 Edge Microgateway JWT 端点 (edgemicro-auth/jwkPublicKeys
) 获取 JWT。
当您对 Edge Microgateway 执行标准设置和配置时,系统会部署此端点。
要从 Apigee 端点获取 JWT,您必须先执行标准的 Edge Microgateway 设置,并且
必须连接到互联网。此处以 Apigee 端点为例进行说明
,不是必需的。如果您愿意,可以使用其他 JWT 令牌端点。如果包含,则需要使用
为该端点提供的 API。
以下步骤说明了如何使用 edgemicro-auth/jwkPublicKeys
端点获取令牌:
- 您必须执行标准
设置和配置 Edge Microgateway,以部署
edgemicro-auth
代理 Apigee Edge 上的组织/环境。如果您以前执行过此步骤,则无需重复。 - 如果您已将 Edge Microgateway 部署到 Apigee Cloud,则必须连接到互联网,以便从此端点获取 JWT。
-
停止 Edge Microgateway:
edgemicro stop
- 在您之前创建的配置文件 (
$HOME/.edgemicro
/org-env-config.yaml
) 中, 指向extauth:publickey_url
属性添加到 Apigee Edge 组织/环境中的edgemicro-auth/jwkPublicKeys
端点。例如:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
使用您在配置文件名称中使用的组织/环境名称,像之前一样重启 Edge Microgateway。例如:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
从授权端点获取 JWT 令牌。因为您使用的是
edgemicro-auth/jwkPublicKeys
可以使用此 CLI 命令:
您可以使用 edgemicro token
命令或
API。例如:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
其中:
- your_org 是您之前为其创建的 Apigee 组织的名称 已配置 Edge Microgateway。
- your_env 是组织中的环境。
i
选项用于指定具有商品的开发者应用中的使用方密钥 (包含edgemicro-auth
代理)。s
选项用于指定来自满足以下条件的开发者应用的使用方密钥: 产品的edgemicro-auth
代理。
此命令要求 Apigee Edge 生成 JWT,然后可用于验证 API 调用。
另请参阅生成令牌。测试独立配置
如需测试配置,请使用 Authorization 标头中添加的令牌调用 API,如下所示:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
示例:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
输出示例:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
使用本地代理模式
在本地代理模式下,Edge Microgateway 不需要 microgateway-aware 代理 要部署在 Apigee Edge 上您可以配置“本地代理”通过提供 本地代理名称、基本路径和目标网址 启动 microgateway。然后,对 microgateway 的 API 调用会发送到目标 本地代理的网址。在所有其他方面,本地代理模式与 处于普通模式的 Edge Microgateway。身份验证的工作原理与峰值一样 限制和配额强制执行、自定义插件等。
用例和示例
当您只需将单个代理与 Edge Microgateway 相关联时,本地代理模式非常有用 实例。例如,您可以将 Edge Microgateway 作为 Sidecar 代理添加到 Kubernetes 中, microgateway 和 2 个 Service 均在单个 Pod 中运行,而 microgateway 则通过 microgateway 管理 以及相应的配套服务下图说明了这种架构 Microgateway 在 Kubernetes 集群中用作 Sidecar 代理。每个微网关实例 仅发送到其配套服务上的单个端点:
这种架构的一大优势是 管理部署到容器环境中的各项服务,例如 Kubernetes 集群
配置本地代理模式
如需将 Edge Microgateway 配置为在本地代理模式下运行,请按以下步骤操作:
- 请确保您已安装 Edge Microgateway 3.0.1 或更高版本。否则,您必须
执行以下命令以升级到最新版本:
npm install -g edgemicro
如果您需要帮助,请参阅安装 Edge Microgateway。
- 运行
edgemicro init
以准确设置本地配置环境 就像在典型的 Edge Microgateway 设置中一样。另请参阅 配置 Edge Microgateway。 - 像在典型的 Edge Microgateway 设置中一样运行
edgemicro configure
过程。例如:edgemicro configure -o your_org -e your_env -u your_apigee_username
此命令会将 edgemicro-auth 政策部署到 Edge 并返回密钥 和 Secret(启动微网关所需的密钥)。如果您需要帮助,请参阅 配置 Edge Microgateway。
- 在 Apigee Edge 上,创建 API 产品并使用以下强制性配置
要求(您可以根据需要管理所有其他配置):
<ph type="x-smartling-placeholder">
- </ph>
- 您必须为产品添加 edgemicro-auth 代理。此代理
是在您运行
edgemicro configure
时自动部署的。 - 您必须提供资源路径。Apigee 建议将此路径添加到
商品:
/**
。如需了解详情,请参阅配置资源路径的行为。另请参阅创建 API 请参阅 Edge 文档。
- 您必须为产品添加 edgemicro-auth 代理。此代理
是在您运行
在 Apigee Edge 上创建开发者。如果您有其他需求,也可以使用现有开发者 愿望。如需帮助,请参阅使用 Edge 管理界面添加开发者。
- 在 Apigee Edge 上,创建一个开发者应用。您必须将 API 产品添加到 新创建的应用如需帮助,请参阅在 Edge 中注册应用 管理界面。
- 在安装了 Edge Microgateway 的机器上,导出以下内容
环境变量,其中值为“1”。
export EDGEMICRO_LOCAL_PROXY=1
- 执行以下
start
命令:edgemicro start -o your_org -e your_environment -k your_key -s your_secret \ -a local_proxy_name -v local_proxy_version -t target_url -b base_path
其中:
- your_org 是您的 Apigee 组织。
- your_environment 是贵组织中的环境。
- your_key 是应用运行时返回的键
edgemicro configure
。 - your_secret 是运行密钥时返回的 Secret
edgemicro configure
。 - local_proxy_name 是将创建的本地代理的名称。
- local_proxy_version 是代理的版本号。
- target_url 是代理目标(代理将 调用)。
- base_path 是该代理的基本路径。此值必须以正向开头 斜杠。对于根基本路径,只需指定正斜杠;例如“/”。
例如:
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \ -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \ -t http://mocktarget.apigee.net -b /echo
测试配置
您可以通过调用代理端点来测试本地代理配置。例如:
如果您将基本路径指定为 /echo
,则可以按如下方式调用该代理:
curl http://localhost:8000/echo { "error" : "missing_authorization", "error_description" : "Missing Authorization header" }
此初始 API 调用产生了错误,因为您没有提供有效的 API 密钥。您可以找到 找到之前创建的开发者应用在 Edge 界面中打开应用,复制 使用方密钥,并按如下方式使用该密钥:
curl http://localhost:8000/echo -H 'x-api-key:your_api_key'
例如:
curl http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"
输出示例:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }