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/CodewhaleCodeWhale 是一个用 Rust 编写的开源终端编码代理coding agent可以在容器里以最小信任边界跑起来而不用污染你的主机环境。本教程带你完成 CodeWhale Docker 部署的完整流程官方镜像怎么用、卷持久化如何配置让会话与配置跨重启保留、API Key 等环境注入的安全做法以及多项目隔离、toolbox 自定义镜像和 Compose 模板。官方镜像长什么样先认识镜像契约 CodeWhale 每次发版都会为linux/amd64和linux/arm64两种架构发布预构建的 Docker 镜像。官方镜像刻意保持极简 非 root契约项说明运行用户非 root 的codewhale用户UID/GID 为1000:1000权限模型不提供免密sudo不能改基础系统用途定位面向挂载进来的工作区干活而不是改容器底层环境状态目录用户状态应持久化到挂载在/home/codewhale/.codewhale的卷中这个契约写得很清楚官方镜像就是越小越好的运行层。如果你需要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 最重要的安全原则。变量是否必填作用DEEPSEEK_API_KEY是DeepSeek API 密钥DEEPSEEK_BASE_URL否自定义 API 地址例如企业网关或代理DEEPSEEK_NO_COLOR否设为1时关闭终端彩色输出三种常用注入方式按场景选一个单条-e内联临时试跑最方便Key 直接引用宿主 shell 里已有的变量注意用双引号让$DEEPSEEK_API_KEY展开--env-file把 Key 写进一个本地.env文件不提交进仓库然后docker run --rm -it --env-file .env ghcr.io/hmbown/codewhale:latest适合团队内部流程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_IMAGEghcr.io/hmbown/codewhale:vX.Y.Z \ --build-arg TOOLBOX_PACKAGESgit 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_IMAGEghcr.io/hmbown/codewhale:vX.Y.Z \ CODEWHALE_TOOLBOX_IMAGEcodewhale-toolbox:my-project \ CODEWHALE_HOME_VOLUMEcodewhale-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 ❓问题解决每次重启会话都没了忘了挂状态卷补上-v codewhale-home:/home/codewhale/.codewhale绑定挂载启动失败宿主目录属主不是1000:1000用chown准备或改用命名卷想装git/node却提示无权限默认镜像禁止系统级安装构建 toolbox 镜像再运行忘记设 API Key 容器也启动了用 Compose 模板里的${DEEPSEEK_API_KEY:?set DEEPSEEK_API_KEY}强制校验小结按官方最小镜像 命名卷持久化 运行时环境注入三板斧部署 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CodeWhale Docker部署：卷持久化与环境注入完整教程
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/CodewhaleCodeWhale 是一个用 Rust 编写的开源终端编码代理coding agent可以在容器里以最小信任边界跑起来而不用污染你的主机环境。本教程带你完成 CodeWhale Docker 部署的完整流程官方镜像怎么用、卷持久化如何配置让会话与配置跨重启保留、API Key 等环境注入的安全做法以及多项目隔离、toolbox 自定义镜像和 Compose 模板。官方镜像长什么样先认识镜像契约 CodeWhale 每次发版都会为linux/amd64和linux/arm64两种架构发布预构建的 Docker 镜像。官方镜像刻意保持极简 非 root契约项说明运行用户非 root 的codewhale用户UID/GID 为1000:1000权限模型不提供免密sudo不能改基础系统用途定位面向挂载进来的工作区干活而不是改容器底层环境状态目录用户状态应持久化到挂载在/home/codewhale/.codewhale的卷中这个契约写得很清楚官方镜像就是越小越好的运行层。如果你需要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 最重要的安全原则。变量是否必填作用DEEPSEEK_API_KEY是DeepSeek API 密钥DEEPSEEK_BASE_URL否自定义 API 地址例如企业网关或代理DEEPSEEK_NO_COLOR否设为1时关闭终端彩色输出三种常用注入方式按场景选一个单条-e内联临时试跑最方便Key 直接引用宿主 shell 里已有的变量注意用双引号让$DEEPSEEK_API_KEY展开--env-file把 Key 写进一个本地.env文件不提交进仓库然后docker run --rm -it --env-file .env ghcr.io/hmbown/codewhale:latest适合团队内部流程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_IMAGEghcr.io/hmbown/codewhale:vX.Y.Z \ --build-arg TOOLBOX_PACKAGESgit 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_IMAGEghcr.io/hmbown/codewhale:vX.Y.Z \ CODEWHALE_TOOLBOX_IMAGEcodewhale-toolbox:my-project \ CODEWHALE_HOME_VOLUMEcodewhale-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 ❓问题解决每次重启会话都没了忘了挂状态卷补上-v codewhale-home:/home/codewhale/.codewhale绑定挂载启动失败宿主目录属主不是1000:1000用chown准备或改用命名卷想装git/node却提示无权限默认镜像禁止系统级安装构建 toolbox 镜像再运行忘记设 API Key 容器也启动了用 Compose 模板里的${DEEPSEEK_API_KEY:?set DEEPSEEK_API_KEY}强制校验小结按官方最小镜像 命名卷持久化 运行时环境注入三板斧部署 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考