E2B Fragments用户支持：问题排查与故障诊断指南
项目地址: https://gitcode.com/GitHub_Trending/fr/fragments 概述
E2B Fragments是一个基于Next.js 14的开源AI应用生成平台，集成了多种LLM提供商和代码执行环境。本文档提供全面的问题排查指南，帮助开发者快速定位和解决使用过程中遇到的各种问题。
快速诊断流程图
环境配置问题排查
1. 基础环境验证
Node.js版本兼容性检查
# 检查Node.js版本
node --version
# 要求: Node.js 18+
# 推荐: Node.js 20+
# 检查npm版本
npm --version
依赖安装验证
# 清理并重新安装依赖
rm -rf node_modules package-lock.json
npm install
# 验证关键依赖
npm list @e2b/code-interpreter
npm list next
npm list ai
2. 环境变量配置
必需环境变量检查表
| 变量名 | 描述 | 获取地址 | 验证方法 |
|---|---|---|---|
E2B_API_KEY | E2B代码解释器API密钥 | e2b.dev | 访问E2B控制台 |
OPENAI_API_KEY | OpenAI API密钥 | platform.openai.com | 调用测试API |
ANTHROPIC_API_KEY | Anthropic API密钥 | console.anthropic.com | 验证配额状态 |
| 其他LLM密钥 | 对应提供商API密钥 | 各提供商控制台 | 分别验证 |
环境变量配置文件示例
# .env.local 完整配置示例
E2B_API_KEY="e2b_xxxxxxxxxxxxxxxx"
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"
# 可选配置
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
RATE_LIMIT_MAX_REQUESTS=10
RATE_LIMIT_WINDOW="1m"
运行时问题排查
1. 应用启动故障
常见启动错误及解决方案
| 错误类型 | 症状 | 解决方案 |
|---|---|---|
| 端口占用 | Error: listen EADDRINUSE: address already in use :::3000 | 更改端口: npm run dev -- -p 3001 |
| 内存不足 | JavaScript heap out of memory | 增加内存: NODE_OPTIONS="--max-old-space-size=4096" |
| 模块缺失 | Cannot find module '@e2b/code-interpreter' | 重新安装依赖: npm install |
启动诊断命令
# 检查Next.js构建状态
npm run build
# 开发模式详细日志
npm run dev 2>&1 | tee dev.log
# 生产环境测试
npm run build && npm start
2. 代码执行问题
E2B沙箱执行故障排查
// 代码执行状态检查示例
const { exec } = require('@e2b/code-interpreter')
async function testSandbox() {
try {
const result = await exec('python3', ['-c', 'print("Hello World")'])
console.log('沙箱状态:', result.success ? '正常' : '异常')
console.log('输出:', result.stdout)
console.log('错误:', result.stderr)
} catch (error) {
console.error('沙箱连接失败:', error.message)
}
}
常见执行错误代码表
| 错误代码 | 含义 | 解决方案 |
|---|---|---|
E2B_CONNECTION_ERROR | 无法连接到E2B服务 | 检查网络和API密钥 |
SANDBOX_TIMEOUT | 执行超时 | 增加超时时间或优化代码 |
DEPENDENCY_MISSING | 缺少依赖包 | 更新Dockerfile配置 |
AI集成问题排查
1. LLM提供商配置验证
多提供商支持矩阵
| 提供商 | 配置变量 | 基础URL | 状态检查 |
|---|---|---|---|
| OpenAI | OPENAI_API_KEY | 默认 | curl https://api.openai.com/v1/models |
| Anthropic | ANTHROPIC_API_KEY | 默认 | 检查控制台配额 |
| Google AI | GOOGLE_AI_API_KEY | 默认 | 验证项目配置 |
| Mistral | MISTRAL_API_KEY | 默认 | 测试模型访问 |
LLM连接测试脚本
# 测试OpenAI连接
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
https://api.openai.com/v1/models
# 测试Anthropic连接
curl -H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
https://api.anthropic.com/v1/messages \
-d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"Hello"}]}'
2. 模型响应异常处理
响应错误代码解析
| HTTP状态码 | 错误类型 | 处理建议 |
|---|---|---|
| 401 | 未授权 | 检查API密钥和权限 |
| 429 | 速率限制 | 调整请求频率或升级套餐 |
| 500 | 服务器错误 | 重试或联系提供商支持 |
认证与授权问题
1. Supabase集成排查
认证状态检查
// 认证状态监控示例
import { supabase } from '../lib/supabase'
// 检查Supabase初始化
if (!supabase) {
console.error('Supabase未正确初始化')
// 检查环境变量: SUPABASE_URL, SUPABASE_ANON_KEY
}
// 监听认证状态变化
supabase.auth.onAuthStateChange((event, session) => {
console.log('认证事件:', event)
console.log('会话状态:', session ? '已登录' : '未登录')
})
常见认证问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 无法登录 | Supabase配置错误 | 验证环境变量和网络连接 |
| 会话丢失 | 浏览器存储问题 | 清除缓存或检查存储权限 |
| API密钥获取失败 | 数据库权限问题 | 检查Supabase表权限设置 |
性能优化与监控
1. 资源使用监控
关键性能指标
| 指标 | 正常范围 | 异常处理 |
|---|---|---|
| 内存使用 | < 500MB | 检查内存泄漏或优化代码 |
| CPU占用 | < 70% | 分析计算密集型操作 |
| 响应时间 | < 2s | 优化AI调用或缓存策略 |
监控配置示例
// 添加性能监控
const { performance } = require('perf_hooks')
async function monitorOperation(operationName, operation) {
const start = performance.now()
try {
const result = await operation()
const duration = performance.now() - start
console.log(`${operationName} 耗时: ${duration.toFixed(2)}ms`)
return result
} catch (error) {
console.error(`${operationName} 执行失败:`, error)
throw error
}
}
2. 日志与调试
结构化日志配置
// 增强调试信息
console.debug = function(...args) {
if (process.env.NODE_ENV === 'development') {
console.log('[DEBUG]', new Date().toISOString(), ...args)
}
}
// 错误处理增强
process.on('unhandledRejection', (reason, promise) => {
console.error('未处理的Promise拒绝:', reason)
// 可在此添加错误上报
})
高级故障诊断
1. 网络问题排查
网络连接测试
# 测试E2B服务连通性
ping api.e2b.dev
# 测试端口连通性
nc -zv api.e2b.dev 443
# 检查DNS解析
nslookup api.e2b.dev
2. 安全配置验证
安全最佳实践检查表
| 检查项 | 状态 | 建议 |
|---|---|---|
| API密钥保密 | ✅ | 使用环境变量，不提交到版本控制 |
| HTTPS强制 | ✅ | 生产环境启用SSL |
| 速率限制 | ⚠️ | 配置合理的限流策略 |
| 输入验证 | ✅ | 对所有用户输入进行验证 |
紧急恢复步骤
1. 系统完全故障恢复
# 1. 停止当前服务
pkill -f "next dev"
pkill -f "node"
# 2. 清理并重新安装
rm -rf node_modules .next
npm install
# 3. 验证环境配置
cat .env.local | grep -E "(API_KEY|URL)"
# 4. 重新启动
npm run dev
2. 数据备份与恢复
关键数据备份清单
- 环境配置文件 (.env.local)
- 自定义模板配置 (sandbox-templates/)
- 模型配置文件 (lib/models.json)
- 模板配置文件 (lib/templates.json)
支持资源与后续步骤
1. 自助诊断工具
创建诊断脚本 diagnose.js:
const { execSync } = require('child_process')
console.log('=== E2B Fragments 系统诊断 ===')
// 检查Node.js环境
try {
const nodeVersion = execSync('node --version').toString().trim()
console.log('✅ Node.js版本:', nodeVersion)
} catch (error) {
console.log('❌ Node.js未正确安装')
}
// 检查关键依赖
const dependencies = ['@e2b/code-interpreter', 'next', 'ai']
dependencies.forEach(dep => {
try {
execSync(`npm list ${dep} --depth=0`)
console.log(`✅ ${dep} 已安装`)
} catch {
console.log(`❌ ${dep} 未安装`)
}
})
2. 问题上报模板
当需要寻求技术支持时，请提供以下信息：
问题描述模板
## 环境信息
- 操作系统: [例如 Ubuntu 22.04]
- Node.js版本: [例如 v20.15.0]
- npm版本: [例如 10.7.0]
## 错误信息
[粘贴完整的错误日志]
## 重现步骤
1.
2.
3.
## 预期行为
[描述期望的结果]
## 实际行为
[描述实际发生的情况]
## 已尝试的解决方案
- [ ] 重新安装依赖
- [ ] 验证环境变量
- [ ] 检查网络连接
通过本指南的系统性排查，大多数E2B Fragments使用问题都能得到快速解决。如遇复杂问题，建议按照问题上报模板收集完整信息后寻求社区或官方支持。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
