# 故障排除

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [electron/main.ts](file://electron/main.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/lib/forge-data.ts](file://src/lib/forge-data.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/app/api/im-channels/[id]/route.ts](file://src/app/api/im-channels/[id]/route.ts)
- [src/app/api/im-channels/[id]/connect/route.ts](file://src/app/api/im-channels/[id]/connect/route.ts)
- [src/lib/mcp-test.ts](file://src/lib/mcp-test.ts)
- [src/app/api/chat/route.ts](file://src/app/api/chat/route.ts)
- [src/app/api/api-providers/[id]/test/route.ts](file://src/app/api/api-providers/[id]/test/route.ts)
- [src/app/api/api-providers/cli-login/route.ts](file://src/app/api/api-providers/cli-login/route.ts)
- [src/hooks/use-chat.ts](file://src/hooks/use-chat.ts)
- [src/hooks/use-im-channels.ts](file://src/hooks/use-im-channels.ts)
- [src/hooks/use-cron-tasks.ts](file://src/hooks/use-cron-tasks.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构与定位](#项目结构与定位)
3. [核心组件与常见问题域](#核心组件与常见问题域)
4. [架构总览与故障路径](#架构总览与故障路径)
5. [详细故障排查流程](#详细故障排查流程)
6. [依赖关系与耦合分析](#依赖关系与耦合分析)
7. [性能问题识别与优化](#性能问题识别与优化)
8. [错误代码与症状对照表](#错误代码与症状对照表)
9. [监控与告警最佳实践](#监控与告警最佳实践)
10. [结论](#结论)

## 简介
本指南面向使用 Forge 的用户与开发者，聚焦于安装、运行、功能异常、网络与数据库相关问题的系统化排查方法。内容覆盖日志分析、网络诊断、数据库检查、性能优化、错误对照与监控告警建议，帮助快速定位并解决问题，降低停机时间与维护成本。

## 项目结构与定位
Forge 是基于 Electron + Next.js 的桌面应用，后端服务以独立 Node 进程在本地启动，数据存储采用 SQLite（WAL 模式），并通过数据库迁移与自动同步机制保障配置一致性。IM 桥接层支持多平台消息通道，定时任务引擎负责周期性执行与结果记录。

```mermaid
graph TB
subgraph "桌面进程"
A["Electron 主进程<br/>启动本地服务/目录监听/剪贴板"]
end
subgraph "Next.js 服务"
B["API 路由层<br/>会话/消息/设置/IM/定时任务"]
C["核心库<br/>数据库/桥接/定时任务/MCP 测试"]
end
subgraph "外部系统"
D["Claude Code CLI"]
E["IM 平台<br/>飞书/电报/Discord"]
F["SQLite 数据库"]
end
A --> |"启动/通信"| B
B --> C
C --> F
C --> |"读取/写入"| F
C --> D
C --> E
```

图示来源
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/im/bridge-manager.ts:45-626](file://src/lib/im/bridge-manager.ts#L45-L626)
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)

章节来源
- [README.md:343-382](file://README.md#L343-L382)
- [package.json:13-26](file://package.json#L13-L26)

## 核心组件与常见问题域
- 安装与启动
  - 缺少 Claude Code CLI 或未认证
  - 首次启动弹窗与 Gatekeeper 提示
  - 服务器启动失败（端口占用/环境变量）
- 数据库与数据迁移
  - 数据目录位置与权限
  - 数据库文件损坏/锁
  - 迁移逻辑与兼容性
- IM 桥接
  - 凭据配置错误/鉴权失败
  - 连接断开/重连退避
  - 消息重复/去重策略
- 定时任务
  - 任务未触发/重复执行
  - 执行结果记录与状态更新
- MCP 服务器
  - 命令存在性/可执行性
  - HTTP/SSE 可达性
- 聊天与权限
  - 权限决策失败
  - 会话恢复异常

章节来源
- [README.md:268-341](file://README.md#L268-L341)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/lib/im/bridge-manager.ts:45-626](file://src/lib/im/bridge-manager.ts#L45-L626)
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)
- [src/lib/mcp-test.ts:9-50](file://src/lib/mcp-test.ts#L9-L50)

## 架构总览与故障路径
```mermaid
sequenceDiagram
participant U as "用户"
participant M as "主进程(electron/main)"
participant S as "Next.js 服务"
participant DB as "数据库(lib/db)"
participant IM as "桥接管理器(lib/im)"
participant CLI as "Claude Code CLI"
U->>M : 启动应用
M->>M : 查找可用端口/准备环境
M->>S : 启动本地服务(生产用系统 Node)
S-->>M : 服务就绪(健康检查)
U->>S : 访问设置/IM/定时任务
S->>DB : 初始化/迁移/查询/写入
S->>IM : 启动/停止/轮询适配器
IM->>CLI : 通过 SDK 发起调用
IM-->>U : 返回消息/附件/状态
```

图示来源
- [electron/main.ts:74-139](file://electron/main.ts#L74-L139)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/im/bridge-manager.ts:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)

## 详细故障排查流程

### 一、安装与启动问题
- 症状
  - 应用无法启动或黑屏
  - 弹出“服务器无法启动”提示
  - 首次启动出现 Gatekeeper 提示
- 排查步骤
  1) 确认 Claude Code CLI 已安装且可执行：参考安装与认证说明。
  2) 检查主进程日志输出（标准输出/错误输出）以确认端口占用与 Node 可用性。
  3) 若为首次启动，按提示放行应用或调整安全设置。
  4) 在开发模式下，确认 Next.js 服务已在本地端口运行；生产模式下确认打包资源与独立服务脚本存在。
- 关键定位点
  - 服务器启动与等待逻辑、错误对话框提示。
  - 环境变量 PATH 对 CLI 的可见性扩展。
  - 数据目录初始化与迁移。

章节来源
- [README.md:268-305](file://README.md#L268-L305)
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [electron/main.ts:85-103](file://electron/main.ts#L85-L103)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)

### 二、数据库问题（连接/迁移/锁）
- 症状
  - 启动时报数据库相关错误
  - 数据不一致/迁移失败
  - 查询缓慢或锁冲突
- 排查步骤
  1) 确认数据目录存在且有写权限（默认位于用户家目录下的隐藏目录）。
  2) 检查数据库文件是否存在且非空；必要时进行迁移。
  3) 使用 WAL 模式下并发读取通常较稳定，避免同时对同一数据库进行大事务。
  4) 如怀疑损坏，备份后尝试重建数据库（保留上传目录与模板）。
- 关键定位点
  - 数据目录获取与自动创建
  - 迁移逻辑（工作空间/会话/IM 状态等）
  - PRAGMA 设置与索引

章节来源
- [src/lib/forge-data.ts:20-103](file://src/lib/forge-data.ts#L20-L103)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)

### 三、IM 桥接问题（配置/鉴权/重连）
- 症状
  - 通道状态显示未配置/错误
  - 消息无法接收/发送
  - 连接频繁断开
- 排查步骤
  1) 在设置中校验各通道凭据是否完整、格式正确。
  2) 观察通道状态变化与错误信息，确认是否触发电路 breaker（连续失败后暂停重连）。
  3) 检查消息去重与重复处理逻辑，避免重复响应。
  4) 使用连接接口测试通道连通性。
- 关键定位点
  - 适配器生命周期与轮询循环
  - 重连指数退避与电路 breaker
  - 去重集合与清理策略
  - 连接接口与状态更新

章节来源
- [src/lib/im/bridge-manager.ts:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)
- [src/lib/im/bridge-manager.ts:278-328](file://src/lib/im/bridge-manager.ts#L278-L328)
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)
- [src/app/api/im-channels/[id]/route.ts:4-39](file://src/app/api/im-channels/[id]/route.ts#L4-L39)

### 四、定时任务问题（未触发/记录异常）
- 症状
  - 任务未按计划执行
  - 执行记录缺失或状态异常
- 排查步骤
  1) 确认任务已启用且表达式有效。
  2) 检查调度器是否已启动（存在启用任务时自动启动）。
  3) 查看任务执行记录表，核对最近一次执行时间与结果。
  4) 对一次性任务，确认其在执行后被自动禁用。
- 关键定位点
  - 调度器启动条件与定时 tick
  - 任务匹配与并发执行控制
  - 执行记录插入与任务状态更新

章节来源
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)

### 五、MCP 服务器问题（命令/HTTP/SSE）
- 症状
  - MCP 状态显示不可用
  - 任务中调用 MCP 失败
- 排查步骤
  1) 对 stdio 协议，验证命令是否存在且可执行（绝对路径或 PATH 中）。
  2) 对 HTTP/SSE 协议，验证 URL 可达且返回 2xx 或特定允许的状态码。
  3) 检查配置字段（命令参数、环境变量、URL、Headers）是否正确。
- 关键定位点
  - 连接测试函数与协议分支
  - 数据库中 MCP 配置与状态字段

章节来源
- [src/lib/mcp-test.ts:9-50](file://src/lib/mcp-test.ts#L9-L50)
- [src/lib/db.ts:443-498](file://src/lib/db.ts#L443-L498)

### 六、聊天与权限问题（权限决策/会话恢复）
- 症状
  - 权限决策失败或无响应
  - 会话恢复异常/零块
- 排查步骤
  1) 检查权限请求与响应链路，确认回调与状态机正常。
  2) 若恢复产生零块或抛错，按提示使用全新会话重试。
  3) 核对前端 Hook 的错误日志输出，定位具体失败环节。
- 关键定位点
  - 权限请求/响应处理
  - 会话恢复与重试策略
  - 前端 Hook 错误捕获

章节来源
- [src/app/api/chat/route.ts:198-205](file://src/app/api/chat/route.ts#L198-L205)
- [src/hooks/use-chat.ts:681-684](file://src/hooks/use-chat.ts#L681-L684)

### 七、API 提供商测试与登录
- 症状
  - API 提供商状态异常
  - 登录或测试失败
- 排查步骤
  1) 使用测试接口验证提供商配置与鉴权。
  2) 若使用 CLI 登录，确认 CLI 已认证且可用。
  3) 检查状态字段与错误信息，定位具体失败原因。
- 关键定位点
  - 测试路由中的错误捕获与返回
  - CLI 登录路由的异常处理

章节来源
- [src/app/api/api-providers/[id]/test/route.ts:29-40](file://src/app/api/api-providers/[id]/test/route.ts#L29-L40)
- [src/app/api/api-providers/cli-login/route.ts:79](file://src/app/api/api-providers/cli-login/route.ts#L79)

## 依赖关系与耦合分析
```mermaid
graph LR
EM["electron/main.ts"] --> NS["Next.js 服务"]
NS --> DB["lib/db.ts"]
NS --> IM["lib/im/bridge-manager.ts"]
NS --> CRON["lib/cron/engine.ts"]
DB --> FS["文件系统/数据目录"]
IM --> SDK["@anthropic-ai/claude-agent-sdk"]
EM --> ENV["环境变量/PATH"]
```

图示来源
- [electron/main.ts:177-289](file://electron/main.ts#L177-L289)
- [src/lib/db.ts:18-437](file://src/lib/db.ts#L18-L437)
- [src/lib/im/bridge-manager.ts:45-626](file://src/lib/im/bridge-manager.ts#L45-L626)
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)

章节来源
- [package.json:27-41](file://package.json#L27-L41)
- [README.md:343-350](file://README.md#L343-L350)

## 性能问题识别与优化
- 识别要点
  - IM 消息处理延迟：关注轮询间隔、会话锁等待、SDK 调用并发限制。
  - 数据库写入压力：批量写入、索引命中情况、WAL 模式下的读写分离。
  - 定时任务堆积：任务数量过多、执行耗时长、一次性任务未及时禁用。
- 优化建议
  - 控制并发：合理设置 SDK 并发上限，避免阻塞。
  - 索引与查询：确保常用查询命中索引，减少全表扫描。
  - 任务拆分：将长耗时任务拆分为多个短任务，降低单次执行时间。
  - 日志采样：生产环境降低高频日志级别，保留关键路径日志。

[本节为通用指导，无需列出章节来源]

## 错误代码与症状对照表
- 启动类
  - 服务器启动失败：检查主进程日志与端口占用；确认系统 Node 可用。
  - Gatekeeper 弹窗：按提示放行或调整安全设置。
- 数据库类
  - 数据目录不存在/无权限：检查数据目录路径与权限。
  - 数据库损坏/锁：备份后重建数据库，避免长时间大事务。
- IM 类
  - 通道未配置/鉴权失败：检查凭据与令牌有效性；关注电路 breaker 触发。
  - 连接断开/重连退避：查看重连次数与指数退避策略。
- 定时任务类
  - 任务未触发：检查启用状态与表达式；确认调度器已启动。
  - 执行记录异常：核对执行记录表与任务状态字段。
- MCP 类
  - 不可用：检查命令存在性或 HTTP/SSE 可达性。
- 聊天/权限类
  - 权限决策失败：检查请求/响应链路与前端 Hook 错误。
  - 会话恢复异常：按提示使用全新会话重试。

章节来源
- [electron/main.ts:272-288](file://electron/main.ts#L272-L288)
- [src/lib/forge-data.ts:20-26](file://src/lib/forge-data.ts#L20-L26)
- [src/lib/im/bridge-manager.ts:555-601](file://src/lib/im/bridge-manager.ts#L555-L601)
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)
- [src/lib/mcp-test.ts:9-50](file://src/lib/mcp-test.ts#L9-L50)
- [src/app/api/chat/route.ts:198-205](file://src/app/api/chat/route.ts#L198-L205)

## 监控与告警最佳实践
- 日志采集
  - 主进程 stdout/stderr：记录服务启动、端口选择、子进程退出码。
  - 业务日志：IM 桥接状态变更、重连尝试、去重与异常；定时任务执行结果。
- 指标监控
  - 数据库：连接数、慢查询、WAL 文件大小。
  - IM：消息吞吐、平均处理时延、重连次数、错误率。
  - 定时任务：触发计数、执行时延、失败率。
- 告警阈值
  - 连续重连失败超过阈值触发告警（电路 breaker）。
  - 定时任务执行超时或失败率升高触发告警。
  - 数据库锁等待时间过长触发告警。
- 响应流程
  - 自动降级：在严重异常时关闭部分功能（如 IM 通道）。
  - 快速回滚：变更配置或回滚到上一个稳定版本。
  - 清理与恢复：定期清理上传目录与临时文件，必要时重建数据库。

[本节为通用指导，无需列出章节来源]

## 结论
通过结合日志分析、网络与数据库检查、性能优化与监控告警，可以系统化地定位与解决 Forge 的常见问题。建议在日常运维中建立标准化的巡检清单与应急预案，持续优化关键路径，提升稳定性与可维护性。