本指南旨在解决私有化部署客户在集成第三方身份源（如飞书、LDAP、企业微信等）时遇到的各类登录认证问题。

• 客户端无法加载登录配置
• 浏览器认证失败
• 客户端认证失败
• 账号密码登录失败
• 短信、邮箱、动态口令验证码发送/校验失败
• 登录态无法正常颁发、无法登录成功，无法使用飞连后续功能等

在开始通用的排障流程前，我们建议您首先查阅针对特定身份源的常见问题和排障指南。这些文档可能包含了针对您所遇问题的快速解决方案。

• 飞书认证排障指南
• LDAP 认证排障指南
• 身份认证常见问题

如果上述文档未能解决您的问题，请继续遵循下文的排障步骤进行深度排查。

检查飞连 server 到第三方平台的网络联通性

1. 使用 ping 命令测试网络可达性，以飞书为例：ping open.feishu.cn。
2. 检查是否可以正常请求，是否有请求响应比较慢的情况。

分析服务日志

获取日志

您可以通过以下任一方式获取**用户门户（Portal）**服务的日志：

• 通过运维平台
  登录飞连 server 运维平台，导航至集群管理 ＞ 服务列表 ＞ 用户门户，查看详情获取服务日志。
• 通过服务器后台
  使用 SSH 登录到飞连服务器后台查看日志文件。文件路径如下：

  /otp/corplink/log/portal.*.log
  

分析日志

在获取到日志和服务器访问权限后，请按以下顺序进行深度排查。

1. 服务日志分析
   请在用户门户（Portal）服务的日志文件中，重点关注用户尝试登录时间点附近的输出，并分析其中的错误信息。
   • 关键日志指标
     • 搜索关键词：​在日志中优先搜索 ERROR, Exception, login, thid_party_login 等关键词，快速定位异常。
     • 关注响应时间：​注意记录中每个请求的处理耗时。如果耗时过长（例如 ＞ 5s），通常表明存在网络或性能瓶颈。
   • 常见错误模式诊断
     • 模式一：参数错误（Error Code 40000）
       • 现象：​日志显示 /api/login 接口返回 40000（参数错误），并可能伴有数据库相关的报错。
       • 排查方向：​这通常与数据库连接有关。请重点检查数据库是否因主备切换等原因，导致当前的应用连接实例处于只读状态。例如：主备切换后，未能及时更新 online.yaml 配置文件中的数据库地址，导致应用仍在尝试写入旧的主库（现为只读备库）。
     • 模式二：第三方平台错误
       • 现象：​日志中直接记录了来自第三方平台（如 LDAP、飞书）的报错信息。
       • 排查方向：​请根据报错内容，前往对应的第三方平台检查相关配置，例如：IP 白名单是否正确、应用权限是否足够、用户账号是否存在等。

性能与负载排查

如果日志中没有明确的错误指向，问题可能源于服务性能压力。

1. 服务性能监控
   1. 登录飞连运维平台，打开 Grafana 监控看板。
   2. 进入“用户门户（Portal）”服务的仪表盘。
   3. 重点关注以下两个指标在问题发生时间段内的变化：
      • 接口响应时延（Latency）：​查看 P99 或 P95 分位数时延是否存在异常尖峰。
      • 每秒请求数（QPS）：​确认请求量是否远超正常水平，导致服务过载。
        
        
2. 服务器负载检查
   服务性能下降也可能由底层服务器资源耗尽引起。
   1. 通过 SSH 登录到飞连服务器后台。
   2. 使用 top, htop, iostat 等标准 Linux 命令，检查以下系统指标：
      • 系统平均负载（Load Average）：​确认负载是否远超 CPU 核心数。
      • CPU / 内存使用率：​检查是否有进程异常占用大量资源。
      • 磁盘 I/O（iowait）：​检查磁盘读写是否成为瓶颈。

• 飞连认证渠道工程师：请通过飞书搜索飞连 FOC，提交工单处理。
• 企业用户：请通过火山引擎官网提交工单处理。