500错误需先确认请求是否到达aionclaw进程：用x-request-id在服务端日志中搜索，无匹配则问题在网关层；有匹配则查error日志堆栈、检查数据库健康状态（/actuator/health/db）、复现请求并用ide调试定位异常源头。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在调用 AionClaw 后端接口时收到 500 Internal Server Error，说明请求已抵达服务端，但后端在处理过程中发生了未捕获的异常或环境故障，此时不能只盯着前端请求是否规范，必须进入服务端上下文定位真实失败点。
确认请求是否真正到达 AionClaw 应用进程
第一步不是看日志，而是验证请求有没有穿过网关/负载均衡落到 AionClaw 实例上。打开浏览器 Network 面板，复制出错请求的完整 URL 和请求头（尤其是 X-Request-ID 或 trace-id），然后登录 AionClaw 所在服务器，执行：
【grep -r "your-request-id" /var/log/aionclaw/ --include="*.log"】
如果完全搜不到任何匹配行，说明请求被拦截在前置组件（如 Nginx、CLB、K8s Ingress）层。此时应立即检查 CLB 的访问日志，重点关注 upstream_status 字段：若为 - 或空值，代表请求压根没发到后端；若为 500，才说明问题真正在 AionClaw 内部。
快速提取关键错误堆栈
在确认请求已进入 AionClaw 进程后，直接定位最近 30 秒内的 ERROR 级日志行：
cd /var/log/aionclaw && tail -n 200 application.log | grep -A 5 -B 5 "ERROR\|Exception\|Caused by"
重点捕获三类信息：异常类名（如 NullPointerException）、发生位置（文件名+行号）、最顶层的 Caused by 链。Spring Boot 项目中，若看到 org.springframework.web.HttpRequestMethodNotSupportedException，说明是 405 被错误包装成了 500——这属于全局异常处理器配置缺陷，不是业务逻辑崩了。
注意：不要依赖日志时间戳判断“最新”，有些日志框架异步刷盘会导致时间错乱，以 grep 出的最后几行 为准。
检查运行时依赖状态
方法一：验证数据库连接是否存活
进入 AionClaw 应用所在服务器，执行 curl http://localhost:8080/actuator/health -s | jq '.components.db.status'。返回 "UP" 是基础要求；若为 "DOWN"，立刻检查 application.yml 中 spring.datasource.url 是否指向了正确的地址和端口，【特别注意数据库密码是否因特殊字符未做 URL 编码】。
方法二：手动触发一次最小化依赖探活
curl -X GET "http://localhost:8080/actuator/health/db" -H "Authorization: Bearer ${TOKEN}" 2>/dev/null | grep -q "UP" || echo "DB is unreachable"
这一步绕过 Spring Boot 的复合健康检查逻辑，直击数据库连接池底层，能暴露 HikariCP 初始化失败等隐藏问题。
复现并隔离异常请求
第一步：用 curl 复现原始请求，强制输出响应头和 body：
curl -v -X POST "https://api.aionclaw.dev/v1/tasks" -H "Content-Type: application/json" -d '{"name":"test"}'
第二步：观察 -v 输出中的 > 行之后是否紧跟 X-Application-Error-ID 头。如果有，拿这个 ID 去查日志，比用时间戳精准十倍。
第三步：若复现稳定，立即在本地启动 AionClaw（profile=dev），用相同 payload 请求 localhost:8080，IDE 中在 DispatcherServlet.doDispatch() 方法首行打条件断点，条件设为 request.getRequestURL().toString().contains("/v1/tasks")，单步步入，直到抛出异常的位置浮出水面。
