最近在开发一个需要展示代码演示的项目时发现很多在线工具要么功能单一要么交互体验不佳。为了在技术分享、教学演示或项目汇报中更流畅地展示代码执行过程一个集代码编辑、实时运行和结果展示于一体的“代码TV”式工具就显得非常实用。本文将手把手带你从零构建一个轻量级的Web版代码演示工具涵盖前端界面、后端逻辑以及安全的代码执行沙箱无论是用于个人学习笔记还是团队技术分享都能直接复用。1. 背景与核心概念什么是“代码TV”“代码TV”并非一个特定的开源项目而是一种对交互式代码演示工具的生动比喻。它核心解决的问题是如何让观众像看电视一样清晰、直观、无需复杂环境准备地看到一段代码从编写到运行的完整过程。传统的代码分享方式如粘贴代码片段或录制GIF存在明显短板静态代码片段无法展示运行结果和交互过程。录制视频/GIF文件体积大观众无法与之交互如修改参数且内容无法被搜索引擎检索。要求观众本地运行环境配置是最大的门槛可能因系统、版本差异而失败。因此一个理想的“代码TV”工具应具备以下特征在线编辑提供一个在浏览器中直接编写代码的编辑器。多语言支持至少支持如 JavaScript、Python、Java 等常见语言的运行。安全执行代码必须在隔离的沙箱环境中运行防止恶意代码危害服务器。实时展示点击运行后能即时输出结果包括控制台打印、图形化输出等。界面友好通常采用左右或上下分栏布局一边是代码编辑器另一边是运行结果输出区域。本文将实现的正是这样一个工具。我们将使用Node.js Express作为后端服务React构建前端界面并利用Docker容器来实现安全、隔离的代码执行沙箱。2. 环境准备与版本说明在开始编码前请确保你的开发环境已就绪。以下是本文示例所使用的核心环境与版本你可以根据实际情况进行调整。操作系统macOS / Linux (WSL2) / Windows。建议使用 Linux 环境以便于 Docker 操作。Node.jsv18.x 或 v20.x LTS 版本。这是后端运行时和前端构建的基础。npm通常随 Node.js 安装版本 9.x 或 10.x。Dockerv24.x 或更高版本。这是实现代码安全沙箱的关键。请确保 Docker 守护进程正在运行 (sudo systemctl start docker或通过 Docker Desktop 启动)。代码编辑器VS Code 或其他你熟悉的 IDE。项目结构预览 我们将创建一个名为code-tv的根目录其下包含两个主要部分code-tv/ ├── server/ # 后端 Node.js 服务 │ ├── src/ │ ├── package.json │ └── Dockerfile.sandbox # 用于构建沙箱环境的Dockerfile └── client/ # 前端 React 应用 ├── src/ └── package.json3. 核心原理与架构拆解在动手之前理解整个系统的数据流和核心组件至关重要。3.1 系统架构图逻辑描述[用户浏览器] | | (1) 编写代码点击运行 v [前端 React 应用] (编辑器: Monaco Editor, 状态管理) | | (2) 发送 POST 请求包含代码和语言类型 v [后端 Express API 服务器] | | (3) 验证请求准备执行环境 v [Docker 沙箱容器] (临时创建执行代码) | | (4) 获取执行结果stdout, stderr, 退出码 v [后端 Express API 服务器] | | (5) 清理容器返回 JSON 响应 v [前端 React 应用] | | (6) 解析并展示结果 v [用户浏览器]3.2 关键技术点解析代码编辑器前端选用微软开源的Monaco Editor它就是 VS Code 使用的编辑器核心功能强大支持语法高亮、智能提示、多语言等。安全沙箱这是最核心也最危险的部分。绝对不能在 Node.js 主进程中直接使用eval或child_process.exec执行用户代码。我们将为每次代码运行启动一个全新的Docker 容器。容器具有以下安全优势隔离性容器内的进程与宿主机隔离文件系统、网络、进程空间都是独立的。资源限制可以方便地限制容器的 CPU、内存使用量防止耗尽服务器资源。快速清理执行完毕后容器会被立即销毁不留痕迹。前后端通信前端通过 RESTful API 与后端交互后端返回结构化的执行结果。多语言支持原理我们为每种支持的语言准备一个基础的 Docker 镜像如node:alpine,python:alpine,openjdk:alpine。后端根据用户选择的语言类型选择对应的镜像来启动容器并将用户代码作为参数或文件传入容器内执行。4. 完整实战构建后端沙箱服务我们先从后端开始构建接收代码并安全执行的核心逻辑。4.1 创建后端项目并初始化# 创建项目根目录和server目录 mkdir -p code-tv/server cd code-tv/server # 初始化Node.js项目 npm init -y # 安装必要的依赖 npm install express cors dockerode body-parser npm install --save-dev nodemonexpress: Web 框架。cors: 处理跨域请求便于前端调试。dockerode: Node.js 的 Docker 远程 API 客户端用于程序化控制 Docker。body-parser: 解析请求体。nodemon: 开发工具监听文件变化自动重启。4.2 创建沙箱 Dockerfile在server/目录下创建Dockerfile.sandbox。这是一个通用的、轻量的基础镜像我们用它来构建包含多种语言运行时的环境。为了简化我们先支持 Node.js 和 Python。# server/Dockerfile.sandbox # 使用多阶段构建减小镜像体积 FROM alpine:latest as builder # 安装 Node.js 和 Python RUN apk add --no-cache nodejs npm python3 py3-pip # 创建一个非root用户以增强安全性 RUN addgroup -S appgroup adduser -S appuser -G appgroup # 切换到工作目录 WORKDIR /sandbox # 切换用户 USER appuser # 默认命令保持容器运行等待执行指令 CMD [tail, -f, /dev/null]说明这个镜像包含了 Node.js 和 Python3 环境。我们使用alpine版本以减小体积。创建非 root 用户appuser是重要的安全实践避免代码在容器内以 root 权限运行。最后的CMD是为了让容器启动后不退出等待我们通过docker exec传入执行命令。构建此镜像在 server 目录下docker build -f Dockerfile.sandbox -t code-sandbox:latest .4.3 实现核心的 Express 服务器创建server/src/index.js文件// server/src/index.js const express require(express); const cors require(cors); const bodyParser require(body-parser); const Docker require(dockerode); const path require(path); const app express(); const PORT process.env.PORT || 3001; // 中间件 app.use(cors()); // 允许所有跨域请求生产环境应配置具体来源 app.use(bodyParser.json()); // 创建 Docker 客户端实例默认连接本地 Docker 守护进程 const docker new Docker(); // 存储活跃容器的 Map用于超时清理简易实现 const activeContainers new Map(); // 健康检查端点 app.get(/health, (req, res) { res.json({ status: OK, service: code-tv-backend }); }); // 执行代码的核心端点 app.post(/api/run, async (req, res) { const { code, language javascript } req.body; if (!code || typeof code ! string) { return res.status(400).json({ error: Invalid code payload }); } // 定义语言到执行命令的映射 const languageConfig { javascript: { image: code-sandbox:latest, command: [node, -e], args: [code], timeout: 5000, // 5秒超时 }, python: { image: code-sandbox:latest, command: [python3, -c], args: [code], timeout: 5000, }, // 未来可以扩展 java, go 等 // java: { image: openjdk:alpine, ... } }; const config languageConfig[language]; if (!config) { return res.status(400).json({ error: Unsupported language: ${language} }); } let container; try { // 1. 创建容器 container await docker.createContainer({ Image: config.image, Cmd: [tail, -f, /dev/null], // 保持容器运行 AttachStdout: true, AttachStderr: true, Tty: false, HostConfig: { // 资源限制防止恶意代码 Memory: 100 * 1024 * 1024, // 100MB MemorySwap: 200 * 1024 * 1024, // 200MB CpuPeriod: 100000, CpuQuota: 50000, // 限制50% CPU NetworkMode: none, // 禁用网络增强安全 AutoRemove: true, // 执行后自动删除容器重要 }, User: appuser, // 指定以非root用户运行 }); // 启动容器 await container.start(); const containerId container.id; activeContainers.set(containerId, setTimeout(() { // 超时强制清理后备机制 container.stop().catch(console.error); activeContainers.delete(containerId); }, config.timeout 2000)); // 比执行超时稍长 // 2. 在容器内执行代码 const exec await container.exec({ Cmd: [...config.command, ...config.args], AttachStdout: true, AttachStderr: true, }); // 启动执行流并获取输出 const stream await exec.start({ hijack: true, stdin: false }); let output ; let errorOutput ; stream.on(data, (chunk) { output chunk.toString(); }); stream.on(end, async () { // 获取执行退出信息 const inspect await exec.inspect(); const exitCode inspect.ExitCode; // 3. 清理容器 const timeoutId activeContainers.get(containerId); if (timeoutId) clearTimeout(timeoutId); activeContainers.delete(containerId); try { await container.stop(); } catch (e) { // 容器可能已自动移除 } // 4. 返回结果给前端 res.json({ success: exitCode 0, output: output.trim(), error: exitCode ! 0 ? (errorOutput || Process exited with code ${exitCode}) : null, language, exitCode, }); }); stream.on(error, (err) { errorOutput err.message; }); } catch (error) { console.error(Execution error:, error); // 确保发生错误时尝试清理容器 if (container) { try { await container.stop().catch(() {}); } catch {} try { await container.remove().catch(() {}); } catch {} } res.status(500).json({ success: false, output: , error: Server error during execution: ${error.message}, }); } }); // 全局错误处理中间件 app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: Something went wrong! }); }); app.listen(PORT, () { console.log(Code-TV backend server running on http://localhost:${PORT}); });4.4 运行与验证后端服务修改server/package.json添加启动脚本scripts: { start: node src/index.js, dev: nodemon src/index.js }确保 Docker 守护进程正在运行并且code-sandbox:latest镜像已构建成功。启动后端服务cd server npm run dev使用curl或 Postman 测试 APIcurl -X POST http://localhost:3001/api/run \ -H Content-Type: application/json \ -d {code: console.log(\Hello, Code TV!\); for(let i0;i3;i){ console.log(i); }, language: javascript}预期返回{ success: true, output: Hello, Code TV!\n0\n1\n2, error: null, language: javascript, exitCode: 0 }5. 完整实战构建前端交互界面后端准备就绪后我们构建一个简单但功能完整的前端界面。5.1 创建 React 应用并安装依赖# 回到项目根目录 cd ../.. # 使用 Vite 快速创建 React 项目比 create-react-app 更轻快 npm create vitelatest client -- --template react cd client npm install monaco-editor/react axiosmonaco-editor/react: React 封装的 Monaco Editor 组件。axios: 用于向后端发送 HTTP 请求。5.2 实现主应用组件替换client/src/App.jsx文件// client/src/App.jsx import React, { useState, useRef } from react; import Editor from monaco-editor/react; import axios from axios; import ./App.css; // 后端API地址开发环境代理或直接指定 const API_BASE_URL http://localhost:3001; function App() { // 编辑器实例引用 const editorRef useRef(null); // 当前代码 const [code, setCode] useState(// 欢迎使用 Code TV // 选择语言编写代码点击“运行”查看结果。 console.log(Hello, World!); function factorial(n) { if (n 1) return 1; return n * factorial(n - 1); } console.log(5! , factorial(5)); ); // 选择的语言 const [language, setLanguage] useState(javascript); // 执行结果 const [result, setResult] useState({ output: , error: , loading: false }); // 编辑器主题 const [theme, setTheme] useState(vs-light); // 处理编辑器挂载 function handleEditorDidMount(editor, monaco) { editorRef.current editor; } // 运行代码 const runCode async () { if (!code.trim()) { setResult({ output: , error: 代码不能为空, loading: false }); return; } setResult({ output: , error: , loading: true }); try { const response await axios.post(${API_BASE_URL}/api/run, { code: code, language: language, }); const { success, output, error } response.data; if (success) { setResult({ output: output, error: , loading: false }); } else { setResult({ output: , error: error || 执行出错, loading: false }); } } catch (err) { console.error(请求失败:, err); setResult({ output: , error: 网络或服务器错误: ${err.message || 请检查后端服务是否启动}, loading: false, }); } }; // 清空输出 const clearOutput () { setResult({ output: , error: , loading: false }); }; // 语言选项 const languageOptions [ { value: javascript, label: JavaScript }, { value: python, label: Python }, ]; return ( div classNameapp-container header classNameapp-header h1 代码 TV - 在线代码演示工具/h1 p安全、实时地编写并运行代码片段/p /header div classNamecontrols-panel div classNamecontrol-group label htmlForlanguage-select编程语言/label select idlanguage-select value{language} onChange{(e) { setLanguage(e.target.value); // 切换语言时可以更新示例代码 if (e.target.value python) { setCode(# Python 示例 print(Hello, World!) def fibonacci(n): a, b 0, 1 for _ in range(n): print(a, end ) a, b b, a b print() fibonacci(10)); } else { setCode(// JavaScript 示例 console.log(Hello, World!); function factorial(n) { if (n 1) return 1; return n * factorial(n - 1); } console.log(5! , factorial(5));); } }} {languageOptions.map((opt) ( option key{opt.value} value{opt.value} {opt.label} /option ))} /select /div div classNamecontrol-group label htmlFortheme-select编辑器主题/label select idtheme-select value{theme} onChange{(e) setTheme(e.target.value)} option valuevs-lightLight/option option valuevs-darkDark/option option valuehc-blackHigh Contrast/option /select /div div classNamebutton-group button onClick{runCode} disabled{result.loading} classNamebtn-run {result.loading ? 运行中... : ▶ 运行代码} /button button onClick{clearOutput} classNamebtn-clear ️ 清空输出 /button /div /div div classNamemain-content div classNameeditor-section h3代码编辑器/h3 Editor height60vh language{language} value{code} theme{theme} onChange{(value) setCode(value || )} onMount{handleEditorDidMount} options{{ minimap: { enabled: true }, fontSize: 14, scrollBeyondLastLine: false, wordWrap: on, automaticLayout: true, }} / /div div classNameoutput-section h3运行结果/h3 div classNameoutput-display {result.loading ? ( div classNameloading正在安全沙箱中执行代码请稍候.../div ) : ( {result.error ( pre classNameoutput-error{result.error}/pre )} {result.output ( div classNameoutput-header标准输出/div pre classNameoutput-stdout{result.output}/pre / )} {!result.output !result.error ( div classNameoutput-placeholder 运行结果将显示在这里。点击“运行代码”开始。 /div )} / )} /div div classNameexecution-info small 语言: strong{language}/strong | 后端状态: span classNamestatus-ok● 在线/span | 执行环境: Docker 沙箱 (资源受限无网络) /small /div /div /div footer classNameapp-footer p strong提示/strong 代码在隔离的 Docker 容器中执行拥有严格的 CPU/内存限制且无网络访问权限请勿尝试恶意操作。 /p /footer /div ); } export default App;5.3 添加基础样式创建或修改client/src/App.css/* client/src/App.css */ * { box-sizing: border-box; margin: 0; padding: 0; font-family: Segoe UI, Tahoma, Geneva, Verdana, sans-serif; } body { background-color: #f5f7fa; color: #333; line-height: 1.6; } .app-container { max-width: 1400px; margin: 0 auto; padding: 20px; min-height: 100vh; display: flex; flex-direction: column; } .app-header { text-align: center; margin-bottom: 30px; padding-bottom: 20px; border-bottom: 2px solid #e1e4e8; } .app-header h1 { color: #2c3e50; margin-bottom: 10px; } .app-header p { color: #7f8c8d; font-size: 1.1rem; } .controls-panel { background: white; padding: 20px; border-radius: 10px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05); margin-bottom: 25px; display: flex; flex-wrap: wrap; gap: 25px; align-items: center; } .control-group { display: flex; align-items: center; gap: 10px; } .control-group label { font-weight: 600; color: #555; } .control-group select { padding: 8px 15px; border: 1px solid #d1d9e0; border-radius: 6px; background-color: white; font-size: 0.95rem; cursor: pointer; transition: border-color 0.2s; } .control-group select:focus { outline: none; border-color: #3498db; } .button-group { display: flex; gap: 15px; margin-left: auto; } button { padding: 10px 22px; border: none; border-radius: 6px; font-size: 1rem; font-weight: 600; cursor: pointer; transition: all 0.2s ease; } .btn-run { background-color: #2ecc71; color: white; } .btn-run:hover:not(:disabled) { background-color: #27ae60; } .btn-run:disabled { background-color: #95a5a6; cursor: not-allowed; } .btn-clear { background-color: #e74c3c; color: white; } .btn-clear:hover { background-color: #c0392b; } .main-content { display: flex; flex: 1; gap: 25px; margin-bottom: 25px; } media (max-width: 1024px) { .main-content { flex-direction: column; } } .editor-section, .output-section { flex: 1; background: white; border-radius: 10px; padding: 20px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05); display: flex; flex-direction: column; } .editor-section h3, .output-section h3 { color: #2c3e50; margin-bottom: 15px; padding-bottom: 10px; border-bottom: 1px solid #eee; } .output-display { flex: 1; background-color: #f8f9fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 20px; overflow-y: auto; min-height: 300px; font-family: Consolas, Monaco, Courier New, monospace; font-size: 0.95rem; white-space: pre-wrap; word-break: break-all; } .loading { color: #3498db; text-align: center; padding: 40px; font-style: italic; } .output-error { color: #e74c3c; background-color: #fdf2f2; padding: 15px; border-radius: 5px; border-left: 4px solid #e74c3c; } .output-header { font-weight: bold; color: #2c3e50; margin-bottom: 10px; } .output-stdout { color: #27ae60; background-color: #f7fdf9; padding: 15px; border-radius: 5px; border-left: 4px solid #27ae60; } .output-placeholder { color: #95a5a6; text-align: center; padding: 40px; font-style: italic; } .execution-info { margin-top: 20px; padding-top: 15px; border-top: 1px dashed #ddd; color: #7f8c8d; font-size: 0.9rem; } .status-ok { color: #2ecc71; font-weight: bold; } .app-footer { margin-top: auto; padding: 20px; text-align: center; background-color: #f1f8ff; border-radius: 10px; color: #5a6c7d; font-size: 0.9rem; border: 1px solid #e1e8ed; }5.4 运行前端应用在client目录下启动开发服务器npm run dev根据终端提示通常是http://localhost:5173在浏览器中打开应用。确保后端服务 (http://localhost:3001) 也在运行。现在你可以在左侧编写 JavaScript 或 Python 代码点击“运行代码”右侧会安全地显示执行结果。6. 常见问题与排查思路在开发和部署过程中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案前端点击运行后一直显示“运行中...”或报网络错误。1. 后端服务未启动。2. 后端端口被占用或与前端的API_BASE_URL不匹配。3. Docker 守护进程未运行。1. 检查server目录下npm run dev是否成功控制台有无报错。2. 确认后端服务地址。前端App.jsx中的API_BASE_URL需与后端实际地址一致。开发时可配置 Vite 代理。3. 运行docker ps命令确认 Docker 服务状态。后端日志显示Error: connect ECONNREFUSED或dockerode连接失败。Docker 守护进程未运行或当前用户无权访问 Docker Socket。1. 启动 Docker Desktop 或运行sudo systemctl start docker(Linux)。2. 将当前用户加入docker组sudo usermod -aG docker $USER然后重新登录。代码执行超时返回Process exited with code 137。容器因超出内存限制而被系统终止 (OOM Killer)。1. 检查后端代码中Memory和MemorySwap的限制是否过小。2. 用户代码可能存在内存泄漏或无限循环。可在前端增加运行超时提示并引导用户检查代码逻辑。Python 代码中import第三方库失败。沙箱基础镜像 (code-sandbox:latest) 中未安装该库且容器无网络 (NetworkMode: none)。1. 对于演示工具可以预先在Dockerfile.sandbox中安装常用库如numpy,requests。2. 如果需动态安装则必须开放容器网络 (NetworkMode: bridge)但这会显著增加安全风险需谨慎评估。执行结果中包含奇怪的字符或格式错乱。容器输出流的编码或换行符问题。在后端处理stream数据时确保正确解码 (chunk.toString()) 并处理可能的缓冲区拼接问题。本文示例已做简单处理复杂输出可能需要更精细的控制。频繁运行后docker ps -a发现大量已停止的容器。容器未成功自动清理。确保createContainer时设置了HostConfig: { AutoRemove: true }。同时后端代码中的错误处理逻辑必须包含容器清理的catch块防止因异常导致容器残留。7. 最佳实践与工程建议将“代码TV”投入生产环境或团队使用时需要考虑更多工程化因素。安全性强化镜像最小化为每种语言使用独立的、更精简的官方-slim或-alpine镜像减少攻击面。更严格的资源限制根据语言特性设置 CPU 份额 (CpuShares)、进程数 (PidsLimit)、文件描述符限制。只读文件系统在HostConfig中设置ReadonlyRootfs: true防止代码写入文件系统。能力限制使用CapDrop删除所有 Linux Capabilities或仅添加必要的最小集。系统调用过滤考虑使用seccomp配置文件来限制容器内可用的系统调用。性能与可扩展性容器池预热对于高并发场景可以预先创建并维护一个“温暖”的容器池执行时直接使用避免每次创建容器的开销。异步处理与队列将代码执行请求放入消息队列如 Redis、RabbitMQ由独立的 Worker 进程消费并执行避免 HTTP 请求线程被长时间阻塞。结果缓存对相同的代码和语言组合可以缓存执行结果一段时间减少重复计算。功能扩展支持更多语言在languageConfig中添加 Java、Go、C 等配置。需要构建包含对应编译/运行环境的 Docker 镜像。图形化输出对于 Python 的matplotlib可以安装xvfb等虚拟显示设备将图形渲染为图片返回给前端。代码分享与持久化为执行成功的代码生成一个唯一 ID并支持通过 URL 分享。这需要引入数据库如 SQLite、PostgreSQL来存储代码片段和结果。用户认证与配额增加用户登录功能并限制每个用户单位时间内的代码执行次数和资源消耗防止滥用。部署与监控容器化部署将前后端都 Docker 化使用docker-compose.yml统一管理便于一键部署。日志聚合将后端服务的访问日志、错误日志以及 Docker 容器的执行日志收集到 ELK 或 Loki 等日志系统中便于问题追踪。健康检查为后端服务添加/health端点本文已实现并配置 Kubernetes 或 Docker Swarm 的存活探针。监控告警监控服务器的 CPU、内存、磁盘 I/O 以及 Docker 容器的创建频率和失败率设置阈值告警。通过以上步骤我们完成了一个具备核心功能的“代码TV”工具。它不仅是一个演示项目更是一个理解 Web 全栈开发、容器安全、前后端交互的绝佳实践。你可以在此基础上根据实际需求参考最佳实践部分进行深化和扩展构建出更强大、更安全的在线代码执行平台。 从零构建Web版代码演示工具：基于Docker沙箱的安全执行环境
最近在开发一个需要展示代码演示的项目时发现很多在线工具要么功能单一要么交互体验不佳。为了在技术分享、教学演示或项目汇报中更流畅地展示代码执行过程一个集代码编辑、实时运行和结果展示于一体的“代码TV”式工具就显得非常实用。本文将手把手带你从零构建一个轻量级的Web版代码演示工具涵盖前端界面、后端逻辑以及安全的代码执行沙箱无论是用于个人学习笔记还是团队技术分享都能直接复用。1. 背景与核心概念什么是“代码TV”“代码TV”并非一个特定的开源项目而是一种对交互式代码演示工具的生动比喻。它核心解决的问题是如何让观众像看电视一样清晰、直观、无需复杂环境准备地看到一段代码从编写到运行的完整过程。传统的代码分享方式如粘贴代码片段或录制GIF存在明显短板静态代码片段无法展示运行结果和交互过程。录制视频/GIF文件体积大观众无法与之交互如修改参数且内容无法被搜索引擎检索。要求观众本地运行环境配置是最大的门槛可能因系统、版本差异而失败。因此一个理想的“代码TV”工具应具备以下特征在线编辑提供一个在浏览器中直接编写代码的编辑器。多语言支持至少支持如 JavaScript、Python、Java 等常见语言的运行。安全执行代码必须在隔离的沙箱环境中运行防止恶意代码危害服务器。实时展示点击运行后能即时输出结果包括控制台打印、图形化输出等。界面友好通常采用左右或上下分栏布局一边是代码编辑器另一边是运行结果输出区域。本文将实现的正是这样一个工具。我们将使用Node.js Express作为后端服务React构建前端界面并利用Docker容器来实现安全、隔离的代码执行沙箱。2. 环境准备与版本说明在开始编码前请确保你的开发环境已就绪。以下是本文示例所使用的核心环境与版本你可以根据实际情况进行调整。操作系统macOS / Linux (WSL2) / Windows。建议使用 Linux 环境以便于 Docker 操作。Node.jsv18.x 或 v20.x LTS 版本。这是后端运行时和前端构建的基础。npm通常随 Node.js 安装版本 9.x 或 10.x。Dockerv24.x 或更高版本。这是实现代码安全沙箱的关键。请确保 Docker 守护进程正在运行 (sudo systemctl start docker或通过 Docker Desktop 启动)。代码编辑器VS Code 或其他你熟悉的 IDE。项目结构预览 我们将创建一个名为code-tv的根目录其下包含两个主要部分code-tv/ ├── server/ # 后端 Node.js 服务 │ ├── src/ │ ├── package.json │ └── Dockerfile.sandbox # 用于构建沙箱环境的Dockerfile └── client/ # 前端 React 应用 ├── src/ └── package.json3. 核心原理与架构拆解在动手之前理解整个系统的数据流和核心组件至关重要。3.1 系统架构图逻辑描述[用户浏览器] | | (1) 编写代码点击运行 v [前端 React 应用] (编辑器: Monaco Editor, 状态管理) | | (2) 发送 POST 请求包含代码和语言类型 v [后端 Express API 服务器] | | (3) 验证请求准备执行环境 v [Docker 沙箱容器] (临时创建执行代码) | | (4) 获取执行结果stdout, stderr, 退出码 v [后端 Express API 服务器] | | (5) 清理容器返回 JSON 响应 v [前端 React 应用] | | (6) 解析并展示结果 v [用户浏览器]3.2 关键技术点解析代码编辑器前端选用微软开源的Monaco Editor它就是 VS Code 使用的编辑器核心功能强大支持语法高亮、智能提示、多语言等。安全沙箱这是最核心也最危险的部分。绝对不能在 Node.js 主进程中直接使用eval或child_process.exec执行用户代码。我们将为每次代码运行启动一个全新的Docker 容器。容器具有以下安全优势隔离性容器内的进程与宿主机隔离文件系统、网络、进程空间都是独立的。资源限制可以方便地限制容器的 CPU、内存使用量防止耗尽服务器资源。快速清理执行完毕后容器会被立即销毁不留痕迹。前后端通信前端通过 RESTful API 与后端交互后端返回结构化的执行结果。多语言支持原理我们为每种支持的语言准备一个基础的 Docker 镜像如node:alpine,python:alpine,openjdk:alpine。后端根据用户选择的语言类型选择对应的镜像来启动容器并将用户代码作为参数或文件传入容器内执行。4. 完整实战构建后端沙箱服务我们先从后端开始构建接收代码并安全执行的核心逻辑。4.1 创建后端项目并初始化# 创建项目根目录和server目录 mkdir -p code-tv/server cd code-tv/server # 初始化Node.js项目 npm init -y # 安装必要的依赖 npm install express cors dockerode body-parser npm install --save-dev nodemonexpress: Web 框架。cors: 处理跨域请求便于前端调试。dockerode: Node.js 的 Docker 远程 API 客户端用于程序化控制 Docker。body-parser: 解析请求体。nodemon: 开发工具监听文件变化自动重启。4.2 创建沙箱 Dockerfile在server/目录下创建Dockerfile.sandbox。这是一个通用的、轻量的基础镜像我们用它来构建包含多种语言运行时的环境。为了简化我们先支持 Node.js 和 Python。# server/Dockerfile.sandbox # 使用多阶段构建减小镜像体积 FROM alpine:latest as builder # 安装 Node.js 和 Python RUN apk add --no-cache nodejs npm python3 py3-pip # 创建一个非root用户以增强安全性 RUN addgroup -S appgroup adduser -S appuser -G appgroup # 切换到工作目录 WORKDIR /sandbox # 切换用户 USER appuser # 默认命令保持容器运行等待执行指令 CMD [tail, -f, /dev/null]说明这个镜像包含了 Node.js 和 Python3 环境。我们使用alpine版本以减小体积。创建非 root 用户appuser是重要的安全实践避免代码在容器内以 root 权限运行。最后的CMD是为了让容器启动后不退出等待我们通过docker exec传入执行命令。构建此镜像在 server 目录下docker build -f Dockerfile.sandbox -t code-sandbox:latest .4.3 实现核心的 Express 服务器创建server/src/index.js文件// server/src/index.js const express require(express); const cors require(cors); const bodyParser require(body-parser); const Docker require(dockerode); const path require(path); const app express(); const PORT process.env.PORT || 3001; // 中间件 app.use(cors()); // 允许所有跨域请求生产环境应配置具体来源 app.use(bodyParser.json()); // 创建 Docker 客户端实例默认连接本地 Docker 守护进程 const docker new Docker(); // 存储活跃容器的 Map用于超时清理简易实现 const activeContainers new Map(); // 健康检查端点 app.get(/health, (req, res) { res.json({ status: OK, service: code-tv-backend }); }); // 执行代码的核心端点 app.post(/api/run, async (req, res) { const { code, language javascript } req.body; if (!code || typeof code ! string) { return res.status(400).json({ error: Invalid code payload }); } // 定义语言到执行命令的映射 const languageConfig { javascript: { image: code-sandbox:latest, command: [node, -e], args: [code], timeout: 5000, // 5秒超时 }, python: { image: code-sandbox:latest, command: [python3, -c], args: [code], timeout: 5000, }, // 未来可以扩展 java, go 等 // java: { image: openjdk:alpine, ... } }; const config languageConfig[language]; if (!config) { return res.status(400).json({ error: Unsupported language: ${language} }); } let container; try { // 1. 创建容器 container await docker.createContainer({ Image: config.image, Cmd: [tail, -f, /dev/null], // 保持容器运行 AttachStdout: true, AttachStderr: true, Tty: false, HostConfig: { // 资源限制防止恶意代码 Memory: 100 * 1024 * 1024, // 100MB MemorySwap: 200 * 1024 * 1024, // 200MB CpuPeriod: 100000, CpuQuota: 50000, // 限制50% CPU NetworkMode: none, // 禁用网络增强安全 AutoRemove: true, // 执行后自动删除容器重要 }, User: appuser, // 指定以非root用户运行 }); // 启动容器 await container.start(); const containerId container.id; activeContainers.set(containerId, setTimeout(() { // 超时强制清理后备机制 container.stop().catch(console.error); activeContainers.delete(containerId); }, config.timeout 2000)); // 比执行超时稍长 // 2. 在容器内执行代码 const exec await container.exec({ Cmd: [...config.command, ...config.args], AttachStdout: true, AttachStderr: true, }); // 启动执行流并获取输出 const stream await exec.start({ hijack: true, stdin: false }); let output ; let errorOutput ; stream.on(data, (chunk) { output chunk.toString(); }); stream.on(end, async () { // 获取执行退出信息 const inspect await exec.inspect(); const exitCode inspect.ExitCode; // 3. 清理容器 const timeoutId activeContainers.get(containerId); if (timeoutId) clearTimeout(timeoutId); activeContainers.delete(containerId); try { await container.stop(); } catch (e) { // 容器可能已自动移除 } // 4. 返回结果给前端 res.json({ success: exitCode 0, output: output.trim(), error: exitCode ! 0 ? (errorOutput || Process exited with code ${exitCode}) : null, language, exitCode, }); }); stream.on(error, (err) { errorOutput err.message; }); } catch (error) { console.error(Execution error:, error); // 确保发生错误时尝试清理容器 if (container) { try { await container.stop().catch(() {}); } catch {} try { await container.remove().catch(() {}); } catch {} } res.status(500).json({ success: false, output: , error: Server error during execution: ${error.message}, }); } }); // 全局错误处理中间件 app.use((err, req, res, next) { console.error(err.stack); res.status(500).json({ error: Something went wrong! }); }); app.listen(PORT, () { console.log(Code-TV backend server running on http://localhost:${PORT}); });4.4 运行与验证后端服务修改server/package.json添加启动脚本scripts: { start: node src/index.js, dev: nodemon src/index.js }确保 Docker 守护进程正在运行并且code-sandbox:latest镜像已构建成功。启动后端服务cd server npm run dev使用curl或 Postman 测试 APIcurl -X POST http://localhost:3001/api/run \ -H Content-Type: application/json \ -d {code: console.log(\Hello, Code TV!\); for(let i0;i3;i){ console.log(i); }, language: javascript}预期返回{ success: true, output: Hello, Code TV!\n0\n1\n2, error: null, language: javascript, exitCode: 0 }5. 完整实战构建前端交互界面后端准备就绪后我们构建一个简单但功能完整的前端界面。5.1 创建 React 应用并安装依赖# 回到项目根目录 cd ../.. # 使用 Vite 快速创建 React 项目比 create-react-app 更轻快 npm create vitelatest client -- --template react cd client npm install monaco-editor/react axiosmonaco-editor/react: React 封装的 Monaco Editor 组件。axios: 用于向后端发送 HTTP 请求。5.2 实现主应用组件替换client/src/App.jsx文件// client/src/App.jsx import React, { useState, useRef } from react; import Editor from monaco-editor/react; import axios from axios; import ./App.css; // 后端API地址开发环境代理或直接指定 const API_BASE_URL http://localhost:3001; function App() { // 编辑器实例引用 const editorRef useRef(null); // 当前代码 const [code, setCode] useState(// 欢迎使用 Code TV // 选择语言编写代码点击“运行”查看结果。 console.log(Hello, World!); function factorial(n) { if (n 1) return 1; return n * factorial(n - 1); } console.log(5! , factorial(5)); ); // 选择的语言 const [language, setLanguage] useState(javascript); // 执行结果 const [result, setResult] useState({ output: , error: , loading: false }); // 编辑器主题 const [theme, setTheme] useState(vs-light); // 处理编辑器挂载 function handleEditorDidMount(editor, monaco) { editorRef.current editor; } // 运行代码 const runCode async () { if (!code.trim()) { setResult({ output: , error: 代码不能为空, loading: false }); return; } setResult({ output: , error: , loading: true }); try { const response await axios.post(${API_BASE_URL}/api/run, { code: code, language: language, }); const { success, output, error } response.data; if (success) { setResult({ output: output, error: , loading: false }); } else { setResult({ output: , error: error || 执行出错, loading: false }); } } catch (err) { console.error(请求失败:, err); setResult({ output: , error: 网络或服务器错误: ${err.message || 请检查后端服务是否启动}, loading: false, }); } }; // 清空输出 const clearOutput () { setResult({ output: , error: , loading: false }); }; // 语言选项 const languageOptions [ { value: javascript, label: JavaScript }, { value: python, label: Python }, ]; return ( div classNameapp-container header classNameapp-header h1 代码 TV - 在线代码演示工具/h1 p安全、实时地编写并运行代码片段/p /header div classNamecontrols-panel div classNamecontrol-group label htmlForlanguage-select编程语言/label select idlanguage-select value{language} onChange{(e) { setLanguage(e.target.value); // 切换语言时可以更新示例代码 if (e.target.value python) { setCode(# Python 示例 print(Hello, World!) def fibonacci(n): a, b 0, 1 for _ in range(n): print(a, end ) a, b b, a b print() fibonacci(10)); } else { setCode(// JavaScript 示例 console.log(Hello, World!); function factorial(n) { if (n 1) return 1; return n * factorial(n - 1); } console.log(5! , factorial(5));); } }} {languageOptions.map((opt) ( option key{opt.value} value{opt.value} {opt.label} /option ))} /select /div div classNamecontrol-group label htmlFortheme-select编辑器主题/label select idtheme-select value{theme} onChange{(e) setTheme(e.target.value)} option valuevs-lightLight/option option valuevs-darkDark/option option valuehc-blackHigh Contrast/option /select /div div classNamebutton-group button onClick{runCode} disabled{result.loading} classNamebtn-run {result.loading ? 运行中... : ▶ 运行代码} /button button onClick{clearOutput} classNamebtn-clear ️ 清空输出 /button /div /div div classNamemain-content div classNameeditor-section h3代码编辑器/h3 Editor height60vh language{language} value{code} theme{theme} onChange{(value) setCode(value || )} onMount{handleEditorDidMount} options{{ minimap: { enabled: true }, fontSize: 14, scrollBeyondLastLine: false, wordWrap: on, automaticLayout: true, }} / /div div classNameoutput-section h3运行结果/h3 div classNameoutput-display {result.loading ? ( div classNameloading正在安全沙箱中执行代码请稍候.../div ) : ( {result.error ( pre classNameoutput-error{result.error}/pre )} {result.output ( div classNameoutput-header标准输出/div pre classNameoutput-stdout{result.output}/pre / )} {!result.output !result.error ( div classNameoutput-placeholder 运行结果将显示在这里。点击“运行代码”开始。 /div )} / )} /div div classNameexecution-info small 语言: strong{language}/strong | 后端状态: span classNamestatus-ok● 在线/span | 执行环境: Docker 沙箱 (资源受限无网络) /small /div /div /div footer classNameapp-footer p strong提示/strong 代码在隔离的 Docker 容器中执行拥有严格的 CPU/内存限制且无网络访问权限请勿尝试恶意操作。 /p /footer /div ); } export default App;5.3 添加基础样式创建或修改client/src/App.css/* client/src/App.css */ * { box-sizing: border-box; margin: 0; padding: 0; font-family: Segoe UI, Tahoma, Geneva, Verdana, sans-serif; } body { background-color: #f5f7fa; color: #333; line-height: 1.6; } .app-container { max-width: 1400px; margin: 0 auto; padding: 20px; min-height: 100vh; display: flex; flex-direction: column; } .app-header { text-align: center; margin-bottom: 30px; padding-bottom: 20px; border-bottom: 2px solid #e1e4e8; } .app-header h1 { color: #2c3e50; margin-bottom: 10px; } .app-header p { color: #7f8c8d; font-size: 1.1rem; } .controls-panel { background: white; padding: 20px; border-radius: 10px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05); margin-bottom: 25px; display: flex; flex-wrap: wrap; gap: 25px; align-items: center; } .control-group { display: flex; align-items: center; gap: 10px; } .control-group label { font-weight: 600; color: #555; } .control-group select { padding: 8px 15px; border: 1px solid #d1d9e0; border-radius: 6px; background-color: white; font-size: 0.95rem; cursor: pointer; transition: border-color 0.2s; } .control-group select:focus { outline: none; border-color: #3498db; } .button-group { display: flex; gap: 15px; margin-left: auto; } button { padding: 10px 22px; border: none; border-radius: 6px; font-size: 1rem; font-weight: 600; cursor: pointer; transition: all 0.2s ease; } .btn-run { background-color: #2ecc71; color: white; } .btn-run:hover:not(:disabled) { background-color: #27ae60; } .btn-run:disabled { background-color: #95a5a6; cursor: not-allowed; } .btn-clear { background-color: #e74c3c; color: white; } .btn-clear:hover { background-color: #c0392b; } .main-content { display: flex; flex: 1; gap: 25px; margin-bottom: 25px; } media (max-width: 1024px) { .main-content { flex-direction: column; } } .editor-section, .output-section { flex: 1; background: white; border-radius: 10px; padding: 20px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05); display: flex; flex-direction: column; } .editor-section h3, .output-section h3 { color: #2c3e50; margin-bottom: 15px; padding-bottom: 10px; border-bottom: 1px solid #eee; } .output-display { flex: 1; background-color: #f8f9fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 20px; overflow-y: auto; min-height: 300px; font-family: Consolas, Monaco, Courier New, monospace; font-size: 0.95rem; white-space: pre-wrap; word-break: break-all; } .loading { color: #3498db; text-align: center; padding: 40px; font-style: italic; } .output-error { color: #e74c3c; background-color: #fdf2f2; padding: 15px; border-radius: 5px; border-left: 4px solid #e74c3c; } .output-header { font-weight: bold; color: #2c3e50; margin-bottom: 10px; } .output-stdout { color: #27ae60; background-color: #f7fdf9; padding: 15px; border-radius: 5px; border-left: 4px solid #27ae60; } .output-placeholder { color: #95a5a6; text-align: center; padding: 40px; font-style: italic; } .execution-info { margin-top: 20px; padding-top: 15px; border-top: 1px dashed #ddd; color: #7f8c8d; font-size: 0.9rem; } .status-ok { color: #2ecc71; font-weight: bold; } .app-footer { margin-top: auto; padding: 20px; text-align: center; background-color: #f1f8ff; border-radius: 10px; color: #5a6c7d; font-size: 0.9rem; border: 1px solid #e1e8ed; }5.4 运行前端应用在client目录下启动开发服务器npm run dev根据终端提示通常是http://localhost:5173在浏览器中打开应用。确保后端服务 (http://localhost:3001) 也在运行。现在你可以在左侧编写 JavaScript 或 Python 代码点击“运行代码”右侧会安全地显示执行结果。6. 常见问题与排查思路在开发和部署过程中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案前端点击运行后一直显示“运行中...”或报网络错误。1. 后端服务未启动。2. 后端端口被占用或与前端的API_BASE_URL不匹配。3. Docker 守护进程未运行。1. 检查server目录下npm run dev是否成功控制台有无报错。2. 确认后端服务地址。前端App.jsx中的API_BASE_URL需与后端实际地址一致。开发时可配置 Vite 代理。3. 运行docker ps命令确认 Docker 服务状态。后端日志显示Error: connect ECONNREFUSED或dockerode连接失败。Docker 守护进程未运行或当前用户无权访问 Docker Socket。1. 启动 Docker Desktop 或运行sudo systemctl start docker(Linux)。2. 将当前用户加入docker组sudo usermod -aG docker $USER然后重新登录。代码执行超时返回Process exited with code 137。容器因超出内存限制而被系统终止 (OOM Killer)。1. 检查后端代码中Memory和MemorySwap的限制是否过小。2. 用户代码可能存在内存泄漏或无限循环。可在前端增加运行超时提示并引导用户检查代码逻辑。Python 代码中import第三方库失败。沙箱基础镜像 (code-sandbox:latest) 中未安装该库且容器无网络 (NetworkMode: none)。1. 对于演示工具可以预先在Dockerfile.sandbox中安装常用库如numpy,requests。2. 如果需动态安装则必须开放容器网络 (NetworkMode: bridge)但这会显著增加安全风险需谨慎评估。执行结果中包含奇怪的字符或格式错乱。容器输出流的编码或换行符问题。在后端处理stream数据时确保正确解码 (chunk.toString()) 并处理可能的缓冲区拼接问题。本文示例已做简单处理复杂输出可能需要更精细的控制。频繁运行后docker ps -a发现大量已停止的容器。容器未成功自动清理。确保createContainer时设置了HostConfig: { AutoRemove: true }。同时后端代码中的错误处理逻辑必须包含容器清理的catch块防止因异常导致容器残留。7. 最佳实践与工程建议将“代码TV”投入生产环境或团队使用时需要考虑更多工程化因素。安全性强化镜像最小化为每种语言使用独立的、更精简的官方-slim或-alpine镜像减少攻击面。更严格的资源限制根据语言特性设置 CPU 份额 (CpuShares)、进程数 (PidsLimit)、文件描述符限制。只读文件系统在HostConfig中设置ReadonlyRootfs: true防止代码写入文件系统。能力限制使用CapDrop删除所有 Linux Capabilities或仅添加必要的最小集。系统调用过滤考虑使用seccomp配置文件来限制容器内可用的系统调用。性能与可扩展性容器池预热对于高并发场景可以预先创建并维护一个“温暖”的容器池执行时直接使用避免每次创建容器的开销。异步处理与队列将代码执行请求放入消息队列如 Redis、RabbitMQ由独立的 Worker 进程消费并执行避免 HTTP 请求线程被长时间阻塞。结果缓存对相同的代码和语言组合可以缓存执行结果一段时间减少重复计算。功能扩展支持更多语言在languageConfig中添加 Java、Go、C 等配置。需要构建包含对应编译/运行环境的 Docker 镜像。图形化输出对于 Python 的matplotlib可以安装xvfb等虚拟显示设备将图形渲染为图片返回给前端。代码分享与持久化为执行成功的代码生成一个唯一 ID并支持通过 URL 分享。这需要引入数据库如 SQLite、PostgreSQL来存储代码片段和结果。用户认证与配额增加用户登录功能并限制每个用户单位时间内的代码执行次数和资源消耗防止滥用。部署与监控容器化部署将前后端都 Docker 化使用docker-compose.yml统一管理便于一键部署。日志聚合将后端服务的访问日志、错误日志以及 Docker 容器的执行日志收集到 ELK 或 Loki 等日志系统中便于问题追踪。健康检查为后端服务添加/health端点本文已实现并配置 Kubernetes 或 Docker Swarm 的存活探针。监控告警监控服务器的 CPU、内存、磁盘 I/O 以及 Docker 容器的创建频率和失败率设置阈值告警。通过以上步骤我们完成了一个具备核心功能的“代码TV”工具。它不仅是一个演示项目更是一个理解 Web 全栈开发、容器安全、前后端交互的绝佳实践。你可以在此基础上根据实际需求参考最佳实践部分进行深化和扩展构建出更强大、更安全的在线代码执行平台。