企业官网建设流程全解析

HolyClaude本地构建实战：从源码构建full与slim镜像并读懂Dockerfile

【免费下载链接】HolyClaudeAI coding workstation: Claude Code + web UI + 8 AI CLIs + headless browser + 50+ tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude

HolyClaude 是一个开箱即用的 AI 编程工作站容器：把 Claude Code、CloudCLI 网页界面、8 个 AI CLI、Chromium 无头浏览器和 50+ 开发工具全部预装进一个 Docker 镜像。本文带你从源码本地构建full 与 slim 两种镜像，并逐段读懂这份约 1000 行的 Dockerfile，帮你彻底搞懂这个"一键 AI 开发环境"是怎么炼成的。

为什么要本地构建镜像？🤔

平时直接docker pull官方镜像最省事，但本地构建有几个好处：

• 可复现：Dockerfile 中所有组件都锁定了版本号和 SHA256 校验值，你构建出的镜像与官方发布完全一致；
• 可定制：想改预装工具、换 Node 版本、加自己的补丁，都可以先读懂再动手；
• 适配私有环境：内网机器、ARM 服务器、NAS 等场景下，自己构建更灵活。

构建前准备：只需源码和 Docker

本地构建没有任何额外依赖，准备好两样东西即可：

1. 一台装有 Docker（或 Podman）的机器，建议至少 8GB 内存、预留 10GB 以上磁盘空间；
2. HolyClaude 源码仓库（git clone 后进入目录即可）。

💡 full 镜像构建时间较长（要编译 ffmpeg 安全补丁、安装大量 CLI），slim 镜像快得多，第一次练手建议先构建 slim。

一键构建 full 与 slim 镜像

进入仓库根目录后，两条命令搞定：

# 构建 full 镜像（默认，全量工具，推荐大多数人使用） docker build -t holyclaude . # 构建 slim 镜像（仅核心工具，体积更小，适合小 VPS / NAS） docker build --build-arg VARIANT=slim -t holyclaude:slim .

区别在哪？由VARIANT这个构建参数控制：slim 镜像跳过 full 独有的部署类 CLI（Vercel、Netlify、Cloudflare Wrangler 等）、ffmpeg 安全补丁和 Azure CLI，但Claude Code 本体、网页 UI、无头浏览器和核心开发工具两者都有。

如果需要在 Apple Silicon、树莓派等 ARM 机器上构建：

docker buildx build --platform linux/arm64 -t holyclaude .

构建完成后，把 Compose 文件里的image: coderluii/holyclaude:latest换成你本地镜像名holyclaude，然后照常docker compose up -d即可。仓库里提供了三套现成模板，可以直接参考：docker-compose.yaml、docker-compose.full.yaml 和 docker-compose.podman-rootless.yaml。

读懂 Dockerfile：镜像是怎么炼成的？

这份 Dockerfile 看似很长，实际结构非常清晰，可以分成 5 个部分理解。

1️⃣ 多阶段构建：三个"预制菜"阶段

文件开头定义了辅助构建阶段：

• esbuild-builder（Dockerfile#L12-L22）：用 Go 编译 3 个指定版本的 esbuild 二进制，供后续 Web 终端插件使用；
• ffmpeg-security-builder（Dockerfile#L24-L48）：仅 full 变体启用，把官方 ffmpeg 安全补丁编译成 deb 包，补丁源在 security/patches/ffmpeg/ 目录；
• python-runtime（Dockerfile#L50）：提供 Python 3.14 运行时。

最终镜像基于Node 26.9.0 + Debian Bookworm搭建，这种"多阶段 + 主阶段"的写法让每一层的职责都清晰可查。

2️⃣ 一切皆锁版本、带校验

第 62-147 行 是一长串ARG参数：s6-overlay、fzf、Chromium 153、Claude Code 2.1.276……每个下载都绑定版本号 + SHA256 校验值，并区分 amd64/arm64 双架构。构建时先sha256sum -c校验、再安装，任何篡改或上游变动都会让构建直接失败——这就是官方强调的"可复现构建"。

3️⃣ Claude Code 的安装细节（新手易踩坑）

第 335-348 行 安装 Claude Code CLI 时有两个精心设计的点：

• 特意先WORKDIR /workspace并切换到claude用户，因为安装脚本在 root 属主的目录下会挂起（Dockerfile 注释里专门标注了 CRITICAL）；
• 安装后立刻rm -f ~/.claude.json，保证容器内不带任何预置会话数据。

4️⃣ s6-overlay 多进程守护：一个容器跑多个服务

普通容器只跑一个进程，而 HolyClaude 要在容器内同时守护 4 个服务，靠的是 s6-overlay/s6-rc.d/ 下的服务定义：

启动流程是：scripts/entrypoint.sh 先做 UID 映射和状态恢复，再exec /init把 PID 1 交给 s6-overlay。完整架构图解可以阅读 docs/architecture.md。

5️⃣ 收尾：变体标记、健康检查与入口

最后几行（第 962-1015 行）做三件事：

• 把full或slim写入/etc/holyclaude-variant，运行时按变体加载不同的记忆模板（config/claude-memory-full.md / config/claude-memory-slim.md）；
• 设置HEALTHCHECK每 30 秒探活 3001 端口；
• ENTRYPOINT指向 entrypoint.sh，容器启动即全自动。

构建完成后如何验证？

启动容器后做三个检查：

1. 浏览器打开http://localhost:3001，能看到 CloudCLI 登录页；
2. docker ps中容器状态显示(healthy)，对应上面的健康检查；
3. 在网页端完成 Anthropic 账号登录后，发一句"列出当前目录"，Claude Code 正常响应即全链路打通。

仓库还附带了一整套测试脚本，想深入验证可以看 tests/ 目录，例如 tests/product_facts.test.mjs 会校验 contracts/product-facts.json 与 Dockerfile、Compose 文件中的关键版本是否一致。

常见问题速查 🛠️

总结

从docker build一条命令，到锁定版本、校验和、多阶段构建、s6-overlay 守护——HolyClaude 的 Dockerfile 是一份很好的生产级 Docker 镜像范本。跑通 full 和 slim 两个变体后，你就既拥有了本地镜像，也理解了它每个设计决策背后的原因。

📖 延伸阅读：docs/architecture.md（架构详解）、docs/ollama.md（本地模型接入）、docs/troubleshooting.md（故障排查）。

【免费下载链接】HolyClaudeAI coding workstation: Claude Code + web UI + 8 AI CLIs + headless browser + 50+ tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude