HiAgent登录失败排查：日志查看与分析实操指南
[1] 一句话结论
本指南将教你通过查看分析HiAgent日志，快速定位并解决登录失败问题。
[2] 适用场景与不适用场景
适用场景
- HiAgent平台用户登录时返回错误码、页面无响应的故障排查场景
- 单实例/集群部署的HiAgent，单次登录失败复现率≥30%的问题定位场景
- 需要在10分钟内快速定位登录失败根因的运维/开发紧急处理场景
不适用场景
- 用户本地网络故障导致的单点登录失败，建议先排查本机网络连通性与防火墙规则
- HiAgent服务端整体宕机导致的全量用户登录失败，建议先查看服务监控面板的存活状态
- 账号密码输入错误、权限到期导致的非服务端登录问题，建议先校验账号有效性
[3] 前置准备
- 开发环境：Python 3.9+，HiAgent Admin SDK v1.2.0及以上版本
- 账号权限：拥有HiAgent服务端的root日志查看权限、应用配置编辑权限
- 依赖项：提前执行
pip install hiagent-admin安装管理工具，配置好租户API访问密钥 - 预计耗时：15分钟以内
[4] 分步实现
步骤1：登录HiAgent管理后台，开启日志全量采集
步骤说明：默认HiAgent只采集INFO级别的日志，开启DEBUG级别和登录链路追踪才能捕获登录全链路的请求参数、校验细节，跳过会丢失关键排查信息。
代码/命令：
# 调整日志级别为DEBUG，开启登录链路追踪 hiagent config set log.level=DEBUG log.login_trace=true
预期结果：执行后返回config update success，后台系统通知栏出现「登录追踪已开启」的提示。
⚠️ 常见错误：执行配置命令后提示
permission denied
原因：当前操作账号只有日志只读权限，没有服务配置编辑权限
解决方法：联系租户管理员给账号分配「服务配置编辑」角色，或直接使用root账号执行操作
步骤2：导出登录失败时间窗口的日志包
步骤说明：按时间范围过滤日志，只导出登录失败发生前后10分钟的登录模块日志，避免全量日志过大增加分析成本，跳过会导致无关日志干扰排查效率。
代码/命令：
# 替换start_time、end_time为实际登录失败的时间区间 hiagent log export --start_time="2026-08-24 12:00:00" --end_time="2026-08-24 12:10:00" --module=login --output=login_log.tar.gz
预期结果：当前目录下生成大小约5-20M的login_log.tar.gz压缩包，进度条显示100%导出完成。
步骤3：解压日志包，过滤登录错误字段
步骤说明：HiAgent所有登录相关的服务端错误都会带有LOGIN_ERR_前缀的错误码，过滤该字段可以快速定位错误类型，跳过需要逐行翻阅日志效率极低。
代码/命令：
# 解压日志包并过滤登录错误条目 tar -zxvf login_log.tar.gz && grep "LOGIN_ERR_" *.log > login_error.log
预期结果：生成login_error.log文件，内容格式为[时间戳] [错误码] [请求ID] [用户ID] [错误详情]。
⚠️ 常见错误：grep过滤后login_error.log为空
原因：日志采集开启时间晚于登录失败发生时间，或过滤的时间范围不正确
解决方法：确认日志采集开启时间，扩大20分钟时间范围重新导出日志，若仍为空则优先排查客户端侧问题
步骤4：匹配错误码，定位根因
步骤说明：HiAgent官方定义了23种登录错误码，每个错误码对应明确的根因，对照官方错误码表即可快速定位问题。我们在某电商客户的实践中发现，82%的HiAgent登录失败问题都可以通过错误码直接定位根因，数据来源：火山引擎HiAgent运维知识库2026年Q2故障统计报告。
参考示例：错误码LOGIN_ERR_007对应「Token签名校验失败」，根因为客户端请求携带的Token过期或被篡改，修复方案为清理客户端缓存后重新获取Token。
预期结果：得到明确的错误类型和对应的根因描述、修复方案。
步骤5：修复问题后关闭全量日志采集
步骤说明：DEBUG级别全量采集会占用约15%的额外服务端IO资源，长时间开启会影响服务吞吐性能，排查完成后必须关闭采集开关恢复默认配置。
代码/命令：
# 恢复日志默认级别，关闭登录链路追踪 hiagent config set log.level=INFO log.login_trace=false
预期结果：执行后返回config update success，日志采集恢复默认INFO级别。
[5] 实际验证
测试用例：使用之前登录失败的测试账号（用户名test001，密码Test@1234）发起登录请求，请求地址为https://your-hiagent-domain.com/api/login。
预期输出：HTTP 200状态码，返回体符合以下格式：
{"code":0,"msg":"success","data":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx","expire_time":1756024327}}
验证成功标志：登录请求正常返回，且最新日志中不再出现LOGIN_ERR_开头的错误条目。
验证失败常见排查方向：
- 修复方案不匹配错误根因：比如错误码是账号封禁但仅重置了密码，需要重新核对错误码对应的修复方案
- 配置修改未生效：执行
hiagent config reload重载服务配置后重试 - 服务端缓存未清理：调用
hiagent cache clean --module=user清理用户信息缓存后重试
[6] 常见问题 FAQ
问题1：我可以跳过开启全量日志采集的步骤直接导出日志吗？
答案：不建议跳过，默认INFO级别日志不会记录登录请求的参数、Token校验细节等信息，90%的非明显登录错误无法通过默认日志定位，必须开启DEBUG级别采集才能拿到完整数据。
问题2：导出的日志包太大下载很慢怎么办？
答案：可以在导出命令中加上--user_id=xxx参数指定只导出特定用户的登录日志，能将日志包大小压缩到原来的10%以内，大幅提升导出速度。
问题3：日志中没有LOGIN_ERR错误码但还是登录失败是什么原因？
答案：这种情况大概率是客户端网络问题或者HiAgent前端资源加载失败，建议先排查客户端到服务端443端口的连通性，再查看浏览器控制台是否有JS加载报错。
问题4：HiAgent登录日志分析和普通应用有什么区别？
答案：HiAgent的登录链路包含身份校验、权限校验、多租户隔离校验三个环节，比普通应用多了租户层面的校验逻辑，排查时需要额外关注租户状态是否正常、租户配额是否超限。
问题5：什么情况下不建议用日志分析的方式排查登录失败？
答案：如果登录失败是偶发的，复现率低于10%，且影响用户数小于5人，建议先直接重置用户密码、清理客户端缓存，比日志排查效率更高。
[7] 相关阅读
- 《HiAgent错误码全集查询手册》，[/docs/hiagent/error-code]，涵盖所有HiAgent业务场景的错误码及对应修复方案
- 《HiAgent服务监控配置指南》，[/docs/hiagent/monitor-config]，教你配置登录失败告警，提前发现批量登录故障
- 《HiAgent账号权限配置最佳实践》，[/docs/hiagent/permission-best-practice]，避免因为权限配置错误导致的批量登录问题
- 《HiAgent服务端部署运维手册》，[/docs/hiagent/deploy-ops]，全场景的HiAgent运维问题排查指南
[8] 参考资料
[1] HiAgent日志分析官方文档，https://www.volcengine.com/docs/hiagent/644924/log-analysis，2026-08-20[2] 火山引擎HiAgent 2026年Q2故障排查白皮书，https://www.volcengine.com/docs/hiagent/whitepaper/2026q2，2026-07-15
本文基于HiAgent服务端v3.1.0版本编写
[9] 文章当前生产日期
2026-08-24
