您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
开始使用
- 如何安装 Edge Microgate?
- 请参阅安装 Edge Microgate。
- 如何运行 Edge Microgate?
- 请参阅 设置和配置 Edge Microgate。
- 我是否需要数据库才能运行 Microgate?
- 通过 Edge Microgate 代理的 API 可以与作为目标服务的一部分运行的数据库交互。但是,Edge Microgate 的运行独立于任何数据库或后端数据存储区。
操作
- Edge 上的哪些更改需要重启 Edge Microgate?
- Edge Microgate 会自动轮询对 Apigee Edge 所做的更改,例如对微网关感知型代理、产品或开发者应用的更改。默认轮询间隔为 600 秒;不过,您可以通过
config_change_poll_interval
配置设置更改间隔时间。 请参阅 edgemicro 属性。 - 如果您不想等待轮询间隔,请使用
edgemicro reload
命令选择最新更改。请参阅 重新加载微网关集群。 - 如何区分 Edge 上部署的代理和 Edge Microgate 上的代理?
- 配置 Edge Microgate 时,系统会将 Apigee Edge 上部署的微网关感知型代理列表下载到 Edge Microgate 的本地配置。微网关感知型代理是带有
edgemicro_
前缀的代理。 - 使用 Edge Microgate 进行日志记录时,我有哪些选择?
- Edge Microgate 具有内置的日志记录功能。如需了解详情,请参阅 管理日志文件。
- 您还可以编写自定义插件,通过 Edge Microgate 来使用第三方日志记录服务。由于 Edge Microgate 的运作方式不同,您无法使用 Apigee Edge 消息日志记录政策来记录 Edge Microgate 的消息。另请参阅 适用于 Microgate 的 Logging 插件社区文章。
- 我可以在 Edge Microgate 实例之间重复使用密钥/密钥组合吗?
- 只要 Microgate 实例的组织和环境相同,您就可以重复使用在配置期间生成的密钥/密钥对。
- 如何将 Edge Microgate 配置为在生产环境中启动?
- 您可以为启动命令参数设置环境变量,例如
EDGEMICRO_KEY
、EDGEMICRO_SECRET
、EDGEMICRO_ORG
和EDGEMICRO_ENV
。借助这些(和其他)变量,您可以使用单个命令edgemicro start
启动 Edge Microgate。另请参阅 设置环境变量。 - 我可以将自定义产品或开发者应用属性与 Edge Microgate 搭配使用吗?
- 不会。默认情况下,Edge Microgate 仅对与基本路由和安全相关的属性起作用。不过,作为权宜之计,您有以下可能的选项:
-
将自定义特性添加到 Edge Microgate 部署到 Apigee Edge 的
edgemicro-auth
代理中。在使用 API 密钥或 OAuth 令牌安全性时,您可以使用这些属性。 - 修改 OAuth 插件以针对这些属性执行操作。
-
将自定义特性添加到 Edge Microgate 部署到 Apigee Edge 的
- 请求标头大小是否有限制?
- 如果您将 Node.js 升级到 v8.14.0 或更高版本,请注意,请求允许的标头大小上限已从 80KB 减少到 8KB。超过 8KB 的标头会导致 HTTP 431 错误。
- 在 Node.js v11.6.0 中添加了一个 Node.js 配置选项,可让您更改默认的标头大小上限。此参数 (
--max-http-header-size
) 可让您指定 HTTP 标头的大小上限(以字节为单位)。 - 如需更改默认配置,请在命令行中设置
NODE_OPTIONS
环境变量的值,如下所示:NODE_OPTIONS=--max-http-header-size=NUM_BYTES
例如:
NODE_OPTIONS=--max-http-header-size=80000
Edge Microgate 使用哪些管理 API?
以下 Edge Microgate 命令会调用 Apigee Edge 管理 API 来完成其工作,如 Edge Microgate 的 CLI 参考文档中所述:
edgemicro configure
edgemicro upgradeauth
edgemicro upgradekvm
edgemicro rotatekey
edgemicro cert check
edgemicro cert delete
edgemicro cert install
以下部分列出了每个命令使用的 Management API 调用。
edgemicro configure
和 upgradeauth
命令会调用以下管理 API:
- (列出部署)
GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/deployments
- (获取部署信息)
GET: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=java&name=micro-gateway-products-javacallout-2.0.0.jar
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=adjust-quota.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-jwk.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=generate-verify-jwt.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jsrsasign-all-min.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=jwt-initialization.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-jwk-response.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-product-list.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=send-public-key.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-jwt-variables.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-quota-variables.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=set-response.js
- (上传资源)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/resources?type=jsc&name=validate-params.js
- (创建 API 代理)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis?action=import&validate=false&name=edgemicro-auth
- (上传政策)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/policies
- (上传代理)
POST: https://api.enterprise.apigee.com/v1/o/[org]/apis/edgemicro-auth/revisions/1/proxies?name=default
- (部署代理)
POST: https://api.enterprise.apigee.com/v1/o/[org]/e/[env]/apis/edgemicro-auth/revisions/1/deployments
upgradekvm
命令会调用以下 Management API:
PUT: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
rotatekey
命令会调用以下 Management API:
GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway/entries/private_key
cert check
命令会调用以下 Management API:
GET: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
cert delete
命令会调用以下 Management API:
DELETE: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps/microgateway
cert install
命令会调用以下 Management API:
POST: https://api.enterprise.apigee.com/v1/organizations/[org]/environments/[env]/keyvaluemaps
Deployment
- 我可以在运行目标服务的同一台服务器上部署 Edge Microgate 吗?
- 能。Edge Microgate 是一个轻量级进程,可以在目标服务附近(包括在同一台机器上)运行。
- 我可以将现有 Edge 代理软件包部署为 Edge Microgate 部署吗?
- 不能。Edge Microgate 感知代理有特定要求,并且不支持常规 Edge 代理的所有功能。请参阅第 2 部分:在 Apigee Edge 上创建实体
- 我可以为同一 API 代理在 Edge 代理软件包部署和 Edge Microgate 部署之间启用故障切换功能吗?
- 不能。Edge Microgate 不了解 Apigee Edge 上的非 Microgate API 代理部署情况。
- Edge Microgate 的高可用性部署模型是什么?
- 如需详细讨论如何使用 NGINX 作为负载平衡器来运行 Edge Microgate,请参阅 使用 Apigee Edge Microgate 和 NGINX 管理 API。
- 我可以将哪些负载平衡器与 Edge Microgate 搭配使用?
- Edge Microgate 可与任何负载平衡器搭配使用。
- 我可以部署的 Edge Microgate 代理数量是否有限制?
- 请参阅为常规 Edge 代理指定的产品配置限制。您可以在 Apigee Edge 组织和环境中部署并通过 Edge Microgate 调用的微网关感知型代理的数量必须符合相同的限制。
- 我可以将 Edge Microgate 部署与特定组织和环境相关联吗?
- 配置 Edge Microgate 实例时,您必须将其与特定 Edge 组织和环境关联。
- 如果我是多区域客户,我可以将 Edge Microgate 部署与特定区域相关联吗?
- Edge Microgate 会自动选择最佳区域来与 Apigee Edge 交互。您可以在要提供服务的每个区域中部署 Edge Microgate 实例。
管理
- 我必须是组织管理员才能配置和部署 Edge Microgate 吗?
- 能。您需要拥有组织管理员凭据才能配置和部署 Edge Microgate 网关。
- 我必须是组织管理员才能运行 Edge Microgate 吗?
- 不可以。Edge Microgate 是一个
Node.js
应用,任何有权在给定机器上运行此类应用的用户都可以运行该应用。 - 我的组织中的任何用户都可以使用 Edge Microgate 吗?
- 您无需是 Apigee Edge 组织用户,即可通过 Edge Microgate 进行 API 调用。但是,您必须拥有组织级权限才能创建或更改部署在 Edge 上的 Edge Microgate 感知型代理。
性能
- 使用 Edge Microgate 时有哪些性能注意事项?
- 如果运行与目标应用并置的 Edge Microgate,请确保服务器具有足够的容量。
- 大规模运行 Edge Microgate 的最佳实践有哪些?
- Apigee 建议在 NGINX 等负载平衡器面向的不同服务器上运行多个 Edge Microgate 实例。另请参阅 Apigee 社区中的 使用 Apigee Edge Microgate 和 NGINX 管理 API 和 纵向横向扩缩。
- 默认情况下,Edge Microgate TPS 是什么?微网关实例需要哪些硬件要求
- 使用 Edge Microgate 时,硬件要求和 TPS 测量结果很难衡量。这取决于您的设置,其中包括调整 Edge Microgate、插件使用情况、自定义插件以及配置 TLS 等其他内容。Apigee 通常建议您了解这些项目组合,并使用您的特定设置进行性能测试。
私有云部署
- Edge Microgate 是否与适用于私有云的 Edge 搭配使用?
- 能。如需了解详情,请参阅 Apigee Private Cloud 配置步骤。
插件
- Edge Microgate 是如何强制执行配额的?
- 您可以选择向 Edge Microgate 实例添加配额插件。如需了解详情,请参阅使用配额插件。
- 如何通过 Edge Microgate 强制执行 Spike Arrest?
- 您可以选择向 Edge Microgate 实例添加高峰控制插件。如需了解详情,请参阅使用高峰控制插件。
- 除了
Node.js
之外,有没有其他方法可以编写适用于 Edge Microgate 的插件? - 不可以。插件必须使用
Node.js
编写。 - 如果 Edge Microgate 无法将 Analytics 数据上传到 Edge,会发生什么情况?
- Edge Microgate 具有内存中缓冲区。如果缓冲区已满,较旧的载荷会被丢弃,以便 API 流量顺畅流动。
- 我可以向 Edge Microgate 添加政策吗?
- 如果您将常规 Apigee Edge 政策附加到 Apigee Edge 中的微网关感知型代理,则这些政策会被忽略。取而代之的是,Edge Microgate 使用插件来提供与 Edge 中的政策类似的功能,例如配额、高峰控制、API 密钥安全性和 OAuth2 安全性。您还可以编写自定义插件。请参阅使用插件和开发自定义插件。
以下 Apigee 社区帖子和博客讨论了其他插件使用场景:
安全性
- 如何保护
/products
资源? - 概览
- 配置 Edge Microgate 时,系统会将一个名为
edgemicro-auth
的 API 代理部署到 Apigee Edge 上的“organization:environment”中。此代理会公开一个/products
端点,该端点会返回 API 产品列表。如果您是在 2018 年 10 月 5 日或之前安装的 Edge Microgate 的,Apigee 建议您采取措施保护此端点,因为响应中会包含在您的 Apigee 组织中创建和修改 API 产品的开发者的电子邮件地址。 - 您可以通过升级 Edge Microgate 或配置双向 TLS 来保护端点。下面介绍了这两种方式。
- 检查
/products
端点是否受到保护 -
如果您不确定
/products
端点是否受到保护,请转到验证/products
资源是否受保护部分并执行相关步骤,然后再继续。方法 1:升级 Edge Microgate
如果您是在 2018 年 10 月 5 日或之前安装的 Edge Microgate,Apigee 建议您升级到最新版本的 Edge Microgate。请按照 在连接到互联网的情况下升级 Edge Microgate 中的步骤操作。
如果您目前无法升级,请转到选项 2。
方法 2:配置双向 TLS
如果您目前无法升级 Edge Microgate,Apigee 建议使用双向 TLS(也称为双向 TLS)来保护 Edge Microgate 与
edgemicro-auth
代理之间的通信。- 打开
$HOME/.edgemicro/org-env-config.yaml
文件。如果找不到此文件,请参阅 Edge Microgate 的安装位置。 - 将以下
tlsOptions
代码块添加到org-env-config.yaml
文件中,以在 Edge Microgate 和 Apigee Edge 之间启用双向 TLS:edge_config: bootstrap: >- https://domain/edgemicro/bootstrap/organization/org/environment/env jwt_public_key: 'https://domain/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' tlsOptions: agentOptions: requestCert: true cert: 'path/to/cert' key: 'path/to/key'
例如:
tlsOptions: agentOptions: requestCert: true cert: '/Users/jdoe/twowayssl/ssl/client.key' key: '/Users/jdoe/twowayssl/ssl/ca.crt'
您还可以添加以下
agentOptions
可选参数:ca
:指定证书授权机构的路径。pfx
:如果您想使用 p12/pfx 文件(而不是证书和密钥),请添加此参数。passphrase
:pfx 文件的密码。ciphers
:指定 TLS 加密方式。
- 确保部署了
edgemicro-auth
代理的虚拟主机已启用双向 TLS。 如需了解详情,请参阅 Apigee Edge 文档中的为双向 TLS 定义虚拟主机。以下屏幕截图展示了如何在 Apigee Edge 界面中在虚拟主机上启用双向 TLS:
- 查看 Edge 界面中的
edgemicro-auth
API 代理,并确保在代理配置中指定正确的虚拟主机。例如,如果您创建了一个名为mutualtls
且启用了 TLS 的虚拟主机,则代理的HTTPProxyConnection
节应如下所示:<HTTPProxyConnection> <BasePath>/edgemicro-auth</BasePath> <Properties/> <VirtualHost>mutualtls</VirtualHost> </HTTPProxyConnection>
- 打开
/products
资源是否受到保护/products
资源是否受到保护。在完成保护资源的步骤(方法 1 或方法 2)后,请务必执行此测试。您可以使用 c网址 执行此操作,例如:
curl -v https://your_domain/edgemicro-auth/products
/products
端点已受到保护:
{ "error":"unauthorized", "error_description": "authentication failed" }
或
curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number
如果您看到如下所示的响应,则表明 /products
资源不受保护,并且可能会公开开发者电子邮件地址:
{ "apiProduct":[ { "apiResources":[ "/", "/**" ], "approvalType":"auto", "attributes":[ ], "createdAt":1537374680948, "createdBy":"jdoe@foo.com", "description":"", "displayName":"mock", "environments":[ "test" ], "lastModifiedAt":1537374680948, "lastModifiedBy":"test@test.com", "name":"mock", "proxies":[ "edgemicro-auth", "edgemicro_mock" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ "" ] } ] }
Apigee 还建议您测试 HTTP 虚拟主机:
例如:
curl -v http://your_domain/edgemicro-auth/products
如果 c网址 调用返回 API 产品列表,则系统可能会公开开发者的电子邮件地址。如果您不希望使用此未使用 TLS 的虚拟主机公开端点,请务必将其从 edgemicro-auth
HTTPProxyConnection 配置中移除。
如需保护该资源,请执行以下任一操作:
目前,您无法续订给定 Edge Microgate 实例的 JWT 令牌。
临时解决方法:
每个 JWT 令牌都有一个 exp 属性,指示令牌的失效日期。应用可以通过直接对 edgemicro-auth
令牌端点进行 API 调用,计算出到期时间并请求新令牌。例如,您可以进行如下 API 调用:
POST https: //{your_org}-{your_env}.apigee.net/edgemicro-auth/token
... JSON 正文如下所示:
{ "client_id": {your_id}, "client_secret": {your_secret},
"grant_type": "client_credentials" }
另请参阅:
- Edge Microgate 文档中的使用 OAuth 令牌或 API 密钥来保护 API。
- 在 Apigee 社区中,不记名令牌到期时需要续期的流程是什么。
目前,我们只会检查基本路径,以确定 API 是否获准用于与特定 OAuth 令牌关联的 API 产品。
例如:
- 创建一个带有
edgemicro_
前缀且带有基本路径和目标的代理。 - 将此代理添加到产品中。将其命名为
edgemicro-prod1
。 - 使用 API 密钥或 OAuth 令牌通过 Edge Microgate 调用 API 时,Edge Microgate 会检查 API 的基路径是否与获准使用相应密钥或令牌的产品列表的
edgemicro_*
代理的基路径匹配。
另请参阅 Apigee 社区中的 在产品中使用 edgemicro 网关时,需要在资源下使用的产品中将哪个网址列入白名单?。
目前仅支持默认 Apigee SSL 证书。目前不支持自定义 SSL 证书。
权宜解决方法:
如果您希望使用自定义(非 Apigee 默认)SSL 证书,有以下几种选择:
-
请使用非 SSL
jwt_public_key
端点。修改 Edge Microgate 配置文件以使用http://{org}-{env}.apigee.net/edgemicro-auth/publicKey
或者 -
在启动 Edge Microgate 之前,请设置以下环境变量:export
NODE_TLS_REJECT_UNAUTHORIZED ="0"
另请参阅 Apigee 社区中的 验证 SSL 证书上的 Edge Micro 安装错误。
edgemicro-auth
代理部署到 Edge,并且此部署需要组织管理员凭据。您可以使用自己的令牌,但必须先关闭 Edge Microgate 的内置授权。具体操作步骤如下:
- 打开 Edge Microgate 的配置文件。
-
将两个 OAuth 设置更改为 true,如下所示:
oauth: allowNoAuthorization: true allowInvalidAuthorization: true
edgemicro start -o [org] -e [env] -k [key] -s [secret]
测试和调试
- 如何防止在负载测试期间出现“打开过多文件”错误?
-
在某些情况下,您的系统可能会遇到打开文件连接过多的情况,这可能会导致 Edge Micro 崩溃。默认日志记录需要两个 HTTP 连接,以用于通过 Microgate 的传入和传出事务。
出于测试和基准化分析的目的,Apigee 建议将系统的 ulimit 命令设置为无限制:
ulimit -n unlimited
。另请参阅 Apigee 社区中的负载测试期间出现 Edge Microgate 错误。 - 有关快速开发和调试的提示
-
如果您正在为 Edge Microgate 开发插件,可能会发现对快速开发的支持有限。
目前,请参考以下提示:
- 如需启动 Edge Microgate,您可以将环境变量 EDGEMICRO_KEY 和 EDGEMICRO_SECRET 设置为 Microgate 启动命令所需的密钥/密钥对。这样,您无需在命令行中输入密钥/密钥即可启动 Edge Microgate。另请参阅 Edge Microgate 文档中的 设置环境变量部分。
-
以 DEBUG 模式启动 Edge Microgate,以便在命令终端中查看其他输出:
DEBUG=* edgemicro start -o [org] -e [env] -k [key] -s [secret]
业务和许可
- Apigee-127 与 Edge Microgate 支持模型之间的关系是什么?
-
Apigee-127 是开源模型支持的开源软件项目。也就是说,如果您尝试修复某些问题,可以在 GitHub 项目中提出问题并发出拉取请求。Apigee-127 不需要或不包含与 Apigee 的任何软件许可协议。
另一方面,Edge Microgate 是 Apigee 为 Apigee 客户提供的企业产品。也就是说,Apigee 客户可以使用 Google Cloud Apigee Edge 支持来创建支持服务工单、功能请求和错误报告。