Claude Code DevContainer与远程开发实战

效率 vs 安全
    ├── 高效模式：--dangerously-skip-permissions
    │     └── Claude 自由执行所有操作，无需逐一确认
    │     └── 风险：可能误删文件、修改系统配置、泄露敏感信息
    │
    └── 安全模式：逐条审批
          └── 每次文件编辑、命令执行都需手动确认
          └── 代价：流程严重断裂，实际不可用

graph TB
    subgraph 宿主机["🖥️ 宿主机（你的电脑）"]
        A["文件系统 - 完全隔离"]
        B["网络 - 可控白名单"]
        C["进程 - 容器内可见"]
        D["Secrets - 按需挂载"]
    end

    subgraph 容器["🐳 容器（Claude Code 运行环境）"]
        E["项目代码 - 挂载卷"]
        F["开发工具 - 预装"]
        G["Claude Code - 自主运行"]
        H["运行时依赖 - 全部包含"]
    end

    E -.->|"只读/读写"| A
    G -->|"无法突破"| 宿主机

    style 宿主机 fill:#e8f5e9
    style 容器 fill:#fff3e0

# Dockerfile.claude
FROM node:20-bookworm

# 安装基础开发工具
RUN apt-get update && apt-get install -y \
    git \
    curl \
    jq \
    ripgrep \
    bash-completion \
    && rm -rf /var/lib/apt/lists/*

# 安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 创建非 root 用户（安全最佳实践）
RUN useradd -m -s /bin/bash developer
USER developer
WORKDIR /home/developer/workspace

# 设置环境变量
ENV NODE_OPTIONS="--max-old-space-size=4096"

ENTRYPOINT ["claude"]

# 构建镜像
docker build -t claude-sandbox -f Dockerfile.claude .

# 基础运行（交互模式）
docker run -it --rm \
  -v $(pwd):/home/developer/workspace \
  -e ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} \
  claude-sandbox

# 高级运行（跳过权限确认 + 资源限制）
docker run -it --rm \
  -v $(pwd):/home/developer/workspace \
  -e ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} \
  --memory=8g \
  --cpus=4 \
  --network=none \
  claude-sandbox \
  --dangerously-skip-permissions

#!/bin/bash
# run-claude-sandbox.sh

NETWORK_NAME="claude-net"

# 创建受限网络
docker network create \
  --driver bridge \
  --subnet 172.28.0.0/16 \
  $NETWORK_NAME 2>/dev/null || true

# 运行容器
docker run -it --rm \
  --network $NETWORK_NAME \
  -v $(pwd):/home/developer/workspace \
  -e ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} \
  --memory=8g \
  --cpus=4 \
  claude-sandbox \
  --dangerously-skip-permissions

# 在 Dockerfile 中（需要 root 权限）
RUN apt-get install -y iptables

# 在 entrypoint 脚本中
COPY entrypoint.sh /entrypoint.sh

#!/bin/bash
# entrypoint.sh — 网络白名单

# 仅允许 HTTPS 出站（npm install、git push 等）
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 80 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT   # git SSH
iptables -A OUTPUT -j DROP

# 切换到非 root 用户执行 Claude Code
exec gosu developer claude --dangerously-skip-permissions

my-project/
├── .devcontainer/
│   ├── devcontainer.json      # 主配置文件
│   ├── Dockerfile             # 自定义镜像（可选）
│   ├── docker-compose.yml     # 多服务编排（可选）
│   ├── post-create.sh         # 容器创建后执行脚本
│   └── claude-settings.json   # Claude Code 项目配置
├── src/
├── package.json
└── README.md

// .devcontainer/devcontainer.json
{
  "name": "Claude Code Dev Environment",
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      "NODE_VERSION": "20"
    }
  },

  // 挂载卷：仅项目目录 + 有限的宿主机资源
  "mounts": [
    "source=claude-node-modules,target=/workspace/node_modules,type=volume",
    "source=claude-cache,target=/home/developer/.claude,type=volume"
  ],

  // 环境变量
  "remoteEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  },

  // 容器设置
  "containerEnv": {
    "NODE_OPTIONS": "--max-old-space-size=4096"
  },

  // VS Code 扩展（预装）
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ],
      "settings": {
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  },

  // 容器创建后执行的脚本
  "postCreateCommand": "bash .devcontainer/post-create.sh",

  // 以非 root 用户运行
  "remoteUser": "developer",

  // 功能扩展（可选）
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },

  // 安全相关
  "runArgs": [
    "--memory=8g",
    "--cpus=4"
  ]
}

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/base:bookworm

ARG NODE_VERSION=20

# 安装 Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - \
    && apt-get install -y nodejs

# 安装 Claude Code 和常用全局工具
RUN npm install -g \
    @anthropic-ai/claude-code \
    typescript \
    ts-node \
    @types/node

# 创建工作目录
RUN mkdir -p /workspace && chown vscode:vscode /workspace
WORKDIR /workspace

# 配置 Claude Code 安全默认值
USER vscode
RUN mkdir -p /home/vscode/.claude

#!/bin/bash
# .devcontainer/post-create.sh

set -e

echo "🚀 初始化开发环境..."

# 安装项目依赖
if [ -f "package.json" ]; then
    npm install
fi

# 配置 Claude Code 项目设置
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Read",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(curl|wget).*http://internal.*"
    ]
  }
}
EOF

echo "✅ 环境初始化完成"
echo "💡 运行 'claude' 开始使用 Claude Code"

# .devcontainer/docker-compose.yml
version: '3.8'

services:
  # 主开发容器
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
      - claude-cache:/home/developer/.claude
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://dev:dev@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    mem_limit: 8g
    cpus: 4

  # PostgreSQL 数据库
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: myapp
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Redis 缓存
  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  claude-cache:
  postgres-data:
  redis-data:

{
  "name": "Claude Code Full Stack",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "postCreateCommand": "bash .devcontainer/post-create.sh",
  "remoteUser": "developer"
}

# 方式 1：VS Code 命令面板（推荐）
# Ctrl+Shift+P → "Dev Containers: Reopen in Container"

# 方式 2：CLI 直接打开
code --remote devcontainer=./path/to/project /workspace

# 方式 3：从终端手动构建并进入
cd my-project
docker compose -f .devcontainer/docker-compose.yml build
docker compose -f .devcontainer/docker-compose.yml run app claude

#!/bin/bash
# setup-remote-server.sh — 在远程服务器上执行

# 1. 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

# 2. 安装 Claude Code
sudo npm install -g @anthropic-ai/claude-code

# 3. 安装 tmux（会话保持）
sudo apt-get install -y tmux

# 4. 创建工作目录
mkdir -p ~/projects && cd ~/projects

# 5. 配置 Claude Code 认证（使用 API Key）
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

echo "✅ 远程开发环境就绪"

# 在远程服务器上创建 tmux 会话
tmux new-session -s claude-dev -d -c ~/projects/my-project

# 在 tmux 会话中启动 Claude Code
tmux send-keys -t claude-dev 'claude --dangerously-skip-permissions' Enter

# 从本地 SSH 附着到会话
ssh -t your-server 'tmux attach -t claude-dev'

# Ctrl+B, D — 分离会话（Claude Code 继续运行）
# 再次连接时，所有上下文完好无损

# ~/.ssh/config
Host claude-dev
    HostName your-server-ip
    User developer
    IdentityFile ~/.ssh/id_ed25519
    ForwardAgent yes
    # 保持连接
    ServerAliveInterval 60
    ServerAliveCountMax 3
    # 复用连接（加速重连）
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

mkdir -p ~/.ssh/sockets

ssh claude-dev              # 一键连接
tmux attach -t claude-dev   # 恢复 Claude Code 会话

# 在远程服务器上
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 在本地机器上
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# 现在可以通过 Tailscale IP 直连（无需公网暴露）
ssh [email protected]

sequenceDiagram
    participant 本地终端
    participant Claude服务器
    participant 远程服务器
    participant 手机

    本地终端->>Claude服务器: 启动会话，建立加密隧道
    本地终端->>Claude服务器: 对话进行中...

    Note over 本地终端,远程服务器: 需要离开电脑
    本地终端->>Claude服务器: 发起 Remote Control
    Claude服务器-->>远程服务器: E2E 加密隧道建立

    手机->>远程服务器: SSH + tmux attach
    远程服务器->>Claude服务器: 继续同一会话
    Note over 手机,Claude服务器: 上下文完整保留

    手机->>Claude服务器: "继续重构 API 模块"
    Claude服务器-->>手机: 已了解之前的所有改动

# 在本地终端中，Claude Code 会话内输入
> /remote-control

# 系统会生成一个同步码，例如：
# 🔗 Remote Control 已启用
# 同步码: ABCD-EFGH-IJKL-MNOP
# 在任何终端输入以下命令连接此会话：
#   claude --remote-control ABCD-EFGH-IJKL-MNOP

# 在远程服务器上连接
ssh your-server
claude --remote-control ABCD-EFGH-IJKL-MNOP

# 场景：在公司开始工作，回家继续

# 上午 9:00 — 公司电脑
cd ~/projects/my-app
claude                          # 启动 Claude Code
# ... 进行大量代码编辑和讨论 ...
/remote-control                 # 准备下班，启用远程控制

# 晚上 8:00 — 家里电脑
ssh home-server
claude --remote-control XXXX-XXXX-XXXX-XXXX
# 完整的上下文、文件状态、对话历史全部恢复
# 继续说"接着下午的 API 重构继续"

mkdir -p my-app/.devcontainer
cd my-app

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/typescript-node:20

# 安装额外工具
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# 全局安装 Claude Code
RUN npm install -g @anthropic-ai/claude-code

# 配置 Claude Code 默认设置
USER node
RUN mkdir -p /home/node/.claude
COPY --chown=node:node claude-claude.md /home/node/.claude/CLAUDE.md

WORKDIR /workspace

<!-- .devcontainer/claude-claude.md -->
# 项目规则

## 技术栈
- Next.js 14 App Router
- TypeScript 严格模式
- PostgreSQL (通过 Prisma ORM)
- Redis (通过 ioredis)

## 代码规范
- 使用函数式组件和 hooks
- 所有 API 路由需要错误处理
- 数据库查询使用 Prisma Client
- 测试使用 Vitest

## 目录结构
- src/app/ — 页面和 API 路由
- src/components/ — React 组件
- src/lib/ — 工具函数和配置
- prisma/ — 数据库 schema 和迁移

## 开发命令
- npm run dev — 启动开发服务器
- npm run build — 生产构建
- npm run test — 运行测试
- npx prisma migrate dev — 数据库迁移

# .devcontainer/docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ..:/workspace:cached
      - node-modules:/workspace/node_modules
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://dev:dev@db:5432/myapp
      - REDIS_URL=redis://redis:6379
      - NEXTAUTH_SECRET=dev-secret-change-in-prod
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
    command: sleep infinity  # 保持容器运行
    mem_limit: 8g
    cpus: 4

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: myapp
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev -d myapp"]
      interval: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  node-modules:
  postgres-data:
  redis-data:

#!/bin/bash
# .devcontainer/post-create.sh
set -e

echo "🚀 初始化全栈开发环境..."

# 安装依赖
npm install

# 数据库迁移
npx prisma generate
npx prisma migrate dev --name init

# 验证服务
echo "检查 PostgreSQL 连接..."
pg_isready -h db -U dev -d myapp && echo "✅ PostgreSQL 就绪"

echo "检查 Redis 连接..."
redis-cli -h redis ping && echo "✅ Redis 就绪"

echo ""
echo "======================================="
echo "  环境就绪！运行以下命令开始开发："
echo "  claude    # 启动 Claude Code"
echo "  npm run dev  # 启动开发服务器"
echo "======================================="

# Step 1: 在 VS Code 中打开项目
code my-app

# Step 2: 重新在容器中打开
# Ctrl+Shift+P → "Dev Containers: Reopen in Container"
# 等待构建完成（首次约 3-5 分钟）

# Step 3: 在容器终端中启动 Claude Code
claude --dangerously-skip-permissions

# Step 4: 让 Claude 帮你创建完整项目
> 请根据 CLAUDE.md 中的规范，创建 Next.js 全栈应用的基础结构，
> 包含用户认证模块和 CRUD API

# 服务器上：启动 tmux 会话
tmux new -s dev -d
tmux send-keys -t dev 'claude --dangerously-skip-permissions' Enter

# 手机上：使用 claude-term 等 SSH 终端 app
ssh your-server
tmux attach -t dev
# 在手机上直接给 Claude 下达指令

graph LR
    subgraph 外部访问
        A[开发者终端]
        B[手机/平板]
    end

    subgraph 网络层
        C[Tailscale VPN]
        D[SSH 密钥认证]
    end

    subgraph 隔离层
        E[Docker 网络命名空间]
        F[iptables 白名单]
        G[只读文件系统挂载]
    end

    subgraph 运行时
        H[Claude Code 容器]
        I[非 root 用户]
        J[资源限制 cgroup]
    end

    subgraph 审计层
        K[会话日志]
        L[文件变更追踪]
        M[网络请求记录]
    end

    A --> C --> E --> H
    B --> D --> E
    H --> K
    H --> L
    H --> M

#!/bin/bash
# security-audit.sh — 在容器中运行的安全审计

echo "🔒 Claude Code 容器安全审计"
echo "=============================="

# 检查 1: 非 root 运行
echo -n "1. 非 root 用户: "
if [ "$(id -u)" != "0" ]; then
    echo "✅ PASS (uid=$(id -u))"
else
    echo "❌ FAIL — 不要以 root 运行"
fi

# 检查 2: 无宿主机敏感文件挂载
echo -n "2. 敏感目录隔离: "
if ! mount | grep -qE '(home|etc|root)/'; then
    echo "✅ PASS"
else
    echo "⚠️  WARNING — 检测到宿主机目录挂载"
    mount | grep -E '(home|etc|root)/'
fi

# 检查 3: 网络限制
echo -n "3. 网络限制: "
if ! curl -s --connect-timeout 2 http://169.254.169.254 > /dev/null 2>&1; then
    echo "✅ PASS (云元数据不可达)"
else
    echo "❌ FAIL — 云元数据端点可达，存在凭证泄露风险"
fi

# 检查 4: 资源限制
echo -n "4. 内存限制: "
if [ -f /sys/fs/cgroup/memory.max ]; then
    cat /sys/fs/cgroup/memory.max
else
    echo "⚠️  未设置 cgroup 内存限制"
fi

# 检查 5: 环境变量中无明文密钥
echo -n "5. 环境变量安全: "
if env | grep -qiE '(password|secret|token).*=.{8,}'; then
    echo "⚠️  WARNING — 检测到可能的环境变量泄露"
else
    echo "✅ PASS"
fi

echo ""
echo "审计完成"

graph TD
    START[选择远程开发方案] --> Q1{团队规模?}
Q1 --> |＞ 个人开发者| Q2{需要 GPU?}
Q1 --> |＞ 团队| DEV[DevContainer 方案<br/>标准化 + 版本控制]

    Q2 -->|是| CLOUD[SSH 远程服务器<br/>GPU 云实例]
    Q2 -->|否| Q3{项目复杂度?}

    Q3 -->|简单| DOCKER[Docker 沙箱<br/>快速隔离]
    Q3 -->|复杂| Q4{需要数据库等<br/>外部服务?}

    Q4 -->|是| DEV
    Q4 -->|否| DOCKER

    style START fill:#e3f2fd
    style DEV fill:#c8e6c9
    style DOCKER fill:#fff9c4
    style CLOUD fill:#f8bbd0

flowchart TB
    subgraph 本地["💻 本地开发"]
        A[编写 .devcontainer/ 配置] --> B[git commit & push]
        B --> C[VS Code Reopen in Container]
    end

    subgraph 容器["🐳 容器环境"]
        C --> D[自动构建镜像]
        D --> E[启动 PostgreSQL + Redis]
        E --> F[执行 post-create.sh]
        F --> G["启动 Claude Code<br/>--dangerously-skip-permissions"]
    end

    subgraph AI["🤖 AI 辅助开发"]
        G --> H[阅读 CLAUDE.md 项目规则]
        H --> I[理解代码库结构]
        I --> J[执行开发任务]
        J --> K{任务完成?}
        K -->|否| I
        K -->|是| L[生成测试 + 文档]
    end

    subgraph 远程["🌐 远程访问"]
        G -.->|Remote Control| M[手机/平板 SSH]
        G -.->|tmux detach| N[断开不中断]
        N -.->|tmux attach| O[恢复会话]
    end

    L --> P[git commit]
    P --> Q[CI/CD 流水线]

    style 本地 fill:#e8f5e9
    style 容器 fill:#fff3e0
    style AI fill:#e3f2fd
    style 远程 fill:#f3e5f5