HolyClaude在群晖/QNAP NAS上部署：SMB/CIFS挂载避坑与文件监听完整配置

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）或威联通（QNAP）NAS上部署HolyClaude，核心就三件事：用 Docker Compose 一键启动、把数据目录规划好、避开SMB/CIFS 挂载的四个经典大坑（文件监听失效、SQLite 锁、符号链接、权限静默失败）。HolyClaude 官方平台支持表中明确标注 Synology / QNAP 为 ✅ 完全支持，NAS 场景开箱即用。

一、为什么 NAS 是 HolyClaude 的理想落脚点

HolyClaude 是一个"AI 编码工作站"容器：内置 Claude Code + Web UI（CloudCLI）+ 8 个 AI CLI + 无头浏览器 Chromium + 50+ 开发工具，docker compose up一条命令就能跑。它同时提供amd64 和 arm64两个架构，因此：

你的 NAS 类型	建议镜像	说明
x86_64（Intel/AMD）	coderluii/holyclaude:latest（full）	原生性能
ARM 机型（Intel N100/ARM 板卡）	latest或slim	arm64 原生构建
存储空间紧张	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 locked	SQLite 一律放本地存储，别放共享
3️⃣	默认无符号链接	npm 全局安装、Python.local可能异常	挂载选项加mfsymlinks；HolyClaude 因此把.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_USEPOLLING	1	让 Node.js 的文件监听器（chokidar）改用轮询
WATCHFILES_FORCE_POLLING	true	让 Python 生态（如 uvicorn/vite 的 watchfiles）改用轮询

在 Compose 文件的environment中加入（模板参考 docker-compose.full.yaml）：

environment: - TZ=Asia/Shanghai - PUID=1026 # NAS 上运行 Docker 的用户 UID - PGID=100 - CHOKIDAR_USEPOLLING=1 - WATCHFILES_FORCE_POLLING=true

只在你真正使用网络挂载时才开启——轮询比 inotify 更耗 CPU，本地盘上请保持注释状态。

五、权限设置：PUID/PGID 一步到位

NAS 上最常见的permission denied，本质是容器内用户 ID 与 NAS 上目录属主不匹配：

1. 在 NAS 上查看 Docker 运行用户的 UID/GID（群晖可查"用户"或docker exec一个临时容器id）；
2. 在 Compose 中设置PUID/PGID与之一致；
3. 由于容器内的chown在 CIFS 上可能失效，直接在NAS 共享/文件夹权限设置里把data/claude和workspace属主改对，比在容器里改更可靠。

另外两条避坑提醒（来自 docs/troubleshooting.md）：

• 🚫不要挂载整个/home或/home/claude目录——会遮挡镜像自带的claude可执行文件，导致claude: command not found；
• 群晖上若启动时报Too many levels of symbolic links，先用官方提供的只读诊断脚本定位链接环（见排障文档对应小节），再处理，切勿直接删数据。

六、最快部署步骤

1. 在 NAS 上创建/volume1/docker/holyclaude，建好data/claude、workspace子目录；
2. 放入 Compose 文件（新手直接用 docker-compose.yaml 精简模板；需要全部选项用 docker-compose.full.yaml）；
3. 启动并验证：

docker compose up -d docker logs -f holyclaude # 看到 CloudCLI 启动成功即可

4. 浏览器打开http://NAS_IP:3001，创建 CloudCLI 账号（约 10 秒），用你的 Anthropic 账号登录——完成 ✅
5. 改完挂载或权限后，用热重载验证文件监听是否生效；不生效时检查上一节的两个轮询变量。

七、参考文档

资料	路径
主文档（平台支持/环境变量全表/持久化）	README.md
排障指南（含 SMB/CIFS 专属章节与群晖符号链接诊断）	docs/troubleshooting.md
配置参考（SMB/CIFS 变量说明）	docs/configuration.md
内置给 Claude 的运维备忘（NAS 场景要点）	config/claude-memory-full.md

✅NAS 部署一句话总结：数据目录放本地盘、SQLite 不碰网络共享、CHOKIDAR_USEPOLLING=1+WATCHFILES_FORCE_POLLING=true开启轮询监听、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