Apigee 已知问题

不适用

如果用户向 UpdateControlPlaneAccess API 提供无效的服务账号，操作会进入重试循环，实际上会使组织无法调用该 API，直到操作超时。

不适用

apigee-logger 利用 Google IAM 服务账号将日志发送到 Cloud Logging。这是因为 FluentBit 不支持工作负载身份联合，导致 apigee-logger 无法利用此功能。

不适用

不适用

354716994

364872027

对于 Apigee 和 Apigee Hybrid 1.13 版及更高版本，Apigee JWS 或 JWT 政策中使用的密钥的必需 PEM 格式存在任何偏差都可能导致解析错误。例如，不允许在 "-----END" 行（封装后边界）紧前面放置除换行符 (/n) 之外的任何字符，否则会导致错误。

为防止此错误，请确保除换行符（例如尾随空格或斜杠）之外，封装后边界紧前面没有字符。

如需详细了解用于公钥或私钥的编码，请参阅 IETF RFC 7468。

310191899

与较多的每秒查询次数 (QPS) 搭配使用时，以下端点可能会遇到超时情况：

• organizations.environments.apis.revisions.
  deployments.deploy
• organizations.environments.apis.revisions.
  deployments.undeploy
• organizations.environments.sharedflows.revisions.
  deployments.deploy
• organizations.environments.sharedflows.revisions.
  deployments.undeploy

为了降低超时的可能性，我们建议您在使用这些端点时将目标设置为 3 QPS。

329304975

Apigee 对每个环境实施 1,000 个基本路径的临时限制，以避免在部署 API 代理修订版本时可能发生的失败。

此限制实施后，您最多可以为每个环境部署 1,000 个 API 代理修订版本（每个修订版本包含一个基本路径）。 如果 API 代理或修订版本包含多个基本路径，则每个环境的基本路径总数不得超过 1,000。

333791378

如需了解安装可解决问题的补丁的步骤，请参阅问题排查。

310384001

289583112

如果 OASValidation 政策指定 <OASResource> 并将安全要求设置为全球级别，则系统不会强制执行安全要求。

解决方法：如需确保强制执行，必须在传入 OASValidation 政策的 <OASResource> 元素的 OpenAPI 规范中将所有安全要求设置为操作级别。

205666368

请参阅关于在目标端点或目标服务器中设置 TLS 选项。

295929616

由于内存不足问题，在 OSE 上安装或升级到 Apigee Hybrid 1.10.0 至 1.10.2 可能会失败。已在 Apigee Hybrid 1.10.3 版中修复。

292268968

如果防火墙强制所有流量通过转发代理，apigee-udca 可能会进入崩溃循环退避状态。

269573358

• 如果 JSON 内容与预期模式不匹配，则 OASValidation 政策会失败。例如，如果标头需要一个格式为 <text>@<text> 的值并且填充了缺少 @ 符号的文本，则政策将失败并显示 Unable to parse JSON 错误。
• 如果 OASValidation 政策指定 <OASResource> 包含使用 $ref 架构的 path 参数，则该政策将失败并显示 Unable to parse JSON - Unrecognized token 错误。

  解决方法：请勿在 <OASResource> 元素中指定的 OpenAPI 规范的 path 参数中使用 $ref。

299953958

• 使用 OpenAPI 3.0.0 规范的循环引用时，Apigee 部署将失败，因为它会进入无限循环。

解决方法：使用不包含循环引用的 OpenAPI 规范 yaml。

289254725

在以下情况下，包含 OASValidation 政策的代理部署可能会失败：

• OASValidation 政策中用于验证的 OpenAPI 规范采用 YAML 格式，并且
• YAML 格式的 OpenAPI 规范包含浮点数。例如：

  schema:
  type: number
  example: 2.345

284500460

为避免增加对客户端的响应的延迟时间，应将消息日志记录政策附加到 PostClientFlowPostClientFlow。如需详细了解如何在 PostClientFlows 中使用政策，请参阅使用流控制 API 代理。

282997216

仅使用 Cassandra Jolokia 密码的字母数字字符。使用特殊字符（包括但不限于“!”“@”“#”“$”“%”“^”“&”和“*”）可能会导致 Cassandra 启动失败。

271415351

对 SharedFlow 或 API 代理的并发部署请求可能会导致管理服务器中出现不一致的状态，其中多个修订显示为已部署。例如，当使用不同修订版本实现 CI/CD 部署流水线的并发运行时，可能会发生这种情况。为避免此问题，请避免在当前部署完成之前部署 API 代理或 SharedFlow。

271689008

使用 OpenShift 4.7 版到 4.10 版上的 cert-manager v1.10.1 时，cert-manager pod 无法按预期启动。如需解决此问题，请按照 cert-manager 1.10 版本说明中所述修改安全配置限制条件。

270371160

Apigee 入站流量网关仅支持 TLS1.2+，不支持早期版本的 TLS。

269139342

Apigee 组织验证不遵循 overrides.yaml 中设置的 HTTP 转发代理规则。设置 validateOrg: false 以跳过此验证。

266452840

在某些情况下，使用 Anthos Service Mesh 1.15.3-asm.6 时，Web 套接字不适用于 Apigee X 和 Apigee Hybrid。

242213234

尝试加载 API 产品时可能会返回此错误：“产品未成功加载。错误：没有来自 Apigee 连接代理的可用连接。”

在 Google Cloud 项目中启用 VPC Service Controls 并将 iamcredentials.googleapis.com 添加为服务边界中的一项受限服务后，会出现此问题。

解决方法：手动创建出站流量规则，如下所示：

-egressTo:
    operations:
    -serviceName: "iamcredentials.googleapis.com"
        methodSelectors:
        -method:
    resources:
    -projects/608305225983
  egressFrom:
    identityType: ANY_IDENTITY

247540503

在高吞吐量的某些情况下，使用加密密钥查找的竞态条件可能导致 KVM 查找失败。

258699204

如果 apigee-telemetry-app 或 apigee-telemetry-proxy pod 出现问题，请更改 metrics 资源请求和资源限制属性，以匹配以下配置属性参考文档：指标中的默认值。

使用带有 ‑‑telemetry 标志的 apigeectl apply 应用更改：

apigeectl apply --telemetry -f overrides.yaml

260324159

在某些情况下，由于同步器中发生“套接字已关闭”错误，API 代理和共享流可能需要大约 20 到 30 分钟才能部署到运行时平面中。

254505866

如果您选择的区域不是以下区域，则使用界面预配 API Hub 会失败：

• asia-east1
• asia-southeast1
• europe-west1
• europe-west4
• us-central1
• us-east1
• us-west1
• us-west4

251897633

仅当您选择或直接点击文本，Apigee Hybrid 版本选择器才起作用。

250875730

预计每分钟发生一次，不会影响结算费用。

260772383

如果在 AKS 上安装 Hybrid，您可能会看到以下错误：

envoy config listener '0.0.0.0_443' failed to bind or apply socket options: cannot bind '0.0.0.0:443': Permission denied

解决方法：将以下 svcAnnotations 节添加到替换文件中：

ingressGateways:
- name: INGRESS_NAME
  ...
  svcAnnotations:
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"

请参阅配置 Hybrid 运行时。另请参阅将内部负载均衡器与 AKS 搭配使用。

241786534

使用组织范围的 UDCA 时，MART 有时无法连接到 FluentD。组织范围的 UDCA 是 Apigee Hybrid 1.8 版中的默认设置。请参阅配置属性参考文档中的 orgScopedUDCA。

在 Apigee Hybrid 1.6.6 版中将 apigee-logger 从 fluend 迁移到 fluent-bit 后，日志记录器在使用 CentOS 或 RHEL 的 Anthos Bare Metal 上不再起作用。

231758700
231976420

从 Docker Hub 拉取 Apigee Hybrid 的映像时，用户遇到以下错误：ERRO[0001] Metadata for targets expired。这适用于以下 Hybrid 组件：

• google/apigee-authn-authz
• google/apigee-mart-server
• google/apigee-runtime
• google/apigee-synchronizer

临时解决方法

如果遇到此错误，您可以使用以下两种解决方法之一：

• 切换为使用 gcr.io/apigee-release 来拉取 Hybrid 映像。
• 通过将 DOCKER_CONTENT_TRUST 环境变量设置为 0 来停用 Docker 内容信任

当前的 apigee-logger 配置（包括活跃性探测）与 Kubernetes 运行时不兼容，导致日志未按预期发送到 Cloud Logging。此问题还会导致 apigee-logger Pod 定期崩溃。此问题会影响 AKS、Anthos Bare Metal 和其他平台上的 Apigee Hybrid 安装。请注意，在某些情况下，此问题会导致日志量过多。

如果请求路径中除基本路径外未包含一个完整路径段，则不包含操作或不包含 HTTP 匹配的操作将返回 404 错误代码。例如，对 /basepath 的请求将失败，但对 /basepath/user 的请求可能会成功。为防止失败，请在可配置的 API 代理中添加至少包含一个 http_match 的 Operations 部分。

在可配置的 API 代理的代理基本路径中使用通配符 * 会导致将错误请求路径转发到后端目标。

在该问题解决之前，为防止转发不正确的请求路径，请避免在可配置的 API 代理基本路径中使用 *。

在 Apigee 界面中，您无法查看、确认部署状态或管理您的归档部署（如部署 API 代理所述），也无法使用调试界面（如使用调试所述）。如需解决此问题，您可以使用 gcloud 或 API 列出环境中的所有归档部署，并使用 Debug API。

目前不支持回滚归档部署。 如需移除归档部署的某个版本，您需要重新部署旧版归档或删除环境。

Apigee in VS Code 不支持 ServiceCallout 和 ExternalCallout 政策中的 Google 身份验证（如使用 Google 身份验证中所述）。

无效的 HTTP 标头错误：Istio Ingress 会将所有传入的目标响应切换到 HTTP2 协议。由于 Hybrid 消息处理器仅支持 HTTP1，因此调用 API 代理时，您可能会看到以下错误：

http2 error: Invalid HTTP header field was received: frame type: 1, stream: 1,

name: [:authority], value: [domain_name]

如果出现此错误，您可以采取以下任一措施来纠正问题：

• 修改目标服务以忽略响应中的主机标头。
• 如有必要，使用 API 代理中的 AssignMessage 政策移除主机标头。

• 虽然在您的门户上使用 SmartDocs 发布 API 时，Apigee 支持 OpenAPI 规范 3.0，但还有一小部分功能得不到支持。例如，用于组合和扩展架构的 allOf 属性。

  如果 OpenAPI 规范中引用了不受支持的功能，则在某些情况下，工具会忽略该功能，但仍呈现 API 参考文档。在其他情况下，不受支持的功能将导致错误，进而导致 API 参考文档无法成功呈现。无论哪种情况，您都需要修改 OpenAPI 规范，以避免使用不受支持的功能，直到将来的版本支持它为止。

• 在门户中使用“试用此 API”时，无论如何设置 OpenAPI 规范中 consumes 的值，Accept 标头都设置为 application/json。

• 目前不支持多用户同时进行门户更新（例如页面、主题背景、CSS 或脚本修改）。
• 如果您从门户中删除 API 参考文档页面，则无法重新创建该页面；您需要删除然后重新添加 API 产品，再重新生成 API 参考文档。
• 自定义门户主题背景时，更改最多可能需要 5 分钟才能完全生效。

在未来版本中，将把搜索集成到集成式门户中。

自定义网域不支持具有 SAML 身份提供商的单一退出 (SLO)。如需通过 SAML 身份提供商启用自定义网域，请在配置 SAML 设置时将“退出网址”字段留空。

• API 代理请求和响应计数（适用于代理和目标）显示异常峰值

  以下示例展示了此类峰值：

  （查看放大图片）

  
• 由于错误，系统会短暂地错误注册计数，稍后计数会更正。当 API 流量减少（导致 API 网关缩容）时，会发生这种情况。
• 如需区分请求的实际峰值与此问题，请参阅 API 分析页面（特别是代理性能和目标性能页面）

受影响的指标：

• apigee.googleapis.com/proxyv2/request_count
• apigee.googleapis.com/proxyv2/response_count
• apigee.googleapis.com/targetv2/request_count
• apigee.googleapis.com/targetv2/response_count

新指标

您可以使用新指标来避免此问题。

对于 Apigee Hybrid，请参阅指标收集概览和查看指标。

解决方法：在 Hybrid 上停用日志记录代理。

解决方法：要保持触发和忘记行为，请执行以下操作：

1. 将 <Response>calloutResponse</Response> 添加到 ServiceCallout。
2. 将 continueOnError 设置为 true。

解决方法：避免在代理中使用多个 SpikeArrest 政策来防止出现问题。

对于特定密钥，如果存在连续流量，则该密钥的速率可能不会限制为更新后的速率。如果某特定键有 5 分钟没有流量，则速率将反映出来。

解决方法：如果速率必须立即生效，请使用新的引用变量重新部署代理。或者使用两个具有不同流变量的条件高峰控制来调整速率。

可配置 API 代理的 API Monitoring 可能会针对来自目标具有非 2xx 状态的响应显示“（未设置）”故障代码。

如果代理使用同一目标主机在两个或多个流中设置两个或多个 io.timeout.millis 值，则系统仅会遵循 io.timeout.millis 值。

在升级到 Apigee Hybrid 1.8.x 期间，运行 apigeectl init 并确认 check-ready 成功后，您可能会注意到，如果您查看 pod，则 Cassandra 架构验证作业会处于错误状态。这种情况不会造成影响，您可以放心地进入升级流程的下一步。

不允许将具有相同路径的代理部署到连接到同一实例和环境组的多个环境，系统应返回有关基本路径冲突的警告消息。系统不会显示任何错误，并且部署似乎成功了。

临时解决方法：部署时以及部署后，验证基本路径与已部署的代理不存在冲突，并根据需要进行更正。

尝试保存先前部署的代理时，部署可能会失败，并显示指出修订版本不可变的错误。

解决方法：点击保存按钮旁边的下拉箭头，然后选择保存为新修订版本。然后，重新尝试部署。

如果更新 Apigee 服务器支持的默认加密集以增强安全性，可能会导致某些 TLS 版本出现 Unsupported protocol 错误。遇到这些错误的客户应查看 Envoy 的 FIPS 版本支持的加密的完整列表。

在调用 gRPC 目标服务器时，返回的唯一尾部便是“grpc-status”尾部。所有其他尾部的片段都会从响应中移除。