aioful/mirror/dev-env

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

fix: 修复 CNB 构建配置

.devcontainer
data
scripts
.cnb.yml
.dockerignore
.env.example
.gitignore
Dockerfile
Makefile
README.md
docker-compose.yaml
entrypoint.sh

🚀 Ultimate Docker Development Environment

这是一个功能完整、生产级的 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 用户运行
🎯 配置提取: 从镜像提取默认配置，保持仓库干净

🚀 快速开始

1. 克隆项目

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

2. 初始化环境

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

# 步骤 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

3. 构建镜像

make build

4. 提取默认配置（⚠️ 关键步骤）

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

为什么需要这一步？

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

5. 启动环境

make up

6. 访问开发环境

打开浏览器访问: 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 辅助

# 清理未使用的 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 等）

AI CLI 工具

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 命令参考

初始化和配置

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 镜像中，重启容器不会丢失。

🔧 DevContainer 支持

本项目完整支持 VSCode DevContainer：

本地开发

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

GitHub Codespaces

直接在浏览器中打开开发环境
无需本地安装 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-in-Docker（可选）

如需在容器内使用 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

🎨 自定义配置

添加 VSCode 扩展

编辑 .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'"

🔐 安全配置

修改 Code-Server 密码

编辑 .env：

CS_PASSWORD=your_secure_password

重启生效：

make restart

API Keys 配置

推荐方式（环境变量）：

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

替代方式（手动登录）：

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

AI CLI 工具无法使用

# 进入容器
make enter

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

# 手动登录
gemini login

📝 更新日志

v1.1.0 (2025-02-15)

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

v1.0.0 (2025-02-15)

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

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

About

🚀 功能完整的 Docker 开发环境，支持 Code-Server 浏览器开发、多语言运行时（Node.js/Python/Go/Rust/Deno/Bun）、AI CLI 工具（Gemini/Claude/CodeBuddy/OpenCode）和 DevContainer 规范。一键导入仓库、自动安装依赖、配置持久化保存。

dockerdevcontainercode-servernodejspythongolangclaude-codeopencodegemini-clicodebuddy

356.00 KiB