常见问题与故障排查

转换失败（500）

• 现象：文档转换，错误原因: ...。
• 排查：
  • 确认文件格式是否受支持（确保扩展名与 MIME 类型一致）。
  • 检查磁盘权限以及目录是否存在（UPLOAD_DIR/CONVERTED_DIR）。
  • 检查日志，并根据 X-Task-Id 追踪相应链路。

数据库连接错误 / 表初始化失败

• 现象：启动时控制台提示 数据表创建失败。
• 排查：
  • 检查 DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME。
  • 确认 MySQL 服务已启动且网络可达。
  • 尝试使用手动 SQL 语句创建数据库和授权。

下载原始文件失败

• 现象：404 文件不存在 或下载网络文件返回非 200。
• 排查：
  • 本地路径是否正确；文件是否已被清理或未保存（例如，若 UPLOAD_DIR 未设置，文件可能不会被保存）。
  • 网络 URL 是否可跨域访问且无需认证。

命中缓存但文件不一致

• 现象：X-From-Cache: true，但内容与预期不同。
• 排查：
  • 检查 FILE_HASH_ALGORITHM 和哈希计算方式是否稳定。
  • 对文件内容变化较小但哈希值未变的情况，进行二次校验（例如增加时间戳或元数据）。

大文件与性能问题

• 现象：转换慢或服务卡顿。
• 排查：
  • 调整 MAX_FILE_SIZE 和并发数；考虑队列化处理。
  • 升级 CPU / 内存；考虑使用对象存储和 CDN。

Webhook 未收到

• 现象：业务系统未收到回调。
• 排查：
  • 检查 CONVERTED_WEBHOOK_URL 是否正确且可被公网访问。
  • 网络或防火墙策略是否阻断。

端口占用

• 现象：服务无法启动，提示端口已被占用。
• 排查：更换 PORT 或释放占用进程（PM2/其他服务）。

版本与依赖问题

• 建议：定期更新 Node.js、NPM 依赖版本，修复安全与兼容性问题。