🚀 快速启动（使用源码运行） #

本指南将帮助你在本地快速运行 TDUCK 社区版前后端项目。

一、最小开发环境 #

请确保本地或服务器已安装以下环境：

建议使用 Linux 或 macOS 环境，Windows 请使用 PowerShell / Git Bash。

二、启动步骤 #

1️⃣ 创建数据库 #

1. 创建数据库（字符集建议：utf8mb4）
2. 执行项目目录中的初始化脚本：

doc/tduck.sql

2️⃣ 启动后端服务 #

进入后端项目根目录，执行：

mvn clean install -DskipTests
cd tduck-platform/tduck-api
mvn clean package -DskipTests
java -Dfile.encoding=UTF-8 -jar target/tduck-api.jar

启动成功后，默认服务端口：8998

3️⃣ 启动前端项目 #

进入前端项目根目录：

npm config set registry https://registry.npmmirror.com
cd tduck-front
npm install   # 或 cnpm install
npm run serve

启动成功后，前端默认端口：8888

4️⃣ 访问系统 #

浏览器打开：

http://localhost:8888

即可进入 TDUCK 管理与表单系统界面。

三、常见问题提示 #

• 请确认后端服务已成功启动且无报错
• 数据库账号信息需与 application.yml 中保持一致
• 如端口被占用，可在配置文件中自行修改
• Node 版本过低可能导致依赖安装失败

四、常见启动问题排查 #

1️⃣ 后端启动失败 / 端口无法访问 #

现象：

• java -jar 启动后直接退出
• 浏览器访问 http://localhost:8998 无响应

排查点：

• 是否安装 JDK 1.8（不是 11 / 17）

  bash

  java -version
  

• 端口是否被占用：

  bash

  lsof -i:8998
  

• 是否成功打包生成：

  tduck-api/target/tduck-api.jar
  

2️⃣ 数据库连接失败 #

现象：

• 启动报错：Cannot create PoolableConnectionFactory
• 控制台提示账号密码错误

排查点：

• MySQL 是否启动

• 数据库是否已执行 tduck.sql

• 检查 application.yml / application-custom.yml：

  yaml

  spring:
    datasource:
      url: jdbc:mysql://localhost:3306/tduck?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
      username: root
      password: xxxx
  

3️⃣ 前端依赖安装失败 #

现象：

• npm install 卡住
• 报 node-sass、ELIFECYCLE 错误

解决：

npm config set registry https://registry.npmmirror.com
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

4️⃣ 页面空白 / 接口 404 #

现象：

• 页面可以打开，但登录失败或数据为空

排查：

• 后端是否正常启动

• 前端 .env.development 中 API 地址是否正确：

  VUE_APP_BASE_API=http://localhost:8998
  

5️⃣ 端口被占用 #

修改方式：

• 后端：server.port=xxxx
• 前端：vue.config.js 中 devServer.port