diff --git a/README.md b/README.md new file mode 100644 index 0000000..01f5b33 --- /dev/null +++ b/README.md @@ -0,0 +1,373 @@ +# RunBin + +RunBin 是一个在线代码执行和分享平台,支持多种编程语言的代码运行、编译和结果展示。 + +## ✨ 功能特性 + +- 🚀 在线代码执行 - 支持多种编程语言的代码运行 +- 📝 代码分享 - 通过唯一 ID 分享代码片段 +- 🐳 Docker 隔离 - 使用 Docker 容器保证代码执行安全 +- 💾 灵活存储 - 支持内存和数据库两种存储方式 +- 🔄 异步处理 - Worker 进程异步处理代码执行任务 +- 📊 性能统计 - 记录执行时间和内存使用情况 +- 🌐 Web 界面 - 现代化的前端界面,支持代码编辑器 + +## 🏗️ 架构 + +项目采用前后端分离架构: + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ │ │ │ │ │ +│ Web 前端 │─────▶│ API 服务 │─────▶│ PostgreSQL │ +│ (Vue 3) │ │ (Gin) │ │ 数据库 │ +│ │ │ │ │ │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ + │ + ▼ + ┌─────────────┐ ┌─────────────┐ + │ │ │ │ + │ Worker │─────▶│ Docker │ + │ 服务 │ │ 运行环境 │ + │ │ │ │ + └─────────────┘ └─────────────┘ +``` + +### 组件说明 + +- **Web 前端**: 基于 Vue 3 + Vite 的现代化前端应用 +- **API 服务**: 使用 Gin 框架构建的 RESTful API 服务 +- **Worker 服务**: 后台任务处理服务,负责执行用户提交的代码 +- **PostgreSQL**: 持久化存储代码和执行结果 +- **Docker**: 提供安全的代码执行环境 + +## 📋 前置要求 + +- Go 1.24.2 或更高版本 +- Docker 和 Docker daemon +- PostgreSQL 数据库(可选,用于生产环境) +- Node.js 和 npm(用于前端开发) + +## 🚀 快速开始 + +### 1. 克隆项目 + +```bash +git clone https://github.com/dreamstarsky/runbin.git +cd runbin +``` + +### 2. 安装依赖 + +```bash +# 安装 Go 依赖 +go mod download + +# 安装前端依赖 +cd web +npm install +cd .. +``` + +### 3. 配置数据库(可选) + +如果使用数据库存储,需要先创建数据库并运行迁移: + +```bash +# 创建数据库 +createdb runbin + +# 运行迁移 +psql -d runbin -f migrations/0001_init_pastes.sql +psql -d runbin -f migrations/0002_create_queue_table.sql +psql -d runbin -f migrations/0003_add_compilelog_column.sql +``` + +### 4. 配置服务 + +编辑配置文件: + +#### API 服务配置 (`config/api.yaml`) + +```yaml +app: + env: "release" # release or debug + port: 8080 + +storage: + type: "database" # memory or database + database: + dsn: "host=localhost port=5432 user=postgres password=password dbname=runbin sslmode=disable" +``` + +#### Worker 服务配置 (`config/worker.yaml`) + +```yaml +storage: + type: "database" + database: + dsn: "host=localhost port=5432 user=postgres password=password dbname=runbin sslmode=disable" + +limit: + time: 10.0 # 最大执行时间(秒) + cpu: 1.0 # CPU 限制 + memory: 512 # 内存限制(MB) + size: 1024000 # 输出大小限制(字节) + +process: 1 # Worker 进程数 + +name: "default name" + +compilerimage: "cpp_gcc-latest:latest" # 编译器镜像 +``` + +### 5. 启动服务 + +#### 启动 API 服务 + +```bash +go run cmd/api/main.go +``` + +API 服务将在 `http://localhost:8080` 上运行。 + +#### 启动 Worker 服务 + +```bash +go run cmd/worker/main.go +``` + +#### 启动前端开发服务器 + +```bash +cd web +npm run dev +``` + +前端将在 `http://localhost:5173` 上运行。 + +## 🐳 Docker 部署 + +### 构建镜像 + +```bash +# 构建 API 和 Worker 镜像 +docker build -t runbin-api -f Dockerfile.api . +docker build -t runbin-worker -f Dockerfile.worker . + +# 构建前端镜像 +cd web +docker build -t runbin-web . +``` + +### 使用 Docker Compose + +创建 `docker-compose.yml`: + +```yaml +version: '3.8' + +services: + postgres: + image: postgres:15 + environment: + POSTGRES_DB: runbin + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + + api: + image: runbin-api + ports: + - "8080:8080" + depends_on: + - postgres + environment: + DATABASE_DSN: "host=postgres port=5432 user=postgres password=password dbname=runbin sslmode=disable" + + worker: + image: runbin-worker + depends_on: + - postgres + - api + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + DATABASE_DSN: "host=postgres port=5432 user=postgres password=password dbname=runbin sslmode=disable" + + web: + image: runbin-web + ports: + - "80:80" + environment: + BACKEND_URL: "http://localhost:8080" + +volumes: + postgres_data: +``` + +启动所有服务: + +```bash +docker-compose up -d +``` + +## 📡 API 文档 + +### 提交代码 + +```http +POST /api/pastes +Content-Type: application/json + +{ + "code": "your code here", + "language": "cpp", + "stdin": "input data", + "run": true +} +``` + +响应: + +```json +{ + "id": "uuid-string", + "message": "Paste created successfully" +} +``` + +### 获取代码结果 + +```http +GET /api/pastes/:id +``` + +响应: + +```json +{ + "id": "uuid-string", + "code": "your code here", + "language": "cpp", + "stdin": "input data", + "stdout": "program output", + "stderr": "error output", + "status": "completed", + "compile_log": "compilation output", + "execution_time_ms": 100, + "memory_usage_kb": 1024, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:01Z", + "backend": "worker-name" +} +``` + +### 获取支持的语言列表 + +```http +GET /api/languages +``` + +响应: + +```json +{ + "languages": ["cpp", "python", "java", "go"] +} +``` + +## 🗂️ 项目结构 + +``` +. +├── cmd/ +│ ├── api/ # API 服务入口 +│ └── worker/ # Worker 服务入口 +├── config/ # 配置文件 +│ ├── api.yaml +│ └── worker.yaml +├── internal/ +│ ├── config/ # 配置加载 +│ ├── controller/ # 控制器层 +│ ├── model/ # 数据模型 +│ ├── repository/ # 数据访问层 +│ ├── router/ # 路由配置 +│ └── worker/ # Worker 任务处理 +├── migrations/ # 数据库迁移文件 +├── web/ # 前端应用 +│ ├── src/ # 源代码 +│ ├── public/ # 静态资源 +│ └── dist/ # 构建输出 +├── workerEnv/ # Worker 环境配置 +├── go.mod # Go 模块定义 +└── LICENSE # Apache 2.0 许可证 +``` + +## 🔧 开发指南 + +### 添加新的编程语言支持 + +1. 在 Worker 中添加新的任务处理器(参考 `internal/worker/RunCppTask.go`) +2. 准备相应的 Docker 镜像 +3. 在 `worker.yaml` 中配置编译器镜像 +4. 在控制器中更新支持的语言列表 + +### 本地开发 + +```bash +# 启动开发模式 API +go run cmd/api/main.go + +# 启动开发模式 Worker +go run cmd/worker/main.go + +# 启动前端热重载 +cd web && npm run dev +``` + +### 构建生产版本 + +```bash +# 构建 API +go build -o bin/api cmd/api/main.go + +# 构建 Worker +go build -o bin/worker cmd/worker/main.go + +# 构建前端 +cd web && npm run build +``` + +## 🔒 安全性 + +- 所有代码在 Docker 容器中执行,与主机隔离 +- 配置了资源限制(CPU、内存、执行时间) +- 支持输出大小限制,防止恶意代码 +- CORS 配置保护 API 访问 + +## 🤝 贡献 + +欢迎贡献代码!请遵循以下步骤: + +1. Fork 本仓库 +2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 开启 Pull Request + +## 📄 许可证 + +本项目采用 Apache License 2.0 许可证。详见 [LICENSE](LICENSE) 文件。 + +## 📞 联系方式 + +如有问题或建议,请通过 GitHub Issues 联系我们。 + +--- + +Made with ❤️ by dreamstarsky diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..11518e5 --- /dev/null +++ b/README_EN.md @@ -0,0 +1,375 @@ +# RunBin + +[中文](README.md) | English + +RunBin is an online code execution and sharing platform that supports running, compiling, and displaying results for multiple programming languages. + +## ✨ Features + +- 🚀 Online Code Execution - Run code in multiple programming languages +- 📝 Code Sharing - Share code snippets via unique IDs +- 🐳 Docker Isolation - Secure code execution using Docker containers +- 💾 Flexible Storage - Supports both in-memory and database storage +- 🔄 Async Processing - Worker processes handle code execution tasks asynchronously +- 📊 Performance Stats - Track execution time and memory usage +- 🌐 Web Interface - Modern frontend with code editor support + +## 🏗️ Architecture + +The project uses a frontend-backend separation architecture: + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ │ │ │ │ │ +│ Web Client │─────▶│ API Server │─────▶│ PostgreSQL │ +│ (Vue 3) │ │ (Gin) │ │ Database │ +│ │ │ │ │ │ +└─────────────┘ └─────────────┘ └─────────────┘ + │ + │ + ▼ + ┌─────────────┐ ┌─────────────┐ + │ │ │ │ + │ Worker │─────▶│ Docker │ + │ Service │ │ Environment │ + │ │ │ │ + └─────────────┘ └─────────────┘ +``` + +### Components + +- **Web Client**: Modern frontend application built with Vue 3 + Vite +- **API Server**: RESTful API service built with Gin framework +- **Worker Service**: Background task processing service for executing user-submitted code +- **PostgreSQL**: Persistent storage for code and execution results +- **Docker**: Provides secure code execution environment + +## 📋 Prerequisites + +- Go 1.24.2 or higher +- Docker and Docker daemon +- PostgreSQL database (optional, for production) +- Node.js and npm (for frontend development) + +## 🚀 Quick Start + +### 1. Clone the Repository + +```bash +git clone https://github.com/dreamstarsky/runbin.git +cd runbin +``` + +### 2. Install Dependencies + +```bash +# Install Go dependencies +go mod download + +# Install frontend dependencies +cd web +npm install +cd .. +``` + +### 3. Setup Database (Optional) + +If using database storage, create the database and run migrations: + +```bash +# Create database +createdb runbin + +# Run migrations +psql -d runbin -f migrations/0001_init_pastes.sql +psql -d runbin -f migrations/0002_create_queue_table.sql +psql -d runbin -f migrations/0003_add_compilelog_column.sql +``` + +### 4. Configure Services + +Edit the configuration files: + +#### API Service Configuration (`config/api.yaml`) + +```yaml +app: + env: "release" # release or debug + port: 8080 + +storage: + type: "database" # memory or database + database: + dsn: "host=localhost port=5432 user=postgres password=password dbname=runbin sslmode=disable" +``` + +#### Worker Service Configuration (`config/worker.yaml`) + +```yaml +storage: + type: "database" + database: + dsn: "host=localhost port=5432 user=postgres password=password dbname=runbin sslmode=disable" + +limit: + time: 10.0 # Max execution time (seconds) + cpu: 1.0 # CPU limit + memory: 512 # Memory limit (MB) + size: 1024000 # Output size limit (bytes) + +process: 1 # Number of worker processes + +name: "default name" + +compilerimage: "cpp_gcc-latest:latest" # Compiler image +``` + +### 5. Start Services + +#### Start API Server + +```bash +go run cmd/api/main.go +``` + +The API server will run at `http://localhost:8080`. + +#### Start Worker Service + +```bash +go run cmd/worker/main.go +``` + +#### Start Frontend Development Server + +```bash +cd web +npm run dev +``` + +The frontend will run at `http://localhost:5173`. + +## 🐳 Docker Deployment + +### Build Images + +```bash +# Build API and Worker images +docker build -t runbin-api -f Dockerfile.api . +docker build -t runbin-worker -f Dockerfile.worker . + +# Build frontend image +cd web +docker build -t runbin-web . +``` + +### Using Docker Compose + +Create `docker-compose.yml`: + +```yaml +version: '3.8' + +services: + postgres: + image: postgres:15 + environment: + POSTGRES_DB: runbin + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + + api: + image: runbin-api + ports: + - "8080:8080" + depends_on: + - postgres + environment: + DATABASE_DSN: "host=postgres port=5432 user=postgres password=password dbname=runbin sslmode=disable" + + worker: + image: runbin-worker + depends_on: + - postgres + - api + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + DATABASE_DSN: "host=postgres port=5432 user=postgres password=password dbname=runbin sslmode=disable" + + web: + image: runbin-web + ports: + - "80:80" + environment: + BACKEND_URL: "http://localhost:8080" + +volumes: + postgres_data: +``` + +Start all services: + +```bash +docker-compose up -d +``` + +## 📡 API Documentation + +### Submit Code + +```http +POST /api/pastes +Content-Type: application/json + +{ + "code": "your code here", + "language": "cpp", + "stdin": "input data", + "run": true +} +``` + +Response: + +```json +{ + "id": "uuid-string", + "message": "Paste created successfully" +} +``` + +### Get Code Result + +```http +GET /api/pastes/:id +``` + +Response: + +```json +{ + "id": "uuid-string", + "code": "your code here", + "language": "cpp", + "stdin": "input data", + "stdout": "program output", + "stderr": "error output", + "status": "completed", + "compile_log": "compilation output", + "execution_time_ms": 100, + "memory_usage_kb": 1024, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:01Z", + "backend": "worker-name" +} +``` + +### Get Supported Languages + +```http +GET /api/languages +``` + +Response: + +```json +{ + "languages": ["cpp", "python", "java", "go"] +} +``` + +## 🗂️ Project Structure + +``` +. +├── cmd/ +│ ├── api/ # API service entry point +│ └── worker/ # Worker service entry point +├── config/ # Configuration files +│ ├── api.yaml +│ └── worker.yaml +├── internal/ +│ ├── config/ # Configuration loading +│ ├── controller/ # Controller layer +│ ├── model/ # Data models +│ ├── repository/ # Data access layer +│ ├── router/ # Route configuration +│ └── worker/ # Worker task processing +├── migrations/ # Database migration files +├── web/ # Frontend application +│ ├── src/ # Source code +│ ├── public/ # Static assets +│ └── dist/ # Build output +├── workerEnv/ # Worker environment configuration +├── go.mod # Go module definition +└── LICENSE # Apache 2.0 License +``` + +## 🔧 Development Guide + +### Adding New Language Support + +1. Add a new task processor in Worker (refer to `internal/worker/RunCppTask.go`) +2. Prepare the corresponding Docker image +3. Configure the compiler image in `worker.yaml` +4. Update the supported language list in the controller + +### Local Development + +```bash +# Start API in development mode +go run cmd/api/main.go + +# Start Worker in development mode +go run cmd/worker/main.go + +# Start frontend with hot reload +cd web && npm run dev +``` + +### Build for Production + +```bash +# Build API +go build -o bin/api cmd/api/main.go + +# Build Worker +go build -o bin/worker cmd/worker/main.go + +# Build frontend +cd web && npm run build +``` + +## 🔒 Security + +- All code executes in Docker containers, isolated from the host +- Configured resource limits (CPU, memory, execution time) +- Output size limits to prevent malicious code +- CORS configuration to protect API access + +## 🤝 Contributing + +Contributions are welcome! Please follow these steps: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/AmazingFeature`) +3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + +## 📄 License + +This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details. + +## 📞 Contact + +For questions or suggestions, please contact us via GitHub Issues. + +--- + +Made with ❤️ by dreamstarsky