Skip to content

fix(nas-mcp): 修复会话假重登 + 30 分钟探活自愈 - #327

Open
keyapi wants to merge 5 commits into
mainfrom
claude/cranky-meitner-9a0d6b
Open

keyapi wants to merge 5 commits into
mainfrom
claude/cranky-meitner-9a0d6b

Conversation

@keyapi

@keyapi keyapi commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • 根因:synology_api 用类级 BaseApi.shared_session 缓存 Authentication,新建 FileStation 会复用旧会话、不重新登录 → nas_client(relogin=True) 是「假重登」。DSM 会话过期后永远报 119 Invalid session / SID not found.(老 42 天进程和重启后 3 小时进程均复现,实测闲置超时约 2 小时)。

  • 修复:重建前清空 BaseApi.shared_session;新增 retry_on_session() 覆盖 search / folder_size / md5 / archive / thumbnail;tool_list_shares() 改为重试循环(原闭包绑定旧客户端)。

  • 测试:tests/test_smoke.py 第 15 节,服务端强制 logout 后 nas_health / nas_list_shares 必须自动恢复。

  • 部署:镜像 nas-mcp:0.1.1 已替换生产容器;/usr/local/bin/nas-mcp-healthcheck.sh + nas-mcp-healthcheck.timer(30 分钟,连续 2 次失败才重启;LoginError/ConnectionError 不重启)。

  • 文档:nas_mcp/docs/reference/self-healing.md 记录根因、频率结论(30 分钟推荐,10 分钟不必要)与失败分类。

  • 调研:docs/research/2026-11-03-nas-mcp-opensource-landscape.md —— 现成开源 NAS MCP 横评与借鉴清单(不整体替换)。

  • P0 加固(镜像 0.1.2):GET /healthz(本机免令牌、不调 DSM);登录失败熔断(5 分钟 3 次 → 停 15 分钟);重登串行。唯一会话名实测不适用(自定义名 402;webui 重复登录不互踢);单飞时间窗会掩盖外部登出,已移除。

  • 0.1.3 兼容性/可观测性:MCP ping;工具并发上限(默认 8);DSM 错误码翻译;Thumb API 运行时发现;启动校验;新增离线单测 nas_mcp/tests/test_offline.py(23 项)+ GitHub Actions。

Test plan

  • py_compile 通过;check_secrets.py 零告警;diff 凭证扫描零命中

  • canary 容器回归:强制 logout 后 nas_health=true、nas_list_shares total=2(旧代码必挂)

  • 生产外部 HTTPS:nas_health / nas_list_shares / nas_list_folder 全部正常

  • 故障演练:docker stop nas-mcp → 第 1 次 x1、第 2 次自动 docker restart → 恢复健康

  • systemctl list-timers nas-mcp-healthcheck.timer 显示 30 分钟周期

  • 0.1.2 回归:强制登出后恢复、熔断第 4 次立即拦截、/healthz 无需令牌、非 healthz GET 仍 401

  • 0.1.3 离线单测 23/23 通过(容器内执行,不连 NAS)

  • 真实调用:Thumb 发现 entry.cgi v3、408 错误翻译、/healthz 0.1.3

🤖 Generated with Claude Code

keyapi and others added 2 commits November 3, 2026 13:51
记录 2026-11-03 容器「活着但不可用」的故障、恢复过程与三类失败的区分;
新增 A/B/C 自愈方案对比与探活频率结论(30 分钟推荐,10 分钟不必要),
顺带记录 tool_list_shares 闭包重登失效的独立小 bug。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
根因:synology_api 用类级 BaseApi.shared_session 缓存 Authentication,
新建 FileStation 会直接复用旧会话、不会重新登录,relogin 是假重登;
DSM 会话过期后永远报 119 Invalid session。

- nas_client() 重建前清空 BaseApi.shared_session
- 新增 retry_on_session(),覆盖 search / folder_size / md5 / archive / thumbnail
- tool_list_shares 改为重试循环(原先闭包绑定旧客户端)
- 新增回归测试:强制登出后 nas_health / nas_list_shares 必须自动恢复
- 文档更新根因、频率结论与已部署的 30 分钟探活方案

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@keyapi keyapi changed the title docs(nas-mcp): 假活故障复盘与自愈方案 fix(nas-mcp): 修复会话假重登 + 30 分钟探活自愈 Nov 3, 2026
keyapi and others added 3 commits November 3, 2026 15:31
重扫群晖 MCP 生态:mrquj 安全/传输姿态最接近(119 重认证+重放、/healthz、
路径策略),cmeans 工程最成熟(vDSM 矩阵 CI、单飞重认证、Auto Block 防护)。
我们的图片/PDF/Office 渲染与中文目录是其缺口,结论是不整体替换、按 P0/P1/P2
清单借鉴;并记录唯一会话名、healthz、API 发现、错误码翻译等待办。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- 新增 GET /healthz:本机回环、免令牌、不调 DSM,返回策略/会话/实例状态
- 登录失败熔断:5 分钟内连续 3 次 LoginError → 停 15 分钟,避免 DSM Auto Block 封 IP
- 重登在 _nas_lock 内串行,避免并发登录风暴
- 实测「唯一会话名」不可行:自定义 session 名返回 402;webui 重复登录不互踢
- 移除单飞时间窗(会掩盖「刚登录就被外部登出」,导致不恢复)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- 支持 MCP ping;工具并发上限(NAS_MCP_MAX_CONCURRENCY,默认 8)
- DSM 错误码翻译(借用 synology_api 自带码表,输出可操作中文)
- Thumb API 运行时发现 + 缓存,失败回退 entry.cgi v3
- 启动时校验 NAS_URL / USERNAME / PASSWORD
- 新增离线单测 23 项 + GitHub Actions(不连 NAS、不需要网络)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant