GitHub - CooloiStudio/ClaudeCodeInDocker: 将Claude Code运行在Docker容器中，提供完全隔离的开发环境 · GitHub
Skip to content

CooloiStudio/ClaudeCodeInDocker

BranchesTags

Repository files navigation

Claude Code Docker

🚀 容器化的Claude Code解决方案 - 实现环境隔离与本地化体验的完美结合

将Claude Code运行在Docker容器中，提供完全隔离的开发环境，同时保持如同本地安装般的透明使用体验。

✨ 特性

  • 🔒 完全隔离: 容器化运行，不影响宿主机环境
  • ⚡ 快速启动: 优化的启动流程，3秒内响应
  • 🌍 跨平台: 支持Linux、macOS、Windows
  • 🎯 零配置: 只需API密钥即可使用
  • 📦 轻量化: 基于Ubuntu 22.04，镜像体积小
  • 🛡️ 安全设计: 最小权限原则，只读配置
  • 🔧 稳定性增强: 内存优化、健康检查、自动恢复
  • 📦 NVM管理: 使用nvm管理最新的Node.js LTS版本，提高兼容性
  • 🔍 详细构建: 安装时显示详细的Docker构建进度和步骤

🚀 快速开始

一键安装

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/your-repo/claude-docker/main/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/your-repo/claude-docker/main/install.ps1" | Invoke-Expression

手动安装

  1. 克隆项目

    git clone https://github.com/your-repo/claude-docker.git
cd claude-docker

  2. 运行安装脚本

    # Linux/macOS
./install.sh

# Windows
.\install.ps1

    注意: 安装过程会显示详细的Docker构建步骤，包括：

    • 系统依赖安装
    • nvm和Node.js LTS安装
    • npm镜像源配置
    • Claude Code安装
    • 监控和健康检查配置

  3. 配置API密钥

    export ANTHROPIC_AUTH_TOKEN="sk-your-api-key-here"
# 或创建 .env 文件
echo "ANTHROPIC_AUTH_TOKEN=sk-your-api-key-here" > .env

💡 基本使用

安装完成后，可以像使用本地Claude Code一样：

# 代码分析
claude "分析这个Python项目的架构"

# 代码生成  
claude "创建一个Flask Web应用"

# 代码优化
claude "优化这个JavaScript函数的性能"

# 文档生成
claude "为这个项目生成README文档"

🛠️ 命令参考

基本命令

claude "任务描述"          # 执行Claude Code任务
claude --help             # 显示帮助信息
claude --version          # 显示版本信息

管理命令

claude --status           # 查看容器状态
claude --logs             # 查看容器日志
claude --shell            # 进入容器shell
claude --stop             # 停止容器
claude --restart          # 重启容器
claude --monitor          # 监控容器资源
claude --health           # 检查容器健康状态

测试命令

# Linux/macOS
./test-nvm.sh             # 测试nvm安装
./check-lts-version.sh    # 检查LTS版本信息

# Windows
.\test-nvm.ps1            # 测试nvm安装
.\check-lts-version.ps1   # 检查LTS版本信息

⚙️ 配置

API密钥配置

方法1: 环境变量 (推荐)

export ANTHROPIC_AUTH_TOKEN="sk-your-api-key-here"

方法2: .env文件

# 在项目目录或任何工作目录创建 .env 文件
echo "ANTHROPIC_AUTH_TOKEN=sk-your-api-key-here" > .env

可选配置

# 自定义API端点
export ANTHROPIC_BASE_URL="https://your-proxy.example.com/v1"

# 或添加到 .env 文件
echo "ANTHROPIC_BASE_URL=https://your-proxy.example.com/v1" >> .env

🏗️ 项目结构

claude-docker/
├── dockerfile            # 优化的容器定义 (使用nvm)
├── docker-compose.yml   # 简化的编排配置
├── claude               # 统一的执行脚本
├── claude.ps1           # Windows PowerShell脚本
├── install.sh           # Linux/macOS安装脚本
├── install.ps1          # Windows安装脚本
├── debug-segfault.sh    # Linux/macOS调试脚本
├── debug-segfault.ps1   # Windows调试脚本
├── fix-segfault.ps1     # Windows快速修复脚本
├── test-nvm.sh          # Linux/macOS nvm测试脚本
├── test-nvm.ps1         # Windows nvm测试脚本
├── check-lts-version.sh # Linux/macOS LTS版本检查脚本
├── check-lts-version.ps1 # Windows LTS版本检查脚本
├── README.md            # 项目文档
└── bak/                 # 原始文件备份

🔧 高级用法

开发模式

# 进入容器进行调试
claude --shell

# 查看详细日志
claude --logs

# 检查容器状态
claude --status

# 监控资源使用
claude --monitor

# 检查健康状态
claude --health

# 检查LTS版本信息
.\check-lts-version.ps1

### 自定义配置

如需修改容器配置，可以编辑 `docker-compose.yml`:

```yaml
version: '3.8'
services:
  claude-code-service:
    build: .
    container_name: claude-code-service
    volumes:
      - .:/workspace
    environment:
      - ANTHROPIC_AUTH_TOKEN=${ANTHROPIC_AUTH_TOKEN:-}
      - ANTHROPIC_BASE_URL=${ANTHROPIC_BASE_URL:-}
    restart: unless-stopped

🐛 故障排除

常见问题

1. Docker未运行

# Linux/macOS
sudo systemctl start docker
# 或启动 Docker Desktop

# Windows
# 启动 Docker Desktop

2. API密钥未配置

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 检查 .env 文件
cat .env

3. 容器启动失败

# 查看详细日志
claude --logs

# 重新构建镜像 (显示详细进度)
docker-compose build --no-cache --progress=plain

# 重启容器
claude --restart

4. 命令不可用

# 检查安装路径
which claude

# 手动添加到PATH
export PATH="$HOME/.claude-docker:$PATH"

🚨 Segmentation Fault 问题解决

如果遇到 "Segmentation fault (core dumped)" 错误，请按以下步骤处理：

1. 运行诊断脚本

Linux/macOS:

./debug-segfault.sh

Windows:

.\debug-segfault.ps1

2. 常见原因和解决方案

内存不足

  • 症状：容器频繁崩溃，内存使用率过高
  • 解决：增加Docker Desktop内存分配（建议4GB以上）
  • 命令：claude --monitor 监控内存使用

Node.js版本兼容性

  • 症状：特定操作时崩溃
  • 解决：使用nvm管理最新的Node.js LTS版本（已优化）
  • 命令：claude --health 检查配置

文件系统性能

  • 症状：Windows下文件操作缓慢导致超时
  • 解决：使用WSL2后端，优化文件映射
  • 配置：在Docker Desktop中启用WSL2

网络连接问题

  • 症状：API调用失败导致进程异常
  • 解决：检查网络连接，配置代理
  • 命令：claude --logs 查看错误日志

3. 自动修复

运行诊断脚本后，选择自动应用修复：

# Linux/macOS
./debug-segfault.sh

# Windows
.\debug-segfault.ps1

脚本会自动：

  • 重新构建优化后的镜像
  • 调整内存配置
  • 添加健康检查
  • 实现自动重启机制

4. 手动修复步骤

如果自动修复失败，可以手动执行：

# 1. 停止容器
claude --stop

# 2. 清理资源
docker system prune -f

# 3. 重新构建
docker-compose build --no-cache

# 4. 启动容器
claude --restart

# 5. 检查状态
claude --status

5. Windows特定优化

Docker Desktop设置：

  • 内存：分配4GB或更多
  • CPU：分配2核或更多
  • 磁盘：使用WSL2后端
  • 网络：启用IPv6

系统优化：

  • 关闭不必要的后台程序
  • 增加虚拟内存
  • 使用SSD存储

获取帮助

如果遇到问题：

  1. 查看 claude --help 获取使用帮助
  2. 运行 claude --logs 查看详细日志
  3. 使用诊断脚本分析问题
  4. 检查 Issues 页面
  5. 提交新的Issue报告问题

🔄 更新

更新到最新版本：

# 重新运行安装脚本
curl -sSL https://raw.githubusercontent.com/your-repo/claude-docker/main/install.sh | bash

# 或手动更新
cd ~/.claude-docker
git pull
docker-compose build --no-cache
claude --restart

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

MIT License

🎯 设计理念

这个项目的核心理念是：

  • 容器只做一件事: 运行Claude Code，不处理Git/SSH等
  • 配置最小化: 只需要API密钥，避免复杂的环境检测
  • 用户体验优先: 透明的本地化使用感受
  • 架构简洁性: 减少层次和依赖，提高可维护性
  • 稳定性优先: 内存优化、错误处理、自动恢复
  • 版本管理: 使用nvm确保Node.js LTS版本一致性
  • 透明构建: 详细的构建过程输出，便于问题诊断

真正实现"安装一次，使用如本地"的容器化Claude Code体验。

About

将Claude Code运行在Docker容器中，提供完全隔离的开发环境

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors