华为云 APIG 调用 401/403/超时分层排查：鉴权、流控、后端与域名

API 网关（APIG）把鉴权、流控、路由和协议转换挡在后端服务前面。线上常见现象是：控制台调试能通、客户端却 401；偶发 403；或者长时间无响应最后超时。很多人一上来就改后端代码或加大超时，其实先按「响应码 + 错误体」把问题定层，再逐项核对，会快很多。本文按华为云 APIG 常见配置，整理一份可复用的分层排查清单。

一、先定层：用状态码和错误体分类

排查前先固定一次可复现请求，记下：

• HTTP 状态码（401 / 403 / 429 / 502 / 504 / 超时无响应）
• 响应 Body 里的 error_code / error_msg（APIG 网关错误码形如 APIG.0303，以错误码为准，错误信息文字可能调整）
• 请求是否走自定义域名、是否 HTTPS、是否带 X-Apig-* 调试头
• 调试位置：控制台「调试」、同一 VPC 内 curl、公网客户端

粗分可以这样看（状态码只是线索，最终以 error_code 对照官方错误码表为准）：

控制台「调用分析 / 调用日志」或对接 LTS 后，能看到网关侧拒绝点；后端完全没收到请求时，可能是网关鉴权或策略拒绝，也可能是路由、网络或连接后端失败；结合调用日志与错误码定层，再决定是否改业务代码。

二、401：鉴权没过关

401 表示「没认出你是谁」或「签名对不上」。常见认证方式与核对点如下。

1. App 认证（HMAC / 签名）

很多开放 API 默认走 AppKey + AppSecret 签名。核对顺序建议：

1. Key / Secret 是否抄错或用了旧值：确认用的是该 API 已授权凭据的当前 Key/Secret（官方错误码 APIG.0303 即 APP 认证信息错误）。
2. 签名算法与规范是否一致：Canonical Request 的 method、path、query 排序、header 参与范围、body hash，任一不一致都会验签失败。
3. 时间偏差：签名带时间戳，官方排查建议明确要求检查客户端机器时间是否正确。容器、CI 机、嵌入式设备时钟漂移很常见，建议统一 NTP 校时。
4. Host / Path 是否用了「实际发出去」的那份：经代理改写 Host、或 path 多/少末尾 /，签名串与网关看到的不一致。

用 curl 做最小复现时，先确认同一 App、同一环境、同一 API 在控制台调试是否成功；控制台通、脚本不通，优先查签名实现与时钟，而不是后端。

# 示例：先确认本机时间（签名对时间敏感）
date -u
# 再对调试域名发一次带完整签名头的请求（签名头按所用 SDK/规范生成）
curl -v -X POST 'https://{apig-endpoint}/{basePath}/{apiPath}' \
  -H 'Content-Type: application/json' \
  -H 'X-Sdk-Date: ...' \
  -H 'Authorization: ...' \
  -d '{"ping":1}'

2. AppCode（简易认证）

官方文档写法是在请求 Header 中携带 X-Apig-AppCode，值为凭据详情里的 AppCode，网关只校验 AppCode、不校验签名。核对：

• API 是否为 APP 认证并开启了「支持简易认证」；已有 API 后开启的，需要重新发布才生效
• AppCode 所属凭据是否已授权（绑定）该 API
• 是否用 HTTPS（或 GRPCS）调用：简易认证不支持 HTTP
• 是否误把 Key 当成 AppCode 传

3. IAM 认证 / 自定义认证 / 其他 APP 认证方式

• IAM 认证（Token 或 AK/SK）：Token 过期、获取 Token 与调用跨区、AK/SK 签名不一致等，对应官方错误码 APIG.0301（IAM 认证信息错误）、APIG.0307（Token 需更新）。
• 实例开启的其他 APP 认证方式（如 app_api_key、app_basic、app_jwt 等，需在实例配置参数中开启）：确认实例开关已开、Header 写法与官方说明一致；若用的是 JWT 认证插件，校验失败对应 APIG.0319，需核对 token 与公钥/JWKS。
• 前端自定义认证（依赖 FunctionGraph 函数）：函数返回需符合约定格式（statusCode 与 body 内 status: allow/deny）；官方说明函数响应码非 200 时网关返回 500。排查时同时看 FunctionGraph 日志，并留意是否开启了「宽松模式」。

习惯做法：先用控制台调试（可指定认证方式）拿到「网关认为正确」的基线，再对比客户端 SDK 生成的 Canonical 串；比直接在业务日志里猜更省时间。

三、403：认出你了，但不许过

403 多半是策略层拒绝，但具体原因以 error_code 为准。

1. 凭据未授权 / 环境未发布

API 创建后需要：发布到环境 → APP 认证的 API 授权给凭据 → 客户端调用的正是该环境。不同情况错误码不同：官方错误码表中，凭据未绑定或未授权该 API 对应 APIG.0304（403）；API 不存在或未发布到环境对应 APIG.0101（404）。所以不要凭状态码下结论，先看错误码。

2. ACL 与 IP 访问控制

• 黑名单命中：源 IP（或经 ELB/CDN 后网关看到的 IP）在拒绝列表。
• 白名单模式：未列入则直接拒绝。
• 经多层代理时，网关看到的可能是代理出口 IP，而不是终端真实 IP；白名单要按网关实际看到的源地址来配，必要时先在调用日志里确认源 IP。

3. 流控

官方错误码中超出流控为 APIG.0308（429）。如果客户端或中间层把错误统一包装过，状态码可能失真，此时以原始响应体里的错误码为准，再对照流控策略的 API、用户、凭据、源 IP 各维度限制。

4. 其他策略

请求体/URI/Header 过大、跨域预检未开 CORS、第三方认证等插件校验失败，也会返回各自的错误码与状态码（不一定是 403）。以响应 error_code 对照官方错误码表，比只看状态码可靠。

四、超时与 5xx：后端与网络

网关鉴权通过后，请求才会打到后端。这一层重点看「网关有没有把请求送出去」以及「等多久算超时」。

1. 后端超时配置

APIG 上每个 API 的后端定义里有后端超时时间，上限受实例参数 backend_timeout 约束（以当前实例配置参数页为准）。后端处理超过该值，网关返回后端超时（官方错误码 APIG.0201/APIG.0203，504），即使后端后来算完了，客户端也已经失败。

核对：

1. 控制台该 API 的后端超时是否覆盖 P99 耗时。
2. 各层超时预算是否有层次：后端业务处理预算通常小于网关后端超时，网关后端超时又小于客户端的总等待预算，中间留出网络与重试余量；真正的长任务改成异步（提交后返回任务 ID，再轮询或回调），不要靠一路加大超时。
3. 慢请求是偶发还是全量：偶发优先查后端依赖（DB、下游 HTTP）；全量优先查地址/端口/协议配错。

2. 后端地址与协议

• 协议 HTTP / HTTPS 与后端监听是否一致；HTTPS 后端证书是否被网关信任（自签需按文档处理）。
• 路径拼接：网关「前缀剥离 / 追加」与后端真实路由是否对齐；多一个环境前缀就会 404，个别网关配置下也可能落到错误页或超时。
• 负载通道：用**负载通道（VPC 通道）**指向 ECS/CCE 等时，成员健康检查失败可能导致无可用后端，常见表现为后端不可用（502）；以错误码为准。

# 在与 APIG 后端同 VPC 的跳板机上，直接探测后端（绕过网关）
curl -v --max-time 5 http://{backend-ip}:{port}/{path}
# 若这里就不通，先修安全组/监听/服务，再回头看 APIG

3. 安全组、ACL 与 DNS

• 安全组：放行 APIG 出方向访问后端端口（网关节点网段以当前区域文档为准；VPC 通道场景下重点放行通道健康检查与业务端口）。
• 网络 ACL：子网级拒绝会让「安全组已放行」仍然不通。
• 后端用域名时：网关侧解析结果是否指向正确内网地址；内网域名是否仅在某 VPC DNS 可达。

4. 与 ELB / CCE 的衔接

后端挂在 ELB 上时，ELB 健康检查失败会导致网关拿到的上游不稳定。CCE 场景下 Service/Ingress 变更、Pod 未 Ready、网络策略拦截，都会在「鉴权已通过、后端随机失败」时出现——用调用日志里的后端延迟与状态码对齐 Pod 事件，比只盯 APIG 控制台更快。

五、域名、HTTPS 与跨域

1. 自定义域名

• 域名已在 APIG 绑定，且 DNS 的 CNAME 指向控制台给出的解析目标。
• 未生效时客户端可能打到旧 IP/旧网关，表现像「偶发 401」或证书名不匹配。
• 调试域名与正式域名的环境、分组可能不同，不要混用。

2. HTTPS 证书

• 证书与私钥匹配、未过期、链路完整（缺中间证时部分客户端失败）。
• SNI：多证书时客户端是否发送正确 Server Name。
• HTTP 强制跳转 HTTPS 后，客户端仍走 HTTP 明文，可能被重定向或直接失败。

3. CORS

浏览器预检 OPTIONS 若未在网关或后端正确放行，前端会报跨域，网络面板里往往先看到 OPTIONS 4xx。可在 APIG 配跨域插件/策略，或保证后端正确响应 Access-Control-Allow-*；两处都配时注意不要互相覆盖出矛盾值。

六、推荐排查顺序（可当作检查单）

1. 固定一次失败请求：状态码、error_code、域名、环境、AppId。
2. 401：密钥、签名串、时钟、认证类型是否与 API 配置一致；控制台调试对比。
3. 403/404：按错误码区分——凭据未授权（APIG.0304）、访问控制、API 未发布（APIG.0101，404）。
4. 429：对照流控策略各维度限制；客户端退避重试、削峰；业务确需更高额度时按流控规则调整策略或申请配额。
5. 超时/5xx：后端超时配置 → 同 VPC 直连后端 → 负载通道健康 → 安全组/ACL → ELB/Pod 健康。
6. 仅浏览器失败：证书、CORS、混合内容；用 curl 对比是否复现。
7. 仍不明：打开 APIG 调用日志 / LTS，确认拒绝发生在鉴权、策略还是后端阶段。

七、速查表

八、常见坑

1. 改完 API 定义忘记发布：编辑态与运行态不一致，调试域名仍走旧配置。
2. Secret 旋转后旧客户端未更新：部分成功、部分 401，像「偶发」，其实是多版本客户端并存。
3. 白名单只加了办公网出口：回家/移动网络/云上压测机出口不同，表现为与网络环境相关的拒绝。
4. 超时没有层次：后端日志显示成功，客户端已失败。后端业务预算通常应小于网关后端超时，网关又小于客户端总等待预算，并留出网络余量；长任务改异步。
5. 把 ELB 的 502 都当成 APIG 问题：先确认请求是否已到达 ELB/Pod。
6. 调试域名用于生产：限流、证书、SLA 与正式独立域名不同，排障结论不能直接外推。

九、小结

APIG 的 401/403/超时，本质是「认证 → 授权/策略 → 转发后端 → 域名协议」的管道问题。先读状态码与 error_code 定层，再用控制台调试作对照，最后才动后端代码与超时数字。把调用日志接到 LTS 后，拒绝点会清晰很多。配置项以当前区域控制台与官方文档为准；文中排查顺序、网络与 CORS/证书等通用建议来自一般运维实践，并非逐项官方保证，数字（超时上限、流控默认值等）以所用实例版本的控制台与官方文档为准。本文以 APIG 当前实例版用户指南为准，共享版（仅存量用户）界面与能力有差异。

参考（华为云官方文档）

• 调用 APIG 开放的 API（各认证方式请求写法）：https://support.huaweicloud.com/usermanual-apig/apig_03_0046.html
• APIG 的 API 错误码说明：https://support.huaweicloud.com/usermanual-apig/apig_03_0048.html
• 配置 API 简易认证 AppCode：https://support.huaweicloud.com/usermanual-apig/apig_03_0058.html
• 配置 API 的前端自定义认证：https://support.huaweicloud.com/usermanual-apig/apig_03_0069.html
• 配置 API 的流量控制：https://support.huaweicloud.com/usermanual-apig/apig_03_0025.html
• 配置 APIG 实例参数（backend_timeout、ratelimit_api_limits 等）：https://support.huaweicloud.com/usermanual-apig/apig_03_0039.html
• 调用 API 报 “Incorrect IAM authentication information”：https://support.huaweicloud.com/apig_faq/apig-faq-0003.html