社区版常见问题与排错指南 #

在部署和运行 Tduck 社区版时，如果遇到故障，请先对照以下常见错误及排错方案进行自查。

1. 运行不起来 (启动没有任何日志) #

• 根本原因：服务器未安装 Java 运行环境，或环境变量配置错误。
• 排错方案：
  1. 在命令行中运行 java -version，检查是否正确输出了 Java 版本信息。
  2. 如果提示命令不存在，请参考对应系统的 JDK 安装指南，先安装 JDK 1.8 并配置好 JAVA_HOME 环境变量。

2. 报错：invalid file bad magic number exec format error #

• 根本原因：部署命令中指定的 jar 包路径不正确，或者下载传输过程中 jar 包损坏。
• 排错方案：
  1. 检查运行命令中的 Jar 包绝对路径，确认该路径下确实存在该文件。
  2. 尝试在本地重新上传 Jar 包，确保传输模式为二进制（Binary），避免传输中文件损坏。

3. 数据库导入后没有表 #

• 根本原因：在宝塔等面板中创建数据库后，仅上传了 SQL 文件但未执行“导入”操作。
• 排错方案：
  1. 如果在宝塔部署，请进入数据库列表，找到对应的数据库，确认点击了“导入”按钮。
  2. 如果宝塔导入失败，建议使用本地的 Navicat 或 DBeaver 等数据库客户端，手动连接服务器并执行项目下的 doc/tduck.sql 文件。

4. 报错：Could not initialize class ... SerializedLambdaMeta #

• 根本原因：使用了高版本的 JDK（如 JDK 11, JDK 17 等）运行项目，导致 MyBatis-Plus 的反射兼容性问题。
• 排错方案：
  • 必须使用 JDK 1.8 运行后端项目，请勿使用任何高版本。请在启动前确认执行命令的 java 路径指向的是 Java 8。

5. 页面发布后访问 404 或预览 404 #

• 根本原因：Nginx 没有配置单页面应用（SPA）的路由重定向。
• 排错方案：
  • 请修改您部署前端对应的 Nginx 虚拟主机配置文件，在 location / 块中加入 try_files $uri $uri/ /index.html;。例如：
  nginx

  location / {
      root   /www/wwwroot/tduck-front;
      index  index.html index.htm;
      try_files $uri $uri/ /index.html; # [!code hl]
  }
  

  • 修改后重新加载 Nginx 配置（nginx -s reload）。

6. 文件/图片上传不了，提示保存失败 #

• 根本原因：使用的是源码或前后端分离部署，但未在配置文件中配置有效的存储介质。
• 排错方案：
  1. Tduck 默认不支持空配置上传。如果是本地开发调试，需要按照 文件存储设置 配置本地磁盘路径。
  2. ⚠️ 特别注意：修改了后端的 application-dev.yml / application-prod.yml 配置文件后，必须重新对后端项目进行打包编译 (Maven Package)，然后再运行新生成的 jar 包，否则配置不会生效。

7. 点击登录报错 / 接口请求 500 #

• 根本原因：后端服务未启动，或者后端服务与数据库/Redis 的连接中断。
• 排错方案：
  1. 检查后端服务的控制台，查看是否有数据库连接超时的报错。
  2. 确认数据库是否已经正确初始化，且连接配置无误。社区版 TDuck 采用 Ehcache 本地内存加磁盘缓存（而不是 Redis）处理会话，因此不需要安装 Redis。
  3. 确认后端的配置文件中没有多余的空格或缩进错误。