Edge Microgate 操作和配置参考

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

Edge Microgate v. 2.5.x

本主题讨论如何管理和配置 Edge Microgate。

在连接到互联网的情况下升级 Edge Microgate

  1. 执行以下 npm 命令以升级到最新版本的 Edge Microgate:
    npm upgrade edgemicro -g

    如需升级到特定版本的 Edge Microgate,您需要在升级命令中指定版本号。如果您未指定版本号,系统会安装最新版本。例如,如需升级到版本 2.5.26,请使用以下命令:

    npm upgrade edgemicro@2.5.26 -g
  2. 检查版本号。例如,如果您安装了版本 2.5.26:
    edgemicro --version
    current nodejs version is v8.9.0
    current edgemicro version is 2.5.26
        
  3. 最后,升级到最新版本的 edgemicro-auth 代理:
    edgemicro upgradeauth -o org_name -e env_name -u username

更改配置

您需要了解的配置文件包括:

  • 默认系统配置文件
  • 新初始化的 Edge Microgate 实例的默认配置文件
  • 用于正在运行的实例的动态配置文件

本部分将讨论这些文件,以及您需要了解的关于更改的注意事项。

默认系统配置文件

安装 Edge Microgate 时,默认系统配置文件会放在这里:

prefix/lib/node_modules/edgemicro/config/default.yaml

其中,prefixnpm 前缀目录。如果您找不到此目录,请参阅 Edge Microgate 的安装位置

如果您更改系统配置文件,则必须重新初始化、重新配置并重启 Edge Microgate 网关:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

新初始化的 Edge Microgate 实例的默认配置文件

当您运行 edgemicro init 时,系统会将系统配置文件(如上所述)default.yaml 放在 ~/.edgemicro 目录中。

如果您在 ~/.edgemicro 中更改配置文件,则必须重新配置并重启 Edge Microgate 网关:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

用于运行实例的动态配置文件

当您运行 edgemicro configure [params] 时,系统会在 ~/.edgemicro 中创建动态配置文件。该文件按以下格式命名:org-env-config.yaml,其中 orgenv 是您的 Apigee Edge 组织和环境的名称。您可以使用此文件进行配置更改,然后在零停机的情况下重新加载它们。例如,如果您添加并配置了一个插件,则可以重新加载配置,而无需停机(如下所述)。

如果 Edge Microgate 正在运行(零停机选项)

  1. 重新加载 Edge Microgate 配置:
    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 Microgate 停止

  1. 重启 Edge Microgate:
    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 Microgate 配置参考文档

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 Microgate 所需的密钥和密钥的命令行界面命令可以存储在以下环境变量中:

  • EDGEMICRO_ORG
  • EDGEMICRO_ENV
  • EDGEMICRO_KEY
  • EDGEMICRO_SECRET

设置这些变量是可选操作。设置好这些参数后,在使用命令行界面 (CLI) 配置和启动 Edge Microgate 时,您不必指定它们的值。

在 Edge Microgate 服务器上配置 SSL

您可以将 Microgate 服务器配置为使用 SSL。例如,配置 SSL 后,您可以通过使用“https”协议的 Edge Microgate 调用 API,如下所示:

https://localhost:8000/myapi

如需在 Microgate 服务器上配置 SSL,请按以下步骤操作:

  1. 使用 openssl 实用程序或您偏好的任何方法生成或获取 SSL 证书和密钥。
  2. edgemicro:ssl 属性添加到 Edge Microgate 配置文件中。如需查看完整的选项列表,请参阅下表。例如:
    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
  3. 重启 Edge Microgate。根据您修改的是默认文件或运行时配置文件,按照更改配置中列出的步骤操作。

以下是配置文件的 edgemicro 部分的示例,其中配置了 SSL:

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 pfx 文件的路径,该文件包含客户端的 PFX 格式的私钥、证书和 CA 证书。
passphrase 包含私钥或 PFX 的密码的字符串。
ca 指向包含 PEM 格式的可信证书列表的文件的路径。
ciphers 描述要使用的加密的字符串,以“:”分隔。
rejectUnauthorized 如果为 true,则根据提供的 CA 列表验证服务器证书。如果验证失败,则会返回错误。
secureProtocol 要使用的 SSL 方法。例如,SSLv3_method 将 SSL 强制设置为版本 3。
servername SNI(服务器名称指示)TLS 扩展的服务器名称。
requestCert 对于双向 SSL,为 true;对于单向 SSL,为 false

使用客户端 SSL/TLS 选项

在连接到目标端点时,您可以将 Edge Microgate 配置为 TLS 或 SSL 客户端。在 Microgate 配置文件中,使用目标元素设置 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 pfx 文件的路径,该文件包含客户端的 PFX 格式的私钥、证书和 CA 证书。
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 Microgate 使用部署在 Apigee Edge 上的代理进行 OAuth2 身份验证。此代理会在您首次运行 edgemicro configure 时部署。您可以更改此代理的默认配置,以向 JSON Web 令牌 (JWT) 添加对自定义声明的支持、配置令牌过期时间并生成刷新令牌。如需了解详情,请参阅 GitHub 中的 edgemicro-auth 页面。

使用自定义身份验证服务

默认情况下,Edge Microgate 使用部署在 Apigee Edge 上的代理进行 OAuth2 身份验证。此代理会在您首次运行 edgemicro configure 时部署。默认情况下,此代理的网址在 Edge Microgate 配置文件中指定,如下所示:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

如果要使用自己的自定义服务处理身份验证,请将配置文件中的 authUri 值更改为指向您的服务。例如,您可能有一项服务使用 LDAP 验证身份。

管理日志文件

Edge Microgate 会记录每个请求和响应的相关信息。日志文件为调试和问题排查提供了有用的信息。

日志文件的存储位置

默认情况下,日志文件存储在 /var/tmp 中。

如何更改默认的日志文件目录

日志文件的存储目录在 Edge Microgate 配置文件中指定。另请参阅更改配置

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

选择此设置后,日志将发送至标准输出。目前,您无法将日志同时发送到 stdout 和日志文件。

如何设置日志记录级别

您可以设置以下日志级别:infowarnerror。建议设置信息等级。它会记录所有 API 请求和响应,并且是默认设置。

如何更改日志间隔

您可以在 Edge Microgate 配置文件中配置这些时间间隔。另请参阅更改配置

可配置的属性包括:

  • 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 Microgate 实例都会生成三种类型的日志文件:

  • api - 记录流经 Edge Microgate 的所有请求和响应。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 网络令牌 (JWT) 的 JSON。如果要将这些对象输出到日志文件中,请在启动 Edge Microgate 时设置 DEBUG=*。例如:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

“api”日志文件的内容

“api”日志文件包含有关通过 Edge Microgate 的请求和响应流的详细信息。“api”日志文件的名称如下所示:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

对于向 Edge Microgate 发出的每个请求,“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 - 取决于具体情况。可能是 info、warn 或 error,具体取决于日志级别。可以是统计信息记录的统计信息、有关警告的警告或错误的错误。
  • req - 标识事件。在这种情况下,这是来自客户端的请求。
  • m - 请求中使用的 HTTP 动词。
  • u - 网址中基本路径后面的部分。
  • h - Edge Microgate 监听的主机和端口号。
  • r - 发起客户端请求的远程主机和端口。
  • i - 请求 ID。所有 4 个事件条目共用此 ID。每个请求都分配有一个唯一的请求 ID。按请求 ID 关联日志记录可让您深入了解目标的延迟时间。
  • d - 自 Edge Microgate 收到请求以来的时长(以毫秒为单位)。在上面的示例中,目标在 7 毫秒后收到请求 0 的响应(第 3 行),并在额外的 4 毫秒后将响应发送到客户端(第 4 行)。换句话说,请求总延迟时间为 11 毫秒,其中目标为 7 毫秒,Edge Microgate 本身占用了 4 毫秒。

2. 向目标发出的传出请求的示例:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
  • 1436403888651 - Unix 日期戳
  • info - 取决于具体情况。可能是 info、warn 或 error,具体取决于日志级别。可以是统计信息记录的统计信息、有关警告的警告或错误的错误。
  • treq - 标识事件。在本例中,即目标请求。
  • m - 目标请求中使用的 HTTP 动词。
  • u - 网址中基本路径后面的部分。
  • h - 后端目标的主机和端口号。
  • i - 日志条目的 ID。所有四个事件条目将共用此 ID。

3. 来自目标的传入响应示例

1436403888672 info tres s=200, d=7, i=0

1436403888651 - Unix 日期戳

  • info - 取决于具体情况。可能是 info、warn 或 error,具体取决于日志级别。可以是统计信息记录的统计信息、有关警告的警告或错误的错误。
  • tres - 用于标识事件。在此示例中,目标响应为。
  • s - HTTP 响应状态。
  • d - 时长(以毫秒为单位)。目标调用 API 所花费的时间。
  • i - 日志条目的 ID。所有四个事件条目将共用此 ID。

4. 对客户端的传出响应示例

1436403888676 info res s=200, d=11, i=0

1436403888651 - Unix 日期戳

  • info - 取决于具体情况。可能是 info、warn 或 error,具体取决于日志级别。可以是统计信息记录的统计信息、有关警告的警告或错误的错误。
  • res - 用于标识事件。在这种情况下,是对客户端的响应。
  • s - HTTP 响应状态。
  • d - 时长(以毫秒为单位)。这是 API 调用所用的总时间,包括目标 API 所用的时间以及 Edge Microgate 本身所用的时间。
  • i - 日志条目的 ID。所有四个事件条目将共用此 ID。

日志文件时间表

日志文件会按 rotate_interval 配置属性指定的间隔轮替。系统会继续向同一日志文件中添加条目,直到轮替间隔到期。但是,每次重启 Edge Microgate 时,它都会收到一个新的 UID,并会使用此 UID 创建一组新的日志文件。另请参阅良好的日志文件维护做法

错误消息

某些日志条目包含错误消息。为帮助确定错误发生的位置和原因,请参阅 Edge Microgate 错误参考文档

Edge Microgate 配置参考文档

配置文件的位置

本部分介绍的配置属性位于 Edge Microgate 配置文件中。另请参阅更改配置

Edge_config 属性

这些设置用于配置 Edge Microgate 实例与 Apigee Edge 之间的交互。

  • bootstrap:(默认值:无)指向在 Apigee Edge 上运行的 Edge Microgate 专用服务的网址。Edge Microgate 使用此服务与 Apigee Edge 通信。当您执行生成公钥/私钥对的命令时,系统会返回此网址:edgemicro genkeys。如需了解详情,请参阅设置和配置 Edge Microgate
  • jwt_public_key:(默认值:none)指向 Apigee Edge 上部署的 Edge Microgate 代理的网址。此代理充当向客户端颁发已签名的访问令牌的身份验证端点。当您执行命令来部署代理时,系统会返回此网址:edgemicro configure。如需了解详情,请参阅设置和配置 Edge Microgate

Edgemicro 属性

这些设置用于配置 Edge Microgate 进程。

  • port:(默认值:8000)Edge Microgate 进程监听的端口号。
  • max_connections:(默认值:-1)指定 Edge Microgate 可以接收的并发传入连接数上限。如果超出此限值,系统会返回以下状态:

    res.statusCode = 429; // Too many requests
  • max_connections_hard:(默认值:-1)在关闭连接之前,Edge Microgate 可以接收的并发请求数量上限。此设置旨在防范拒绝服务攻击。通常,应将其设置为大于 max_connections 的数字。
  • logging
    • level:(默认值:error)
      • info - 记录流经 Edge Microgate 实例的所有请求和响应。
      • warn - 仅记录警告消息。
      • error - 仅记录错误消息。
    • dir:(默认值:/var/tmp)存储日志文件的目录。
    • stats_log_interval:(默认值:60)将统计信息记录写入 API 日志文件时的间隔时间(以秒为单位)。
    • rotate_interval:(默认值:24)轮播日志文件时的间隔时间(以小时为单位)。
  • plugins:插件用于向 Edge Microgate 添加功能。如需详细了解如何开发插件,请参阅开发自定义插件
  • dir:从 ./gate 目录到 ./plugins 目录的相对路径,或绝对路径。
  • sequence:要添加到 Edge Microgate 实例的插件模块列表。模块将按此处指定的顺序执行。
  • debug :向 Edge Microgate 进程添加远程调试功能。
    • port:要监听的端口号。例如,将 IDE 调试程序设置为监听此端口。
    • args:调试过程的参数。例如:args --nolazy
  • config_change_poll_interval::(默认值:600 秒)Edge Microgate 会定期加载新配置,并在发生任何更改时执行重新加载。轮询会提取对 Edge 所做的任何更改(对产品、微网关感知代理等所做的更改)以及对本地配置文件所做的更改。
  • disable_config_poll_interval::(默认值:false)设置为 disable_config_poll_interval:disable_config_poll_interval:自动更改轮询。
  • request_timeout:为目标请求设置超时。超时时间设置为以秒为单位。如果发生超时,Edge Microgate 将返回 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 Microgate 强制执行客户端身份验证的方式。

  • allowNoAuthorization(默认值:false)如果设置为 true,则允许 API 调用在没有任何授权标头的情况下通过 Edge Microgate 标头。将此项设置为 false 可要求使用 Authorization 标头(默认)。
  • allowInvalidAuthorization(默认值:false)如果设置为 true,则在 Authorization 标头中传递的令牌无效或过期时允许 API 调用传递。请将此项设置为 false 以要求提供有效令牌(默认)。
  • authorization-header:(默认值: Authorization: Bearer)用于将访问令牌发送到 Edge Microgate 的标头。如果目标需要使用 Authorization 标头实现其他目的,您可能希望更改默认设置。
  • api-key-header:(默认值:x-api-key)用于将 API 密钥传递给 Edge Microgate 的标头或查询参数的名称。另请参阅使用 API 密钥
  • keep-authorization-header(默认值:false)如果设置为 true,则请求中发送的 Authorization 标头会传递到目标(保留该标头)。
  • allowOAuthOnly - 如果设置为 true,则每个 API 都必须带有包含不记名访问令牌的授权标头。仅允许使用 OAuth 安全模型(同时保持向后兼容性)。(添加于 2.4.x)
  • allowAPIKeyOnly - 如果设置为 true,则每个 API 都必须携带带有 API 密钥的 x-api-key 标头(或自定义位置)。通过此设置,您可以仅允许使用 API 密钥安全模型(同时保持向后兼容性)。(新增 2.4.x)
  • gracePeriod - 此参数有助于防止因系统时钟与 JWT 授权令牌中指定的不早于 (nbf) 或颁发时间 (iat) 时间之间存在细微差异而引发的错误。请将此参数设置为允许出现此类差异的秒数。(添加于 2.5.7 版)

插件专用属性

如需详细了解每个插件的可配置属性,请参阅“使用插件”。

过滤代理

您可以过滤 Edge Microgate 实例将处理哪些微网关感知型代理。Edge Microgate 启动时,它会下载与其关联的组织中所有感知到微网关的代理。使用以下配置来限制微网关将处理哪些代理。例如,此配置将微网关将处理的代理限制为三个:edgemicro_proxy-1edgemicro_proxy-2edgemicro_proxy-3

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

配置 Google Analytics(分析)推送频率

使用以下配置参数来控制 Edge Microgate 向 Apigee 发送分析数据的频率:

  • bufferSize(可选):在开始删除最早的记录之前,缓冲区可以容纳的最大分析记录数。默认值:10000
  • batchSize(可选):发送到 Apigee 的一批分析记录的大小上限。默认值:500
  • flushInterval(可选):每次清空发送到 Apigee 的一批分析记录之间的毫秒数。默认值:5000

例如:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮盖分析数据

以下配置可防止请求路径信息显示在边缘分析中。将以下内容添加到微网关配置,以遮盖请求 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

下图显示了 Analytics 信息中心内的两个隔离代理:edgemicro_hello-healthedgemicro_mock-health

使用这些参数可将 Analytics 信息中心内的相对路径和绝对路径作为单独的代理进行分隔:

  • relativePath(可选):指定要在 Analytics 信息中心内隔离的相对路径。例如,如果您指定 /healthcheck,则包含路径 /healthcheck 的所有 API 调用都将在信息中心内显示为 edgemicro_proxyname-health。请注意,此标志会忽略代理基本路径。 如需根据完整路径(包括基本路径)进行隔离,请使用 proxyPath 标志。
  • proxyPath(可选):指定要在分析信息中心内隔离的完整 API 代理路径(包括代理基本路径)。例如,如果您指定 /mocktarget/healthcheck,其中 /mocktarget 是代理基本路径,则路径为 /mocktarget/healthcheck 的所有 API 调用都将在信息中心内显示为 edgemicro_proxyname-health

例如,在以下配置中,分析插件会隔离包含 /healthcheck 的任何 API 路径。这意味着,/foo/healthcheck/foo/bar/healthcheck 在分析信息中心内将被分离为名为 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

在公司防火墙后设置 Edge Microgate

支持 v2.4.x

如果 Edge Microgate 安装在防火墙后面,网关可能无法与 Apigee Edge 通信。在这种情况下,您可以考虑采用以下两种方式:

选项 1:

第一个选项是在 microgate 配置文件中将 edgemicro:proxy_tunnel 选项设置为 true:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

proxy_tunneltrue 时,Edge Microgate 会使用 HTTP CONNECT 方法通过单个 TCP 连接建立 HTTP 请求隧道。(如果用于配置代理的环境变量启用了 TLS,也是如此)。

选项 2:

第二个选项是指定代理,并在微网关配置文件中将 agent_tunnel 设置为 false。例如:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

在这种情况下,您可以设置以下变量来控制要使用的每个 HTTP 代理的主机,或者哪些主机不应处理 Edge Microgate 代理:HTTP_PROXYHTTPS_PROXYNO_PROXY

您可以将 NO_PROXY 设置为 Edge Microgate 不应代理的网域列表(以英文逗号分隔)。例如:

export NO_PROXY='localhost,localhost:8080'

HTTP_PROXYHTTPS_PROXY 设置为 HTTP 代理端点,Edge Microgate 可以向其发送消息。例如:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

如需详细了解这些变量,请参阅 https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

另请参阅

在 Apigee 社区中, 如何在公司防火墙后面设置 Edge Microgate

在微网关感知型代理中使用通配符

您可以在 edgemicro_*(Microgate 感知)代理的基本路径中使用一个或多个“*”通配符。例如,借助 /team/*/members 的基本路径,客户端可以调用 https://[host]/team/blue/membershttps://[host]/team/green/members,而无需创建新的 API 代理来支持新团队。请注意,不支持 /**/

重要提示:Apigee 不支持将通配符“*”用作基本路径的第一个元素。例如,以下查询不受支持:/*/ 搜索。

轮替 JWT 密钥

在首次生成 JWT 后,您可能需要更改存储在 Edge 加密 KVM 中的公钥/私钥对。生成新密钥对的这一过程称为密钥轮替。

Edge Microgate 如何使用 JWT

JSON Web 令牌 (JWT) 是 RFC7519 中所述的令牌标准。JWT 提供了一种对一组声明进行签名的方法,JWT 接收方可以可靠地验证这些声明。

Edge Microgate 将 JWT 用作 OAuth 安全性的不记名令牌。为 Edge Microgate 生成 OAuth 令牌时,您会收到 JWT。然后,您可以在 API 调用的授权标头中使用 JWT。例如:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

生成新的 JWT

您可以使用 edgemicro token 命令或 API 为 Edge Microgate 生成 JWT。例如:

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

此命令要求 Apigee Edge 生成 JWT,然后使用该 JWT 验证 API 调用。-i-s 参数是 Apigee Edge 组织中开发者应用的使用方 ID 和 Secret 值。

或者,您也可以使用 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 是贵组织的环境(例如“测试”或“生产”)。
  • client_id 是您之前创建的开发者应用中的消费者 ID。
  • client_secret 是您之前创建的开发者应用中的使用方密钥。

什么是密钥轮替?

在首次生成 JWT 后,您可能需要更改存储在 Edge 加密 KVM 中的公钥/私钥对。生成新密钥对的这一过程称为密钥轮替。轮替密钥时,系统会生成新的私钥/公钥对,并将其存储在 Apigee Edge 组织/环境的“microgate”KVM 中。此外,旧公钥及其原始密钥 ID 值会保留。

为了生成 JWT,Edge 使用加密的 KVM 中存储的信息。您在最初设置(已配置)Edge Microgate 时,会创建名为 microgateway 的 KVM,并使用密钥进行填充。KVM 中的密钥用于对 JWT 进行签名和加密。

KVM 密钥包括:

  • private_key - 用于为 JWT 签名的最新(最近创建的)RSA 私钥。

  • public_key - 最新(最近创建的)证书,用于验证使用 private_key 签名的 JWT。

  • 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 流量。

如何进行密钥轮替

本部分介绍如何执行密钥轮替。

如果您在版本 2.5.2 之前配置了 Edge Microgate 实例

如果您在版本 2.5.2 之前配置了 Edge Microgate 实例,则必须运行以下两个命令来升级 KVM 和身份验证政策:

upgradekvm -o org -e env -u username

如需详细了解此命令,请参阅升级 KVM

下一个命令会升级您在配置 Edge Microgate 时部署到 Apigee 组织的 edgemicro-oauth 代理。此代理提供生成令牌所需的服务。

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 v6.9.1
current edgemicro version is 2.5.7
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(儿童)。此 ID 用于匹配特定键。 在密钥轮替期间,Edge Microgate 使用此值来选择一组密钥。如需了解详情,请参阅 JSON Web 密钥规范第 4.5 节

密钥轮替后,Edge 会向 Edge Microgate 返回多个密钥。请注意,在下面的示例中,每个键都有一个唯一的“kid”(密钥 ID)值。然后,微网关使用这些密钥来验证授权令牌。如果令牌验证失败,微网关会检查密钥集中是否有较旧的密钥,并尝试查找该密钥。返回的密钥的格式为 JSON Web 密钥 (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 Microgate 会下载您 Edge 组织中名称前缀为“edgemicro_”开头的所有代理。您可以更改此默认值以下载名称与模式匹配的代理。

  1. 打开 Edge Micro 配置文件:~/.edgemicro/org-env-config.yaml
  2. 在 Edge_config 下添加 ProxyPattern 元素。例如,以下模式将下载 Edgemicro_foo、edgemicro_Fast 和 edgemicro_first 等代理。
    edge_config:
    …
    proxyPattern: edgemicro_f*

指定不使用 API 代理的产品

在 Apigee Edge 中,您可以创建不包含任何 API 代理的 API 产品。 此产品配置允许与该产品关联的 API 密钥与贵组织中部署的任何代理配合使用。从 2.5.4 版开始,Edge Microgate 支持此产品配置。

调试和问题排查

连接到调试程序

您可以使用调试程序(例如 node-inspector)运行 Edge Microgate。这对于排查和调试自定义插件非常有用。

  1. 在调试模式下重启 Edge Microgate。为此,请将 DEBUG=* 添加到 start 命令的开头。例如:
    DEBUG=* edgemicro start -o  myorg -e test -k
          db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
          6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
  2. 启动调试程序,将其设置为监听调试过程的端口号。
  3. 您现在可以单步调试 Edge Microgate 代码、设置断点、监视表达式等。

您可以指定与调试模式相关的标准 Node.js 标志。例如,--nolazy 有助于调试异步代码。

检查日志文件

如果您遇到问题,请务必检查日志文件,了解执行详情和错误信息。如需了解详情,请参阅管理日志文件

使用 API 密钥安全性

API 密钥提供了一种简单的机制,用于对向 Edge Microgate 发出请求的客户端进行身份验证。如需获取 API 密钥,您可以从包含 Edge Microgate 身份验证代理的 Apigee Edge 产品中复制使用方密钥(也称为客户端 ID)的值。

缓存键

API 密钥用于交换不记名令牌,而后者会被缓存。如需停用缓存,您可以对 Edge Microgate 的传入请求设置 Cache-Control: no-cache 标头。

使用 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 Microgate

使用 OAuth2 令牌安全性

本部分介绍了如何获取 OAuth2 访问令牌和刷新令牌。访问令牌用于通过微网关进行安全的 API 调用。刷新令牌用于获取新的访问令牌。

如何获取访问令牌

本部分介绍如何使用 edgemicro-auth 代理获取访问令牌。

您还可以使用 edgemicro token CLI 命令获取访问令牌。如需详细了解 CLI,请参阅管理令牌

API 1

替换网址中的组织和环境名称,并将 client_idclient_secret 正文参数替换为从 Apigee Edge 上的开发者应用获取的使用方 ID 和使用方 Secret 值:

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

(在 v2.5.31 中添加)将客户端凭据作为基本身份验证标头发送,将 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 响应。请注意,tokenaccess_token 属性没有区别。您可以使用其中任何一项。
{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

如何获取刷新令牌

如需获取刷新令牌,请对 edgemicro-auth 代理的 /token 端点进行 API 调用。您必须使用 password 授权类型进行此 API 调用。以下步骤介绍了此过程。

  1. 使用 /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"
    }
  2. 您现在可以使用刷新令牌,通过调用同一 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 应用。Edge Microgate 有一个 forever.json 文件,您可以通过配置该文件来控制 Edge Microgate 的重启次数和重启间隔。此文件会配置一个名为 forever-monitor 的 Forever 服务,该服务以编程方式管理 Forever。

您可以在 Edge Microgate 根安装目录中找到 forever.json 文件。请参阅 Edge Microgate 的安装位置。如需详细了解配置选项,请参阅 forever-monitor 文档

edgemicro forever 命令包含一些标志,可用于指定 forever.json 文件的位置(-f 标志),以及启动/停止永久监控进程(-a 标志)。例如:

edgemicro forever -f ~/mydir/forever.json -a start

如需了解详情,请参阅 CLI 参考文档中的永久监控

指定配置文件端点

如果您运行多个 Edge Microgate 实例,可能希望从一个位置管理这些实例的配置。为此,您可以指定一个 HTTP 端点,Edge Micro 可从该端点下载其配置文件。您可以在使用 -u 标志启动 Edge Micro 时指定此端点。

例如:

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 Microgate 使用的 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 Microgate

您可以运行 Edge Microgate,它与任何 Apigee Edge 依赖项完全断开连接。这种场景称为独立模式,可让您在没有互联网连接的情况下运行和测试 Edge Microgate。

在独立模式下,以下功能不起作用,因为它们需要连接到 Apigee Edge:

  • OAuth 和 API 密钥
  • 配额
  • 分析

另一方面,自定义插件和高峰控制可以正常运行,因为它们不需要连接到 Apigee Edge。此外,借助一个名为 extauth 的新插件,您还可以在独立模式下使用 JWT 授权对微网关的 API 调用。

配置和启动网关

如需以独立模式运行 Edge Microgate,

  1. 确保您已安装 Edge Microgate 2.5.25 或更高版本。如果不是最新版本,您必须执行以下命令才能升级到最新版本:
    npm install -g edgemicro

    如需帮助,请参阅安装 Edge Microgate

  2. 创建一个如下所示的配置文件:$HOME/.edgemicro/org_name-env_name-config.yaml

    例如:

    vi $HOME/.edgemicro/foo-bar-config.yaml
  3. 将以下代码粘贴到文件中:
    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
  4. 导出以下环境变量(值为“1”):
    export EDGEMICRO_LOCAL=1
  5. 执行以下 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 /
  6. 测试配置。
    curl http://localhost:8000/echo  { "error" : "missing_authorization" }

    由于 extauth 插件位于 foo-bar-config.yaml 文件中,因此您会收到“missing_authorization”错误。此插件会验证 API 调用的授权标头中必须包含的 JWT。在下一部分中,您将获得一个 JWT,允许 API 调用顺利进行,而不会出现任何错误。

示例:获取授权令牌

以下示例展示了如何从 Apigee Edge 上的 Edge Microgate JWT 端点 (edgemicro-auth/jwkPublicKeys) 获取 JWT。对 Edge Microgate 执行标准设置和配置时,系统会部署此端点。如需从 Apigee 端点获取 JWT,您必须先执行标准的 Edge Microgate 设置,并连接到互联网。Apigee 端点在此处仅作示例用途,并非必需。您可以根据需要使用其他 JWT 令牌端点。如果这样做,您需要使用为该端点提供的 API 获取 JWT。

以下步骤说明了如何使用 edgemicro-auth/jwkPublicKeys 端点获取令牌:

  1. 您必须对 Edge Microgate 执行标准设置和配置,以将 edgemicro-auth 代理部署到 Apigee Edge 上的组织/环境。如果您之前执行过此步骤,则无需重复。
  2. 如果您已将 Edge Microgate 部署到 Apigee Cloud,则必须连接到互联网,才能从此端点获取 JWT。
  3. 停止 Edge Microgate:
    edgemicro stop
  4. 在您之前创建的配置文件 ($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'
  5. 使用您在配置文件名称中使用的组织/环境名称,像之前一样重启 Edge Microgate。例如:
    edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
  6. 从授权端点获取 JWT 令牌。由于您使用的是 edgemicro-auth/jwkPublicKeys 端点,因此可以使用以下 CLI 命令:

您可以使用 edgemicro token 命令或 API 为 Edge Microgate 生成 JWT。例如:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

其中:

  • your_org 是您之前为其配置 Edge Microgate 的 Apigee 组织的名称。
  • your_env 是组织中的环境。
  • i 选项用于指定符合以下条件的开发者应用的使用方密钥:开发者应用具有包含 edgemicro-auth 代理的产品。
  • s 选项用于指定来自具有包含 edgemicro-auth 代理的产品的开发者应用的使用方密钥。

此命令要求 Apigee Edge 生成 JWT,然后使用该 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 Microgate 不需要在 Apigee Edge 上部署 microgate 感知型代理。而是应在启动微网关时通过提供本地代理名称、基本路径和目标网址来配置“本地代理”。然后,对微网关的 API 调用将发送到本地代理的目标网址。在所有其他方面,本地代理模式的工作方式与在普通模式下运行 Edge Microgate 相同。身份验证的运行方式与高峰控制和配额强制执行、自定义插件等相同。

使用场景和示例

如果您只需要将一个代理与 Edge Microgate 实例相关联,则本地代理模式非常有用。例如,您可以将 Edge Microgate 作为 Sidecar 代理注入 Kubernetes,其中 Microgate 和 Service 分别在单个 Pod 中运行,并且微网关管理进出其配套服务的流量。下图说明了此架构,其中 Edge Microgate 是在 Kubernetes 集群中充当 Sidecar 代理。每个微网关实例仅与其配套服务上的单个端点进行通信:

Edgemicro 是 Sidecar

这种架构的优势在于,Edge Microgate 可为部署到容器环境(例如 Kubernetes 集群)的各项服务提供 API 管理。

配置本地代理模式

如需将 Edge Microgate 配置为在本地代理模式下运行,请按以下步骤操作:

  1. 确保您已安装 Edge Microgate 2.5.25 或更高版本。如果不是最新版本,您必须执行以下命令才能升级到最新版本:
    npm install -g edgemicro

    如需帮助,请参阅安装 Edge Microgate

  2. 运行 edgemicro init 以设置本地配置环境,就像在典型的 Edge Microgate 设置中所做的那样。另请参阅配置 Edge Microgate
  3. 运行 edgemicro configure,就像在典型的 Edge Microgate 设置过程中一样。例如:
    edgemicro configure -o your_org -e your_env -u your_apigee_username

    此命令会将 edgemicro-auth 政策部署到 Edge,并返回启动微网关所需的密钥和密文。如需帮助,请参阅配置 Edge Microgate

  4. 在 Apigee Edge 上,创建一个具有以下强制性配置要求的 API 产品(您可以根据需要管理所有其他配置):
    • 必须edgemicro-auth 代理添加到产品中。此代理是在您运行 edgemicro configure 时自动部署的。
    • 必须提供资源路径。Apigee 建议将此路径添加到产品:/**。如需了解详情,请参阅配置资源路径的行为。另请参阅 Edge 文档中的创建 API 产品
  5. 在 Apigee Edge 上,您可以创建一个开发者,也可以根据需要聘用现有的开发者。如需帮助,请参阅使用 Edge 管理界面添加开发者

  6. 在 Apigee Edge 上,创建开发者应用。您必须将刚刚创建的 API 产品添加到该应用。如需帮助,请参阅在 Edge 管理界面中注册应用
  7. 在安装 Edge Microgate 的机器上,导出以下值为“1”的环境变量。
    export EDGEMICRO_LOCAL_PROXY=1
  8. 执行以下 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 是您运行 edgemicro configure 时返回的 Secret。
    • 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":""
}