故障排除
本页汇集使用 Almirant 时最常见的问题及其解决方案。如果没有列出你的问题，请通过 [email protected] 联系支持团队。
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| IDE 无法连接 MCP | URL 或 API 密钥不正确 | 确认 URL 为 https://api.almirant.ai/mcp?projectId=<id>，且 API 密钥有效。如果使用 localhost，请确认后端正在运行。 |
| 连接 MCP 时出现 "Unauthorized" | API 密钥已过期或被撤销 | 在 设置 > API 密钥 中生成新的 API 密钥，并更新 IDE 配置。 |
| MCP 已连接但看不到项目 | 缺少 projectId 或其值不正确 | 检查 URL 中的 projectId。可以从在 Almirant 中打开项目时的浏览器 URL 获取它，或在没有 projectId 的情况下使用 list_projects。 |
| 无法登录 | Google 账户未获授权 | 你的电子邮件必须在组织允许的电子邮件列表中。请联系管理员将其添加。 |
| 工作项未显示在看板中 | 工作项已归档或筛选器生效 | 检查看板顶部栏中已启用的筛选器。如果工作项已归档，请启用“显示已归档项”筛选器以查看它们。 |
| AI 不实现任务 | 工作项描述不够充分 | 确保工作项包含详细描述和验收标准。没有上下文，AI 无法确定该实现什么。 |
| 看板中的拖放无法使用 | 与浏览器扩展冲突 | 禁用会修改 DOM 的扩展（激进的广告拦截器、拦截事件的无障碍工具）。在无痕窗口中尝试。 |
| Webhook 未收到事件 | URL 无法访问或需要 HTTPS | 确认 URL 可从互联网访问并使用 HTTPS。检查 设置 > Webhooks 中的投递日志以查看错误。 |
| Webhook 返回 401 | 签名验证不正确 | 请确保使用原始（raw）请求正文而不是已解析的请求正文来计算 HMAC 签名。确认密钥与已配置的值一致。 |
| 迭代无法关闭 | 有未解决的工作项 | 迭代可以在存在待处理工作项时关闭。关闭时可以将未完成项移至 Backlog 或下一个迭代。 |
| 导入潜在客户（CSV）时出错 | 文件格式不正确 | 确认 CSV 使用逗号作为分隔符，并包含必需列（name、email）。从导入页面下载模板。 |
| 反馈小组件未显示 | 脚本未加载或密钥不正确 | 确认脚本位于 </body> 之前，URL 正确（https://cdn.almirant.ai/feedback-widget.iife.js），且 publicKey 有效。 |
| 从 IDE 连接时出现 "CORS" 错误 | 后端未为你的源配置 CORS | 如果使用本地后端，请确认 .env 中的 CORS_ORIGIN 包含正确的源。在生产环境中不应出现此问题。 |
| AI 规划未生成结果 | 未配置 AI 提供商 | 前往 设置 > 集成 并连接 AI 提供商（Anthropic 或 OpenAI）。至少需要一个有效的 API 密钥。 |
| 加载大型看板时性能缓慢 | 可见工作项过多 | 使用筛选器限制可见工作项。归档较早完成的工作项。看板在可见工作项少于 200 个时性能最佳。 |
高级调试
验证 MCP 连接
在 Claude Code 中运行以下命令以验证连接是否正常：
使用 `list_projects` 工具列出我的项目
如果能看到你的项目，连接就正确；否则：
- 确认后端正在运行（本地开发中使用
bun run dev:api） - 检查
.mcp.json或.claude/settings.json中的 URL - 确认 API 密钥对所指定项目具有权限
- 检查后端日志中的身份验证错误
验证 Webhooks
如需调试无效的 webhook：
- 前往 设置 > Webhooks 并选择该 webhook
- 检查 投递 标签以查看最近尝试
- 点击一次失败的投递以查看详情（请求、响应、标头）
- 如果没有投递，请确认订阅的事件与正在执行的操作匹配
- 使用 webhook.site 等服务测试 Almirant 是否正确发送请求
反馈小组件问题
如果小组件未显示或无法工作：
- 打开浏览器控制台（F12 > 控制台）并查找错误
- 确认脚本已正确加载：在控制台中输入
FeedbackWidget。如果结果为undefined，则脚本未加载 - 确认
FeedbackWidget.isReady()返回true - 检查项目配置中的
publicKey是否正确 - 如果使用 React，请确保
<FeedbackWidget>组件已挂载到树中
浏览器日志
对于任何 Web 界面问题：
- 打开开发者工具（F12）
- 前往 控制台 标签并查找红色错误
- 前往 网络 标签并筛选失败的请求（状态码 4xx 或 5xx）
- 如果报告缺陷，请附上：
- 控制台错误截图
- 出现问题的页面 URL
- 浏览器及版本
- 复现步骤
提示
如果某项功能没有按预期工作，第一步始终是检查浏览器控制台和后端日志。大多数问题都可通过这两个位置的信息解决。