HolyClaude在群晖/QNAP NAS上部署SMB/CIFS挂载避坑与文件监听完整配置【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude在群晖Synology或威联通QNAPNAS上部署HolyClaude核心就三件事用 Docker Compose 一键启动、把数据目录规划好、避开SMB/CIFS 挂载的四个经典大坑文件监听失效、SQLite 锁、符号链接、权限静默失败。HolyClaude 官方平台支持表中明确标注 Synology / QNAP 为 ✅ 完全支持NAS 场景开箱即用。一、为什么 NAS 是 HolyClaude 的理想落脚点HolyClaude 是一个AI 编码工作站容器内置 Claude Code Web UICloudCLI 8 个 AI CLI 无头浏览器 Chromium 50 开发工具docker compose up一条命令就能跑。它同时提供amd64 和 arm64两个架构因此你的 NAS 类型建议镜像说明x86_64Intel/AMDcoderluii/holyclaude:latestfull原生性能ARM 机型Intel N100/ARM 板卡latest或slimarm64 原生构建存储空间紧张coderluii/holyclaude:slim精简镜像缺的工具 Claude 会按需秒装 NAS 的容器管理器如群晖 Container Manager展示的是解压后的镜像大小会比 Docker Hub 上标注的压缩体积大属正常现象。二、目录规划NAS 上最容易踩的坑先排掉在群晖上建议把 Compose 项目放在本地存储卷如/volume1/docker/holyclaude目录结构如下/volume1/docker/holyclaude/ ├── docker-compose.yaml # 配置文件 ├── data/claude/ # 凭据、会话、记忆 —— 重建容器不丢 └── workspace/ # 你的代码项目⚠️ 第一条黄金法则SQLite 数据库永远不要放在网络共享上。CloudCLI 的账号数据库/home/claude/.cloudcli默认存在容器本地存储就是为了避开 CIFS 不支持文件级锁定导致的database is locked错误如果你希望账号在重建容器后保留请用Docker 命名卷cloudcli-data且必须落在 Docker 引擎的本地文件系统上——不要使用指向 NAS 共享/NFS/SMB 的卷驱动或远程选项你自己项目里的.sqlite文件同理放在/workspace的 NAS 路径上也会频繁报锁错误。完整的持久化对照表见 README.md 的 Data Persistence 章节网络共享注意事项见 docs/troubleshooting.md 的 SQLite database is locked 小节。三、SMB/CIFS 挂载四大坑与对策当你的data/claude或workspace落在 SMB/CIFS 挂载点或 Hyper-V 的 Samba 共享时会遇到以下四个坑。官方排障文档 docs/troubleshooting.md 的 SMB/CIFS Gotchas 章节有一句话总结#坑症状对策1️⃣不支持 inotify热重载失效、dev server 感知不到文件变化开启轮询监听见下一节两个变量2️⃣SQLite 锁失败反复报database is lockedSQLite 一律放本地存储别放共享3️⃣默认无符号链接npm 全局安装、Python.local可能异常挂载选项加mfsymlinksHolyClaude 因此把.npm、.local保留在容器本地不要把这两个目录挂到网络共享4️⃣chmod/chown 静默失效容器内改权限看似成功实际无效在 NAS 共享设置或挂载选项uid、gid、file_mode、dir_mode层面解决或让PUID/PGID与共享属主一致 在群晖/QNAP/SMB 挂载上从容器内部执行chmod/chown可能被宿主机文件系统直接忽略——权限问题请优先从NAS 侧解决而不是在容器里反复试。四、文件监听完整配置两个环境变量搞定SMB/CIFS 不支持inotify这是 NAS 上改了文件没反应的根本原因。HolyClaude 提供了两个专用开关完整说明见 docs/configuration.md变量设置值作用CHOKIDAR_USEPOLLING1让 Node.js 的文件监听器chokidar改用轮询WATCHFILES_FORCE_POLLINGtrue让 Python 生态如 uvicorn/vite 的 watchfiles改用轮询在 Compose 文件的environment中加入模板参考 docker-compose.full.yamlenvironment: - TZAsia/Shanghai - PUID1026 # NAS 上运行 Docker 的用户 UID - PGID100 - CHOKIDAR_USEPOLLING1 - WATCHFILES_FORCE_POLLINGtrue只在你真正使用网络挂载时才开启——轮询比 inotify 更耗 CPU本地盘上请保持注释状态。五、权限设置PUID/PGID 一步到位NAS 上最常见的permission denied本质是容器内用户 ID 与 NAS 上目录属主不匹配在 NAS 上查看 Docker 运行用户的 UID/GID群晖可查用户或docker exec一个临时容器id在 Compose 中设置PUID/PGID与之一致由于容器内的chown在 CIFS 上可能失效直接在NAS 共享/文件夹权限设置里把data/claude和workspace属主改对比在容器里改更可靠。另外两条避坑提醒来自 docs/troubleshooting.md不要挂载整个/home或/home/claude目录——会遮挡镜像自带的claude可执行文件导致claude: command not found群晖上若启动时报Too many levels of symbolic links先用官方提供的只读诊断脚本定位链接环见排障文档对应小节再处理切勿直接删数据。六、最快部署步骤在 NAS 上创建/volume1/docker/holyclaude建好data/claude、workspace子目录放入 Compose 文件新手直接用 docker-compose.yaml 精简模板需要全部选项用 docker-compose.full.yaml启动并验证docker compose up -d docker logs -f holyclaude # 看到 CloudCLI 启动成功即可浏览器打开http://NAS_IP:3001创建 CloudCLI 账号约 10 秒用你的 Anthropic 账号登录——完成 ✅改完挂载或权限后用热重载验证文件监听是否生效不生效时检查上一节的两个轮询变量。七、参考文档资料路径主文档平台支持/环境变量全表/持久化README.md排障指南含 SMB/CIFS 专属章节与群晖符号链接诊断docs/troubleshooting.md配置参考SMB/CIFS 变量说明docs/configuration.md内置给 Claude 的运维备忘NAS 场景要点config/claude-memory-full.md✅NAS 部署一句话总结数据目录放本地盘、SQLite 不碰网络共享、CHOKIDAR_USEPOLLING1WATCHFILES_FORCE_POLLINGtrue开启轮询监听、PUID/PGID与 NAS 用户对齐——四步做完HolyClaude 在群晖/QNAP 上就是一键可用的 7×24 AI 编码工作站。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考