ZTNA的排错信息
ZTNA的排错信息
ZTNA 访问失败时，可以结合错误页面、FortiGate 日志和终端状态，判断问题发生在终端证书、应用映射、后端连接、设备信息、标签策略还是用户认证环节。错误码用于确定检查方向，具体原因还需要与同一次访问的日志对应。
本文将错误码统一写成三位数字，例如 066 与日志中的 66 表示同一错误。不同 FortiOS 版本支持的错误码、替换页面和诊断命令可能有所不同。
排错前的准备
先记录以下信息，再复现一次失败访问：
| 信息 | 记录内容 |
|---|---|
| 故障时间 | 失败时间及所在时区，便于对齐终端、EMS 和 FortiGate 日志 |
| 访问目标 | 应用名称、访问域名、目标端口；HTTP/HTTPS 应用同时记录请求路径 |
| 故障表现 | 错误码、页面提示、客户端提示，以及全部终端失败还是个别终端失败 |
| 终端身份 | 终端名称、IP、UID，以及当前连接的 EMS |
| EMS 身份 | EMS 序列号和租户 ID，应与该终端实际所属的管理环境一致 |
| 软件版本 | FortiClient、EMS 和 FortiOS 版本 |
| 策略信息 | 失败请求对应的策略 ID、动作、用户和设备标签 |
排错时需要区分三条连接：
- FortiClient → EMS：用于终端管理、状态上报和配置下发。终端能够上网，不代表它已连接 EMS。
- FortiGate → EMS：用于获取设备信息和标签。EMS 中终端在线，不代表 FortiGate 已取得该终端的最新状态。
- 终端 → FortiGate → 真实服务器：业务访问路径。通过设备和身份检查后，仍需确认应用映射、后端网络和服务正常。
优先处理当前请求的明确错误。修改后重新建立连接，并根据新日志继续判断，不要使用修改前的错误页面确认结果。
错误码速查
终端证书
页面通常显示 Invalid ZTNA Certificate。
| 错误码 | 含义 | 优先检查 |
|---|---|---|
| 001 | 终端 ZTNA 证书无效，FortiGate 无法识别 | 证书有效性、信任关系及设备记录中的证书序列号 |
| 002 | 终端未提供客户端证书，且空证书处理设为阻断 | 此次连接是否提交证书，以及入口的证书要求 |
| 003 | 可管理的非移动终端未提供 ZTNA 证书 | EMS 纳管状态、证书签发及客户端配置下发 |
应用映射与后端连接
应用映射错误通常显示 ZTNA Application Not Found；连接或证书错误可能显示 ZTNA Connection Error。
| 错误码 | 含义 | 优先检查 |
|---|---|---|
| 021 | 未匹配到 API gateway | 请求域名、路径、服务与网关映射 |
| 022 | API gateway 中找不到对应的真实服务器 | 网关下的真实服务器定义与实际请求 |
| 023 | FortiGate 无法解析终端请求中的 FQDN | FortiGate 侧的 DNS 解析 |
| 024 | FortiGate 无法连接指定地址和端口的真实服务器 | 后端服务监听、路由和访问控制 |
| 025 | TCP forwarding 使用通配域名时，FortiGate 无法解析客户端请求的具体 FQDN | 具体域名、通配匹配及 FortiGate DNS |
| 026 | 真实服务器证书的 CN 与 access proxy 中的 FQDN 不匹配 | 配置的后端域名与实际返回的证书名称 |
| 027 | 真实服务器证书已过期 | 证书有效期及设备时间 |
| 028 | 真实服务器证书已被吊销 | 吊销状态和证书更换情况 |
| 029 | 真实服务器证书验证超时 | 验证日志及相关服务的可达性 |
| 030 | 真实服务器证书验证失败 | 证书链、证书内容和具体验证结果 |
| 031 | 真实服务器证书不受信任 | 签发链及 FortiGate 的信任配置 |
门户、策略与身份
策略和身份错误通常显示 ZTNA Policy Deny 或 Denied；门户错误通常显示 ZTNA Portal Error。
| 错误码 | 含义 | 优先检查 |
|---|---|---|
| 041 | 无法匹配 ZTNA 应用网关所用 SSL VPN Web 门户中的书签 | 门户分配、书签目标及请求对应关系 |
| 061 | 没有匹配的 ZTNA 策略 | 目标资源及策略匹配条件 |
| 062 | 命中拒绝策略 | 策略动作、顺序和命中记录 |
| 063 | EMS 签发的终端证书已被吊销 | 证书状态及吊销原因 |
| 064 | 终端标签命中拒绝策略 | 拒绝标签、标签规则及终端实际状态 |
| 065 | 标签未匹配允许策略，发生隐式拒绝 | 所需标签及标签取反条件 |
| 066 | FortiGate 找不到终端设备信息，无法完成设备验证 | EMS 连接、设备记录和当前连接使用的设备身份 |
| 067 | 终端未连接 EMS，被判定为离线并阻断 | FortiClient 到 EMS 的连接及状态同步 |
| 068 | 设备未知或未受管理，策略不允许未受管理设备访问 | 纳管状态、设备身份及策略要求 |
| 069 | 用户组不匹配，授权失败 | 认证返回的组信息与策略允许的组 |
| 071 | 用户认证失败 | 用户凭据、认证方式和认证服务日志 |
详细的错误信息
1. 终端证书排错：001、002、003
先确认失败连接是否提交了客户端证书，再检查证书是否有效、是否属于当前终端。
- 在 EMS 中核对终端管理状态，确认 ZTNA 配置和证书已经下发。
- 检查此次访问实际使用的证书，避免只确认终端上“存在证书”，却没有确认连接是否使用它。
- 对于
001，核对证书有效性、信任关系，并与 FortiGate 设备记录中的证书序列号比较。 - 对于
002，核对入口对空证书的处理要求，查明终端未提交证书的原因。 - 对于
003，重点检查可管理终端的注册、证书签发和配置下发情况。
终端重装 FortiClient、重新注册或迁移 EMS 后，应核对当前证书与当前设备记录是否对应，避免将旧记录作为判断依据。
2. 应用映射与后端排错：021—031
检查应用映射和 DNS
按照“实际请求 → API gateway → 真实服务器”的顺序检查：
- 021：未找到网关。 对照终端实际访问的域名、路径和服务，确认存在对应的网关映射。
- 022：未找到真实服务器。 检查已匹配网关中的真实服务器定义，确认目标地址和端口符合当前请求。此错误不能直接等同于后端网络超时。
- 023：请求域名解析失败。 从 FortiGate 侧检查该 FQDN 的解析结果。终端能够解析，不代表 FortiGate 使用的 DNS 也能解析。
- 024：后端连接失败。 确认后端服务正在监听指定端口，再检查 FortiGate 到后端的路由、返回路径和沿途访问控制。
- 025：通配域名对应的具体域名解析失败。 记录客户端本次请求的完整 FQDN，检查其是否符合通配规则，并确认 FortiGate 能解析该具体域名。
检查后端服务器证书
026—031 指向 FortiGate → 真实服务器 的证书验证，应检查后端实际返回的证书。
- 名称不匹配（026）：对照 access proxy 配置的后端 FQDN 与证书 CN，同时确认后端返回的是预期站点的证书。
- 过期或吊销（027、028）：核对设备时间、证书有效期和吊销状态，按证书管理流程更新或更换证书后复测。
- 验证超时（029）：结合详细日志确定超时环节，再检查该环节依赖的服务和网络路径。
- 验证失败或不受信任（030、031）：检查后端提供的证书链是否完整，以及 FortiGate 是否信任对应的签发链。
3. 门户排错：041
如果部署使用 ZTNA 应用网关与 SSL VPN Web 门户书签的访问方式，应核对用户被分配的门户、门户内的书签目标及当前请求是否对应。
此错误只适用于相关门户访问场景，具体功能支持情况需结合 FortiOS 版本和设备型号确认。
4. 策略与标签排错：061—065
先从失败请求中确认策略 ID、动作和设备标签，再检查策略条件。
| 错误码 | 处理步骤 |
|---|---|
| 061 | 确认存在覆盖目标资源的策略，再逐项核对请求是否满足匹配条件 |
| 062 | 找到实际命中的拒绝策略，检查规则顺序及拒绝行为是否符合授权设计 |
| 063 | 在 EMS 中确认终端证书的吊销状态和原因；设备恢复访问资格后，再按流程签发证书 |
| 064 | 找出导致拒绝的标签，在 EMS 中检查标签规则及触发该标签的终端状态 |
| 065 | 检查是否缺少允许标签，或命中了允许策略中被取反的标签条件 |
例如，允许策略要求终端不带有漏洞标签，而该终端当前带有此标签，也可能出现 065。检查时应同时考虑“缺少所需标签”和“存在被排除的标签”。
部分版本的替换页面会进一步显示导致拒绝的标签、未匹配的标签或 EMS 信息，可用来缩小检查范围。若标签不一致，沿 FortiClient、EMS、FortiGate 依次核对；若标签一致但仍拒绝，则继续检查策略条件及匹配顺序。
5. 设备信息排错：066、067、068
三类错误的检查重点不同：066 侧重 FortiGate 能否取得当前设备的信息，067 侧重终端是否连接 EMS，068 侧重设备是否已纳管并满足策略要求。
066：FortiGate 找不到设备信息
1. 检查 FortiGate 与 EMS 的连接
在 FortiGate 执行：
diagnose endpoint fctems test-connectivity <EMS>
diagnose test application fcnacd 2<EMS> 应替换为当前版本要求的 EMS 连接器标识。检查连接测试结果、EMS 身份及 WebSocket 状态。如果连接异常，先处理 FortiGate 到 EMS 的网络、名称解析和连接器配置问题。
2. 查询当前终端的设备记录
diagnose endpoint ec-shm list <终端IP>
diagnose wad dev query-by uid <UID> <EMS序列号> <租户ID>将占位内容替换为实际值，并与 EMS 中同一终端的记录比较：
- UID、EMS 序列号和租户 ID 是否属于当前终端。
- 注册状态、在线状态是否与 EMS 一致。
- 客户端证书序列号和设备标签是否符合当前终端状态。
如果设备记录存在，但 WAD 查询不到对应信息，应保留两组输出并采集调试日志。某个标签已同步，并不能证明当前失败请求已关联到正确设备。
3. 检查客户端证书获取设置
使用 EMS 标签匹配代理策略时，需要检查客户端证书获取设置。未启用客户端证书检查时，代理无法从客户端证书取得终端 UUID，也就无法完成相应的设备信息查询。
client-cert 的配置位置随版本变化：从 FortiOS 7.6.1 起位于 config firewall vip，较早版本的配置可能位于 config firewall access-proxy。检查当前入口的实际配置，并通过 CLI 帮助确认对应位置。
067：终端离线
- 在 FortiClient 和 EMS 中核对连接状态、最后在线时间，以及终端连接的 EMS 是否正确。
- 如果终端未连接 EMS，检查终端到 EMS 的名称解析、网络连通性及 FortiClient 服务状态。
- 恢复管理连接后，确认 EMS 已显示终端在线。
- 查询 FortiGate 的设备记录。如果仍显示离线，继续检查 FortiGate 与 EMS 的连接及状态更新日志。
- 状态同步后重新发起业务访问，检查新连接是否仍出现
067。
068：设备未知或未受管理
- 在 EMS 中查找终端，确认它已完成注册并处于管理状态。
- 核对失败连接使用的设备身份是否与 EMS 记录一致，尤其注意客户端重装、重新注册或迁移 EMS 后的记录变化。
- 如果业务要求受管理设备访问，先完成纳管和配置下发，再重新测试。
- 检查实际匹配策略对未受管理设备的要求。如果业务确实需要此类访问，应单独明确允许的用户、应用和访问范围。
068 表示当前设备被判定为未知或未受管理，且策略不允许访问；不能仅凭该错误认定终端没有安装 FortiClient。
设备信息恢复后仍然被拒绝
设备信息恢复后，后续检查仍可能因证书、标签或用户条件不满足而拒绝访问。应以新连接的错误码继续排查：
- 如果出现证书错误，对照当前终端证书与 FortiGate 设备记录中的证书序列号。
- 如果出现标签错误，比较终端、EMS 和 FortiGate 的标签，并检查实际命中的策略。
- 如果出现用户错误，继续检查认证结果和组匹配。
需要查看 ZTNA 缓存时，可执行：
diagnose test application fcnacd 76. 用户身份排错：069、071
069 是用户组授权失败，071 是用户认证失败。 设备证书和标签满足要求，并不代表用户身份条件也已满足。
| 错误码 | 排查步骤 |
|---|---|
| 069 | 核对认证返回的用户及组信息，检查组映射是否正确，并与策略允许的用户组比较 |
| 071 | 核对用户名、凭据和实际认证方式，结合认证服务或身份提供方的失败日志定位原因 |
对于 069，重点确认已认证用户是否属于允许访问的组；对于 071，应先解决认证本身的失败，再检查后续授权。
出现问题时调试日志的采集
根据故障位置选择对应调试。开启后复现一次，记录准确时间，采集完成后立即停止，避免持续输出大量日志。
FortiGate 与 EMS 的设备信息交换
diagnose debug app fcnacd -1
diagnose debug enable重点检查 FortiGate 与 EMS 的连接处理及设备信息更新。结合终端 UID、EMS 身份和失败时间筛选相关记录。
WAD 策略匹配
diagnose wad debug enable category policy
diagnose wad debug enable level verbose
diagnose debug enable重点检查代理处理中的策略匹配过程，并与失败请求的目标、设备身份、标签和策略 ID 对应。
停止调试
diagnose debug disable
diagnose debug reset恢复验证
完成处理后，按照原来的访问方式重新测试：
- 确认 EMS 与 FortiGate 对同一终端的管理状态、在线状态、证书和标签记录一致。
- 重新建立业务连接，确认目标应用可以正常访问。
- 检查新连接的日志，确认命中预期策略，原错误不再出现。
- 使用不满足策略条件的终端或用户验证拒绝行为，确认访问控制仍符合预期。
如果问题仍未解决，应保留失败时间、错误码、目标域名和端口、终端 UID、EMS 序列号、租户 ID、相关版本、设备查询输出和调试日志，并补充 FortiClient 诊断报告。所有材料应能够对应到同一次失败访问。
更新历史
| Ver | Description | Author | Rev | Date |
|---|---|---|---|---|
| 1.0 | First Complete | ysheng | tanga | 2026.11.02 |