本地运行与调试指南 #

本节介绍如何在您的开发机上导入并启动 Tduck 社区版的前后端源码，以便于您进行二次开发与 Debug。

💻 1. 开发环境准备 #

在开始之前，请确保您的开发环境中已安装并配置好以下基础软件：

• JDK 1.8 (目前社区版只支持 JDK 1.8 编译运行，切勿使用 JDK 11 或 JDK 17)
• MySQL 5.7+
• Redis (用于存储验证码、Session等，必须启动)
• Node.js (推荐版本 v14.x，建议不要使用太高版本以防依赖包冲突)
• IDE: IntelliJ IDEA (推荐后端) & VS Code (推荐前端)
• Maven: 3.6+

☕ 2. 后端服务启动 (tduck-platform) #

Step 1. 导入项目与数据库 #

1. 使用 IntelliJ IDEA 导入 tduck-platform 父目录，等待 Maven 依赖下载完成。
2. 创建本地数据库（例如名为 tduck），字符集选择 utf8mb4。
3. 导入项目源码目录下的数据库初始化文件：doc/tduck.sql。

Step 2. 配置修改 #

在 tduck-api 模块的 src/main/resources 目录下找到 application-dev.yml (或 application.yml)：

• 数据库配置：修改 spring.datasource.url、username 和 password 为您的本地 MySQL 信息。
• Redis 配置：修改 spring.redis.host、port 和 password，确保本地 Redis 已启动。
• 文件存储：如果是本地测试，可使用默认的 Local 模式，也可以参照 文件存储配置 对接阿里云 OSS。

Step 3. 启动项目 #

找到 tduck-api 模块下的启动主类 com.tduck.cloud.api.TduckApiApplication，直接在 IDEA 中右键点击 Run 启动。 启动成功后，终端会打印出类似如下的日志：

Tduck Application started successfully!
Port: 8999

🎨 3. 前端服务启动 (tduck-front) #

Step 1. 配置文件与代理说明 #

打开前端目录下的 .env.development，可以看到如下关键配置：

# 接口请求前缀，默认开发环境会设置到 axios 的 baseURL 上，并通过 Webpack 代理转发
VUE_APP_API_ROOT = /tduck-api
# 高德地图 key 用于定位/地理位置组件，可按需申请填写
VUE_APP_MAP_KEY = f2200337d0d08538e78729572749882d

打开 vue.config.js，定位到 devServer 部分，系统默认已配置好了反向代理拦截器：

devServer: {
  disableHostCheck: true,
  open: true,
  port: 8888, // 前端启动端口
  proxy: {
    '/tduck-api': {
      target: 'http://localhost:8999', // 确保该端口与后端 tduck-api 服务的启动端口一致
      changeOrigin: true,
      pathRewrite: {
        ['^' + process.env.VUE_APP_API_ROOT]: ''
      }
    }
  }
}

Step 2. 安装依赖并启动 #

打开终端命令行，进入 tduck-front 根目录：

# 1. 安装项目依赖
npm install

# 2. 启动前端本地开发服务器
npm run serve

启动成功后，浏览器会自动打开或控制台会输出本地地址，如 http://localhost:8888/。

⚙️ 4. 表单设计器模块联调 (高级/商业开发选读) #

由于 tduck-form-generator 作为 NPM 依赖引入，如果你获取了表单设计器的完整源码 (tduck-front-full/src/formgen)，可以通过以下命令快速切换本地依赖模式：

# 切换到本地开发软链调试模式 (在 tduck-front-full/src/formgen 中有 watch 任务时使用)
npm run formgen:dev

# 切换回发布引用的正式版本依赖
npm run formgen:prod

此操作会动态修改前端的 package.json 依赖配置并自动执行 npm install。普通开发者如果没有设计器源码，保持默认的 "tduck-form-generator": "1.9.5" 即可。

🔍 5. 联调测试与登录 #

1. 打开浏览器访问：http://localhost:8888
2. 使用默认管理员账号登录测试：
   • 账号：admin@tduckcloud.com
   • 密码：123456
3. 登录成功后即可在本地对表单进行拖拽设计、逻辑配置、数据收集预览等全流程断点调试。