mirror of
https://github.com/agentscope-ai/ReMe.git
synced 2026-10-05 02:41:43 +00:00
88ed21165b
* docs: rebuild documentation site with VitePress * docs: address VitePress review feedback * docs: complete locale redirect validation
106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
---
|
||
title: 诊断、备份与恢复
|
||
description: ReMe 服务健康检查、日志、索引维护、备份迁移和常见恢复流程。
|
||
---
|
||
|
||
# 诊断、备份与恢复
|
||
|
||
ReMe 的恢复原则是：保护 workspace 中的用户文件，通过源文件重建索引、图谱和 catalog。不要为了修复索引而删除或改写用户记忆。
|
||
|
||
## 快速诊断
|
||
|
||
依次执行：
|
||
|
||
```bash
|
||
reme find_reme
|
||
reme version
|
||
reme health_check
|
||
reme status
|
||
reme app_config
|
||
```
|
||
|
||
- `find_reme`：服务是否存在，以及实际 host、port、PID；
|
||
- `version`：CLI 能否成功访问服务；
|
||
- `health_check`：组件健康状态；
|
||
- `status`：状态组件的内存估算和进程 RSS；
|
||
- `app_config`：隐藏密钥后的实际生效配置。
|
||
|
||
## 日志
|
||
|
||
`log_to_console` 和 `log_to_file` 控制日志目标。排查启动失败时先查看第一条异常，而不是后续客户端连接错误。
|
||
|
||
常见类别：
|
||
|
||
| 现象 | 优先检查 |
|
||
|---|---|
|
||
| CLI 找不到服务 | `reme find_reme`、启动目录、端口和进程状态 |
|
||
| 自动记忆失败 | LLM backend、model、API key、base URL |
|
||
| 只有 BM25 结果 | embedding 组件是否真正接入 `file_store` |
|
||
| 新文件没有进入搜索 | 文件所在目录、后缀、watcher 和 `health_check` |
|
||
| Studio 空白但 API 正常 | web extra、静态构建路径和浏览器控制台 |
|
||
| 插件安装后不可用 | 当前 Python 解释器、`plugins` 配置、服务重启 |
|
||
|
||
## 索引维护
|
||
|
||
```bash
|
||
reme reindex scope=all
|
||
reme reindex scope=bm25
|
||
reme reindex scope=embedding
|
||
```
|
||
|
||
`reindex` 从当前 `file_chunks` 重建 BM25 和/或 embedding 派生索引。它不会扫描 workspace、重新分块或重建 wikilink 图谱。
|
||
|
||
如果问题发生在文件摄取阶段，应先确认后台 watcher 正常运行；不能把 `reindex` 当成通用“重新扫描”命令。
|
||
|
||
Daily 索引页可单独重建：
|
||
|
||
```bash
|
||
reme daily_reindex date=2026-09-04
|
||
```
|
||
|
||
## 备份
|
||
|
||
停止写入或停止服务后，优先备份整个 workspace。最重要的目录是：
|
||
|
||
- `session/`：原始对话来源；
|
||
- `resource/`：外部资料；
|
||
- `daily/`：每日记忆；
|
||
- `digest/`：长期记忆。
|
||
|
||
`metadata/` 包含索引、图谱和 file catalog。一起备份可以加速恢复，但它不是唯一事实源。
|
||
|
||
不要只备份进程目录下偶然生成的 `.reme/`；生产使用应明确设置稳定的绝对 `workspace_dir`。
|
||
|
||
## 迁移 workspace
|
||
|
||
1. 停止旧服务，避免迁移期间继续写入。
|
||
2. 复制完整 workspace，并保留文件时间信息。
|
||
3. 使用新的绝对路径启动：
|
||
|
||
```bash
|
||
reme start workspace_dir=/new/location/reme-memory
|
||
```
|
||
|
||
4. 运行 `health_check`、`status` 和一次代表性 `search`。
|
||
5. 如果 embedding 模型或维度发生变化，再重建 embedding 索引。
|
||
|
||
普通 Markdown 和资源文件可以使用版本控制或同步工具；包含敏感对话的 workspace 不应推送到公开仓库。
|
||
|
||
## 从派生状态故障恢复
|
||
|
||
在确认备份可用前，不要删除任何内容。恢复顺序应为：
|
||
|
||
1. 保留 `session/`、`resource/`、`daily/` 和 `digest/`；
|
||
2. 记录当前配置和组件 backend；
|
||
3. 确认故障只发生在 `metadata/`；
|
||
4. 将有问题的派生状态移到隔离备份位置；
|
||
5. 用同一配置启动 ReMe，让 watcher 从源文件重建；
|
||
6. 验证搜索、图谱和 Daily 索引。
|
||
|
||
具体 metadata 文件属于实现细节，不应在自动化脚本里依赖其内部格式。
|
||
|
||
## 并发编辑
|
||
|
||
Studio 或其他编辑器保存完整文件时，应使用 `stat` 返回的 mtime 作为 `save.expected_mtime`。如果文件在打开后被外部修改，保存会失败，从而避免静默覆盖。
|
||
|
||
文件 Job 会校验 workspace containment，并对同一路径加锁。不要绕过这些 Job 直接向不受控制的绝对路径写入。
|