HolyClaude 启动流程逆向解析entrypoint.sh 与 bootstrap.sh 首次启动机制完整指南【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaudeHolyClaude 启动流程的奥秘藏在两个 Shell 脚本里。HolyClaude 是一款开箱即用的 AI 编程工作站AI coding workstation一个 Docker 镜像里打包了 Claude Code、Web 管理界面 CloudCLI、Codex、Gemini、Cursor 等 8 个 AI 命令行工具、headless Chromium 浏览器和 50 开发工具。按下启动键后的头几秒容器内部到底发生了什么本文逐段解析 scripts/entrypoint.sh 与 scripts/bootstrap.sh讲清容器启动 → 权限修复 → 首次初始化 → 服务接管的完整链条帮你快速看懂并排障 HolyClaude 的启动机制。 一、启动流程全景一条命令背后的 4 个阶段Dockerfile 最后一行声明了ENTRYPOINT [/usr/local/bin/entrypoint.sh]——每次容器启动entrypoint.sh 都会先跑一遍全部初始化最后才exec /init把控制权交给 s6-overlayPID 1 进程守护器。整个流程可以拆成 4 个阶段阶段执行者触发条件职责1️⃣ 环境修复entrypoint.sh每次启动校验 Claude Code、UID/GID 重映射、目录体检、恢复登录会话2️⃣ 首次初始化bootstrap.sh仅首次无哨兵文件时拷贝默认配置、记忆模板初始化 CLI 通知钩子生成哨兵3️⃣ 服务守护s6-overlay每次启动拉起 CloudCLI、Xvfb、会话同步服务崩溃自动重启4️⃣ Web 服务CloudCLIs6 启动后监听 3001 端口提供浏览器 UI 二、entrypoint.sh 逐段拆解每次启动都执行的 5 件事1. 预检Claude Code 必须在位脚本第一步就校验/home/claude/.local/bin/claude是否可执行entrypoint.sh L219-L226。如果你挂载目录的方式把镜像内置的 Claude Code 遮住了容器会直接退出并打印修复提示不要把整个/home挂载进容器只挂载~/.claude和/workspace。2. UID/GID 重映射让容器用户对齐宿主机PUID/PGID环境变量默认 1000会先做正则校验非数字自动回退为 1000。以 root 运行时执行usermod -o -u和groupmod修改 claude 用户的 UID/GID这样挂载目录里的文件归属才是正确的——这就是宿主机换个 PUID容器内文件不报错的原因。rootless Podman 场景检测到非 root 会跳过重映射L228-L263。3. 持久化目录体检先验证后放行CLI 持久化预检调用 scripts/prepare-cli-persistence.sh 校验~/.claude根目录与 CLI 状态别名结构任何不安全状态都会在后续操作之前被拦截CloudCLI 状态~/.cloudcli不允许是软链接脚本会真的以 claude 用户身份创建临时文件做写测试并逐个检查 auth.db 及其 WAL/journal 文件可写不满足就立即退出日志给出精确的 UID:GID 提示/workspace不可写时尝试一次 chown 修复仍失败则警告多半是宿主机属主或 PUID/PGID 配错bubblewrap校验/usr/bin/bwrap的 setuid 权限必须为4755 0 0异常时 root 自动修复——这是 Codex 沙箱在受限内核上的基础4. 每启动必做恢复 Claude 登录会话node /usr/local/bin/persist-claude-json.mjspersist-claude-json.mjs是会话连续性的关键Claude Code 会直接改写~/.claude.json该脚本在启动前把持久化目录里保存的会话文件恢复到活动路径保证重建容器后 OAuth 登录态不会被 onboarding 向导覆盖。同一阶段还会执行 Codex 特性开关迁移把旧版config.toml中的codex_hooks自动改写为新字段名hooksL405-L413。5. 可选项Desloppify 与 SSH 远程终端设置HOLYCLAUDE_DESLOPPIFY_SETUP会为指定 AI CLI 配置编码风格HOLYCLAUDE_SSH_ENABLEtrue启用密钥登录的 SSH。SSH 启用逻辑非常严格authorized_keys 必须是绝对路径、只读挂载、不含私钥、不含不支持的密钥类型任何一条不满足就保持禁用并打印警告——典型的 fail-secure 设计。 三、bootstrap.sh 首次启动机制哨兵文件原理哨兵文件判断第一次启动的唯一依据entrypoint.sh 里的关键逻辑只有一行L423-L430/home/claude/.claude/.holyclaude-bootstrapped不存在才运行 bootstrap.sh否则直接跳过。这个哨兵文件位于挂载进容器的~/.claude目录中所以已初始化状态可以跨容器重建存活。注意 bootstrap 失败时只告警不退出——首次初始化是尽力而为的非关键步骤。首次启动具体做了什么步骤内容保护机制拷贝 settings.jsonconfig/settings.json →~/.claude/settings.json先备份现有文件为.bak拷贝记忆模板按/etc/holyclaude-variant选 claude-memory-full.md或 slim 版→CLAUDE.md同样先备份再覆盖Codex 配置生成~/.codex/config.toml审批与沙箱策略由HOLYCLAUDE_CODEX_CLI_PERMISSION_MODE决定default / acceptEdits / bypassPermissions仅在文件不存在时生成已有配置只追加[features] hooks段通知钩子为 Codexhooks.json、Geminisettings.json写入 notify.py 停止通知钩子并预配置 Cursorhooks.json每个文件都只在缺失时写入绝不覆盖用户自定义收尾chown 归属到 PUID:PGIDtouch生成哨兵文件bootstrap.sh L160-L162—设计哲学是只播种一次然后退出哨兵创建后你手改的任何配置都不会被重启覆盖。️ 四、s6-overlay 接管PID 1 守护常驻服务exec /init之后s6-overlay 成为 PID 1拉起 s6-overlay/s6-rc.d/ 中定义的服务cloudclirunroot 时经s6-setuidgid claude降权启动cloudcli --port 3001——这就是 Web UI 入口xvfbrunXvfb :991920x1080 虚拟显示为需要 headed 显示的工具提供兼容环境persist-claude-jsonrun每 60 秒可用HOLYCLAUDE_CLAUDE_JSON_SYNC_INTERVAL调整把容器内~/.claude.json写回持久化目录掉电也不丢会话sshdrun默认不启用只有 entrypoint 的 SSH 检查全部通过才会被挂入服务组相比普通 supervisord 方案s6 会崩溃自动重启、正确转发信号、回收僵尸进程并优雅关机。Dockerfile 还配置了 30 秒间隔的健康检查探测http://localhost:3001/判断服务是否就绪。 五、实战如何重新触发首次启动如果想重跑初始化例如默认配置被改乱只需删除哨兵文件再重启容器——不要删整个目录里面存着登录状态rm ./data/claude/.holyclaude-bootstrapped docker compose restart holyclaude注意./data/claude/可能包含 GitHub 凭据.config/gh/hosts.yml请勿提交到代码仓库或放入未加密备份。 六、快速排障清单症状定位与处理启动即退出Claude Code is missing挂载方式遮住了镜像文件改为只挂载~/.claude与/workspaceCloudCLI state is not writable修正卷属主或去掉只读设置日志会给出要求的精确 UID:GID/workspace is not writable修正宿主机目录属主或核对 PUID/PGID 与宿主机用户一致rootless Podman 报权限类警告keep-id 模式下脚本会跳过 root 专属修复属正常降级行为想重置默认配置删除哨兵文件重启或查看.bak备份手动回滚更多技术细节可参考 docs/architecture.md全部启动相关环境变量见 docs/configuration.md最小化部署模板见 docker-compose.yaml。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考