故障排查

问题：

• 运行 yarn dev 时提示 Node.js 版本错误
• 某些依赖包安装失败
• 构建过程中出现语法错误

解决方案：

• 确保 Node.js 版本 ≥ 18.18
• 使用 nvm 或 corepack 管理 Node.js 版本
• 运行 `node --version` 检查当前版本
• 如果使用 corepack，运行 `corepack enable` 启用

问题：

• yarn install 执行失败
• 依赖包下载超时
• 权限错误

解决方案：

• 检查网络连接，可能需要配置代理
• 清除缓存：`yarn cache clean`
• 删除 node_modules 和 yarn.lock，重新安装
• 使用 corepack 管理 Yarn：`corepack prepare yarn@1.22.22 --activate`

问题：

• docker compose up 报错
• 容器无法启动
• 端口被占用

解决方案：

• 检查 Docker 和 Docker Compose 是否正确安装
• 检查端口占用：`lsof -i :5432`（PostgreSQL）、`lsof -i :6379`（Redis）
• 查看容器日志：`docker compose logs [service-name]`
• 尝试重启服务：`docker compose restart [service-name]`
• 清理并重新创建：`docker compose down -v && docker compose up -d`

问题：

• 应用启动后无法连接数据库
• Redis 连接失败
• API 调用返回认证错误

解决方案：

• 检查 .env.local 文件是否存在且格式正确
• 确认 DATABASE_URL 格式：`postgresql://user:password@host:port/database`
• 确认 REDIS_URL 格式：`redis://host:port`
• 检查 AUTH_SECRET 是否已设置（运行 `openssl rand -base64 32` 生成）
• 重启开发服务器使环境变量生效

问题：

• 应用启动时报错：无法连接到数据库
• Prisma Client 初始化失败
• 数据库查询超时

解决方案：

• 检查 PostgreSQL 服务是否运行：`docker compose ps db`
• 验证 DATABASE_URL 环境变量是否正确
• 测试数据库连接：`psql $DATABASE_URL`
• 检查数据库是否已创建：`psql -l`
• 查看数据库日志：`docker compose logs db`

问题：

• yarn prisma migrate deploy 执行失败
• 数据库架构不匹配
• 迁移文件冲突

解决方案：

• 检查数据库连接是否正常
• 查看迁移历史：`yarn prisma migrate status`
• 重置数据库（开发环境）：`yarn prisma migrate reset`
• 手动应用迁移：`yarn prisma migrate deploy`
• 重新生成 Prisma Client：`yarn prisma generate`

问题：

• yarn prisma studio 命令无响应
• 浏览器无法访问 Prisma Studio

解决方案：

• 检查数据库连接
• 确认端口 5555 未被占用
• 尝试使用其他端口：`yarn prisma studio --port 5556`
• 检查防火墙设置

问题：

• 应用启动时报 Redis 连接错误
• 队列任务无法执行
• Worker 无法消费任务

解决方案：

• 检查 Redis 服务是否运行：`docker compose ps redis`
• 验证 REDIS_URL 环境变量
• 测试 Redis 连接：`redis-cli -u $REDIS_URL ping`
• 查看 Redis 日志：`docker compose logs redis`
• 检查 Redis 内存使用：`redis-cli info memory`

问题：

• 任务执行缓慢
• 队列中任务数量持续增长
• Worker 处理速度跟不上

解决方案：

• 检查 Worker 服务是否正常运行
• 增加 Worker 实例数量
• 查看队列状态：`yarn queue:ui`（如果配置了 Bull Board）
• 检查 Redis 内存使用情况
• 清理失败的任务：`redis-cli FLUSHDB`（谨慎使用）

问题：

• 批量翻译任务失败
• Worker 日志显示错误
• 任务状态一直为 PENDING

解决方案：

• 查看 Worker 日志：`docker compose logs worker`
• 检查任务数据格式是否正确
• 验证相关服务（Milvus、MinIO、PDFMath）是否正常
• 检查 API 密钥和配置是否正确
• 查看 Redis 中的失败任务：`redis-cli KEYS 'bull:*:failed'`

问题：

• 翻译记忆库搜索失败
• 向量写入失败
• Milvus 服务无法访问

解决方案：

• 检查 Milvus 和 etcd 服务是否运行：`docker compose ps milvus etcd`
• 验证 Milvus 连接配置
• 查看 Milvus 日志：`docker compose logs milvus`
• 检查 etcd 状态：`docker compose logs etcd`
• 访问 Attu UI（http://localhost:8001）检查 Milvus 状态

问题：

• 搜索时提示集合不存在
• 向量写入失败，提示集合未找到

解决方案：

• 检查集合是否已创建
• 在 Attu UI 中查看集合列表
• 重新初始化集合（应用会自动创建）
• 检查集合名称是否正确

问题：

• 向量写入失败，提示维度错误
• 搜索时返回维度不匹配错误

解决方案：

• 检查嵌入模型配置，确保维度一致（默认 1536）
• 删除并重建集合（开发环境）
• 验证向量生成代码中的维度设置

问题：

• 文档解析失败
• PDF 文件上传后无法处理
• 解析任务一直处于 PENDING 状态

解决方案：

• 检查 PDFMath 服务是否运行：`docker compose ps pdfmath`
• 查看 PDFMath 日志：`docker compose logs pdfmath`
• 验证 PDFMath 服务 URL 配置
• 测试服务连接：`curl http://localhost:8000/health`（如果配置了健康检查）
• 检查 PDF 文件是否损坏或格式不支持

问题：

• 大文件解析时间过长
• 解析任务超时失败

解决方案：

• 检查文件大小（建议不超过 100MB）
• 增加超时时间配置
• 检查 PDFMath 服务资源使用情况
• 考虑将大文件拆分为多个小文件

问题：

• 文件上传失败
• 文档预览无法加载
• 存储操作报错

解决方案：

• 检查 MinIO 服务是否运行：`docker compose ps minio`
• 验证 MINIO_ACCESS_KEY 和 MINIO_SECRET_KEY 配置
• 检查 MINIO_BUCKET 是否存在
• 查看 MinIO 日志：`docker compose logs minio`
• 访问 MinIO Console（默认 http://localhost:9001）检查状态

问题：

• 文档上传后无法保存
• 上传进度卡住
• 存储空间不足错误

解决方案：

• 检查磁盘空间：`df -h`
• 验证 MinIO 存储路径权限
• 检查文件大小限制
• 查看 MinIO 错误日志
• 验证 S3 兼容 API 配置

问题：

• docker compose up worker 失败
• 本地 yarn dev:worker 报错
• Worker 进程立即退出

解决方案：

• 检查环境变量配置
• 验证 Redis 连接
• 查看 Worker 日志：`docker compose logs worker`
• 检查 Node.js 版本
• 验证依赖是否正确安装
• 检查构建产物：`yarn build:worker`

问题：

• 任务一直处于 PENDING 状态
• 队列中有任务但 Worker 不消费

解决方案：

• 检查 Worker 是否正常运行
• 验证队列名称配置是否正确
• 检查 Worker 日志中的错误信息
• 确认 Worker 订阅了正确的队列
• 重启 Worker 服务

问题：

• 页面响应时间长
• 首次加载很慢
• API 请求超时

解决方案：

• 检查数据库查询性能，使用 Prisma Studio 分析
• 优化数据库索引
• 检查 Redis 缓存是否正常工作
• 查看浏览器网络面板分析请求时间
• 检查服务器资源使用情况（CPU、内存）

问题：

• 登录后立即退出
• Session 无法保持
• API 请求返回 401

解决方案：

• 检查 AUTH_SECRET 是否已设置
• 验证 NEXTAUTH_URL 配置是否正确
• 清除浏览器 Cookie 和 LocalStorage
• 检查 NextAuth 配置
• 查看服务器日志中的认证错误

问题：

• API 请求返回 404
• Server Actions 执行失败
• 路由无法访问

解决方案：

• 检查路由文件是否存在
• 验证 API 路径是否正确
• 查看 Next.js 构建日志
• 检查中间件配置
• 验证请求方法和参数