ai-business-write/技术文档/MinIO问题分析和解决方案.md

MinIO文档生成失败问题分析和解决方案

问题诊断结果

根据诊断脚本的结果，发现了以下问题：

✅ 正常的功能

1. MinIO连接 - 使用 secure=false 可以正常连接
2. 存储桶存在 - finyx 存储桶已存在
3. 文件上传 - 上传功能正常
4. 预签名URL生成 - URL生成功能正常

❌ 发现的问题

1. 环境变量配置错误（关键问题）

当前环境变量还是旧配置：

• MINIO_ENDPOINT: minio.datacubeworld.com:9000 ❌
  • 应该是: 10.100.31.21:9000
• MINIO_ACCESS_KEY: JOLXFXny3avFSzB0uRA5 ❌
  • 应该是: minio_PC8dcY
• MINIO_SECURE: true ❌
  • 应该是: false （重要：新服务器使用HTTP，不是HTTPS）

2. 模板文件缺失（关键问题）

数据库中的模板文件在新MinIO服务器上不存在：

• 例如：/615873064429507639/TEMPLATE/2025/12/8-1请示报告卡（初核报告结论） .docx
• 错误信息：Object does not exist

解决方案

步骤1：更新环境变量配置

方法A：使用修复脚本（推荐）

运行修复脚本自动创建/更新 .env 文件：

python fix_minio_config.py

方法B：手动创建/更新 .env 文件

在项目根目录创建或更新 .env 文件，内容如下：

# MinIO配置
MINIO_ENDPOINT=10.100.31.21:9000
MINIO_ACCESS_KEY=minio_PC8dcY
MINIO_SECRET_KEY=minio_7k7RNJ
MINIO_BUCKET=finyx
MINIO_SECURE=false  # 重要：新服务器使用HTTP，必须是false

⚠️ 重要提示：MINIO_SECURE 必须设置为 false，不是 true！

步骤2：迁移模板文件

模板文件需要从旧MinIO服务器迁移到新服务器，或者重新上传。

方法A：从旧服务器迁移（如果有访问权限）

1. 从旧MinIO服务器下载所有模板文件
2. 上传到新MinIO服务器

方法B：重新上传模板文件

1. 从本地模板目录重新上传模板文件
2. 确保文件路径与数据库中的 file_path 字段匹配

步骤3：验证配置

运行诊断脚本验证配置是否正确：

python diagnose_minio_document_generation.py

应该看到所有测试都通过。

步骤4：重启应用

重要：更新环境变量后，必须重启应用服务才能生效！

关于目录结构

MinIO是对象存储，不需要创建目录。

• 对象名称可以包含路径分隔符（如 /），MinIO会自动处理
• 例如：615873064429507639/TEMPLATE/2024/12/template.docx
• 上传文件时，MinIO会自动创建"虚拟目录"结构

常见问题

Q1: 为什么 MINIO_SECURE 必须是 false？

A: 新MinIO服务器 10.100.31.21:9000 使用HTTP协议，不支持HTTPS。如果设置为 true，客户端会尝试使用HTTPS连接，导致连接失败。

Q2: 如何确认服务器使用HTTP还是HTTPS？

A: 可以尝试访问 http://10.100.31.21:9000 和 https://10.100.31.21:9000，看哪个能正常访问。根据测试结果，该服务器只支持HTTP。

Q3: 模板文件路径格式是什么？

A: 模板文件路径格式为：/{tenant_id}/TEMPLATE/{year}/{month}/{filename}.docx

• 例如：/615873064429507639/TEMPLATE/2025/12/template.docx
• 这个路径存储在数据库的 f_polic_file_config.file_path 字段中

Q4: 如何检查模板文件是否存在？

A: 运行诊断脚本 diagnose_minio_document_generation.py，它会自动检查所有模板文件是否存在。

测试清单

完成修复后，请验证以下功能：

• MinIO连接正常
• 存储桶存在
• 模板文件可以下载
• 生成的文档可以上传
• 预签名URL可以正常生成
• 文档生成接口可以正常调用

相关文件

• diagnose_minio_document_generation.py - 诊断脚本
• fix_minio_config.py - 配置修复脚本
• test_minio_remote_server.py - MinIO连接测试脚本
• MinIO远程服务器测试结果.md - 之前的测试结果

联系支持

如果问题仍然存在，请提供：

1. 诊断脚本的完整输出
2. 应用日志中的错误信息
3. 具体的错误场景（哪个接口、哪个文件ID等）