这是一个功能完整、生产级的 Docker 开发环境，支持多种编程语言、AI 开发工具和 DevContainer 规范。

• 🖥️ 浏览器开发: Code-Server (VS Code in browser)
• 🐳 Docker-in-Docker: 完全隔离的 Docker 环境（可选）
• 🔧 多语言支持: Node.js (NVM), Python, Go, Rust, Deno, Bun
• 🤖 AI 开发工具: Gemini, Claude, CodeBuddy, OpenCode
• 📦 DevContainer 支持: VSCode "Reopen in Container" 一键启动
• ⚡ 快捷命令: 一键导入仓库、快速切换项目、自动安装依赖
• 🔒 安全设计: 非 root 用户运行
• 🎯 配置提取: 从镜像提取默认配置，保持仓库干净

git clone <your-repo-url>
cd docker-dev-env

⚠️ 【必须】首次使用前必须执行以下两步：

# 步骤 1: 基础初始化（创建 .env 和目录结构）
make init

# 步骤 2: 【关键】从镜像提取默认配置（否则 AI CLI 工具会丢失！）
make init-config

# 步骤 3: 编辑配置
vim .env

为什么要执行 make init-config？

• Docker 卷挂载会覆盖容器内原有内容
• 如果不提取，镜像中预装的 AI CLI 工具（gemini、claude、codebuddy、opencode）会丢失

重点配置：

• CS_PASSWORD: Code-Server 登录密码
• GEMINI_API_KEY: Google Gemini API Key
• ANTHROPIC_API_KEY: Claude API Key
• CODEBUDDY_API_KEY: CodeBuddy API Key
• OPENAI_API_KEY: OpenAI API Key

make build

# 从镜像提取默认配置到 data/ 目录
make init-config

为什么需要这一步？

• data/ 目录包含 VS Code 配置、AI CLI 配置等
• 这些配置在镜像中预装了默认值
• 提取到本地后，配置将持久化保存
• 保持 Git 仓库干净（不提交用户数据）

make up

打开浏览器访问: http://localhost:8080

密码: .env 文件中设置的 CS_PASSWORD

---

进入容器后，可以使用以下快捷命令：

# 从 Git 仓库导入项目并自动安装依赖
dev-init-from https://github.com/user/project.git

# 指定本地目录名
dev-init-from https://github.com/user/project.git my-project

# 导入但跳过 LFS 文件（节省时间和空间）
dev-init-from-without-lfs https://github.com/large-files/repo.git

# 设置 LFS 大小限制（默认 100MB）
LFS_MAX_SIZE=256 dev-init-from https://github.com/large-files/repo.git

# 列出所有项目
dev-list

# 快速切换到项目
dev-switch project-name

# 显示环境信息
dev-info

# 启动静态文件服务器（默认端口 3000）
dev-serve

# 指定端口
dev-serve 8080

# 创建公网隧道（需要 cloudflared）
dev-tunnel 8080

# 格式化代码（自动检测项目类型）
dev-format

# 代码检查
dev-lint

# 清理未使用的 Docker 资源
dev-docker-clean

# 查看服务日志
dev-docker-logs [service-name]

# 完整备份开发环境
dev-backup

# 指定备份名称
dev-backup my-backup

# 恢复备份
dev-restore backups/dev-backup-20250215_120000.tar.gz

# 显示所有快捷命令
dev-help

---

语言	版本	说明
Node.js	v22 (默认)	通过 NVM 安装，可切换版本
Python	3.12	系统级安装
Go	1.23	系统级安装
Rust	1.93	通过 rustup 安装
Deno	2.6+	系统级安装
Bun	1.3+	系统级安装

基础工具（Ubuntu 系统 + 微软基础镜像）：

• git + git-lfs          # 版本控制
• zsh + oh-my-zsh       # Shell（已配置插件）
• openssh-server        # SSH 服务端
• openssh-client        # SSH 客户端
• rsync                 # 文件同步
• curl + wget           # 下载工具
• vim + nano            # 文本编辑器
• jq                    # JSON 处理

额外安装工具：

• pnpm                  # 包管理器（Node.js）
• fzf                   # 模糊搜索
• ripgrep               # 代码搜索（rg）
• fd-find               # 文件查找（fd）
• bat                   # 语法高亮 cat
• eza                   # 现代 ls
• tree                  # 目录树
• htop                  # 系统监控
• unzip + p7zip-full    # 解压工具
• net-tools             # 网络工具（ifconfig 等）

gemini          # Google Gemini CLI
claude          # Anthropic Claude Code
codebuddy       # 腾讯 CodeBuddy
opencode        # OpenCode AI

使用方法:

# 进入容器
make enter

# 登录 AI 工具
gemini login
claude login
codebuddy login
opencode login

---

make init              # 基础初始化（创建 .env 和目录结构）
make init-config       # ⚠️ 从镜像提取默认配置（首次运行前【必须】执行）
make init-config-force # 强制重新提取配置（覆盖现有配置）

make build             # 构建镜像
make build-no-cache    # 重新构建（无缓存）
make up                # 启动环境（后台）
make up-fg             # 启动环境（前台，查看日志）
make down              # 停止环境
make restart           # 重启环境

make logs              # 查看所有日志
make logs-dev          # 查看开发环境日志
make enter             # 进入容器 shell（zsh）
make enter-root        # 以 root 身份进入容器
make status            # 查看容器状态
make health            # 检查健康状态

make versions          # 查看所有语言版本
make python            # 进入 Python 交互式环境
make node              # 查看 Node.js 版本信息
go                     # 查看 Go 版本
rust                   # 查看 Rust 版本
deno                   # 查看 Deno 版本
bun                    # 查看 Bun 版本

make clean             # 停止并删除容器
make clean-all         # 完全清理（包括镜像和数据卷）
make backup            # 完整备份开发环境配置
make restore           # 查看可用备份
make restore-file      # 恢复指定备份 (用法: make restore-file BACKUP_FILE=backups/xxx.tar.gz)
make update            # 更新镜像（拉取最新基础镜像）

---

docker-dev-env/
├── .devcontainer/           # DevContainer 配置
│   └── devcontainer.json
├── data/                    # 持久化配置（首次需运行 make init-config）
│   ├── code-server/         # VS Code 配置和扩展
│   ├── config/              # AI CLI 和工具配置
│   └── pnpm-store/          # pnpm 包缓存
├── workspace/               # 你的项目代码 (可通过 .env 中的 WORKSPACE_PATH 配置)
├── backups/                 # 配置备份
├── scripts/                 # 辅助脚本
│   ├── init.sh              # 基础初始化
│   ├── dev-init-config.sh   # 配置提取
│   ├── dev-init-from        # 一键导入仓库
│   ├── dev-commands.sh      # 快捷命令集合
│   ├── dev-welcome.sh       # 欢迎页面
│   ├── dev-backup.sh        # 完整备份功能
│   └── dev-restore.sh       # 恢复功能
├── .env                     # 环境变量配置
├── docker-compose.yaml      # Docker Compose 配置
├── Dockerfile               # 镜像构建文件
├── entrypoint.sh            # 容器启动脚本
├── Makefile                 # 便捷命令
└── README.md                # 本文档

⚠️ 【重要】首次使用前必须执行此步骤！

如果跳过此步骤，会导致以下致命问题：

• AI CLI 工具（gemini、claude、codebuddy、opencode）丢失
• VS Code 配置和扩展丢失
• pnpm 全局包缓存丢失

执行命令：

make init-config

以下数据会持久化保存：

• ./workspace - 你的项目代码 (可通过 .env 中的 WORKSPACE_PATH 配置)
• ./data/code-server - VS Code 设置和扩展
• ./data/config - 工具配置（Git、AI CLI 登录状态等）
• ./data/pnpm-store - pnpm 全局包缓存

注意: 编程语言环境（Node.js、Python、Go、Rust 等）已预装在 Docker 镜像中，重启容器不会丢失。

---

本项目完整支持 VSCode DevContainer：

1. 在 VSCode 中安装 "Dev Containers" 扩展
2. 打开项目文件夹
3. 按 Ctrl+Shift+P，选择 "Dev Containers: Reopen in Container"
4. 自动构建并进入开发环境

• 直接在浏览器中打开开发环境
• 无需本地安装 Docker

---

# 备份所有配置（VSCode、AI CLI 配置、项目文件等）
make backup

备份内容包含：

• data/code-server/ - VS Code 配置和扩展
• data/config/ - AI CLI 和工具配置
• workspace/ - 项目代码 (通过 WORKSPACE_PATH 配置)

# 查看可用备份
make restore

# 恢复指定备份
make restore-file BACKUP_FILE=backups/dev-backup-20250215_120000.tar.gz

---

如需在容器内使用 Docker，取消 docker-compose.yaml 中 DinD 部分的注释：

# 取消注释以下部分启用 DinD
docker:
  image: docker:24-dind
  privileged: true

然后重启环境：

make down
make up

在容器内使用 Docker：

docker ps
docker build -t myapp .
docker run -d myapp

---

编辑 .devcontainer/devcontainer.json：

"customizations": {
    "vscode": {
        "extensions": [
            "your.extension.here"
        ]
    }
}

编辑 Dockerfile：

RUN apt-get update && apt-get install -y \
    your-package \
    && rm -rf /var/lib/apt/lists/*

在 .env 中设置：

WELCOME_CMD="git config --global user.name 'Your Name' && git config --global user.email 'your@email.com'"

---

编辑 .env：

CS_PASSWORD=your_secure_password

重启生效：

make restart

推荐方式（环境变量）：

1. 在 .env 中设置 API Keys
2. 启动时自动加载到容器

替代方式（手动登录）：

make enter
gemini login
claude login

---

make enter
sudo chown -R vscode:vscode /workspace
sudo chown -R vscode:vscode ~/.local/share/code-server

# 确保镜像已构建
make build

# 强制重新提取
make init-config-force

# 查看详细日志
make logs

# 检查端口占用
lsof -i :8080

# 查看容器状态
make status
make health

# 进入容器
make enter

# 检查工具是否安装
which gemini claude codebuddy opencode

# 手动登录
gemini login

---

• ✨ 新增 dev-init-from 一键导入仓库命令
• ✨ 新增快捷命令集合（dev-list, dev-switch, dev-serve 等）
• ✨ 新增自动欢迎页面（登录终端自动显示）
• ✨ 新增配置提取脚本（make init-config）
• 🔧 优化镜像大小（4.51GB）
• 🔧 使用系统 Python 替代 Miniforge
• 🔧 清理 data/ 目录结构

• ✨ 初始版本发布
• 🐳 支持 Docker-in-Docker
• 🤖 集成 AI CLI 工具
• 📦 支持 DevContainer 规范
• 🔧 多语言开发环境

---

欢迎提交 Issue 和 Pull Request！

MIT License

• Code-Server
• Dev Containers
• Microsoft Dev Containers
• Cloud Native Build (CNB) - 灵感来源