Edge Microgate 的操作和配置参考文档

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档。

Edge Microgate 版本 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 Micro 网关时，系统会将默认系统配置文件放在此处：

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

其中 prefix 是 npm 前缀目录。如果您找不到此目录，请参阅 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，其中 org 和 env 是您的 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 Microrouter 已停止：

  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 配置文件中，使用 target 元素设置 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 中。

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

在边缘微网关配置文件中指定用于存储日志文件的目录。另请参阅更改配置。

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 和日志文件。

如何设置日志记录级别

您可以设置以下日志级别：信息、警告和错误。建议选择信息级别。它会记录所有 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 Web 令牌 (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 - 取决于上下文。可能是信息、警告或错误，具体取决于日志级别。可以是统计信息记录的统计信息，在有警告时发出警告，或在出现错误时发出错误提示。
  • req - 标识事件。在这种情况下，从客户端发出请求。
  • m - 请求中使用的 HTTP 动词。
  • u - 网址中基本路径后面的部分。
  • h - Edge Microgate 正在监听的主机和端口号。
  • r - 发起客户端请求的远程主机和端口。
  • i - 请求 ID。所有 4 个事件条目都将共用此 ID。系统会为每个请求分配一个唯一的请求 ID。通过请求 ID 关联日志记录有助于深入了解目标延迟时间。
  • d - 自 Edge Microgate 收到请求以来的时长（以毫秒为单位）。在上面的示例中，目标 0 的响应在 7 毫秒后收到（第 3 行），并在 4 毫秒之后将响应发送到客户端（第 4 行）。换言之，请求总延迟时间为 11 毫秒，其中 7 毫秒由目标占用，4 毫秒由 Edge Microgate 本身占用。

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。所有 4 个事件条目都将共用此 ID。

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

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

1436403888651 - Unix 日期戳记

  • info - 取决于上下文。可能是信息、警告或错误，具体取决于日志级别。可以是统计信息记录的统计信息，在有警告时发出警告，或在出现错误时发出错误提示。
  • tres - 标识事件。在这种情况下，请创建目标响应。
  • s - HTTP 响应状态。
  • d - 持续时间（以毫秒为单位）。目标调用 API 所用的时间。
  • i - 日志条目的 ID。所有 4 个事件条目都将共用此 ID。

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

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

1436403888651 - Unix 日期戳记

  • info - 取决于上下文。可能是信息、警告或错误，具体取决于日志级别。可以是统计信息记录的统计信息，在有警告时发出警告，或在出现错误时发出错误提示。
  • res - 标识事件。在这种情况下，响应客户端。
  • s - HTTP 响应状态。
  • d - 持续时间（以毫秒为单位）。这是 API 调用所花费的总时间，包括目标 API 所用的时间以及 Edge Microgate 本身所用的时间。
  • i - 日志条目的 ID。所有 4 个事件条目都将共用此 ID。

日志文件时间表

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

错误消息

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

Edge Microgate 配置参考文档

配置文件的位置

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

edge_config 属性

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

  • bootstrap：（默认值：none）一个网址，指向指向在 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）：边缘 Microgate 在关闭连接之前可以接收的并发请求数量上限。此设置旨在防止拒绝服务攻击。通常，将其设置为大于 max_connections 的数字。
  • 日志记录：
    • level（默认值：error）
      • info - 记录流经 Edge Microgate 实例的所有请求和响应。
      • warn - 仅记录警告消息。
      • error - 仅记录错误消息。
    • dir（默认值：/var/tmp）存储日志文件的目录。
    • stats_log_interval（默认值：60）统计统计信息写入 API 日志文件的时间间隔（以秒为单位）。
    • rotate_interval（默认值：24）间隔时间（小时）。
  • 插件：插件可向 Edge Microgate 添加功能。如需详细了解如何开发插件，请参阅开发自定义插件。
  • dir：从 ./portal 目录到 ./plugin 目录的相对路径，或绝对路径。
  • 序列：要添加到 Edge Microgate 实例的插件模块列表。模块将按照此处指定的顺序执行。
  • debug ：将边缘调试添加到 Edge Microgate 进程。
    • port：要监听的端口号。例如，设置 IDE 调试程序来监听此端口。
    • args：调试进程的参数。例如：args --nolazy
  • config_change_poll_interval（默认值：600 秒）Edge Microgate 定期加载新配置，并在发生任何更改时执行重新加载。轮询会选取对 Edge 所做的任何更改（对产品、微网关感知代理等所做的更改）以及对本地配置文件所做的更改。
  • disable_config_poll_interval（默认值：false）设置为 true 可关闭自动更改轮询。
  • 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 属性

这些设置可配置边缘身份验证如何强制执行客户端身份验证。

  • allowNoAuthorization：（默认值：false）如果设置为 true，则 API 调用无需经过任何授权标头即可通过 Edge Microgate。将此字段设为 false 可请求授权标头（默认）。
  • allowInvalidAuthorization：（默认值：false）如果设置为 true，则当授权标头中传递的令牌无效或过期时，系统会允许通过 API 调用。将此标记设置为 false 即可要求使用有效的令牌（默认）。
  • authorization-header：（默认：授权：不记名）将访问令牌发送到 Edge Microgate。如果目标需要将 Authorization 标头用于其他目的，您可能需要更改默认设置。
  • api-key-header：（默认：x-api-key）用于将 API 密钥传递给 Edge Microgate 的标头或查询参数的名称。另请参阅使用 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 - 此参数有助于防止系统时钟与 JWT 授权令牌中指定的非之前 (nbf) 或颁发 (iat) 时间之间存在细微差异。请将此参数设置为允许此类差异的秒数。（2.5.7 版）

插件专用属性

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

过滤代理

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

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

配置分析推送频率

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

  • bufferSize（可选）：在开始删除最早的记录之前，缓冲区可以保留的分析记录数上限。默认：10000
  • batchSize（可选）：发送到 Apigee 的分析分析批次的大小上限。默认值：500
  • flushInterval（选填）：每次批量清除发送到 Apigee 的分析记录之间的毫秒数。默认：5000

例如：

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

遮盖分析数据

以下配置可防止请求路径信息显示在 Edge analytics 中。将以下内容添加到 Microgate 配置，以遮盖请求 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（可选）：指定在 Google Analytics（分析）信息中心内隔离的相对路径。例如，如果您指定 /healthcheck，那么包含路径 /healthcheck 的所有 API 调用都将在信息中心内显示为 edgemicro_proxyname-health。请注意，此标志会忽略代理基路径。 如需根据完整路径（包括基本路径）隔离，请使用 proxyPath 标志。
  • proxyPath（可选）：指定要在 Google Analytics（分析）中隔离的完整 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 将在 Google Analytics（分析）信息中心将其拆分为名为 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_tunnel 为 true 时，Edge Microgate 使用 HTTP CONNECT 方法通过单个 TCP 连接建立 HTTP 请求隧道。（如果用于配置代理的环境变量已启用 TLS），也是如此。

选项 2：

第二种方法是在 Microgate 配置文件中指定代理，并将 Proxy_tunnel 设置为 false。例如：

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

在这种情况下，您可以设置以下变量来控制您要使用的每个 HTTP 代理的主机，或者哪些主机不应处理 Edge Microgate 代理：HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。

您可以将 NO_PROXY 设为以逗号分隔的 Edge Microgate 不应代理的网域。例如：

export NO_PROXY='localhost,localhost:8080'

将 HTTP_PROXY 和 HTTPS_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。

在 Microgate-aware 代理中使用通配符

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

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

轮替 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，然后可以用其验证 API 调用。-i 和 -s 参数是 Apigee Edge 组织中开发者应用的使用方 ID 和密钥值。

或者，您也可以使用 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 是您之前创建的开发者应用中的使用方密钥。

什么是密钥轮替？

在最初生成 JWT 后的某个时间，您可能需要更改存储在 Edge 加密 KVM 中的公钥/私钥对。生成新的密钥对的过程称为密钥轮替。在您轮替密钥时，系统会生成新的私钥/公钥对，并将其存储在您的 Apigee Edge 组织/环境中的“微网关”KVM 中。此外，旧的公钥会与原始密钥 ID 值一起保留。

为了生成 JWT，Edge 使用存储在加密 KVM 中的信息。在您最初设置（配置）Edge Microgate 时，系统会创建一个名为 microgateway 并填充了密钥的 KVM。KVM 中的密钥用于为 JWT 签名和加密。

KVM 密钥包括：

  • private_key - 最新（最近创建的）RSA 私钥，用于为 JWT 签名。

  • 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 (kid)。此 ID 用于匹配特定键。在密钥轮替期间，Edge Microgate 使用该值从一组密钥中进行选择。如需了解详情，请参阅 JSON Web Key 规范的第 4.5 节。

密钥轮替后，Edge 会将多个密钥返回到 Edge Microgate。请注意，在下面的示例中，每个键都有一个唯一的“kid”（密钥 ID）值。然后，microgate 使用这些密钥来验证授权令牌。如果令牌验证失败，Microgate 会检查密钥集中是否存在旧密钥并尝试该密钥。返回的密钥格式为 JSON Web Key (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 会下载边缘组织中名称以“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 发出请求的客户端进行身份验证。您可以从包含 Edge Microgate 身份验证代理的 Apigee Edge 产品中复制使用方密钥（也称为客户端 ID）值，以获取 API 密钥。

缓存键

API 密钥会交换不记名令牌，并缓存这些令牌。您可以停用缓存，方法是将传入请求的 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 密钥与代理请求搭配使用，请参阅 安全边缘微网关。

使用 OAuth2 令牌安全

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

如何获取访问令牌

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

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

API 1

用网址替换您的组织和环境名称，并将从 Apigee Edge 的开发者应用中获取的消费者 ID 和消费者密钥值替换为 client_id 和 client_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

（在 2.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 响应。请注意，token 和 access_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 来调用同一 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 文件。请参阅 边缘微网关的安装位置。如需详细了解配置选项，请参阅永久监控文档。

edgemicro forever 命令包含相关标志，以便您指定 forever.json 文件（-f 标志）的位置，以及启动/停止 Forever 监控进程（-a 标志）。例如：

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

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

指定配置文件端点

如果您运行多个 Edge Microgate 实例，您可能希望在单个位置管理其配置。为此，您可以指定 HTTP 端点，Edge Micro 可在该端点上下载其配置文件。您可以在启动 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 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

您可以运行与所有 Apigee Edge 依赖项完全断开连接的 Edge Microgate。在这种场景下，称为“独立模式”，您可以在没有互联网连接的情况下运行和测试 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 是您在配置文件名称中使用的“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 调用的 Authorization 标头中必须包含的 JWT。在下一部分中，您将获取 JWT，允许 API 调用顺利完成，而不会出现错误。

示例：获取授权令牌

以下示例展示了如何从 Apigee Edge (edgemicro-auth/jwkPublicKeys) 上的 Edge Microgate JWT 端点获取 JWT。当您执行 Edge Microgate 的标准设置和配置时，系统会部署此端点。 如需从 Apigee 端点获取 JWT，您必须先执行标准 Edge Microgate 设置，并连接到互联网。此处使用的 Apigee 端点仅用于示例目的，并非必需。如果您愿意，可以使用其他 JWT 令牌端点。如果支持，您需要使用为相应端点提供的 API 获取 JWT。

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

  1. 您必须执行 Edge Microgate 的标准设置和配置，才能在 Apigee Edge 中将 edgemicro-auth 代理部署到您的组织/环境。如果您以前执行过此步骤，则无需重复此步骤。
  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，然后可以用其验证 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 完全相同。Authentication 与峰值阻止和配额强制执行、自定义插件等都一样。

使用场景和示例

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

Edgemicro 作为辅助信息

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

配置本地代理模式

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

  1. 确保您已安装 Edge Microgate 版本 2.5.25 或更高版本。否则，您必须执行以下命令才能升级到最新版本： 
    npm install -g edgemicro

    如果您需要帮助，请参阅安装 Edge Microgate。

  2. 运行 edgemicro init 以设置本地配置环境，操作方式与在典型的 Edge Micro 网关设置中完全相同。另请参阅配置 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 上，创建一个开发者；如果愿意，也可使用现有开发者。如需帮助，请参阅使用边缘管理界面添加开发者。

  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":""
}