# 34.1 开发容器配置

学习如何在企业环境中配置和使用 Claude Code 开发容器，为团队提供一致、安全的开发环境。

## 34.1.1 开发容器概述

### 什么是开发容器

开发容器（Dev Containers）是一种使用 Docker 容器作为完整开发环境的解决方案。它为团队提供：

- **一致性** ：所有开发者使用相同的工具和配置
- **可移植性** ：在不同操作系统上获得相同的开发体验
- **隔离性** ：开发环境与主机系统分离
- **安全性** ：增强的安全措施保护开发环境

### Claude Code 开发容器特性

Claude Code 提供的官方开发容器包含：

- **生产就绪的 Node.js** ：基于 Node.js 20 构建
- **安全设计** ：自定义防火墙限制网络访问
- **开发者工具** ：git、ZSH、fzf 等生产力工具
- **VS Code 集成** ：预配置的扩展和优化设置
- **会话持久性** ：保留命令历史和配置

## 34.1.2 快速入门

### 前置要求

确保您的系统已安装以下组件：

## 检查 Docker 安装

```bash
docker --version

```

## 检查 VS Code 安装

code --version

## 检查 Remote - Containers 扩展

code --list-extensions | grep ms-vscode-remote.remote-containers

### 安装步骤

1. **安装 Docker Desktop**

## macOS

brew install --cask docker

## 启动 Docker Desktop

open /Applications/Docker.app

## 安装 VS Code（如果尚未安装）

brew install --cask visual-studio-code

## 安装 Remote - Containers 扩展

code --install-extension ms-vscode-remote.remote-containers

2. **克隆 Claude Code 参考实现**

```bash
git clone https://github.com/anthropics/claude-code.git
cd claude-code

在 VS Code 中：

```

- 打开命令面板：`Cmd+Shift+P`
- 输入并选择：`Remote-Containers: Reopen in Container`
- 等待容器构建和启动

## 34.1.3 开发容器配置详解

### devcontainer.json 配置

{
"name": "Claude Code Dev Container",
"dockerFile": "Dockerfile",
"context": "..",
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"github.copilot"
],
"settings": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"terminal.integrated.defaultProfile.linux": "zsh"
}
}
},
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "20"
},
"ghcr.io/devcontainers/features/git:1": {}
},
"mounts": [

````bash
    "source=${localWorkspaceFolder},target=/workspace,type=bind",
    "source=claude-code-history,target=/home/vscode/.claude-history,type=volume"
    ],
    "postCreateCommand": "bash .devcontainer/init-firewall.sh",
    "remoteUser": "vscode"
}

### Dockerfile 配置

```dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

````

## 安装 Node.js 20

```dockerfile
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

```

## 安装开发工具

```dockerfile
RUN apt-get update && apt-get install -y \
    git \
    zsh \
    fzf \
    ripgrep \
    jq \
    curl \
    wget \
    vim \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

```

## 安装 Oh My Zsh

```dockerfile
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

```

## 配置 ZSH

```dockerfile
RUN echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && \
    echo 'export EDITOR="vim"' >> ~/.zshrc

```

## 创建非 root 用户

```dockerfile
RUN useradd -m -s /bin/zsh vscode && \
    echo "vscode ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

```

## 设置工作目录

```bash
WORKDIR /workspace

USER vscode

```

### 防火墙脚本 (init-firewall.sh)

#!/bin/bash
set -e

```bash
echo "配置开发容器防火墙..."
```

## 安装 iptables

```bash
sudo apt-get update
sudo apt-get install -y iptables
```

## 清除现有规则

```bash
sudo iptables -F
sudo iptables -X
sudo iptables -t nat -F
sudo iptables -t nat -X
```

## 默认策略：拒绝所有出站连接

```bash
sudo iptables -P OUTPUT DROP
```

## 允许本地回环

```bash
sudo iptables -A OUTPUT -o lo -j ACCEPT
```

## 允许已建立的连接

```bash
sudo iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
```

## 允许 DNS

```bash
sudo iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
```

## 允许 SSH

```bash
sudo iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
```

## 允许 HTTPS（白名单域名）

ALLOWED_DOMAINS=(
"api.anthropic.com"
"code.claude.com"
"github.com"
"npmjs.org"
"registry.npmjs.org"
"cdn.npmjs.org"
)
for domain in "${ALLOWED_DOMAINS[@]}"; do
ip=$(dig +short $domain | head -n 1)
if [ -n "$ip" ]; then

```bash
sudo iptables -A OUTPUT -d $ip -p tcp --dport 443 -j ACCEPT
echo "允许访问: $domain ($ip)"
fi
done
```

## 保存规则

```bash
sudo iptables-save > /etc/iptables/rules.v4
echo "防火墙配置完成"

```

## 34.1.4 企业级自定义配置

### 多环境配置

为不同的开发环境创建不同的配置文件：

.devcontainer/
├── devcontainer.json
├── Dockerfile
├── Dockerfile.dev
├── Dockerfile.staging
├── Dockerfile.prod
├── devcontainer.dev.json
├── devcontainer.staging.json
└── devcontainer.prod.json

**开发环境配置 (devcontainer.dev.json):**

{

"name": "Claude Code Dev Environment",
"dockerFile": "Dockerfile.dev",
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"github.copilot",
"eamodio.gitlens",
"ms-python.python"
]
}
},
"mounts": [

````bash
"source=${localWorkspaceFolder},target=/workspace,type=bind",
"source=dev-node-modules,target=/workspace/node_modules,type=volume"
],
"postCreateCommand": "npm install && npm run setup:dev"
}

**生产环境配置 (devcontainer.prod.json):**

{
  "name": "Claude Code Prod Environment",
  "dockerFile": "Dockerfile.prod",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-vscode.vscode-typescript-next"
      ]
    }
  },
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind"
  ],
  "postCreateCommand": "npm ci && npm run build"
}

### 企业级 Dockerfile

```dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

````

## 设置时区

```dockerfile
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

```

## 安装企业级工具

```dockerfile
RUN apt-get update && apt-get install -y \
    git \
    curl \
    wget \
    vim \
    jq \
    build-essential \
    python3 \
    python3-pip \
    openssl \
    gnupg \
    net-tools \
    iputils-ping \
    subversion \
    mercurial \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

```

## 安装 Node.js 20

```dockerfile
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

```

## 配置 npm 企业镜像

```dockerfile
RUN npm config set registry https://npm.company.com && \
    npm config set @company:registry https://npm.company.com

```

## 安装企业证书

```dockerfile
COPY company-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates

```

## 安装企业 CLI 工具

```dockerfile
RUN npm install -g @company/cli-tools

```

## 配置 Git

```dockerfile
RUN git config --global user.name "Company Developer" && \
    git config --global user.email "[email protected]" && \
    git config --global core.autocrlf input

```

## 安装 Oh My Zsh 和企业主题

```dockerfile
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended && \
    git clone https://github.com/company/zsh-theme.git ~/.oh-my-zsh/custom/themes/company

```

## 配置企业代理

```dockerfile
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080
ENV NO_PROXY=localhost,127.0.0.1,.company.com

```

## 创建用户

```dockerfile
RUN useradd -m -s /bin/zsh vscode && \
    echo "vscode ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

WORKDIR /workspace
USER vscode

```

## 配置企业环境变量

```dockerfile
RUN echo 'export COMPANY_ENV=production' >> ~/.zshrc && \
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

```

### 团队协作配置

**共享配置文件 (.devcontainer/shared-settings.json):**

{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.tabSize": 2,
"editor.insertSpaces": true,
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true,
"files.exclude": {
"**/.git": true,
"**/.DS_Store": true,
"**/node_modules": true,
"**/dist": true
},
"search.exclude": {
"**/node_modules": true,
"**/dist": true,
"\*\*/.git": true
},
"typescript.tsdk": "node_modules/typescript/lib",
"eslint.workingDirectories": ["./"]
}

**推荐扩展 (.vscode/extensions.json):**

{
"recommendations": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"eamodio.gitlens",
"ms-python.python",
"github.copilot",
"github.vscode-pull-request-github",
"redhat.vscode-yaml",
"ms-azuretools.vscode-docker"
]
}

## 34.1.5 安全增强配置

### 强化防火墙规则

#!/bin/bash

## .devcontainer/init-security.sh

set -e

```bash
echo "配置企业级安全防火墙..."

```

## 安装安全工具

```bash
sudo apt-get update
sudo apt-get install -y iptables fail2ban

```

## 配置 iptables

```bash
sudo iptables -F
sudo iptables -X
sudo iptables -t nat -F
sudo iptables -t nat -X

```

## 默认拒绝策略

```bash
sudo iptables -P INPUT DROP
sudo iptables -P FORWARD DROP
sudo iptables -P OUTPUT DROP

```

## 允许本地回环

```bash
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT

```

## 允许已建立的连接

```bash
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

```

## 允许 DNS

```bash
sudo iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

```

## 允许 SSH（仅从特定网络）

```bash
sudo iptables -A INPUT -p tcp -s 10.0.0.0/8 --dport 22 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT

```

## 企业白名单域名

declare -A ALLOWED_DOMAINS=(
["api.anthropic.com"]="443"
["code.claude.com"]="443"
["github.com"]="443"
["npm.company.com"]="443"
["git.company.com"]="443"
["artifacts.company.com"]="443"
)

for domain in "${!ALLOWED_DOMAINS[@]}"; do
    port=${ALLOWED_DOMAINS[$domain]}
ips=$(dig +short $domain)
for ip in $ips; do

```bash
        sudo iptables -A OUTPUT -d $ip -p tcp --dport $port -j ACCEPT
        echo "允许: $domain -> $ip:$port"
    done
done

```

## 阻止常见攻击端口

BLOCKED_PORTS=(23 135 137 138 139 445 1433 3389)
for port in "${BLOCKED_PORTS[@]}"; do

```bash
    sudo iptables -A OUTPUT -p tcp --dport $port -j DROP
    sudo iptables -A OUTPUT -p udp --dport $port -j DROP
done

```

## 保存规则

```bash
sudo iptables-save > /etc/iptables/rules.v4

```

## 配置 fail2ban

```bash
sudo cat > /etc/fail2ban/jail.local << 'EOF'
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 5

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
EOF

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

echo "安全配置完成"

```

### 文件系统权限配置

#!/bin/bash

## .devcontainer/init-permissions.sh

set -e

```bash
echo "配置文件系统权限..."

```

## 创建受限目录结构

```bash
sudo mkdir -p /workspace/``{src,tests,docs,scripts}``
sudo mkdir -p /workspace/.secrets

```

## 设置权限

```bash
sudo chown -R vscode:vscode /workspace
sudo chmod 755 /workspace/``{src,tests,docs,scripts}``
sudo chmod 700 /workspace/.secrets

```

## 配置 .gitignore

```bash
cat > /workspace/.gitignore << 'EOF'
## Secrets
.secrets/
*.key
*.pem
.env.local

## IDE
.vscode/
.idea/

## OS
.DS_Store
Thumbs.db

## Dependencies
node_modules/
EOF

```

## 配置敏感文件保护

```bash
sudo touch /workspace/.secrets/.gitkeep
sudo chmod 600 /workspace/.secrets/.gitkeep

echo "文件系统权限配置完成"

```

## 34.1.6 CI/CD 集成

### GitHub Actions 配置

```yaml
name: Dev Container CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Build dev container
        uses: devcontainers/[email protected]
        with:
          push: never
          imageName: ghcr.io/${{ github.repository }}/devcontainer
          cacheFrom: ghcr.io/${{ github.repository }}/devcontainer:latest

      - name: Run tests in dev container
        uses: devcontainers/[email protected]
        with:
          push: never
          imageName: ghcr.io/${{ github.repository }}/devcontainer
          runCmd: npm test
```

### GitLab CI 配置

stages:

- build
- test

variables:

```bash
  DEV_CONTAINER_IMAGE: $CI_REGISTRY_IMAGE/devcontainer:$CI_COMMIT_SHORT_SHA

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -f .devcontainer/Dockerfile -t $DEV_CONTAINER_IMAGE .
    - docker push $DEV_CONTAINER_IMAGE

test:
  stage: test
  image: $DEV_CONTAINER_IMAGE
  script:
    - npm install
    - npm test
    - npm run lint


```

## 34.1.7 监控和日志

### 容器健康检查

{
"name": "Claude Code Dev Container",
"dockerFile": "Dockerfile",
"healthCheck": {
"test": ["CMD", "curl", "-f", "http://localhost:3000/health"],
"interval": "30s",
"timeout": "10s",
"retries": 3,
"startPeriod": "40s"
}
}

### 日志配置

#!/bin/bash

## .devcontainer/init-logging.sh

## 创建日志目录

```bash
mkdir -p /workspace/logs

```

## 配置日志轮转

```bash
sudo cat > /etc/logrotate.d/devcontainer << 'EOF'
/workspace/logs/*.log {
  daily
  rotate 7
  compress
  delaycompress
  missingok
  notifempty
  create 0644 vscode vscode
}
EOF

```

## 配置应用日志

```bash
cat > /workspace/.env << 'EOF'
LOG_LEVEL=info
LOG_FILE=/workspace/logs/app.log
LOG_MAX_SIZE=10m
LOG_MAX_FILES=5
EOF

echo "日志配置完成"

```

## 34.1.8 最佳实践

### 1\. 版本控制

- 将所有配置文件纳入版本控制
- 使用 `.gitignore` 排除敏感信息
- 使用环境变量管理配置差异

### 2\. 文档化

- 为每个配置文件添加注释
- 创建 README 说明如何使用开发容器
- 记录常见问题和解决方案

### 3\. 安全性

- 定期更新基础镜像
- 使用最小权限原则
- 定期审计防火墙规则

### 4\. 性能优化

- 使用多阶段构建减小镜像大小
- 利用 Docker 缓存层
- 合理配置资源限制

### 5\. 团队协作

- 标准化配置文件
- 共享常用扩展和设置
- 建立配置审查流程

## 34.1.9 故障排查

### 常见问题

**问题 1：容器无法启动**

## 检查 Docker 状态

```bash
docker ps -a

```

## 查看容器日志

```bash
docker logs <container-id>

```

## 重新构建容器

## 在 VS Code 中: Remote-Containers: Rebuild Container

## 检查防火墙规则

```bash
sudo iptables -L -n -v

```

## 测试 DNS 解析

dig api.anthropic.com

## 检查代理配置

```bash
echo $HTTP_PROXY
echo $HTTPS_PROXY

```

**问题 2：网络连接问题**

## 检查容器网络配置

```bash
docker inspect <container-id> | grep -A 10 "NetworkSettings"

```

## 测试容器内网络

```bash
docker exec <container-id> ping -c 4 8.8.8.8

```

## 检查 DNS 配置

```bash
docker exec <container-id> cat /etc/resolv.conf

```

## 验证 HTTPS 连接

```bash
docker exec <container-id> curl -v https://api.anthropic.com

```

**问题 3：权限问题**

## 检查文件权限

ls -la /workspace

## 修复权限

```bash
sudo chown -R vscode:vscode /workspace

```

## 检查容器内用户

```bash
docker exec <container-id> whoami

```

## 检查挂载点权限

```bash
docker inspect <container-id> | grep -A 5 "Mounts"

```

**问题 4：扩展安装失败**

## 手动安装扩展

code --install-extension <extension-id>

## 检查扩展市场连接

```bash
curl -I https://marketplace.visualstudio.com

```

## 查看已安装扩展

code --list-extensions

## 检查扩展日志

tail -f ~/.vscode/extensions/.log

**问题 5：内存或 CPU 问题**

## 检查容器资源使用

```bash
docker stats <container-id>

```

## 增加 Docker Desktop 资源限制

## macOS: Docker Desktop > Preferences > Resources

## 检查容器内存限制

```bash
docker inspect <container-id> | grep -A 5 "Memory"

```

## 优化镜像大小

```bash
docker images | grep devcontainer


```