MemRelay/projects/ebb54e31-5afe-4f9b-a291-4e3b03ca3b21/curated/development/MemRelay Troubleshooting Guide – Known Issues and Resolutions.md

title, type, permalink, stable_id, scope, project_id, workspace_type, usage_profile_id, preference_context, document_type, revision, source_memory_ids, source_checkpoint_ids, source_file_ids, source_git_commit, source_git_commits, source_agent_sync_ids, model_connection, model_name, source_count, source_revisions, source_dispositions, cited_source_ids, job_cited_source_ids, conflicts, supersedes, preferences, source_cursor, source_hash, prompt_version, schema_version, curation_job_id, created_at, updated_at, tags, restored_from_commit

title	type	permalink	stable_id	scope	project_id	workspace_type	usage_profile_id	preference_context	document_type	revision	source_memory_ids	source_checkpoint_ids	source_file_ids	source_git_commit	source_git_commits	source_agent_sync_ids	model_connection	model_name	source_count	source_revisions	source_dispositions	cited_source_ids	job_cited_source_ids	conflicts	supersedes	preferences	source_cursor	source_hash	prompt_version	schema_version	curation_job_id	created_at	updated_at	tags	restored_from_commit
MemRelay Troubleshooting Guide – Known Issues and Resolutions	curated	main/projects/ebb54e31-5afe-4f9b-a291-4e3b03ca3b21/curated/development/mem-relay-troubleshooting-guide-known-issues-and-resolutions	a6632d8d-f445-4932-8ffd-06f721ffc51b	project	ebb54e31-5afe-4f9b-a291-4e3b03ca3b21	development	null	development	troubleshooting	1				null			Sub2API	git-restore	20	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 1 1 1 1 1 1	processed unchanged unsupported skipped 20 0 0 0	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	curated_baseline:a6632d8d-f445-4932-8ffd-06f721ffc51b				0	cd96d5b27b5d1ef34ff30350e40c12b9d9b7e389c5813755521578d1f2597d9c	2026-08-12.3	3	null	2026-08-08T09:52:41.142992+00:00	2026-09-23T15:13:24.173902+00:00	troubleshooting	6a6a895eaf

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 的自动化测试。