手动恢复指南

概览

Claude-mem 的手动恢复系统可以帮助您恢复在处理队列中因工作进程崩溃、系统重启或意外关机而卡住的观测数据。

v5.x 的关键变化：Worker 进程启动时的自动恢复现已被禁用。这使您可以明确控制重新处理发生的时间，从而防止出现意外的重复观察。

什么时候需要手动恢复？

在以下情况下，您应触发手动恢复：

工作节点崩溃或重启 - 观测数据已排队，但工作节点在处理前停止
没有新的摘要出现 - 观察结果被保存，但未被处理成摘要
检测到卡住的消息 - 显示为“处理中”超过5分钟的消息
系统崩溃 - 意外关闭导致消息处于未完成状态

快速开始

使用 CLI 工具（推荐）

交互式命令行工具是恢复卡住观测数据最安全、最简单的方法：

bash

# Check status and prompt for recovery
bun scripts/check-pending-queue.ts

这将会：

检查 Worker 健康
显示队列摘要（待处理、处理中、失败、卡住的数量）
显示有待处理工作的会话
提示您确认恢复
显示最近处理的消息以获取反馈

无需提示自动处理

用于脚本编写或当你确信需要恢复时：

bash

# Auto-process without prompting
bun scripts/check-pending-queue.ts --process

# Limit to 5 sessions
bun scripts/check-pending-queue.ts --process --limit 5

理解队列状态

消息会经历以下生命周期状态：

待处理 → 排队中，等待处理
处理中 → 目前正在由 SDK 代理处理
已处理 → 完成成功
失败 → 经过3次重试后失败

卡住检测

processing 状态下超过 5 分钟 的消息被视为卡住：

它们在Worker 进程启动时会自动重置为 pending
它们不会自动重新处理（需要手动触发）
在检查队列状态时，它们出现在 stuckCount 字段中

恢复方法

方法 1：交互式 CLI 工具

最适合：普通用户、互动会话，以及当您想了解正在发生的情况时

bash

bun scripts/check-pending-queue.ts

示例输出：

Checking worker health...
Worker is healthy ✓

Queue Summary:
  Pending: 12 messages
  Processing: 2 messages (1 stuck)
  Failed: 0 messages
  Recently Processed: 5 messages in last 30 minutes

Sessions with pending work: 3
  Session 44: 5 pending, 1 processing (age: 2m)
  Session 45: 4 pending, 1 processing (age: 7m - STUCK)
  Session 46: 2 pending

Would you like to process these pending queues? (y/n)

特点：

✅ 飞行前健康检查（验证工作人员正在运行）
✅ 按会话的详细排队明细
✅ 用于卡住检测的年龄跟踪
✅ 确认提示（防止意外重复处理）
✅ 使用 --process 标志的非交互模式
✅ 使用 --limit N 的会话限制控制

方法 2：HTTP API

适用于：自动化、脚本编写、与监控系统集成

检查队列状态

bash

curl http://localhost:37777/api/pending-queue

回应:

json

{
  "queue": {
    "messages": [
      {
        "id": 123,
        "session_db_id": 45,
        "claude_session_id": "abc123",
        "message_type": "observation",
        "status": "pending",
        "retry_count": 0,
        "created_at_epoch": 1730886600000
      }
    ],
    "totalPending": 12,
    "totalProcessing": 2,
    "totalFailed": 0,
    "stuckCount": 1
  },
  "recentlyProcessed": [...],
  "sessionsWithPendingWork": [44, 45, 46]
}

关键字段:

totalPending - 待处理消息
totalProcessing - 正在处理的消息
stuckCount - 处理超过5分钟的消息
sessionsWithPendingWork - 需要恢复的会话 ID

触发恢复

bash

curl -X POST http://localhost:37777/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'

回应:

json

{
  "success": true,
  "totalPendingSessions": 15,
  "sessionsStarted": 10,
  "sessionsSkipped": 2,
  "startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}

响应字段:

totalPendingSessions - 数据库中有待处理消息的总会话数
sessionsStarted - 我们开始处理此请求的会话
sessionsSkipped - 会话已在处理（防止重复代理）
startedSessionIds - 我们启动的会话的数据库ID

最佳实践

1. 恢复前请务必检查

bash

# Check queue status first
curl http://localhost:37777/api/pending-queue

# Or use CLI tool which checks automatically
bun scripts/check-pending-queue.ts

2. 从低会话限制开始

bash

# Process only 5 sessions at a time
bun scripts/check-pending-queue.ts --process --limit 5

这可以防止Worker被过多同时运行的 SDK 代理压垮。

3. 恢复期间监测

在恢复运行时监视工作进程日志：

bash

npm run worker:logs

查找：

SDK 代理启动：Starting SDK agent for session...
处理完成：Processed observation...
错误：ERROR 或 Failed to process...

4. 验证恢复成功

查看最近处理的消息：

bash

curl http://localhost:37777/api/pending-queue | jq '.recentlyProcessed'

或者使用会自动显示此内容的命令行工具。

5. 处理失败消息

消息如果失败三次，将被标记为 failed 并且不会自动重试：

bash

# View failed messages
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, message_type, retry_count
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC;
"

如果需要，您可以手动重置它们：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  UPDATE pending_messages
  SET status = 'pending', retry_count = 0
  WHERE status = 'failed';
"

故障排除

恢复未工作

症状：已触发恢复，但消息仍在等待

解决方案:

核查Worker 健康：
bash
```
curl http://localhost:37777/health
```
检查工作日志中的错误：
bash
```
npm run worker:logs | grep -i error
```
重启Worker 进程：
bash
```
npm run worker:restart
```

检查数据库完整性：

bash

sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

消息永远卡住

症状：消息显示为“处理中”，持续数小时

解决方案：强制重置卡住的消息

bash

# Reset all stuck messages to pending
sqlite3 ~/.claude-mem/claude-mem.db "
  UPDATE pending_messages
  SET status = 'pending', started_processing_at_epoch = NULL
  WHERE status = 'processing';
"

# Then trigger recovery
bun scripts/check-pending-queue.ts --process

Worker 在恢复期间意外停止

症状：处理已恢复消息时 Worker 停止

解决方案:

检查可用内存：
bash
```
npm run worker:status
```

减少会话限制：

bash

bun scripts/check-pending-queue.ts --process --limit 3

检查日志中的 SDK 错误：
bash
```
npm run worker:logs | grep -i "sdk"
```
增加工作器内存（如果使用自定义运行器）：
bash
```
npm run worker:restart
```

高级用法

直接数据库检查

查看所有待处理消息：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    id,
    session_db_id,
    message_type,
    status,
    retry_count,
    datetime(created_at_epoch/1000, 'unixepoch') as created_at,
    datetime(started_processing_at_epoch/1000, 'unixepoch') as started_at,
    CAST((strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 AS INTEGER) as age_minutes
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  ORDER BY created_at_epoch;
"

按状态计数消息

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*) as count
  FROM pending_messages
  GROUP BY status;
"

查找有待处理工作的会话

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    session_db_id,
    COUNT(*) as pending_count,
    GROUP_CONCAT(message_type) as message_types
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"

查看最近的失败

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    id,
    session_db_id,
    message_type,
    retry_count,
    datetime(completed_at_epoch/1000, 'unixepoch') as failed_at
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC
  LIMIT 10;
"

集成示例

用于自动恢复的定时任务

bash

#!/bin/bash
# Run every hour to process stuck queues

# Check if worker is healthy
if curl -f http://localhost:37777/health > /dev/null 2>&1; then
  # Auto-process up to 5 sessions
  bun scripts/check-pending-queue.ts --process --limit 5
else
  echo "Worker not healthy, skipping recovery"
  exit 1
fi

监控脚本

bash

#!/bin/bash
# Alert if stuck count exceeds threshold

STUCK_COUNT=$(curl -s http://localhost:37777/api/pending-queue | jq '.queue.stuckCount')

if [ "$STUCK_COUNT" -gt 5 ]; then
  echo "WARNING: $STUCK_COUNT stuck messages detected"
  # Send alert (email, Slack, etc.)
fi

关机前恢复

bash

#!/bin/bash
# Process pending queues before system shutdown

echo "Processing pending queues before shutdown..."
bun scripts/check-pending-queue.ts --process --limit 20

echo "Waiting for processing to complete..."
sleep 10

echo "Stopping worker..."
claude-mem stop

迁移说明

如果您正在从 v4.x 升级到 v5.x：

v4.x 行为（自动恢复）：

Worker 进程在启动时自动恢复了卡住的消息
用户无法控制重新处理的时间

v5.x 行为（手动恢复）：

检测到卡住的消息，但未自动重新处理
用户必须通过 CLI 或 API 明确触发恢复
防止意外的重复观察
提供对处理何时发生的明确控制

迁移步骤：

升级到 v5.x
检查卡住的消息: bun scripts/check-pending-queue.ts
如有需要，处理：bun scripts/check-pending-queue.ts --process
将恢复添加到您的工作流程（定时任务、关机前脚本等）

另请参阅

Worker Service Architecture - 队列处理的技术细节
Troubleshooting - Manual Recovery - 常见问题及解决方法
Database Schema - 待处理消息表结构

手动恢复指南 ​

概览 ​

什么时候需要手动恢复？ ​

快速开始 ​

使用 CLI 工具（推荐） ​

无需提示自动处理 ​

理解队列状态 ​

卡住检测 ​

恢复方法 ​

方法 1：交互式 CLI 工具 ​

方法 2：HTTP API ​

检查队列状态 ​

触发恢复 ​

最佳实践 ​

1. 恢复前请务必检查 ​

2. 从低会话限制开始 ​

3. 恢复期间监测 ​

4. 验证恢复成功 ​

5. 处理失败消息 ​

故障排除 ​

恢复未工作 ​

消息永远卡住 ​

Worker 在恢复期间意外停止 ​

高级用法 ​

直接数据库检查 ​

按状态计数消息 ​

查找有待处理工作的会话 ​

查看最近的失败 ​

集成示例 ​

用于自动恢复的定时任务 ​

监控脚本 ​

关机前恢复 ​

迁移说明 ​

另请参阅 ​

手动恢复指南

概览

什么时候需要手动恢复？

快速开始

使用 CLI 工具（推荐）

无需提示自动处理

理解队列状态

卡住检测

恢复方法

方法 1：交互式 CLI 工具

方法 2：HTTP API

检查队列状态

触发恢复

最佳实践

1. 恢复前请务必检查

2. 从低会话限制开始

3. 恢复期间监测

4. 验证恢复成功

5. 处理失败消息

故障排除

恢复未工作

消息永远卡住

Worker 在恢复期间意外停止

高级用法

直接数据库检查

按状态计数消息

查找有待处理工作的会话

查看最近的失败

集成示例

用于自动恢复的定时任务

监控脚本

关机前恢复

迁移说明

另请参阅