企业官网建设流程全解析

CodeWhale Docker部署：卷持久化与环境注入完整教程

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

CodeWhale 是一个用 Rust 编写的开源终端编码代理（coding agent），可以在容器里以最小信任边界跑起来，而不用污染你的主机环境。本教程带你完成 CodeWhale Docker 部署的完整流程：官方镜像怎么用、卷持久化如何配置让会话与配置跨重启保留、API Key 等环境注入的安全做法，以及多项目隔离、toolbox 自定义镜像和 Compose 模板。

官方镜像长什么样：先认识镜像契约 🐳

CodeWhale 每次发版都会为linux/amd64和linux/arm64两种架构发布预构建的 Docker 镜像。官方镜像刻意保持"极简 + 非 root"：

这个契约写得很清楚：官方镜像就是"越小越好"的运行层。如果你需要apt-get、编译器工具链、Node/Python 包管理器，属于"opt-in"场景，应该另建 toolbox 镜像（见后文），而不是修改默认镜像。

镜像里codewhale和codew是同一个运行时的两个命令名，入口由 Dockerfile 定义，发布路径则由 Dockerfile.release 组装——发布时直接复用与归档包完全一致的编译产物，保证字节级一致。

最快启动方法：一条命令跑起来 🚀

第 1 步：创建持久化数据卷

卷（volume）是 CodeWhale 状态的"家"。会话记录、配置、skills、memory 和离线队列都存放在这里：

docker volume create codewhale-home

💡 官方文档推荐用 Docker 命名卷作为最安全的默认选择：Docker 会按容器可写的属主关系创建它，天然匹配镜像里1000:1000的用户。不加这个挂载，容器每次都是"白板"启动。

第 2 步：拉取并运行镜像

docker pull ghcr.io/hmbown/codewhale:latest docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" \ -w /workspace \ ghcr.io/hmbown/codewhale:latest

三个关键参数逐个看：

• -v codewhale-home:/home/codewhale/.codewhale：把命名卷挂到状态目录，实现卷持久化；
• -v "$PWD:/workspace" -w /workspace：把当前项目目录挂进容器并设为工作目录；
• -e DEEPSEEK_API_KEY=...：环境注入，API Key 只存在于运行时的环境变量里。

可复现的部署建议固定语义化版本标签（把latest换成vX.Y.Z），而不是追latest。

环境注入：API Key 的三种安全传法 🔑

官方 Dockerfile 里有一行注释态度非常明确：API Key 必须在运行时传入，永远不要烤进镜像。这是 Docker 部署 CodeWhale 最重要的安全原则。

三种常用注入方式，按场景选一个：

1. 单条-e内联：临时试跑最方便，Key 直接引用宿主 shell 里已有的变量（注意用双引号让$DEEPSEEK_API_KEY展开）；
2. --env-file：把 Key 写进一个本地.env文件（不提交进仓库），然后docker run --rm -it --env-file .env ghcr.io/hmbown/codewhale:latest，适合团队内部流程；
3. Compose 环境变量：environment:段配合${DEEPSEEK_API_KEY:?...}写法，忘设时直接报错，避免"空 Key 静默启动"。

同样地，不要把 API Key、SSH 私钥写进自定义 toolbox 镜像。SSH 材料需要时建议只读挂载、且仅限确有需要的项目。

卷持久化进阶：绑定挂载与属主坑 ⚠️

默认推荐命名卷。如果你坚持用宿主目录绑定挂载（bind-mount），要记得容器里跑的是 UID1000的用户——目录不可写时，启动会在创建.codewhale/tasks等运行时目录时失败。Linux 宿主机的处理方式是提前准备：

mkdir -p ~/.codewhale sudo chown -R 1000:1000 ~/.codewhale

⚠️chown会把宿主~/.codewhale的属主改给容器 UID。如果你不想让容器"拥有"本地配置，直接用命名卷更省心。

镜像还保留了/home/codewhale/.deepseek目录用于旧版本兼容，一般不需要额外处理。

多项目隔离：一个项目一个卷 📦

会话、配置、skills、memory 和离线队列都存在状态卷里。多个项目共用一个卷，上下文会互相"串台"。官方给出的做法是按项目建独立卷：

project="$(basename "$PWD")" docker volume create "codewhale-${project}-home" docker run --rm -it \ --name "codewhale-${project}" \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v "codewhale-${project}-home:/home/codewhale/.codewhale" \ -v "$PWD:/workspace" \ -w /workspace \ ghcr.io/hmbown/codewhale:latest

如果不同项目需要不同工具链，就为它们构建不同的 toolbox 标签（如codewhale-toolbox:frontend、codewhale-toolbox:backend），实现"环境 + 状态"双隔离。

需要装软件？构建 toolbox 自定义镜像 🧰

默认镜像不允许apt-get。当项目确需在容器内装包时，仓库提供了示例 Dockerfile.toolbox，它在官方镜像之上追加免密sudo和一组常用开发包：

docker build -f docs/examples/Dockerfile.toolbox \ --build-arg CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \ --build-arg TOOLBOX_PACKAGES="git openssh-client curl build-essential pkg-config python3 python3-pip nodejs npm" \ -t codewhale-toolbox:my-project .

两个使用纪律：

• 共享项目请固定CODEWHALE_IMAGE的标签值，latest只用于一次性试验；
• 可复现的容器建议把包"烤"进 Dockerfile，而不是让长生命周期容器里跑sudo apt-get逐步漂移。

Compose 模板：可重复的 docker compose 入口

偏好 Compose 的话，直接使用 compose.toolbox.yml。它会自动构建 toolbox 镜像、把项目状态卷显式命名，还内置了 SSH 材料与本地 CA 证书的只读挂载示例（默认注释掉，按需开启）：

CODEWHALE_IMAGE=ghcr.io/hmbown/codewhale:vX.Y.Z \ CODEWHALE_TOOLBOX_IMAGE=codewhale-toolbox:my-project \ CODEWHALE_HOME_VOLUME=codewhale-my-project-home \ CODEWHALE_WORKSPACE="$PWD" \ docker compose -f docs/examples/compose.toolbox.yml run --rm codewhale

本地 CA 证书与公司代理

需要自签内部服务时，把.crt证书放入/usr/local/share/ca-certificates/再执行update-ca-certificates（需要 toolbox 镜像的sudo）。也可以只读挂载证书目录，用--entrypoint bash加-lc 'sudo update-ca-certificates && exec codewhale'在启动时刷新信任库。

顺手了解：本地构建与流水线用法 📌

• 从源码本地构建：docker build -t codewhale .，多架构需要docker buildx build --platform linux/amd64,linux/arm64 -t codewhale .（构建逻辑见 Dockerfile）。

• 非交互 / 管道模式：stdin 不是 TTY 时，CodeWhale 自动进入一次性模式。比如：

  echo "用结构化英文解释 Cargo.toml" | docker run --rm -i -e DEEPSEEK_API_KEY ghcr.io/hmbown/codewhale:latest

  这让 CodeWhale 可以直接嵌进 CI 管道做代码审查类任务。

• 项目启动脚本：CodeWhale 不会自动执行.codewhale/setup.sh。团队共享的引导逻辑建议写成入库的脚本，通过--entrypoint bash ... -lc './scripts/bootstrap-dev.sh && exec codewhale'显式运行。

常见问题 FAQ ❓

小结

按"官方最小镜像 + 命名卷持久化 + 运行时环境注入"三板斧部署 CodeWhale，你就能得到一个干净、可复现、信任边界最小的容器化终端编码代理环境；有额外工具链需求时再升级到 toolbox 镜像 + Compose 模板。更多细节可以查阅官方文档 docs/DOCKER.md，示例文件在 docs/examples/ 目录下。

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale