运维与排查

日志

ApeAdmin 为 API 请求生成请求 ID，并在 sys_log 中记录方法、路径、状态码、耗时、用户和客户端信息。MCP 调用另有 McpAuditLog，可在管理台查看工具调用结果和失败原因。

排查插件问题时优先查看启动日志、插件 runtime_state / last_error、请求 ID 对应的 sys_log，以及浏览器 Network 中的 API 响应。

常见问题

菜单出现 404

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

插件显示启用但接口不存在

检查插件的 register(app) 是否执行成功，以及是否存在重复前缀。必要时先停用插件，再重新启用；不要直接删除正在运行的插件目录。

AI 文档分析失败

确认后台已配置 DeepSeek API Key、模型和网络访问；检查上传包是否超过大小/文件数限制，是否包含路径穿越、符号链接或加密文件。

官网页面资源 404

确认 Apehub_web 已启用，并检查 /apehub-web 静态挂载是否存在。发布插件包时必须包含 static/docs-portal，但不应包含开发用 node_modules。

生产检查清单

• 修改默认管理员密码并限制管理端访问。
• 使用环境变量或密钥管理配置数据库、JWT、SMTP、AI 和支付凭据。
• 使用迁移脚本而不是依赖自动建表。
• 为上传目录配置备份和访问控制。
• 验证停用、重新启用、升级和卸载流程，并确认菜单、路由、数据库和文件资源没有残留。