快速上手
本指南将帮助您在本地机器上搭建 Tagtag Starter 的后端服务和前端应用。别担心，我们会一步一步带您完成整个过程，就像教小朋友走路一样简单。
环境要求
确保您已安装以下软件。如果没有，赶紧去安装吧，别磨蹭了。
后端
- Java JDK 17+ - 没错，我们用的是最新的 Java，跟上时代潮流
- Maven 3.8+ - 依赖管理的好帮手，不用自己手动下载 jar 包了
- MySQL 8.0+ - 数据存储的基石，数据都靠它
- Redis 6.0+ - 缓存加速的神器，让系统飞起来
前端
- Node.js >= 20.12.0 - 前端运行的基础环境
- pnpm >= 10.0.0 - 比 npm 更快的包管理器，用过都说好
安装步骤
1. 克隆仓库
git clone https://github.com/tagtag-dev/tagtag-starter.git
cd tagtag-starter
这一步应该不会出问题吧？如果出问题了，检查一下您的网络连接，或者换个姿势试试。
2. 初始化数据库 (后端)
- 创建数据库：在 MySQL 中创建一个名为
tagtag的数据库。
CREATE DATABASE tagtag CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
记住，数据库名字必须是 tagtag，别自己发挥改成别的名字，不然系统会找不到数据库的。
- 自动初始化：Tagtag Starter 使用 Spring Boot 的自动初始化功能，会在应用启动时自动执行数据库脚本。没错，就是这么智能，不用您手动导入 SQL 文件了。
脚本位置：
- 表结构脚本：各模块下的
src/main/resources/db/schema.sql - 初始数据脚本：各模块下的
src/main/resources/db/data/目录
自动加载配置（已在 backend/tagtag-start/src/main/resources/application-dev.yml 中配置）：
spring:
datasource:
init:
mode: always
schema-locations:
- classpath*:db/schema.sql
data-locations:
- classpath*:db/data/**.sql
- 初始数据说明：
- 管理员账号：
admin/admin123- 超级管理员，拥有所有权限 - 普通用户账号：
user/user123- 普通用户，权限有限 - 初始角色：超级管理员、管理员、普通用户 - 权限分级，各司其职
- 初始菜单：系统管理、用户管理、角色管理、菜单管理等 - 该有的都有了
记住这些初始账号密码，别到时候登录不上又来找我们。
3. 配置应用 (后端)
编辑 backend/tagtag-start/src/main/resources/application.yml 以匹配您的本地环境（数据库凭据、Redis 主机）。
spring:
datasource:
url: jdbc:mysql://localhost:3306/tagtag?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
username: root
password: your_password
data:
redis:
host: localhost
port: 6379
把 your_password 替换成您真实的数据库密码。别用默认密码，不然被黑客攻破了可别怪我们没提醒您。
4. 启动后端服务
cd backend
mvn clean package -DskipTests
java -jar tagtag-start/target/tagtag-start-0.0.1-SNAPSHOT.jar
或者，直接在您的 IDE 中运行 TagtagApplication.java。如果您用的是 IDEA，直接右键运行就行，不用我们教了吧？
等一会儿，看到控制台输出一堆日志，最后出现类似 "Started TagtagApplication in X.XXX seconds" 的信息，就说明启动成功了。恭喜您，后端服务已经跑起来了！
5. 启动前端应用
- 进入前端目录：
cd frontend - 安装依赖：
pnpm install
这一步可能需要一点时间，毕竟要下载那么多依赖包。耐心等待，别急，好饭不怕晚。
- 启动开发服务器：
pnpm run dev
看到类似 "Local: http://localhost:5666/" 的信息，就说明前端也启动成功了。太棒了，前后端都跑起来了！
验证
启动成功后，您可以访问以下地址来验证系统是否正常运行：
- 前端应用: 访问 http://localhost:5666 - 登录界面，用 admin/admin123 登录试试
- 后端 API 文档: 访问 http://localhost:8080/index.html (Scalar) - 看看系统提供了哪些 API 接口
- 健康检查: 访问 http://localhost:8080/actuator/health - 检查后端服务是否健康
如果这些地址都能正常访问，恭喜您，您已经成功搭建了 Tagtag Starter 系统！给自己鼓个掌吧！
常见问题与解决方案
如果不幸遇到了问题，别慌，我们准备了一份常见问题清单，看看能不能帮到您。
1. 数据库连接失败
问题描述：应用启动时出现数据库连接错误。
解决方案：
- 检查 MySQL 服务是否正常运行 - 先确认服务没挂
- 确认数据库名称、用户名和密码是否正确 - 别输错了
- 检查数据库地址和端口是否正确 - 默认是 localhost:3306
- 确认数据库用户具有足够的权限 - 给它足够的权限，别太抠门
2. Redis 连接失败
问题描述：应用启动时出现 Redis 连接错误。
解决方案：
- 检查 Redis 服务是否正常运行 - 确认 Redis 没挂
- 确认 Redis 地址和端口是否正确 - 默认是 localhost:6379
- 检查 Redis 密码（如果有设置） - 别忘了密码
- 确认 Redis 实例是否允许远程连接 - 检查一下防火墙设置
3. 前端无法访问后端 API
问题描述：前端应用无法连接到后端 API。
解决方案：
- 检查后端服务是否正常运行 - 后端没跑起来，前端当然访问不了
- 确认前端配置的 API 地址是否正确 - 检查一下配置文件
- 检查 CORS 配置是否正确 - 跨域问题是个常见坑
- 检查防火墙设置，确保端口未被阻止 - 别让防火墙挡住了您的路
4. 启动时出现端口冲突
问题描述：应用启动时出现端口已被占用的错误。
解决方案：
- 修改后端端口：编辑
application.yml中的server.port配置 - 换个端口试试 - 修改前端端口：编辑
tagtag-ui/apps/tagtag/.env中的PORT配置 - 前端也可以换端口 - 查找并终止占用端口的进程 - 谁占用了端口，把它干掉
5. Maven 依赖下载失败
问题描述：执行 mvn clean package 时出现依赖下载失败。
解决方案：
- 检查网络连接是否正常 - 网络不通，什么都下载不了
- 清理 Maven 本地仓库：删除
~/.m2/repository目录，重新下载依赖 - 有时候缓存会出问题 - 配置 Maven 镜像：在
settings.xml中配置国内镜像源 - 国内下载慢，用镜像加速
6. pnpm 依赖安装失败
问题描述：执行 pnpm install 时出现依赖安装失败。
解决方案：
- 检查网络连接是否正常 - 网络问题，老生常谈
- 清理 pnpm 缓存：执行
pnpm store prune- 清理一下缓存试试 - 升级 pnpm 版本：执行
npm install -g pnpm- 用最新版总没错 - 配置 pnpm 镜像：在
.npmrc中配置国内镜像源 - 国内下载，镜像加速是王道
7. 编译错误
问题描述：编译过程中出现错误。
解决方案：
- 检查 JDK 版本是否符合要求（JDK 17+） - 别用旧版本了
- 检查 Node.js 版本是否符合要求（Node.js >= 20.12.0） - 前端也得跟上
- 清理编译缓存：执行
mvn clean或pnpm run clean- 清理一下缓存 - 检查代码是否存在语法错误或类型错误 - 自己写的代码，自己检查
8. 登录失败
问题描述：使用初始账号登录失败。
解决方案：
- 确认账号和密码是否正确（初始账号：
admin/admin123） - 别输错了 - 检查后端服务是否正常运行 - 后端没跑起来，当然登录不了
- 检查数据库中是否存在用户数据 - 数据库初始化了吗？
- 检查 JWT 配置是否正确 - JWT 配置错了，登录肯定失败
下一步
现在您已经成功启动了 Tagtag 应用，您可以：
- 登录系统，体验各项功能 - 先玩玩看，熟悉一下系统
- 查看 API 文档，了解系统提供的接口 - 看看有哪些 API 可以用
- 阅读开发指南，学习如何开发新功能 - 开始您的开发之旅
- 查看架构文档，深入了解系统设计 - 了解系统的设计思想
祝您使用愉快！如果遇到问题，欢迎在 GitHub 上提 Issue，我们会尽快回复。当然，更欢迎您直接提交 PR，帮助我们改进 Tagtag Starter。