100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
---
|
||
title: MemRelay Troubleshooting Guide – Known Issues and Resolutions
|
||
type: curated
|
||
permalink: main/projects/ebb54e31-5afe-4f9b-a291-4e3b03ca3b21/curated/development/mem-relay-troubleshooting-guide-known-issues-and-resolutions
|
||
stable_id: a6632d8d-f445-4932-8ffd-06f721ffc51b
|
||
scope: project
|
||
project_id: ebb54e31-5afe-4f9b-a291-4e3b03ca3b21
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: troubleshooting
|
||
revision: 1
|
||
source_memory_ids: []
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: null
|
||
source_git_commits: []
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: git-restore
|
||
source_count: 20
|
||
source_revisions:
|
||
memory:c16b8950-20d2-4d3d-87b3-0a8bfd20790d: '1'
|
||
memory:9092af09-6a60-404e-88ad-3344f2fdf0ca: '1'
|
||
memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca: '1'
|
||
memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136: '1'
|
||
memory:e20b1ae7-4ba7-4c1d-9d79-59af809f9084: '1'
|
||
memory:109e5244-ad26-4650-8a49-e6cebbabe7d7: '1'
|
||
source_dispositions:
|
||
processed: 20
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- curated_baseline:a6632d8d-f445-4932-8ffd-06f721ffc51b
|
||
- curated_baseline:f48a08a1-f276-4045-8ffe-22e7ac39e5c9
|
||
- curated_baseline:d459e837-b05c-4f31-9b05-7f9d09c71f25
|
||
- curated_baseline:b54bd6b0-bbdd-4ab2-92d3-a4f5d58e8f83
|
||
- curated_baseline:08fb4703-1527-4983-bb8e-e4ca735e4316
|
||
- global_guidance_document:d3a20d44-6001-4c88-8772-65dbfac75e6e
|
||
- global_guidance_document:8a861a5f-35c3-4f95-bd5b-6b2297888f56
|
||
- memory:c16b8950-20d2-4d3d-87b3-0a8bfd20790d
|
||
- memory:9092af09-6a60-404e-88ad-3344f2fdf0ca
|
||
- memory:41e5bdb5-a67b-49bc-b8a6-ab20b4c66fca
|
||
- memory:b3fc5d7e-f1d7-4a63-860b-37f9f35cb136
|
||
- memory:e20b1ae7-4ba7-4c1d-9d79-59af809f9084
|
||
- memory:109e5244-ad26-4650-8a49-e6cebbabe7d7
|
||
job_cited_source_ids:
|
||
- curated_baseline:a6632d8d-f445-4932-8ffd-06f721ffc51b
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences: []
|
||
source_cursor: 0
|
||
source_hash: cd96d5b27b5d1ef34ff30350e40c12b9d9b7e389c5813755521578d1f2597d9c
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: null
|
||
created_at: '2026-08-08T09:52:41.142992+00:00'
|
||
updated_at: '2026-09-23T15:13:24.173902+00:00'
|
||
tags:
|
||
- troubleshooting
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
# MemRelay 故障排查与性能优化
|
||
|
||
## 已知问题及解决方案
|
||
|
||
1. **ARM64 构建 / 依赖下载缓慢**
|
||
- *症状*: 在 ARM 主机上 PyPI 与 Debian 包下载极慢。
|
||
- *解决*: 在构建阶段使用仅生效的代理和 Debian 镜像参数，加速依赖下载，不影响运行时网络。
|
||
|
||
2. **Windows `tar` 无法读取模型缓存符号链接**
|
||
- *症状*: 正式部署期间 Windows `tar` 命令无法读取模型缓存的符号链接。
|
||
- *解决*: 使用 Linux 容器并在创建 ZIP 时以只读方式挂载缓存目录。
|
||
|
||
3. **局域网 HTTP 上的 Cookie `Secure` 属性**
|
||
- *症状*: 访问公网 HTTPS 后，内网 HTTP 会话因 Cookie 永久标记 `Secure` 而失效。
|
||
- *解决*: 根据当前请求协议动态设置 `Secure` 标记——HTTPS 设置，HTTP 清除，实现内网与公网同时可用。
|
||
|
||
4. **`memrelay://capabilities` JSON 序列化错误**
|
||
- *症状*: 序列化包含 `datetime` 对象的能力对象时抛出 `json.dumps` 异常。
|
||
- *解决*: 在 JSON 编码前通过 FastAPI `jsonable_encoder` 处理所有 MCP 资源和工具输出。已加入真实时间戳的回归测试。
|
||
|
||
5. **密码库列表延迟 (优化前)**
|
||
- *症状*: 在 ARM64 上列出 Vaultwarden 条目耗时约 20 秒。
|
||
- *解决*: 实现进程内 Bitwarden 快照，在启动、手动同步和定期同步时刷新。读取延迟降至约 420‑431 ms。
|
||
|
||
6. **ARM64 首次启动迁移延迟**
|
||
- *症状*: 迁移后容器首次启动耗时较长，健康检查失败。
|
||
- *解决*: 迁移前保留一致备份，容器完成数据库恢复后再执行健康检查。
|
||
|
||
## 未决事项 / 持续工作
|
||
|
||
- **AI 上游间歇 503/超时**: 任务进入 `waiting_dependency`，模型恢复后自动继续。计划实现 checkpoint‑resume 以避免重复消耗模型配额。
|
||
- **文档调用失败重试**: 失败任务在下次重试时重新生成证据批次，可能导致模型额度重复消耗。评估实现证据断点续跑的可行性。
|
||
- **UI 微调**: 继续根据实际使用反馈调整滚动行为。
|
||
- **Bitwarden 快照刷新间隔**: 进一步评估 optimal schedule 以降低延迟。
|
||
- **迁移文档**: 编写未来版本升级的模式迁移、备份/恢复脚本。
|
||
- **回归测试扩展**: 增加对真实时间字段与 Streamable HTTP MCP 的自动化测试。 |