Repository navigation
Conversation
记录 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>
重扫群晖 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
根因:
synology_api用类级BaseApi.shared_session缓存Authentication,新建FileStation会复用旧会话、不重新登录 →nas_client(relogin=True)是「假重登」。DSM 会话过期后永远报 119Invalid 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_sharestotal=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 仍 4010.1.3 离线单测 23/23 通过(容器内执行,不连 NAS)
真实调用:Thumb 发现
entry.cgi v3、408 错误翻译、/healthz0.1.3🤖 Generated with Claude Code