# DockerCraft

**Repository Path**: noahcbt/docker-craft

## Basic Information

- **Project Name**: DockerCraft
- **Description**: DockerCraft 是一个基于Web的云端Docker镜像构建平台，让开发者无需本地Docker环境即可通过浏览器快速将Dockerfile转换为完整的可部署镜像包。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-14
- **Last Updated**: 2025-11-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DockerCraft 🐳✨

**云端 Docker 镜像构建工坊 - 从 Dockerfile 到完整镜像包，一键搞定**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![React](https://img.shields.io/badge/React-18+-61dafb.svg)](https://reactjs.org/)
[![Docker](https://img.shields.io/badge/Docker-Required-2496ed.svg)](https://www.docker.com/)

## 🌟 项目简介

DockerCraft 是一个基于 Web 的云端 Docker 镜像构建服务，让开发者能够通过友好的界面快速将 Dockerfile 转换为完整的镜像包。无需本地 Docker 环境，即可获得可部署的镜像文件。

## ✨ 核心特性

### 🚀 便捷构建
- **Web 界面操作** - 无需命令行经验，可视化构建 Docker 镜像
- **多输入方式** - 支持文本编辑器直接编写或上传 Dockerfile 文件
- **实时进度** - WebSocket 实时推送构建日志，进度一目了然

### 📦 完整输出
- **多格式支持** - 输出 `.tar` 镜像文件 + 构建摘要文档
- **一键打包** - 自动打包为 ZIP 文件，包含完整部署材料
- **多架构构建** - 支持 `linux/amd64`, `linux/arm64` 等多平台架构

### 🛡️ 智能体验
- **智能错误诊断** - 构建失败时提供详细错误分析和修复建议
- **语法实时检查** - Dockerfile 语法验证和智能提示
- **构建历史** - 保存构建记录，方便追溯和重用

## 🏗️ 系统架构

```mermaid
graph TB
    A[Web前端] --> B[FastAPI后端]
    B --> C[构建任务队列]
    C --> D[Docker引擎]
    D --> E[镜像存储]
    B --> F[文件服务]
    E --> F
    F --> A
```

## 🚀 快速开始

### 环境要求

- Docker & Docker Compose
- Python 3.8+
- Node.js 16+

### 一键部署

```bash
# 克隆项目
git clone https://github.com/your-username/docker-craft.git
cd docker-craft

# 使用 Docker Compose 快速启动
docker-compose up -d

# 访问应用
open http://localhost:3000
```

### 本地开发

**后端服务**：
```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 启动开发服务器
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

**前端服务**：
```bash
cd frontend
npm install
npm run dev
```

## 📖 使用指南

### 基本构建流程

1. **输入 Dockerfile**
   - 在 Web 编辑器中编写或上传 Dockerfile
   - 实时语法检查和提示

2. **配置构建选项**
   ```yaml
   平台架构: linux/amd64, linux/arm64
   镜像名称: my-custom-image
   构建参数: KEY=VALUE
   ```

3. **开始构建**
   - 实时查看构建日志和进度
   - 智能错误诊断和提示

4. **下载结果**
   - 获取包含镜像文件和文档的 ZIP 包
   - 查看构建摘要和安全建议

### API 使用示例

```python
import requests

# 提交构建任务
response = requests.post("http://localhost:8000/api/build", json={
    "dockerfile": "FROM alpine:latest\nRUN echo 'Hello DockerCraft'",
    "platforms": ["linux/amd64"],
    "image_name": "hello-docker-craft"
})

# 获取实时日志
task_id = response.json()["task_id"]
logs = requests.get(f"http://localhost:8000/api/build/{task_id}/logs")
```

## 🗂️ 项目结构

```
docker-craft/
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── components/       # 可复用组件
│   │   ├── pages/           # 页面组件
│   │   └── services/        # API 服务
├── backend/                  # FastAPI 后端
│   ├── app/
│   │   ├── controllers/     # 路由控制器
│   │   ├── services/        # 业务逻辑
│   │   └── models/          # 数据模型
│   ├── storage/             # 文件存储
│   └── tests/               # 测试用例
├── infrastructure/          # 部署配置
│   ├── docker-compose.yml
│   └── nginx/
└── docs/                    # 项目文档
```

## 🔧 配置说明

### 环境变量配置

```bash
# 后端配置
DOCKER_REGISTRY_MIRROR=https://docker.xuanyuan.me
BUILD_TIMEOUT=1800
MAX_FILE_SIZE=1073741824

# 前端配置
VITE_API_BASE_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000
```

### Docker 镜像加速

在 `backend/config/settings.py` 中配置镜像加速器：

```python
REGISTRY_MIRRORS = [
    "https://docker.xuanyuan.me",
    "https://mirror.ccs.tencentyun.com"
]
```

## 🐛 故障排除

### 常见问题

**Q: 构建时出现网络超时错误**
A: 配置国内 Docker 镜像加速器，检查 `config/registry.py` 中的镜像源设置

**Q: 大镜像构建失败**
A: 调整 `BUILD_TIMEOUT` 环境变量，增加构建超时时间

**Q: 前端无法连接后端**
A: 检查 `VITE_API_BASE_URL` 配置，确保 CORS 设置正确

### 日志查看

```bash
# 查看服务日志
docker-compose logs backend
docker-compose logs frontend

# 查看构建任务日志
curl http://localhost:8000/api/build/{task_id}/logs
```

## 🤝 参与贡献

我们欢迎所有形式的贡献！请阅读 [贡献指南](CONTRIBUTING.md) 开始参与。

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🛣️ 开发路线图

- [ ] **v1.0** - 基础构建功能 (当前版本)
- [ ] **v1.1** - 多架构构建支持
- [ ] **v1.2** - 镜像安全扫描
- [ ] **v2.0** - 团队协作功能
- [ ] **v2.1** - CI/CD 流水线集成

## 📞 联系我们

- 项目主页：https://github.com/your-username/docker-craft
- 问题反馈：https://github.com/your-username/docker-craft/issues
- 邮箱：contact@docker-craft.dev

---

**DockerCraft** - 让 Docker 镜像构建像搭积木一样简单！ 🎉

*如果这个项目对你有帮助，请给我们一个 ⭐️ 支持！*