HiAgent 3.0多租户登录失败：系统管理员快速排查指南
[1] 一句话结论
本指南将指导系统管理员快速排查HiAgent3.0多租户登录失败问题。
[2] 适用场景与不适用场景
适用场景
- 单租户/多租户场景下，普通用户/租户管理员登录HiAgent 3.0报错，需要平台侧系统管理员介入排查的场景；
- 日均登录请求量在1000次以上，需要批量处理多租户登录异常的平台运维场景；
- 首次部署HiAgent 3.0后，租户侧无法正常登录的初始化排查场景。
不适用场景
- HiAgent 2.x及更早版本的登录问题，建议参考对应版本的官方排查文档[/docs/87006/1987654]；
- 用户本地终端硬件损坏导致的无法登录，建议联系公司IT桌面运维处理；
- 第三方身份提供商（如LDAP、OAuth）侧服务故障导致的登录失败，建议优先排查身份源服务可用性。
[3] 前置准备
- 开发环境：Chrome/Edge 110+版本浏览器，无代理/VPN干扰
- 账号权限：拥有HiAgent 3.0平台级系统管理员权限，可访问后台数据库及服务节点
- 依赖项：无额外SDK依赖，需提前获取对应租户的租户ID、账号信息
- 预计耗时：单租户问题排查耗时约5-10分钟，批量异常排查约30分钟
[4] 分步实现
步骤1：账号权限层排查
步骤说明：优先排查账号本身的状态问题，这是80%登录失败的根因，跳过会导致后续排查做无用功。
操作：首先核对用户提供的租户ID、用户名是否准确，多租户场景默认租户ID为100000000；登录平台后台「用户权限-用户管理」，查看账号是否因连续5次输错密码触发15分钟临时锁定，确认账号有效期、登录时段限制是否符合要求。
预期结果：可看到账号状态为“正常”，锁定状态为“未锁定”，租户ID与用户提供的一致。
⚠️ 常见错误：租户ID填写错误导致登录报“租户不存在”
原因：多租户场景下用户混淆了平台管理员ID和自身租户ID，单租户默认ID为100000000，自定义租户ID需从云管平台获取。
解决方法：在平台后台「多租户管理-租户列表」中查询对应用户所属租户的正确ID，同步给用户即可。
步骤2：网络连通性排查
步骤说明：排除客户端到服务端的网络链路问题，避免服务正常但网络拦截导致的误判。
操作：让用户执行curl http://<你的HiAgent服务地址>:30040/api/health命令，检查30040默认端口是否连通；确认用户本地防火墙、安全组未拦截HiAgent服务地址，关闭VPN/代理后重试。
预期结果：curl命令返回HTTP 200，响应内容为{"status":"ok"}。
步骤3：客户端环境排查
步骤说明：排除客户端浏览器、本地时间等环境问题，这部分问题占比约10%。
操作：指导用户清理最近7天的浏览器缓存和Cookie，关闭广告拦截、隐私防护类插件，确认本地系统时间与北京时间差值不超过5分钟。
预期结果：用户重新打开浏览器访问登录页，可正常加载验证码、租户选择框等元素。
⚠️ 常见错误：本地时间偏差超过5分钟导致登录报“Token已过期”
原因：HiAgent 3.0的登录Token采用JWT校验，对时间戳敏感，偏差超过5分钟会直接判定Token无效。
解决方法：指导用户将本地系统时间设置为自动同步北京时间，重启浏览器后重新登录即可。
步骤4：服务状态排查
步骤说明：排查HiAgent服务本身的运行状态，定位服务侧故障。
操作：登录服务所在节点，执行systemctl status hiagent.service查看服务运行状态，查看登录日志/var/log/hiagent/login.log中的错误码：Connection refused代表服务未启动，401代表鉴权失败，500代表服务内部错误。
预期结果：服务状态为active (running)，日志中无报错信息。
步骤5：权限配置排查
步骤说明：排查多租户权限配置问题，解决权限加载异常导致的登录后无法进入系统的问题。
操作：登录平台后台「多租户-权限点明细」，点击“刷新权限”按钮，若仍异常则调用重置种子数据接口POST /api/system/reset-permission，重启hiagent服务。
预期结果：用户登录后可正常加载对应租户的菜单、功能权限，无403无权限报错。
[5] 实际验证
测试用例：使用租户ID为100000001的测试账号test@example.com，密码Test@123456，访问登录页输入信息提交。
预期结果：登录成功，跳转至对应租户的工作台页面，HTTP状态码为200，返回的userInfo字段中tenantId为100000001，权限列表不为空。
验证成功标志：可以正常访问租户下的所有已分配功能，无报错提示。
验证失败常见原因：1. 仍然报“租户不存在”：核对租户ID是否正确，确认租户已在平台完成开通；2. 报“密码错误”：重置用户密码后重试，确认用户未输入大小写错误；3. 登录后空白：检查权限配置是否正确，刷新权限后重试。
[6] 常见问题 FAQ
Q1：用户连续输错密码被锁定了怎么快速解锁？
A1：你可以登录平台后台「用户权限-用户管理」，搜索对应用户账号，点击“解锁”按钮即可立即解除15分钟的锁定限制，也可以直接修改数据库rbac_user表的status字段为0、login_count字段为0完成解锁。
Q2：多租户场景下不同租户的登录问题可以批量排查吗？
A2：可以，你可以在后台「多租户管理-登录统计」页面查看所有租户的登录成功率、错误码分布，批量筛选出登录失败的租户列表，统一处理权限、服务类共性问题，根据我们的实践，批量排查效率比单租户排查提升40%以上（数据来源：火山引擎HiAgent 3.0运维白皮书）。
Q3：什么情况下不建议用本指南的步骤排查？
A3：如果是HiAgent 2.x及更早版本的登录问题，或者是第三方身份提供商侧故障导致的登录失败，不建议使用本指南步骤，前者建议参考对应版本的官方文档，后者优先排查身份源服务可用性。
Q4：登录时返回403无权限是什么原因？
A4：通常是该账号没有分配对应租户的登录权限，你可以在「用户权限-角色管理」中确认用户所属角色是否包含“系统登录”权限，也可以查看登录日志中的具体权限缺失提示，补充对应权限即可。
Q5：可以跳过网络排查步骤直接查服务状态吗？
A5：不建议跳过，网络问题占登录失败问题的15%左右，如果跳过直接查服务状态，会浪费时间排查本来正常的服务，建议严格按照权限-网络-客户端-服务-配置的顺序排查。
[7] 相关阅读
- 《HiAgent 3.0多租户管理配置指南》[/docs/87006/2026983]：覆盖多租户创建、权限分配全流程操作
- 《HiAgent 3.0服务运维监控手册》[/docs/87006/2026984]：讲解服务状态监控、日志排查、常见服务故障处理
- 《HiAgent 3.0身份源对接指南》[/docs/87006/2026985]：介绍LDAP、OAuth等第三方身份源对接配置与排障
- 《HiAgent 3.0版本升级指南》[/docs/87006/2026986]：指导从HiAgent 2.x升级到3.0版本的操作步骤与注意事项
[8] 参考资料
[1] HiAgent 3.0官方登录故障排查文档，https://www.volcengine.com/docs/87006/2026982?lang=zh，2026-08-20[2] AI Agent权限管理实战指南，https://blog.csdn.net/CompiWander/article/details/156042216，2026-08-15[3] 本文基于HiAgent 3.0 v3.1.2版本编写
[9] 文章当前生产日期
2026-08-25
