big-AGI故障排查：常见问题与解决方案速查手册
项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI 一、部署与启动故障
1.1 本地开发环境启动失败
| 症状 | 可能原因 | 解决方案 | 验证步骤 |
|---|---|---|---|
npm run dev 无响应 | Node.js版本不兼容 | 安装Node.js 18.x LTS版本nvm install 18 && nvm use 18 | node -v 显示18.x.x |
| 端口3000被占用 | 其他服务占用默认端口 | 修改启动命令npm run dev -- -p 3001 | 访问 http://localhost:3001 |
| 依赖安装时报错 | npm缓存损坏 | 清理缓存并重新安装npm cache clean --force && rm -rf node_modules && npm install | 无错误输出 |
完整启动流程验证
# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/bi/big-AGI
cd big-AGI
# 验证Node版本
node -v # 需显示v18.x.x
# 安装依赖
npm install
# 启动开发服务器
npm run dev
# 预期输出
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
1.2 Docker部署异常
常见Docker命令：
# 构建镜像
docker build -t big-agi .
# 后台运行容器
docker run -d -p 3000:3000 --name big-agi-container big-agi
# 查看实时日志
docker logs -f big-agi-container
# 停止并删除容器
docker stop big-agi-container && docker rm big-agi-container
二、API配置问题
2.1 OpenAI API连接失败
错误排查流程
-
验证API密钥格式
正确格式：sk-开头的51位字符串
❌ 错误示例：sk-proj-开头（新格式需调整权限）、包含空格或换行 -
检查网络连接
# 测试API连通性 curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY"预期返回：模型列表JSON
-
配置环境变量
创建.env.local文件：OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx NEXT_PUBLIC_DEFAULT_MODEL=gpt-4
2.2 本地模型集成问题（Ollama/LocalAI）
| 模型类型 | 典型配置错误 | 解决方案 |
|---|---|---|
| Ollama | 无法连接本地服务 | 检查Ollama服务状态systemctl status ollama确保环境变量 OLLAMA_BASE_URL=http://host.docker.internal:11434 |
| LocalAI | 模型未加载 | 确认models目录包含正确文件ls -l /path/to/localai/models重启LocalAI服务 |
| LM Studio | 端口配置错误 | 在应用设置中开启"Allow network access" 使用端口1234 |
Ollama配置示例：
# .env.local文件
OLLAMA_BASE_URL=http://localhost:11434
NEXT_PUBLIC_OLLAMA_DEFAULT_MODEL=llama3
三、功能模块故障
3.1 聊天功能异常
3.1.1 消息无法发送
3.1.2 文件上传失败
- 文件大小限制：默认限制20MB，修改
.env.local
NEXT_PUBLIC_MAX_ATTACHMENT_SIZE=52428800（50MB） - 不支持的文件类型：检查
src/common/attachment-drafts/attachment.mimetypes.ts
添加新类型：export const ALLOWED_MIME_TYPES = [..., 'application/pdf']
3.2 数据库连接问题
PostgreSQL配置验证：
# 测试数据库连接
psql "postgres://USER:PASS@SOMEHOST.postgres.vercel-storage.com/SOMEDB"
# 初始化数据库
npx prisma db push
# 查看数据库状态
npx prisma studio
MongoDB替代方案： 修改src/server/prisma/schema.prisma：
datasource db {
provider = "mongodb"
url = env("MDB_URI")
}
model LinkStorage {
id String @id @default(uuid()) @map("_id")
// ...其他定义
}
四、高级故障排查
4.1 日志分析
关键日志位置：
- 开发环境：控制台输出
- Docker环境：
docker logs -f big-agi-1 - 生产环境：
src/server/logger/viewer/
常见错误模式及解决：
# API密钥错误
ERROR: AuthenticationError: Invalid API key
# 解决方案：重新配置API密钥
# 路径：设置 > 模型 > OpenAI > 编辑密钥
# 数据库迁移错误
ERROR: P1001: Can't reach database server
# 解决方案：检查数据库连接字符串
# 环境变量：POSTGRES_PRISMA_URL
4.2 性能优化
当应用响应缓慢时：
-
前端优化
- 清除缓存：
Ctrl+Shift+R强制刷新 - 禁用不必要扩展：设置 > 实验室 > 禁用实验性功能
- 清除缓存：
-
后端调优
# .env.local 性能相关配置 NEXT_PUBLIC_STREAMING=true NEXT_PUBLIC_MODEL_CACHE_TTL=300 # 缓存5分钟 API_TIMEOUT=60000 # 超时时间60秒
五、版本升级问题
5.1 升级步骤
5.2 版本不兼容处理
| 问题场景 | 解决方案 |
|---|---|
| 数据库架构变更 | 执行迁移命令npx prisma migrate dev --name init |
| 环境变量新增 | 对比.env.example与现有.env.local添加缺失变量 |
| UI组件异常 | 清除构建缓存npm run clean && npm run build |
六、常见问题速查表
| 问题描述 | 快速解决方案 |
|---|---|
| 无法登录自部署实例 | 检查deploy-authentication.md配置默认用户：admin/CHANGE_ME |
| 语音功能不工作 | 确认浏览器权限 设置 > 网站设置 > 麦克风 |
| 分享链接无法访问 | 检查数据库配置 启用 NEXT_PUBLIC_ENABLE_LINK_SHARING=true |
| 代码执行无结果 | 检查config-feature-browse.md配置浏览器服务 |
七、获取支持
-
查看官方文档
本地文档路径：docs/目录下相关文件 -
提交Issue
访问项目仓库提交详细错误报告，包含：- 复现步骤
- 错误截图
- 相关日志
- 环境信息（系统、浏览器、版本）
-
社区支持
加入Discord社区获取实时帮助（链接见项目README）
读完本文你将能够：
- 诊断并解决90%的常见部署问题
- 配置各种AI模型后端连接
- 优化应用性能和稳定性
- 安全地进行版本升级
收藏本文，以备日后排查故障时快速参考。如有其他未覆盖的问题，欢迎在评论区留言反馈。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
