HolyClaude常见问题终极排错指南权限、SQLite锁、Chromium崩溃一网打尽【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaudeHolyClaude 是一个开箱即用的 AI coding workstationAI 编程工作站把 Claude Code、CloudCLI Web UI、8 个 AI CLI、Chromium 无头浏览器和 50 开发工具打包进一个 Docker 容器。本文面向新手与个人用户是一份 HolyClaude 常见问题排错指南重点解决三大高频故障——文件权限被拒Permission denied、SQLite 数据库锁database is locked、Chromium 崩溃白屏并顺带覆盖热重载失效、重建后掉登录等 8 个常见坑照着做 5 分钟即可恢复。 排错前先做 3 步快速自检遇到问题别慌先收集信息docker compose ps—— 确认 holyclaude 容器在运行docker compose logs --tail 100 holyclaude—— 看启动日志HolyClaude 多数故障会在启动时直接报出受影响的完整路径docker compose pull docker compose up -d更新镜像——很多历史问题终端黑方块、重建后重新登录等在新版本里已直接修复。⚠️ 注意不要在容器内运行cloudcli update或npm install -g cloudcli-ai/cloudclilatest。HolyClaude 内置的是打过补丁的 CloudCLI 运行时容器内自升级会破坏补丁正确升级方式永远是拉取新镜像。完整官方排错文档docs/troubleshooting.md环境变量全集docs/configuration.md。 权限被拒Permission deniedPUID / PGID 三步修复症状写文件失败、git 操作报错、npm install 失败。原因容器用户 ID 与宿主机不一致或者首次启动时 Docker 自动把./workspace创建成了root:root目录。修复步骤在宿主机执行id -u和id -g记下用户 ID 与组 ID把这两个数字写进 Compose 的 environmentenvironment: - PUID1000 - PGID1000重启容器。HolyClaude 启动时会自动修复顶层/workspace的所有权见 scripts/entrypoint.sh如果之后仍报错问题就在宿主机文件本身而不是容器。Rootless Podman SELinux 用户PUID/PGID只改容器内用户rootless Podman 仍会经过 subuid 映射。请直接使用项目自带的 keep-id 配置文件podman compose -f docker-compose.podman-rootless.yaml up -d该文件docker-compose.podman-rootless.yaml使用keep-id与:Z标签处理 SELinux 标签。切记不要给/workspace加:U——它会递归改写宿主机所有权反而让本地编辑失败。NAS 提示Synology、QNAP 或 SMB 挂载会忽略容器内的chmod/chown请改用 NAS 共享设置或让PUID/PGID与共享目录属主一致。️ SQLite 锁错误database is locked把数据库搬回本地盘症状CloudCLI 账户数据库持续报database is locked。原因SQLite 依赖文件级锁而 CIFS/SMB/NFS 网络文件系统不支持这种锁。修复你自己的 SQLite 库如果放在/workspace的网络挂载上移到本地磁盘路径想让 CloudCLI 账户跨重建保留用Docker 本地命名卷而不是 NFS/SMB 驱动的卷volumes: - cloudcli-data:/home/claude/.cloudcli volumes: cloudcli-data:卷名本身不保证本地存储——使用默认本地驱动即可永远不要把.cloudcli绑定挂载到 NAS 路径。近亲错误unable to open database file这是目录权限或只读挂载问题不是网络锁。升级到 v1.5.3 或之后版本HolyClaude 会在 CloudCLI 启动前准备好目录并修复本地卷所有权写入失败时直接停在启动阶段并报出具体路径与 UID/GID不再让 CloudCLI 反复报错。 Chromium 崩溃、白屏、Lighthouse 卡死shm_size 配置方法症状Playwright 测试失败、截图空白、Lighthouse 无响应。原因Docker 默认只给容器 64MB 共享内存而 Chromium 渲染标签页时大量使用/dev/shm64MB 下标签页会随机崩溃。修复在 Compose 中确认或改为shm_size: 2g # 多标签页、复杂页面时加到 4g快速模板 docker-compose.yaml 已内置 2GB 默认值完整选项见 docker-compose.full.yaml。注意区分如果进程刚启动就以 SIGTRAP 或 exit 133 立即退出那不是共享内存问题而是浏览器/运行时构建层面的失败应先检查浏览器构建路径而不是继续加大 shm。v1.5.5 起直连 Chromium、Node/Python Playwright 与 CloudCLI Browser Use 统一使用镜像内置的 Debian Chromium 安全构建/usr/bin/chromium是唯一受支持入口修复路径里不包含运行时playwright install。 NAS 网络盘SMB/CIFS专项热重载失效的轮询修复症状dev server 热重载不生效、文件监视器检测不到改动。原因网络挂载不支持 inotify。修复给 Compose 的 environment 加上轮询开关完整说明见 docs/configuration.md 的 SMB/CIFS 章节environment: - CHOKIDAR_USEPOLLING1 - WATCHFILES_FORCE_POLLINGtrue⚠️ 轮询比 inotify 更耗 CPU只在卷确实位于 NAS/网络共享上时开启本地磁盘保持关闭。另外 CIFS 默认不支持符号链接这正是 HolyClaude 把.npm、.local留在容器本地的原因——不要把它们挂到网络盘上。 容器重建后的四个高频坑重建后又要重新登录v1.3.6 之前的版本可能让全新容器把保存的会话文件覆盖掉。现在 scripts/entrypoint.sh 会先恢复./data/claude/.claude.json.persist再生成默认文件且拒绝用空配置覆盖有效会话。若仍丢失检查./data/claude/是否可写NAS 上请修宿主共享属主或对齐PUID/PGID。claude: command not found通常是把/home或/home/claude整个挂进容器盖住了镜像自带的/home/claude/.local/bin/claude。不要挂载 /home只挂载./data/claude和./workspace这两个受支持的路径。想重新执行首启初始化删除哨兵文件再重启。注意 Bash 的*通配符匹配不到点文件要指名道姓rm ./data/claude/.holyclaude-bootstrapped docker compose restart holyclaude 千万不要删整个./data/claude/——凭据、Git 配置与 GitHub CLI 认证都在里面。更新镜像后新设置不生效原因相同.holyclaude-bootstrapped存在时 scripts/bootstrap.sh 会被跳过删掉它再重启即可。 其他杂症速查表症状原因一句话修复Web 终端显示黑方块、缺字旧镜像的字体栈与多字节解码问题升级到 1.3.5仍异常时在浏览器 DevTools 执行localStorage.setItem(web-terminal-disable-webgl,true)反代/Tailscale 子路径下页面打不开容器不知道自己的基础路径设HOLYCLAUDE_BASE_PATH/holyclaude无尾部斜杠并重建容器Telegram 收不到通知旧文档使用了 Apprise 不接受的短 scheme改用tgram://bot_token/chat_id先跑notify.py test --dry-run --debug验证见 scripts/notify.pyCloudCLI 默认目录不是 /workspace自定义 s6 脚本漏设WORKSPACES_ROOT官方镜像已处理见 s6-overlay/s6-rc.d/cloudcli/run开启 SSH 后 22 端口不监听公钥文件缺失、可写或路径不安全单独只读挂载authorized_keys到/run/holyclaude-ssh/重建后 SSH 主机指纹变了主机密钥没有持久化给/var/lib/holyclaude-ssh加命名卷✅ 排错清单一张表带走先docker compose logs看启动日志多数问题会直接点名路径权限问题 → 对齐PUID/PGIDPodman 用户用 rootless 配置模板数据库锁 → SQLite 一律放本地盘持久化用本地命名卷浏览器崩溃 →shm_size: 2g起步遇到 SIGTRAP/exit 133 则查浏览器构建NAS 挂载 → 开启轮询监视SQLite 远离网络盘升级永远走docker compose pull docker compose up -d别在容器内自升级。更多细节含 Synology 符号链接循环诊断、Git/GitHub CLI 状态迁移等请查阅官方完整排错文档 docs/troubleshooting.md 与配置参考 docs/configuration.md。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HolyClaude常见问题终极排错指南：权限、SQLite锁、Chromium崩溃一网打尽
HolyClaude常见问题终极排错指南权限、SQLite锁、Chromium崩溃一网打尽【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaudeHolyClaude 是一个开箱即用的 AI coding workstationAI 编程工作站把 Claude Code、CloudCLI Web UI、8 个 AI CLI、Chromium 无头浏览器和 50 开发工具打包进一个 Docker 容器。本文面向新手与个人用户是一份 HolyClaude 常见问题排错指南重点解决三大高频故障——文件权限被拒Permission denied、SQLite 数据库锁database is locked、Chromium 崩溃白屏并顺带覆盖热重载失效、重建后掉登录等 8 个常见坑照着做 5 分钟即可恢复。 排错前先做 3 步快速自检遇到问题别慌先收集信息docker compose ps—— 确认 holyclaude 容器在运行docker compose logs --tail 100 holyclaude—— 看启动日志HolyClaude 多数故障会在启动时直接报出受影响的完整路径docker compose pull docker compose up -d更新镜像——很多历史问题终端黑方块、重建后重新登录等在新版本里已直接修复。⚠️ 注意不要在容器内运行cloudcli update或npm install -g cloudcli-ai/cloudclilatest。HolyClaude 内置的是打过补丁的 CloudCLI 运行时容器内自升级会破坏补丁正确升级方式永远是拉取新镜像。完整官方排错文档docs/troubleshooting.md环境变量全集docs/configuration.md。 权限被拒Permission deniedPUID / PGID 三步修复症状写文件失败、git 操作报错、npm install 失败。原因容器用户 ID 与宿主机不一致或者首次启动时 Docker 自动把./workspace创建成了root:root目录。修复步骤在宿主机执行id -u和id -g记下用户 ID 与组 ID把这两个数字写进 Compose 的 environmentenvironment: - PUID1000 - PGID1000重启容器。HolyClaude 启动时会自动修复顶层/workspace的所有权见 scripts/entrypoint.sh如果之后仍报错问题就在宿主机文件本身而不是容器。Rootless Podman SELinux 用户PUID/PGID只改容器内用户rootless Podman 仍会经过 subuid 映射。请直接使用项目自带的 keep-id 配置文件podman compose -f docker-compose.podman-rootless.yaml up -d该文件docker-compose.podman-rootless.yaml使用keep-id与:Z标签处理 SELinux 标签。切记不要给/workspace加:U——它会递归改写宿主机所有权反而让本地编辑失败。NAS 提示Synology、QNAP 或 SMB 挂载会忽略容器内的chmod/chown请改用 NAS 共享设置或让PUID/PGID与共享目录属主一致。️ SQLite 锁错误database is locked把数据库搬回本地盘症状CloudCLI 账户数据库持续报database is locked。原因SQLite 依赖文件级锁而 CIFS/SMB/NFS 网络文件系统不支持这种锁。修复你自己的 SQLite 库如果放在/workspace的网络挂载上移到本地磁盘路径想让 CloudCLI 账户跨重建保留用Docker 本地命名卷而不是 NFS/SMB 驱动的卷volumes: - cloudcli-data:/home/claude/.cloudcli volumes: cloudcli-data:卷名本身不保证本地存储——使用默认本地驱动即可永远不要把.cloudcli绑定挂载到 NAS 路径。近亲错误unable to open database file这是目录权限或只读挂载问题不是网络锁。升级到 v1.5.3 或之后版本HolyClaude 会在 CloudCLI 启动前准备好目录并修复本地卷所有权写入失败时直接停在启动阶段并报出具体路径与 UID/GID不再让 CloudCLI 反复报错。 Chromium 崩溃、白屏、Lighthouse 卡死shm_size 配置方法症状Playwright 测试失败、截图空白、Lighthouse 无响应。原因Docker 默认只给容器 64MB 共享内存而 Chromium 渲染标签页时大量使用/dev/shm64MB 下标签页会随机崩溃。修复在 Compose 中确认或改为shm_size: 2g # 多标签页、复杂页面时加到 4g快速模板 docker-compose.yaml 已内置 2GB 默认值完整选项见 docker-compose.full.yaml。注意区分如果进程刚启动就以 SIGTRAP 或 exit 133 立即退出那不是共享内存问题而是浏览器/运行时构建层面的失败应先检查浏览器构建路径而不是继续加大 shm。v1.5.5 起直连 Chromium、Node/Python Playwright 与 CloudCLI Browser Use 统一使用镜像内置的 Debian Chromium 安全构建/usr/bin/chromium是唯一受支持入口修复路径里不包含运行时playwright install。 NAS 网络盘SMB/CIFS专项热重载失效的轮询修复症状dev server 热重载不生效、文件监视器检测不到改动。原因网络挂载不支持 inotify。修复给 Compose 的 environment 加上轮询开关完整说明见 docs/configuration.md 的 SMB/CIFS 章节environment: - CHOKIDAR_USEPOLLING1 - WATCHFILES_FORCE_POLLINGtrue⚠️ 轮询比 inotify 更耗 CPU只在卷确实位于 NAS/网络共享上时开启本地磁盘保持关闭。另外 CIFS 默认不支持符号链接这正是 HolyClaude 把.npm、.local留在容器本地的原因——不要把它们挂到网络盘上。 容器重建后的四个高频坑重建后又要重新登录v1.3.6 之前的版本可能让全新容器把保存的会话文件覆盖掉。现在 scripts/entrypoint.sh 会先恢复./data/claude/.claude.json.persist再生成默认文件且拒绝用空配置覆盖有效会话。若仍丢失检查./data/claude/是否可写NAS 上请修宿主共享属主或对齐PUID/PGID。claude: command not found通常是把/home或/home/claude整个挂进容器盖住了镜像自带的/home/claude/.local/bin/claude。不要挂载 /home只挂载./data/claude和./workspace这两个受支持的路径。想重新执行首启初始化删除哨兵文件再重启。注意 Bash 的*通配符匹配不到点文件要指名道姓rm ./data/claude/.holyclaude-bootstrapped docker compose restart holyclaude 千万不要删整个./data/claude/——凭据、Git 配置与 GitHub CLI 认证都在里面。更新镜像后新设置不生效原因相同.holyclaude-bootstrapped存在时 scripts/bootstrap.sh 会被跳过删掉它再重启即可。 其他杂症速查表症状原因一句话修复Web 终端显示黑方块、缺字旧镜像的字体栈与多字节解码问题升级到 1.3.5仍异常时在浏览器 DevTools 执行localStorage.setItem(web-terminal-disable-webgl,true)反代/Tailscale 子路径下页面打不开容器不知道自己的基础路径设HOLYCLAUDE_BASE_PATH/holyclaude无尾部斜杠并重建容器Telegram 收不到通知旧文档使用了 Apprise 不接受的短 scheme改用tgram://bot_token/chat_id先跑notify.py test --dry-run --debug验证见 scripts/notify.pyCloudCLI 默认目录不是 /workspace自定义 s6 脚本漏设WORKSPACES_ROOT官方镜像已处理见 s6-overlay/s6-rc.d/cloudcli/run开启 SSH 后 22 端口不监听公钥文件缺失、可写或路径不安全单独只读挂载authorized_keys到/run/holyclaude-ssh/重建后 SSH 主机指纹变了主机密钥没有持久化给/var/lib/holyclaude-ssh加命名卷✅ 排错清单一张表带走先docker compose logs看启动日志多数问题会直接点名路径权限问题 → 对齐PUID/PGIDPodman 用户用 rootless 配置模板数据库锁 → SQLite 一律放本地盘持久化用本地命名卷浏览器崩溃 →shm_size: 2g起步遇到 SIGTRAP/exit 133 则查浏览器构建NAS 挂载 → 开启轮询监视SQLite 远离网络盘升级永远走docker compose pull docker compose up -d别在容器内自升级。更多细节含 Synology 符号链接循环诊断、Git/GitHub CLI 状态迁移等请查阅官方完整排错文档 docs/troubleshooting.md 与配置参考 docs/configuration.md。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考