ljwx-chat/文件上传故障排查.md

文件上传失败故障排查指南

问题现象

上传文件时出现错误提示:

文件上传失败
请确认你的网络是否正常,并检查文件存储服务跨域配置是否正确

问题原因

根据代码分析，这个错误通常由以下原因导致:

1. MinIO 服务未运行 - 最常见原因
2. CORS 跨域配置不正确 - 浏览器阻止跨域请求
3. 网络连接问题 - 无法访问 S3 端点
4. S3 配置错误 - 环境变量配置不正确

快速解决步骤

1. 启动 MinIO 服务

# 启动 MinIO
docker-compose -f docker-compose.minio.yml up -d

# 检查 MinIO 是否运行
docker ps | grep minio

# 查看 MinIO 日志
docker logs lingjingwanxiang-minio

2. 配置 MinIO

# 运行配置脚本
./setup-minio.sh

脚本会自动完成:

• 创建 bucket lingjingwanxiang
• 设置公开访问策略
• 配置 CORS 跨域规则

3. 手动配置 CORS (如果脚本失败)

1. 访问 MinIO 控制台: http://localhost:9003
2. 使用账号密码登录: minioadmin / minioadmin
3. 进入 Buckets → lingjingwanxiang → Configuration
4. 找到 "Anonymous" 访问策略，设置为 public
5. 配置 CORS 规则:
   • Allowed Origins: *
   • Allowed Methods: GET, PUT, POST, DELETE, HEAD
   • Allowed Headers: *
   • Expose Headers: ETag, Content-Length

4. 验证配置

# 测试 MinIO 是否可访问
curl http://localhost:9002/minio/health/live

# 测试 bucket 是否可访问
curl http://localhost:9002/lingjingwanxiang/

# 如果使用外部 IP
curl http://192.168.1.83:9002/lingjingwanxiang/

5. 重启应用

# 重启 LobeChat 容器
docker-compose -f docker-compose.lingjingwanxiang.yml restart

环境变量检查清单

确认 docker-compose.lingjingwanxiang.yml 中的 S3 配置正确:

environment:
  # ✓ 正确 - 使用 path-style
  - S3_ENABLE_PATH_STYLE=1

  # ✓ 正确 - 容器内访问 host 上的 MinIO
  - S3_ENDPOINT=http://host.docker.internal:9002

  # ✓ 正确 - bucket 名称
  - S3_BUCKET=lingjingwanxiang

  # ✓ 正确 - 公开访问域名 (使用局域网 IP)
  - S3_PUBLIC_DOMAIN=http://192.168.1.83:9002

  # ✓ 正确 - MinIO 不需要设置 ACL
  - S3_SET_ACL=0

  # ✓ 正确 - 访问密钥
  - S3_ACCESS_KEY_ID=minioadmin
  - S3_SECRET_ACCESS_KEY=minioadmin

常见问题

Q1: 为什么使用 host.docker.internal ?

A: 因为 MinIO 运行在 host 机器上 (端口 9002), 而 LobeChat 运行在 Docker 容器中。容器需要通过 host.docker.internal 来访问 host 上的服务。

Q2: S3_PUBLIC_DOMAIN 为什么使用 192.168.1.83 ?

A: 这是浏览器访问上传文件的地址，必须是浏览器可以访问到的地址。如果浏览器在同一局域网，使用局域网 IP; 如果需要外网访问，需要配置公网 IP 或域名。

Q3: CORS 错误如何排查？

A: 打开浏览器开发者工具 (F12) → Console, 查看是否有 CORS 相关错误信息:

Access to XMLHttpRequest at 'http://...' from origin 'http://...' has been blocked by CORS policy

如果看到此错误，说明 CORS 配置不正确，需要按照上述步骤配置。

Q4: 文件上传后无法访问？

A: 检查:

1. Bucket 访问策略是否设置为 public
2. S3_PUBLIC_DOMAIN 是否配置正确
3. 浏览器是否可以直接访问 http://192.168.1.83:9002/lingjingwanxiang/

调试技巧

查看上传请求详情

1. 打开浏览器开发者工具 (F12)
2. 切换到 Network 标签页
3. 尝试上传文件
4. 查看失败的请求:
   • Status 0: 网络错误或 CORS 错误
   • Status 403: 权限不足
   • Status 404: Bucket 不存在
   • Status 500: 服务器错误

查看应用日志

# 查看 LobeChat 日志
docker logs -f lingjingwanxiang

# 查看 MinIO 日志
docker logs -f lingjingwanxiang-minio

生产环境建议

对于生产环境，建议:

1. 使用专业的 S3 服务 (如 Cloudflare R2、阿里云 OSS)
2. 配置 HTTPS - 避免安全警告
3. 设置更严格的 CORS 规则 - 只允许特定域名访问
4. 使用强密码 - 不要使用 minioadmin
5. 定期备份 - 配置 MinIO 数据卷备份

需要帮助？

如果按照上述步骤仍然无法解决问题，请提供:

1. 浏览器控制台错误信息
2. LobeChat 容器日志
3. MinIO 容器日志
4. 网络请求详情 (Network 标签页)