快速开始

本指南将帮助您快速搭建和运行 CmdAdmin 项目。

环境准备

必需软件

软件	版本	说明
JDK	21+	Java 开发工具包
Node.js	18+	前端运行环境
PostgreSQL	15+	数据库（或 MySQL 8+）
Redis	6+	缓存数据库
Maven	3.8+	Java 构建工具

验证安装

# 检查 JDK
java -version

# 检查 Maven
mvn -version

# 检查 Node.js
node -v
npm -v

获取源码

方式一：Git 克隆

git clone https://github.com/key1012/cmdadmin.git
cd cmdadmin

方式二：下载压缩包

1. 访问 GitHub Releases
2. 下载最新版本的源码压缩包
3. 解压到本地目录

数据库初始化

1. 创建数据库

# 使用 PostgreSQL
psql -U postgres -c "CREATE DATABASE cmdadmin;"

# 或使用 MySQL
mysql -u root -p -e "CREATE DATABASE cmdadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

2. 执行初始化脚本

# PostgreSQL
psql -U postgres -d cmdadmin -f src/main/resources/db/schema-postgresql.sql
psql -U postgres -d cmdadmin -f src/main/resources/db/data-postgresql.sql

# MySQL
mysql -u root -p cmdadmin < src/main/resources/db/schema-mysql.sql
mysql -u root -p cmdadmin < src/main/resources/db/data-mysql.sql

配置项目

后端配置

编辑 src/main/resources/application-dev.yml：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cmdadmin
    username: postgres
    password: your_password
  
  data:
    redis:
      host: localhost
      port: 6379
      password: your_redis_password

前端配置

编辑 admin-web/.env.development：

VITE_API_BASE_URL=http://localhost:8080/api

启动项目

方式一：IDEA 启动（推荐开发环境）

1. 导入项目

   • 打开 IDEA
   • File → Open → 选择项目根目录
   • 等待 Maven 依赖下载完成

2. 配置数据库

   • 确保 PostgreSQL 和 Redis 已启动
   • 检查 application-dev.yml 配置

3. 启动后端

   • 找到 CmdAdminApplication.java
   • 右键 → Run

4. 启动前端

   • 打开 Terminal
   • 执行 cd admin-web && npm install
   • 执行 npm run dev

方式二：命令行启动

终端 1 - 启动后端：

cd cmdAdmin
mvn spring-boot:run

终端 2 - 启动前端：

cd admin-web
npm install
npm run dev

方式三：Docker 启动

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

访问系统

启动成功后，访问以下地址：

服务	地址	说明
前端页面	http://localhost:5173	默认首页
后端 API	http://localhost:8080/api	REST API
Swagger	http://localhost:8080/api/swagger-ui.html	API 文档

默认账号

账号	密码	角色
admin	admin123	超级管理员
test	test123	普通用户

项目结构

cmdAdmin/
├── src/main/java/com/cmdadmin/     # 后端源码
│   ├── CmdAdminApplication.java    # 启动类
│   ├── common/                     # 公共组件
│   ├── config/                     # 配置类
│   ├── system/                     # 系统模块
│   └── example/                    # 示例模块
├── src/main/resources/             # 配置文件
│   ├── application.yml             # 主配置
│   ├── application-dev.yml         # 开发配置
│   ├── application-prod.yml        # 生产配置
│   └── db/                         # 数据库脚本
├── admin-web/                      # 前端项目
│   ├── src/
│   │   ├── api/                    # API 接口
│   │   ├── components/             # 公共组件
│   │   ├── views/                  # 页面视图
│   │   ├── stores/                 # Pinia 状态
│   │   └── router/                 # 路由配置
│   └── package.json
├── docs/                           # 文档
├── pom.xml                         # Maven 配置
└── README.md

常见问题

1. 端口被占用

# 查找占用 8080 端口的进程
lsof -i :8080

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

2. 数据库连接失败

检查数据库服务是否启动：

# PostgreSQL
sudo systemctl status postgresql

# MySQL
sudo systemctl status mysql

3. Redis 连接失败

# 检查 Redis 状态
redis-cli ping

# 启动 Redis
redis-server

4. 前端依赖安装失败

# 清除缓存
npm cache clean --force

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 重新安装
npm install

5. Maven 依赖下载慢

配置阿里云镜像，编辑 ~/.m2/settings.xml：

<mirrors>
  <mirror>
    <id>aliyun</id>
    <name>Aliyun Maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

下一步

• 项目结构 - 了解项目架构
• 认证授权 - 了解登录机制
• 权限管理 - 了解权限体系
• 部署指南 - 生产环境部署