运维与排查

日志

ApeAdmin-Gin 使用 Zap 输出结构化 JSON 日志。每个请求由 request_id 中间件分配唯一 ID，贯穿整个调用链路。操作日志通过异步队列（auditqueue）写入，不阻塞主请求。

MCP 调用自动记录审计日志，包含请求参数、响应结果、耗时和调用者信息，可在管理台查看。

排查问题时优先查看启动日志、插件状态、RequestID 对应的日志条目，以及浏览器 Network 中的 API 响应。

常见问题

菜单 404

检查菜单 component 是否能在 frontend/src/views 下找到同名 .vue 文件，大小写必须一致；然后退出管理台并重新加载用户菜单。

插件接口不存在

检查插件 Register() 是否执行成功，查看启动日志中的插件加载阶段输出。L2 ZIP 插件需确认 manifest 清单格式正确。必要时先停用再重新启用。

AI 对话失败

确认后台已配置 AI 模型 API Key 和网络访问；检查 MCP 网关超时设置（默认 30s）和并发限制（默认 10）。查看 MCP 审计日志中的错误详情。

资源 404

确认目标插件已启用，检查静态文件目录配置（app.spa_dir）和路由注册是否正常。

生产检查清单

• [ ] 修改 jwt.secret，否则密钥熔断机制拒绝启动（debug=false 时检测默认密钥）。
• [ ] 调整数据库连接池 max_open_conns 匹配实际负载。
• [ ] 确认 API 限流参数（每 IP 每分钟 300 次，burst 50）符合需求。
• [ ] 配置 CORS Origins 为生产域名。
• [ ] 验证优雅关闭流程：插件卸载 → 事件通知 → 日志 drain → DB 断连。
• [ ] 为 uploads/ 目录配置备份和访问控制。