OpenHealth项目PDF文件解析故障排查与解决方案

问题背景

在OpenHealth项目使用过程中，用户反馈上传PDF文件时出现解析失败问题。控制台显示"无法解构未定义的markdown属性"错误，该问题与文档解析服务密切相关。

错误现象分析

系统报错的核心在于文档解析环节未能正确提取markdown格式内容。经过排查发现：

1. 当使用Upstage AI服务时，无效的API密钥会导致解析服务拒绝请求
2. 系统生成的JSON错误日志中明确提示"API key is invalid"
3. 该问题会影响所有文件类型（包括PDF和PNG）的解析功能

根本原因

问题主要由以下因素导致：

1. 环境变量配置问题：Docker容器未正确继承.env文件中的UPSTAGE_API_KEY配置
2. 缓存文件干扰：之前解析失败的JSON缓存文件残留在系统目录中
3. 字符编码限制：初期版本对非拉丁字符集（如西里尔字母）支持不足

解决方案

配置修正方案

1. 修改docker-compose.yaml，显式声明环境变量：

environment:
  UPSTAGE_API_KEY: ${UPSTAGE_API_KEY}
  OPENAI_API_KEY: ${OPENAI_API_KEY}

2. 清理残留文件：

rm -rf public/uploads/*

多解析引擎支持

项目已进行以下改进：

1. 集成多种文档解析引擎作为备选方案
2. 增强字符编码处理能力
3. 优化错误处理机制

最佳实践建议

1. 对于非英语文档，建议先转换为UTF-8编码
2. 定期清理uploads目录下的缓存文件
3. 测试阶段可使用简单PDF文件验证基础功能
4. 关注服务商的字符集支持说明

技术展望

未来版本可考虑：

1. 增加自动字符编码检测
2. 实现解析引擎的智能切换
3. 加入本地OCR作为后备方案
4. 优化多语言支持体系

通过以上改进，OpenHealth项目的文件解析稳定性和兼容性将得到显著提升。