常见问题与故障排查

403 访问被拒绝（CORS）

• 现象：返回 NotAllowed 或 403。
• 排查：检查 WHITE_LIST 是否包含请求来源主机名；在非浏览器请求（curl/Postman）可允许无 origin。

转换失败（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 依赖版本，修复安全与兼容性问题。