started / 环境搭建 - WlAdmin 文档

WlAdmin

正在加载文档...

文档内容较大，正在处理中，请稍候

1. 环境要求

必需环境

软件	版本要求	说明
Node.js	>= 20.19.0	推荐使用 LTS 版本，Next.js 16 和部分依赖包要求
PNPM	>= 10.24.0	项目使用 PNPM 作为包管理器，必须使用 PNPM
MySQL	>= 8.0	用于后端数据库存储
Git	最新版	用于克隆代码和版本控制

可选环境

软件	版本要求	说明
Docker	>= 20.19	用于容器化部署和开发
Docker Compose	>= 2.0	用于管理多容器应用
Redis	>= 6.0	用于生产环境缓存（可选）

⚠️ 重要提示

✅ 必须使用 PNPM，不要使用 npm 或 yarn
✅ Node.js 版本必须 >= 20.19.0（Next.js 16 要求）
❌ 不要运行 npm install 或 yarn install
❌ 只运行 pnpm install 安装依赖

2. 基础环境安装

1. 安装 Node.js

macOS

方式一：使用 Homebrew（推荐）

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js LTS 版本
brew install node@20

# 验证安装
node --version
# 应该显示：v20.x.x 或更高版本

npm --version

方式二：使用 NVM（Node Version Manager）

# 安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载终端配置
source ~/.zshrc  # 或 source ~/.bash_profile

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

# 验证安装
node --version
npm --version

Windows

访问 Node.js 官网
下载并安装 LTS 版本（推荐 20.x）
安装时选择 "Add to PATH" 选项
打开命令提示符或 PowerShell，验证安装：

node --version
npm --version

Linux

Ubuntu/Debian

# 使用 NodeSource 仓库安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

CentOS/RHEL

# 使用 NodeSource 仓库安装 Node.js 20
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

2. 安装 PNPM

PNPM 是项目的包管理器，必须安装。

使用 npm 全局安装（推荐）

# 使用 npm 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version
# 应该显示：10.24.0 或更高版本

使用 Homebrew 安装（macOS）

brew install pnpm

使用独立安装脚本

# macOS/Linux
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Windows (PowerShell)
iwr https://get.pnpm.io/install.ps1 -useb | iex

安装完成后，重新加载终端配置：

# macOS/Linux
source ~/.zshrc  # 或 source ~/.bash_profile

# Windows
# 重新打开 PowerShell 或命令提示符

3. 安装 MySQL

macOS

使用 Homebrew

# 安装 MySQL
brew install mysql@8.0

# 启动 MySQL 服务
brew services start mysql@8.0

# 设置 root 密码（首次安装）
mysql_secure_installation

# 验证安装
mysql --version

Windows

访问 MySQL 官网
下载 MySQL 8.0 Windows Installer
运行安装程序，选择 "Developer Default" 或 "Server only"
设置 root 密码并记住
完成安装后，MySQL 服务会自动启动

Linux

Ubuntu/Debian

# 更新包列表
sudo apt update

# 安装 MySQL Server
sudo apt install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 运行安全配置脚本
sudo mysql_secure_installation

# 验证安装
mysql --version

CentOS/RHEL

# 安装 MySQL Server
sudo yum install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 获取临时 root 密码
sudo grep 'temporary password' /var/log/mysqld.log

# 运行安全配置脚本
sudo mysql_secure_installation

# 验证安装
mysql --version

验证 MySQL 安装

# 登录 MySQL（使用 root 用户）
mysql -u root -p

# 输入密码后，应该看到 MySQL 提示符
mysql> SELECT VERSION();
# 应该显示：8.0.x 或更高版本

mysql> exit;

4. 安装 Git

macOS

# 使用 Homebrew
brew install git

# 或使用 Xcode Command Line Tools
xcode-select --install

Windows

访问 Git 官网
下载并安装 Git for Windows
安装时选择默认选项即可

Linux

# Ubuntu/Debian
sudo apt install git

# CentOS/RHEL
sudo yum install git

验证安装：

git --version

3. 项目克隆与依赖安装

1. 克隆项目

# 克隆项目到本地
git clone https://gitee.com/lyqjob/project-root.git

# 进入项目目录
cd project-root

2. 安装项目依赖

重要：必须在项目根目录执行，使用 PNPM

# 在项目根目录执行，安装所有应用的依赖
pnpm install

说明：

该命令会安装根目录、所有 apps/ 和 packages/ 的依赖
PNPM 使用 workspace 机制，会智能处理依赖共享，避免重复安装
安装过程可能需要几分钟，请耐心等待
如果遇到网络问题，可以使用国内镜像：

# 设置 PNPM 镜像（可选）
pnpm config set registry https://registry.npmmirror.com

# 然后再执行安装
pnpm install

3. 验证安装

安装完成后，检查各个应用的依赖是否安装成功：

# 检查根目录依赖
ls node_modules

# 检查各个应用的依赖
ls apps/node-express-mysql/node_modules
ls apps/react-antd-webpack/node_modules
ls apps/doc-next-ts/node_modules

4. 数据库配置

1. 创建数据库

# 登录 MySQL
mysql -u root -p

# 输入 root 密码后，执行以下 SQL
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 验证数据库创建
SHOW DATABASES;
# 应该能看到 wladmin 数据库

# 退出 MySQL
exit;

2. 初始化数据库表和数据

项目提供了完整的数据库初始化脚本，位于 sql/sqlinit/ 目录。

重要：必须按顺序执行以下脚本

# 进入数据库初始化脚本目录
cd sql/sqlinit

# 1. 创建所有核心数据表（用户、角色、菜单、权限等）
mysql -u root -p wladmin < 建表.sql

# 2. 创建监控数据相关表
mysql -u root -p wladmin < 监控数据相关表.sql

# 3. 导入省市区数据
mysql -u root -p wladmin < 省市区数据.sql

# 4. 导入预制数据：超级管理员（可自定义）、角色、菜单、权限等
mysql -u root -p wladmin < 预制数据.sql

# 5. （可选）索引优化
mysql -u root -p wladmin < 20251219-索引优化.sql

执行顺序说明：

建表.sql：创建所有核心数据表结构（用户表、角色表、菜单表、权限表等）
监控数据相关表.sql：创建监控相关的数据表
省市区数据.sql：导入省市区基础数据
预制数据.sql：导入初始数据（超级管理员账号、默认角色、菜单、权限等）
20251219-索引优化.sql：数据库索引优化（可选，但推荐执行）

默认超级管理员账号：

用户名：superadmin
密码：123456

⚠️ 安全提示：生产环境请务必修改默认密码！

3. 验证数据库初始化

# 登录 MySQL
mysql -u root -p wladmin

# 查看所有表
SHOW TABLES;

# 应该能看到以下表（部分）：
# - users（用户表）
# - roles（角色表）
# - menus（菜单表）
# - permissions（权限表）
# - tokens（Token表）
# - audit_logs（审计日志表）
# 等等...

# 验证超级管理员账号
SELECT id, username, nickname FROM users WHERE username = 'superadmin';

# 退出 MySQL
exit;

5. 环境变量配置

1. 后端环境变量配置

# 进入后端应用目录
cd apps/node-express-mysql

# 复制环境变量模板（如果存在）
# 如果没有模板文件，直接创建 .env 文件
touch .env

编辑 .env 文件，配置以下变量：

# ==================== 应用配置 ====================
# 运行环境：development（开发）| production（生产）
NODE_ENV=development

# 服务端口
PORT=8888

# 服务主机（0.0.0.0 表示监听所有网络接口）
HOST=0.0.0.0

# ==================== 数据库配置（开发环境）====================
DB_DEV_HOST=localhost
DB_DEV_PORT=3306
DB_DEV_USER=root
DB_DEV_PASSWORD=your_mysql_password  # 替换为你的 MySQL root 密码
DB_DEV_NAME=wladmin

# ==================== 数据库配置（生产环境）====================
# 生产环境数据库配置（如果使用）
DB_PRO_HOST=your_production_host
DB_PRO_PORT=3306
DB_PRO_USER=your_production_user
DB_PRO_PASSWORD=your_production_password
DB_PRO_NAME=wladmin

# ==================== JWT 配置 ====================
# JWT 密钥（请使用强密码，建议至少 32 位随机字符串）
JWT_SECRET=your-jwt-secret-key-change-this-in-production
REFRESH_SECRET=your-refresh-secret-key-change-this-in-production

# Session 密钥
SESSION_SECRET=your-session-secret-key-change-this-in-production

# ==================== Redis 配置（可选）====================
# 开发环境 Redis（如果使用）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 生产环境 Redis（如果使用）
PRO_REDIS_HOST=your_production_redis_host
PRO_REDIS_PORT=6379
PRO_REDIS_PASSWORD=your_production_redis_password
PRO_REDIS_DB=0
PRO_CACHE_KEY_PREFIX=wladmin:
PRO_CACHE_KEY_SUFFIX=:cache

# ==================== 缓存配置 ====================
# 缓存类型：memory（内存）| redis（Redis）
CACHE_TYPE=memory

# ==================== 日志配置 ====================
# 日志级别：debug | info | warn | error
LOG_LEVEL=debug

# ==================== 其他配置 ====================
# 是否启用 SourceMap 调试（生产环境建议关闭）
ENABLE_SOURCEMAP_DEBUG=false

# 是否允许超级管理员编辑（生产环境建议关闭）
IS_SUPER_ADMIN_EDIT=true

# 单设备登录开关：on 则登录时清退其他会话并通过 SSE 通知
SINGLE_LOGIN=on

# ==================== AI 配置（可选）====================
# OpenAI API Key（如果使用 OpenAI）
OPENAI=your-openai-api-key

# DeepSeek API Key（如果使用 DeepSeek）
DEEPSEEK_API_KEY=your-deepseek-api-key

# GLM API Key（如果使用 GLM）
GLM_API_KEY=your-glm-api-key

# ==================== 生产环境 URL 配置 ====================
# 生产环境基础 URL
PRO_BASE_URL=https://your-domain.com

配置说明：

DB_DEV_*：开发环境数据库配置，必须配置
DB_PRO_*：生产环境数据库配置，开发环境可以不配置
JWT_SECRET、REFRESH_SECRET、SESSION_SECRET：必须配置，建议使用强密码
REDIS_*：如果使用 Redis 缓存，需要配置；否则使用内存缓存
SINGLE_LOGIN：单设备登录开关，on 表示启用

2. 文档站环境变量配置（可选）

# 进入文档站应用目录
cd apps/doc-next-ts

# 创建 .env 文件（如果需要）
touch .env

文档站通常不需要额外的环境变量配置，如果需要配置 API 地址等，可以添加：

# API 基础地址（如果需要）
NEXT_PUBLIC_API_BASE_URL=http://localhost:8888

3. 前端环境变量配置（可选）

前端应用通常不需要 .env 文件，配置在代码中管理。如果需要，可以创建：

# 进入前端应用目录
cd apps/react-antd-webpack

# 创建 .env 文件（如果需要）
touch .env

6. 启动项目

方式一：在根目录统一启动（推荐）

这种方式使用 Turbo 并行启动所有应用，适合开发环境。

# 在项目根目录执行

# 启动所有应用（并行启动）
pnpm dev

# 或者单独启动某个应用
pnpm dev:frontend   # 只启动 Web 前端
pnpm dev:backend    # 只启动后端服务
pnpm dev:doc        # 只启动文档站

方式二：在各自应用目录启动

如果需要单独调试某个应用，可以进入对应目录启动：

# 启动后端服务（端口 8888）
cd apps/node-express-mysql
pnpm dev

# 启动 Web 前端（端口 8080）
cd apps/react-antd-webpack
pnpm dev

# 启动文档站（端口 8081）
cd apps/doc-next-ts
pnpm dev

启动成功标志

启动成功后，应该能看到以下信息：

后端服务：

Server running on http://0.0.0.0:8888
Database connected successfully

Web 前端：

webpack compiled successfully
App running at http://localhost:8080

文档站：

✓ Ready in X seconds
○ Local: http://localhost:8081

访问应用

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

🌐 Web 前端：http://localhost:8080
🚀 后端 API：http://localhost:8888
📚 文档站：http://localhost:8081
📖 API 文档：http://localhost:8888/api/docs/（如果配置了 Swagger）

默认登录账号：

用户名：superadmin
密码：123456

7. Docker 环境（可选）

如果你熟悉 Docker，可以使用 Docker 快速启动 MySQL 和 Redis 服务，避免本地安装。

1. 安装 Docker 和 Docker Compose

macOS

# 使用 Homebrew 安装
brew install --cask docker
brew install docker-compose

# 或下载 Docker Desktop for Mac
# https://www.docker.com/products/docker-desktop

Windows

下载并安装 Docker Desktop for Windows
安装完成后，Docker Compose 会自动包含在内

Linux

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose

# CentOS/RHEL
sudo yum install docker docker-compose

2. 启动基础设施服务（MySQL + Redis）

# 进入 Docker Compose 目录
cd docker_project/docker-compose

# 配置 MySQL 环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库密码等

# 配置 Redis 配置文件
# 从模板文件复制 Redis 配置文件
cp redis-data/conf/redis.conf.example redis-data/conf/redis.conf

# 编辑 Redis 配置文件，设置 Redis 密码
# 将 redis.conf 文件中的 your-password 替换为你的实际密码
# 例如：requirepass your-password -> requirepass your_redis_password
# 同时更新 user default 和 user admin 的密码配置

# 启动 MySQL 和 Redis
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

3. Redis 配置说明

Redis 配置文件位于 docker_project/docker-compose/redis-data/conf/redis.conf，需要从模板文件 redis.conf.example 复制并配置：

复制配置文件：

cp redis-data/conf/redis.conf.example redis-data/conf/redis.conf

编辑配置文件，修改以下内容：
- requirepass your-password - 设置 Redis 密码（替换 your-password）
- user default on >your-password ~* +@all - 设置 default 用户密码
- user admin on >your-password ~* +@all - 设置 admin 用户密码

配置示例：

requirepass your_redis_password
user default on >your_redis_password ~* +@all
user admin on >your_redis_password ~* +@all

注意：Redis 密码需要与后端服务 .env 文件中的 PRO_REDIS_PASSWORD 配置保持一致。

4. 停止 Docker 服务

# 停止服务
docker-compose down

# 停止服务并删除数据卷（谨慎使用）
docker-compose down -v

8. 常见问题

Q1: 安装依赖时出现 `ERR_PNPM_WORKSPACE_PKG_NOT_FOUND` 错误

错误信息：ERR_PNPM_WORKSPACE_PKG_NOT_FOUND

原因：项目使用了 workspace:* 依赖，需要在 monorepo 根目录安装。

解决：

# 确保在项目根目录执行
cd /Volumes/Work/Template/project_root

# 清理缓存后重新安装
pnpm store prune
pnpm install

# 如果问题仍然存在，删除 node_modules 和锁文件后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

说明：

项目使用 PNPM Workspace 管理依赖，必须在根目录执行 pnpm install
不要进入子应用目录单独安装依赖
如果需要在子应用安装新依赖，使用 pnpm add <package> --filter <app-name>

Q2: Node.js 版本不兼容

错误信息：

You are using Node.js 18.x.x. For Next.js, Node.js version ">=20.9.0" is required.

原因：Next.js 16 要求 Node.js >= 20.9.0，当前版本过低。

解决：

方式一：使用 NVM（推荐）

# 安装 NVM（如果未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.zshrc  # 或 source ~/.bash_profile

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

# 验证版本
node --version  # 应该显示 v20.x.x

方式二：使用 Homebrew（macOS）

# 安装 Node.js 20
brew install node@20

# 验证版本
node --version

方式三：从官网下载安装

访问 Node.js 官网
下载并安装 LTS 版本（20.x）
验证安装：node --version

Q3: 数据库连接失败（开发环境）

错误信息：

connect ECONNREFUSED
或
connect EHOSTUNREACH

原因：数据库服务未启动、配置错误或网络问题。

解决：

1. 检查 MySQL 服务状态

# macOS
brew services list | grep mysql

# Linux
sudo systemctl status mysql
# 或
sudo systemctl status mysqld

# Windows
# 打开服务管理器，检查 MySQL 服务状态

2. 启动 MySQL 服务

# macOS
brew services start mysql@8.0

# Linux
sudo systemctl start mysql
# 或
sudo systemctl start mysqld

# Windows
# 在服务管理器中启动 MySQL 服务

3. 检查数据库配置

# 检查 .env 文件中的数据库配置
cd apps/node-express-mysql
cat .env | grep -E "DB_DEV_"

# 确保配置正确：
# DB_DEV_HOST=localhost
# DB_DEV_PORT=3306
# DB_DEV_USER=root
# DB_DEV_PASSWORD=your_password
# DB_DEV_NAME=wladmin

4. 测试数据库连接

# 测试本地连接
mysql -u root -p -e "SHOW DATABASES;"

# 如果连接失败，检查：
# - 密码是否正确
# - 数据库是否已创建
# - 用户权限是否正确

5. 检查数据库是否已创建

# 登录 MySQL
mysql -u root -p

# 查看所有数据库
SHOW DATABASES;

# 如果 wladmin 数据库不存在，创建它
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

6. Docker 环境数据库连接问题（本地开发）

如果使用本地 Docker 环境，参考以下排查：

# 检查 Docker 容器状态
docker ps -a | grep mysql

# 检查容器日志
docker logs mysql-8

# 测试容器内连接
docker exec -it mysql-8 mysql -u root -p

# ⚠️ 重要：使用容器名称而不是 IP 地址
# 在 .env 文件中配置：
# DB_DEV_HOST=mysql-8  # 或 mysql（容器名称）
# 而不是：DB_DEV_HOST=172.29.0.2  # ❌ 不要使用 IP

Q4: 端口被占用（开发环境）

错误信息：EADDRINUSE: address already in use :8888

原因：端口已被其他进程占用。

解决：

方式一：使用项目提供的脚本（推荐）

# 在项目根目录执行，自动杀死占用端口的进程
pnpm kill:ports

方式二：手动查找并杀死进程

# macOS/Linux - 查找占用端口的进程
lsof -i :8080  # Web 前端端口
lsof -i :8888  # 后端端口
lsof -i :8081  # 文档站端口

# 杀死进程（替换 <PID> 为实际进程 ID）
kill -9 <PID>

# 或一键杀死所有占用端口的进程
lsof -ti:8080,8888,8081 | xargs kill -9

# Windows - 查找占用端口的进程
netstat -ano | findstr :8080
netstat -ano | findstr :8888
netstat -ano | findstr :8081

# 杀死进程（替换 <PID> 为实际进程 ID）
taskkill /PID <PID> /F

方式三：修改端口配置

如果无法杀死占用端口的进程，可以修改应用端口：

# 后端端口（.env 文件）
cd apps/node-express-mysql
vim .env
# 修改：PORT=8889

# 前端端口（package.json 或环境变量）
cd apps/react-antd-webpack
vim package.json
# 修改 dev 脚本中的 PORT=8081

Q5: PNPM 安装速度慢或失败

原因：网络问题或镜像源配置问题。

解决：

方式一：使用国内镜像（推荐）

# 设置 PNPM 镜像源
pnpm config set registry https://registry.npmmirror.com

# 验证配置
pnpm config get registry

# 重新安装
pnpm install

方式二：临时使用镜像

# 单次安装使用镜像
pnpm install --registry https://registry.npmmirror.com

方式三：清理缓存后重新安装

# 清理 PNPM 缓存
pnpm store prune

# 删除 node_modules 和锁文件
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

方式四：检查网络连接

# 测试镜像源连接
curl https://registry.npmmirror.com

# 如果连接失败，尝试其他镜像源
pnpm config set registry https://registry.npmjs.org

Q6: MySQL 密码忘记或无法登录

解决：

macOS/Linux

# 方式一：使用 sudo 直接登录（无需密码）
sudo mysql -u root

# 登录后重置密码
ALTER USER 'root'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;
exit;

# 方式二：使用 mysql_secure_installation 重置
sudo mysql_secure_installation

Windows

停止 MySQL 服务
使用 --skip-grant-tables 启动 MySQL
登录并重置密码
重启 MySQL 服务

详细步骤：请参考 MySQL 官方文档或搜索引擎。

Q7: Docker 服务无法启动

错误信息：

Cannot connect to the Docker daemon
或
docker: command not found

解决：

1. 检查 Docker 是否安装

# 检查 Docker 版本
docker --version

# 如果命令不存在，需要安装 Docker

2. 检查 Docker 服务状态

# macOS/Linux
sudo systemctl status docker

# 如果服务未运行，启动它
sudo systemctl start docker
sudo systemctl enable docker  # 设置开机自启

3. 检查 Docker Compose

# 检查 Docker Compose 版本
docker compose --version
# 或
docker-compose --version

# 如果命令不存在，需要安装 Docker Compose

4. 检查端口占用

# 检查 MySQL 端口
lsof -i :3306

# 检查 Redis 端口
lsof -i :6379

# 如果端口被占用，停止占用端口的服务或修改 Docker 配置

5. 查看 Docker 日志

# 查看容器日志
docker-compose logs

# 查看特定服务日志
docker-compose logs mysql
docker-compose logs redis

6. 重启 Docker 服务

# macOS/Linux
sudo systemctl restart docker

# 或重启 Docker Desktop（macOS/Windows）

Q8: 环境变量配置错误

错误信息：应用启动失败或功能异常。

原因：.env 文件配置错误或缺失。

解决：

1. 检查 .env 文件是否存在

# 后端环境变量
cd apps/node-express-mysql
ls -la .env

# 如果不存在，从模板复制
cp .env.example .env

2. 检查必需的环境变量

# 检查数据库配置
cat .env | grep -E "DB_DEV_|DB_PRO_"

# 检查 JWT 配置
cat .env | grep -E "JWT_SECRET|REFRESH_SECRET|SESSION_SECRET"

# 确保所有必需变量都已配置

3. 验证环境变量格式

# 检查是否有语法错误
# .env 文件格式：
# KEY=value
# 不要有多余的空格或引号（除非值中包含空格）

# ✅ 正确
DB_DEV_HOST=localhost
DB_DEV_PASSWORD=my_password

# ❌ 错误
DB_DEV_HOST = localhost  # 等号两边不要有空格
DB_DEV_PASSWORD="my_password"  # 值不需要引号（除非值中包含空格）

4. 重新加载环境变量

# 修改 .env 文件后，需要重启应用
# 后端服务
cd apps/node-express-mysql
pnpm dev

# 或使用 PM2
pm2 restart node-express-mysql

Q9: 依赖安装后项目无法启动

错误信息：Module not found 或 Cannot find module

原因：依赖安装不完整或 workspace 依赖解析失败。

解决：

1. 检查依赖安装

# 检查 node_modules 是否存在
ls -la node_modules/

# 检查关键依赖是否安装
ls -la node_modules/express/
ls -la node_modules/react/

2. 重新安装依赖

# 清理后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

3. 检查 workspace 依赖

# 如果项目使用 workspace 依赖，确保在根目录安装
cd /Volumes/Work/Template/project_root
pnpm install

# 检查 workspace 依赖是否正确链接
ls -la node_modules/@packages/

4. 检查 Node.js 版本

# 确保 Node.js 版本符合要求
node --version  # 应该 >= 20.19.0

# 如果版本不对，切换版本
nvm use 20

Q10: 如何单独运行某个应用？

方式一：使用 filter 参数（推荐）

# 在项目根目录执行
pnpm dev --filter doc-next-ts        # 只启动文档站
pnpm dev --filter react-antd-webpack # 只启动 Web 前端
pnpm dev --filter node-express-mysql # 只启动后端服务

方式二：进入应用目录

# 启动文档站
cd apps/doc-next-ts
pnpm dev

# 启动 Web 前端
cd apps/react-antd-webpack
pnpm dev

# 启动后端服务
cd apps/node-express-mysql
pnpm dev

方式三：使用根目录脚本

# 在项目根目录
pnpm dev:doc        # 只启动文档站
pnpm dev:frontend   # 只启动 Web 前端
pnpm dev:backend    # 只启动后端服务

Q11: 前端无法连接后端 API

错误信息：Network Error 或 CORS error

原因：后端服务未启动、CORS 配置错误或 API 地址配置错误。

解决：

1. 检查后端服务是否启动

# 检查后端服务状态
curl http://localhost:8888/health

# 如果返回错误，检查后端服务
cd apps/node-express-mysql
pnpm dev

2. 检查 API 地址配置

# 检查前端 API 配置
cd apps/react-antd-webpack
cat src/config/api.config.ts
# 或
cat src/utils/api/request.js

# 确保 API 地址正确：
# http://localhost:8888

3. 检查 CORS 配置

# 检查后端 CORS 配置
cd apps/node-express-mysql
cat config/base/cors.js

# 确保允许前端域名访问

4. 检查浏览器控制台

打开浏览器开发者工具（F12），查看 Network 面板和 Console 面板的错误信息。

Q12: 数据库初始化脚本执行失败

错误信息：SQL 脚本执行报错

原因：脚本执行顺序错误、数据库已存在数据或 SQL 语法错误。

解决：

1. 确保按顺序执行脚本

# 必须按以下顺序执行：
# 1. 建表.sql
mysql -u root -p wladmin < sql/sqlinit/建表.sql

# 2. 监控数据相关表.sql
mysql -u root -p wladmin < sql/sqlinit/监控数据相关表.sql

# 3. 省市区数据.sql
mysql -u root -p wladmin < sql/sqlinit/省市区数据.sql

# 4. 预制数据.sql
mysql -u root -p wladmin < sql/sqlinit/预制数据.sql

2. 如果数据库已有数据

# 方式一：删除数据库后重新创建（谨慎使用）
mysql -u root -p
DROP DATABASE wladmin;
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit;

# 然后重新执行初始化脚本

3. 检查 SQL 脚本语法

# 检查 SQL 脚本是否有语法错误
mysql -u root -p wladmin < sql/sqlinit/建表.sql 2>&1 | grep -i error

# 如果有错误，查看具体错误信息

Q13: 文件权限问题（macOS/Linux）

错误信息：EACCES: permission denied

原因：文件或目录权限不足。

解决：

# 检查文件权限
ls -la apps/node-express-mysql/

# 修复权限
chmod -R 755 apps/node-express-mysql/
chmod +x scripts/*.sh

# 如果涉及上传目录
chmod -R 755 apps/node-express-mysql/data/uploads/

Q14: Windows 环境特殊问题

Git Bash 中命令执行失败

问题：在 Git Bash 中执行 pnpm 命令失败。

解决：

# 使用 PowerShell 或 CMD 执行命令
# 或安装 Git for Windows 的完整版本

路径分隔符问题

问题：Windows 使用反斜杠 \，可能导致路径问题。

解决：

# 使用 Git Bash 或 WSL（Windows Subsystem for Linux）
# 或确保路径使用正斜杠 `/`

Q15: 其他问题

如果遇到其他问题，可以：

查看日志：

# 后端日志
cd apps/node-express-mysql
tail -f logs/output/*.log

# 前端构建日志
cd apps/react-antd-webpack
pnpm dev  # 查看控制台输出

清理后重新开始：

# 清理所有依赖和缓存
./scripts/clean-all-dependencies.sh

# 重新安装依赖
pnpm install

终于搭建好了！ 🎉

1. 环境要求

必需环境

软件	版本要求	说明
Node.js	>= 20.19.0	推荐使用 LTS 版本，Next.js 16 和部分依赖包要求
PNPM	>= 10.24.0	项目使用 PNPM 作为包管理器，必须使用 PNPM
MySQL	>= 8.0	用于后端数据库存储
Git	最新版	用于克隆代码和版本控制

可选环境

软件	版本要求	说明
Docker	>= 20.19	用于容器化部署和开发
Docker Compose	>= 2.0	用于管理多容器应用
Redis	>= 6.0	用于生产环境缓存（可选）

⚠️ 重要提示

✅ 必须使用 PNPM，不要使用 npm 或 yarn
✅ Node.js 版本必须 >= 20.19.0（Next.js 16 要求）
❌ 不要运行 npm install 或 yarn install
❌ 只运行 pnpm install 安装依赖

2. 基础环境安装

1. 安装 Node.js

macOS

方式一：使用 Homebrew（推荐）

# 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js LTS 版本
brew install node@20

# 验证安装
node --version
# 应该显示：v20.x.x 或更高版本

npm --version

方式二：使用 NVM（Node Version Manager）

# 安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载终端配置
source ~/.zshrc  # 或 source ~/.bash_profile

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

# 验证安装
node --version
npm --version

Windows

访问 Node.js 官网
下载并安装 LTS 版本（推荐 20.x）
安装时选择 "Add to PATH" 选项
打开命令提示符或 PowerShell，验证安装：

node --version
npm --version

Linux

Ubuntu/Debian

# 使用 NodeSource 仓库安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

CentOS/RHEL

# 使用 NodeSource 仓库安装 Node.js 20
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node --version
npm --version

2. 安装 PNPM

PNPM 是项目的包管理器，必须安装。

使用 npm 全局安装（推荐）

# 使用 npm 全局安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version
# 应该显示：10.24.0 或更高版本

使用 Homebrew 安装（macOS）

brew install pnpm

使用独立安装脚本

# macOS/Linux
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Windows (PowerShell)
iwr https://get.pnpm.io/install.ps1 -useb | iex

安装完成后，重新加载终端配置：

# macOS/Linux
source ~/.zshrc  # 或 source ~/.bash_profile

# Windows
# 重新打开 PowerShell 或命令提示符

3. 安装 MySQL

macOS

使用 Homebrew

# 安装 MySQL
brew install mysql@8.0

# 启动 MySQL 服务
brew services start mysql@8.0

# 设置 root 密码（首次安装）
mysql_secure_installation

# 验证安装
mysql --version

Windows

访问 MySQL 官网
下载 MySQL 8.0 Windows Installer
运行安装程序，选择 "Developer Default" 或 "Server only"
设置 root 密码并记住
完成安装后，MySQL 服务会自动启动

Linux

Ubuntu/Debian

# 更新包列表
sudo apt update

# 安装 MySQL Server
sudo apt install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 运行安全配置脚本
sudo mysql_secure_installation

# 验证安装
mysql --version

CentOS/RHEL

# 安装 MySQL Server
sudo yum install mysql-server

# 启动 MySQL 服务
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 获取临时 root 密码
sudo grep 'temporary password' /var/log/mysqld.log

# 运行安全配置脚本
sudo mysql_secure_installation

# 验证安装
mysql --version

验证 MySQL 安装

# 登录 MySQL（使用 root 用户）
mysql -u root -p

# 输入密码后，应该看到 MySQL 提示符
mysql> SELECT VERSION();
# 应该显示：8.0.x 或更高版本

mysql> exit;

4. 安装 Git

macOS

# 使用 Homebrew
brew install git

# 或使用 Xcode Command Line Tools
xcode-select --install

Windows

访问 Git 官网
下载并安装 Git for Windows
安装时选择默认选项即可

Linux

# Ubuntu/Debian
sudo apt install git

# CentOS/RHEL
sudo yum install git

验证安装：

git --version

3. 项目克隆与依赖安装

1. 克隆项目

# 克隆项目到本地
git clone https://gitee.com/lyqjob/project-root.git

# 进入项目目录
cd project-root

2. 安装项目依赖

重要：必须在项目根目录执行，使用 PNPM

# 在项目根目录执行，安装所有应用的依赖
pnpm install

说明：

该命令会安装根目录、所有 apps/ 和 packages/ 的依赖
PNPM 使用 workspace 机制，会智能处理依赖共享，避免重复安装
安装过程可能需要几分钟，请耐心等待
如果遇到网络问题，可以使用国内镜像：

# 设置 PNPM 镜像（可选）
pnpm config set registry https://registry.npmmirror.com

# 然后再执行安装
pnpm install

3. 验证安装

安装完成后，检查各个应用的依赖是否安装成功：

# 检查根目录依赖
ls node_modules

# 检查各个应用的依赖
ls apps/node-express-mysql/node_modules
ls apps/react-antd-webpack/node_modules
ls apps/doc-next-ts/node_modules

4. 数据库配置

1. 创建数据库

# 登录 MySQL
mysql -u root -p

# 输入 root 密码后，执行以下 SQL
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 验证数据库创建
SHOW DATABASES;
# 应该能看到 wladmin 数据库

# 退出 MySQL
exit;

2. 初始化数据库表和数据

项目提供了完整的数据库初始化脚本，位于 sql/sqlinit/ 目录。

重要：必须按顺序执行以下脚本

# 进入数据库初始化脚本目录
cd sql/sqlinit

# 1. 创建所有核心数据表（用户、角色、菜单、权限等）
mysql -u root -p wladmin < 建表.sql

# 2. 创建监控数据相关表
mysql -u root -p wladmin < 监控数据相关表.sql

# 3. 导入省市区数据
mysql -u root -p wladmin < 省市区数据.sql

# 4. 导入预制数据：超级管理员（可自定义）、角色、菜单、权限等
mysql -u root -p wladmin < 预制数据.sql

# 5. （可选）索引优化
mysql -u root -p wladmin < 20251219-索引优化.sql

执行顺序说明：

建表.sql：创建所有核心数据表结构（用户表、角色表、菜单表、权限表等）
监控数据相关表.sql：创建监控相关的数据表
省市区数据.sql：导入省市区基础数据
预制数据.sql：导入初始数据（超级管理员账号、默认角色、菜单、权限等）
20251219-索引优化.sql：数据库索引优化（可选，但推荐执行）

默认超级管理员账号：

用户名：superadmin
密码：123456

⚠️ 安全提示：生产环境请务必修改默认密码！

3. 验证数据库初始化

# 登录 MySQL
mysql -u root -p wladmin

# 查看所有表
SHOW TABLES;

# 应该能看到以下表（部分）：
# - users（用户表）
# - roles（角色表）
# - menus（菜单表）
# - permissions（权限表）
# - tokens（Token表）
# - audit_logs（审计日志表）
# 等等...

# 验证超级管理员账号
SELECT id, username, nickname FROM users WHERE username = 'superadmin';

# 退出 MySQL
exit;

5. 环境变量配置

1. 后端环境变量配置

# 进入后端应用目录
cd apps/node-express-mysql

# 复制环境变量模板（如果存在）
# 如果没有模板文件，直接创建 .env 文件
touch .env

编辑 .env 文件，配置以下变量：

# ==================== 应用配置 ====================
# 运行环境：development（开发）| production（生产）
NODE_ENV=development

# 服务端口
PORT=8888

# 服务主机（0.0.0.0 表示监听所有网络接口）
HOST=0.0.0.0

# ==================== 数据库配置（开发环境）====================
DB_DEV_HOST=localhost
DB_DEV_PORT=3306
DB_DEV_USER=root
DB_DEV_PASSWORD=your_mysql_password  # 替换为你的 MySQL root 密码
DB_DEV_NAME=wladmin

# ==================== 数据库配置（生产环境）====================
# 生产环境数据库配置（如果使用）
DB_PRO_HOST=your_production_host
DB_PRO_PORT=3306
DB_PRO_USER=your_production_user
DB_PRO_PASSWORD=your_production_password
DB_PRO_NAME=wladmin

# ==================== JWT 配置 ====================
# JWT 密钥（请使用强密码，建议至少 32 位随机字符串）
JWT_SECRET=your-jwt-secret-key-change-this-in-production
REFRESH_SECRET=your-refresh-secret-key-change-this-in-production

# Session 密钥
SESSION_SECRET=your-session-secret-key-change-this-in-production

# ==================== Redis 配置（可选）====================
# 开发环境 Redis（如果使用）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 生产环境 Redis（如果使用）
PRO_REDIS_HOST=your_production_redis_host
PRO_REDIS_PORT=6379
PRO_REDIS_PASSWORD=your_production_redis_password
PRO_REDIS_DB=0
PRO_CACHE_KEY_PREFIX=wladmin:
PRO_CACHE_KEY_SUFFIX=:cache

# ==================== 缓存配置 ====================
# 缓存类型：memory（内存）| redis（Redis）
CACHE_TYPE=memory

# ==================== 日志配置 ====================
# 日志级别：debug | info | warn | error
LOG_LEVEL=debug

# ==================== 其他配置 ====================
# 是否启用 SourceMap 调试（生产环境建议关闭）
ENABLE_SOURCEMAP_DEBUG=false

# 是否允许超级管理员编辑（生产环境建议关闭）
IS_SUPER_ADMIN_EDIT=true

# 单设备登录开关：on 则登录时清退其他会话并通过 SSE 通知
SINGLE_LOGIN=on

# ==================== AI 配置（可选）====================
# OpenAI API Key（如果使用 OpenAI）
OPENAI=your-openai-api-key

# DeepSeek API Key（如果使用 DeepSeek）
DEEPSEEK_API_KEY=your-deepseek-api-key

# GLM API Key（如果使用 GLM）
GLM_API_KEY=your-glm-api-key

# ==================== 生产环境 URL 配置 ====================
# 生产环境基础 URL
PRO_BASE_URL=https://your-domain.com

配置说明：

DB_DEV_*：开发环境数据库配置，必须配置
DB_PRO_*：生产环境数据库配置，开发环境可以不配置
JWT_SECRET、REFRESH_SECRET、SESSION_SECRET：必须配置，建议使用强密码
REDIS_*：如果使用 Redis 缓存，需要配置；否则使用内存缓存
SINGLE_LOGIN：单设备登录开关，on 表示启用

2. 文档站环境变量配置（可选）

# 进入文档站应用目录
cd apps/doc-next-ts

# 创建 .env 文件（如果需要）
touch .env

文档站通常不需要额外的环境变量配置，如果需要配置 API 地址等，可以添加：

# API 基础地址（如果需要）
NEXT_PUBLIC_API_BASE_URL=http://localhost:8888

3. 前端环境变量配置（可选）

前端应用通常不需要 .env 文件，配置在代码中管理。如果需要，可以创建：

# 进入前端应用目录
cd apps/react-antd-webpack

# 创建 .env 文件（如果需要）
touch .env

6. 启动项目

方式一：在根目录统一启动（推荐）

这种方式使用 Turbo 并行启动所有应用，适合开发环境。

# 在项目根目录执行

# 启动所有应用（并行启动）
pnpm dev

# 或者单独启动某个应用
pnpm dev:frontend   # 只启动 Web 前端
pnpm dev:backend    # 只启动后端服务
pnpm dev:doc        # 只启动文档站

方式二：在各自应用目录启动

如果需要单独调试某个应用，可以进入对应目录启动：

# 启动后端服务（端口 8888）
cd apps/node-express-mysql
pnpm dev

# 启动 Web 前端（端口 8080）
cd apps/react-antd-webpack
pnpm dev

# 启动文档站（端口 8081）
cd apps/doc-next-ts
pnpm dev

启动成功标志

启动成功后，应该能看到以下信息：

后端服务：

Server running on http://0.0.0.0:8888
Database connected successfully

Web 前端：

webpack compiled successfully
App running at http://localhost:8080

文档站：

✓ Ready in X seconds
○ Local: http://localhost:8081

访问应用

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

🌐 Web 前端：http://localhost:8080
🚀 后端 API：http://localhost:8888
📚 文档站：http://localhost:8081
📖 API 文档：http://localhost:8888/api/docs/（如果配置了 Swagger）

默认登录账号：

用户名：superadmin
密码：123456

7. Docker 环境（可选）

如果你熟悉 Docker，可以使用 Docker 快速启动 MySQL 和 Redis 服务，避免本地安装。

1. 安装 Docker 和 Docker Compose

macOS

# 使用 Homebrew 安装
brew install --cask docker
brew install docker-compose

# 或下载 Docker Desktop for Mac
# https://www.docker.com/products/docker-desktop

Windows

下载并安装 Docker Desktop for Windows
安装完成后，Docker Compose 会自动包含在内

Linux

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose

# CentOS/RHEL
sudo yum install docker docker-compose

2. 启动基础设施服务（MySQL + Redis）

# 进入 Docker Compose 目录
cd docker_project/docker-compose

# 配置 MySQL 环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库密码等

# 配置 Redis 配置文件
# 从模板文件复制 Redis 配置文件
cp redis-data/conf/redis.conf.example redis-data/conf/redis.conf

# 编辑 Redis 配置文件，设置 Redis 密码
# 将 redis.conf 文件中的 your-password 替换为你的实际密码
# 例如：requirepass your-password -> requirepass your_redis_password
# 同时更新 user default 和 user admin 的密码配置

# 启动 MySQL 和 Redis
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

3. Redis 配置说明

Redis 配置文件位于 docker_project/docker-compose/redis-data/conf/redis.conf，需要从模板文件 redis.conf.example 复制并配置：

复制配置文件：

cp redis-data/conf/redis.conf.example redis-data/conf/redis.conf

编辑配置文件，修改以下内容：
- requirepass your-password - 设置 Redis 密码（替换 your-password）
- user default on >your-password ~* +@all - 设置 default 用户密码
- user admin on >your-password ~* +@all - 设置 admin 用户密码

配置示例：

requirepass your_redis_password
user default on >your_redis_password ~* +@all
user admin on >your_redis_password ~* +@all

注意：Redis 密码需要与后端服务 .env 文件中的 PRO_REDIS_PASSWORD 配置保持一致。

4. 停止 Docker 服务

# 停止服务
docker-compose down

# 停止服务并删除数据卷（谨慎使用）
docker-compose down -v

8. 常见问题

Q1: 安装依赖时出现 `ERR_PNPM_WORKSPACE_PKG_NOT_FOUND` 错误

错误信息：ERR_PNPM_WORKSPACE_PKG_NOT_FOUND

原因：项目使用了 workspace:* 依赖，需要在 monorepo 根目录安装。

解决：

# 确保在项目根目录执行
cd /Volumes/Work/Template/project_root

# 清理缓存后重新安装
pnpm store prune
pnpm install

# 如果问题仍然存在，删除 node_modules 和锁文件后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

说明：

项目使用 PNPM Workspace 管理依赖，必须在根目录执行 pnpm install
不要进入子应用目录单独安装依赖
如果需要在子应用安装新依赖，使用 pnpm add <package> --filter <app-name>

Q2: Node.js 版本不兼容

错误信息：

You are using Node.js 18.x.x. For Next.js, Node.js version ">=20.9.0" is required.

原因：Next.js 16 要求 Node.js >= 20.9.0，当前版本过低。

解决：

方式一：使用 NVM（推荐）

# 安装 NVM（如果未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.zshrc  # 或 source ~/.bash_profile

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

# 验证版本
node --version  # 应该显示 v20.x.x

方式二：使用 Homebrew（macOS）

# 安装 Node.js 20
brew install node@20

# 验证版本
node --version

方式三：从官网下载安装

访问 Node.js 官网
下载并安装 LTS 版本（20.x）
验证安装：node --version

Q3: 数据库连接失败（开发环境）

错误信息：

connect ECONNREFUSED
或
connect EHOSTUNREACH

原因：数据库服务未启动、配置错误或网络问题。

解决：

1. 检查 MySQL 服务状态

# macOS
brew services list | grep mysql

# Linux
sudo systemctl status mysql
# 或
sudo systemctl status mysqld

# Windows
# 打开服务管理器，检查 MySQL 服务状态

2. 启动 MySQL 服务

# macOS
brew services start mysql@8.0

# Linux
sudo systemctl start mysql
# 或
sudo systemctl start mysqld

# Windows
# 在服务管理器中启动 MySQL 服务

3. 检查数据库配置

# 检查 .env 文件中的数据库配置
cd apps/node-express-mysql
cat .env | grep -E "DB_DEV_"

# 确保配置正确：
# DB_DEV_HOST=localhost
# DB_DEV_PORT=3306
# DB_DEV_USER=root
# DB_DEV_PASSWORD=your_password
# DB_DEV_NAME=wladmin

4. 测试数据库连接

# 测试本地连接
mysql -u root -p -e "SHOW DATABASES;"

# 如果连接失败，检查：
# - 密码是否正确
# - 数据库是否已创建
# - 用户权限是否正确

5. 检查数据库是否已创建

# 登录 MySQL
mysql -u root -p

# 查看所有数据库
SHOW DATABASES;

# 如果 wladmin 数据库不存在，创建它
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

6. Docker 环境数据库连接问题（本地开发）

如果使用本地 Docker 环境，参考以下排查：

# 检查 Docker 容器状态
docker ps -a | grep mysql

# 检查容器日志
docker logs mysql-8

# 测试容器内连接
docker exec -it mysql-8 mysql -u root -p

# ⚠️ 重要：使用容器名称而不是 IP 地址
# 在 .env 文件中配置：
# DB_DEV_HOST=mysql-8  # 或 mysql（容器名称）
# 而不是：DB_DEV_HOST=172.29.0.2  # ❌ 不要使用 IP

Q4: 端口被占用（开发环境）

错误信息：EADDRINUSE: address already in use :8888

原因：端口已被其他进程占用。

解决：

方式一：使用项目提供的脚本（推荐）

# 在项目根目录执行，自动杀死占用端口的进程
pnpm kill:ports

方式二：手动查找并杀死进程

# macOS/Linux - 查找占用端口的进程
lsof -i :8080  # Web 前端端口
lsof -i :8888  # 后端端口
lsof -i :8081  # 文档站端口

# 杀死进程（替换 <PID> 为实际进程 ID）
kill -9 <PID>

# 或一键杀死所有占用端口的进程
lsof -ti:8080,8888,8081 | xargs kill -9

# Windows - 查找占用端口的进程
netstat -ano | findstr :8080
netstat -ano | findstr :8888
netstat -ano | findstr :8081

# 杀死进程（替换 <PID> 为实际进程 ID）
taskkill /PID <PID> /F

方式三：修改端口配置

如果无法杀死占用端口的进程，可以修改应用端口：

# 后端端口（.env 文件）
cd apps/node-express-mysql
vim .env
# 修改：PORT=8889

# 前端端口（package.json 或环境变量）
cd apps/react-antd-webpack
vim package.json
# 修改 dev 脚本中的 PORT=8081

Q5: PNPM 安装速度慢或失败

原因：网络问题或镜像源配置问题。

解决：

方式一：使用国内镜像（推荐）

# 设置 PNPM 镜像源
pnpm config set registry https://registry.npmmirror.com

# 验证配置
pnpm config get registry

# 重新安装
pnpm install

方式二：临时使用镜像

# 单次安装使用镜像
pnpm install --registry https://registry.npmmirror.com

方式三：清理缓存后重新安装

# 清理 PNPM 缓存
pnpm store prune

# 删除 node_modules 和锁文件
rm -rf node_modules pnpm-lock.yaml

# 重新安装
pnpm install

方式四：检查网络连接

# 测试镜像源连接
curl https://registry.npmmirror.com

# 如果连接失败，尝试其他镜像源
pnpm config set registry https://registry.npmjs.org

Q6: MySQL 密码忘记或无法登录

解决：

macOS/Linux

# 方式一：使用 sudo 直接登录（无需密码）
sudo mysql -u root

# 登录后重置密码
ALTER USER 'root'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;
exit;

# 方式二：使用 mysql_secure_installation 重置
sudo mysql_secure_installation

Windows

停止 MySQL 服务
使用 --skip-grant-tables 启动 MySQL
登录并重置密码
重启 MySQL 服务

详细步骤：请参考 MySQL 官方文档或搜索引擎。

Q7: Docker 服务无法启动

错误信息：

Cannot connect to the Docker daemon
或
docker: command not found

解决：

1. 检查 Docker 是否安装

# 检查 Docker 版本
docker --version

# 如果命令不存在，需要安装 Docker

2. 检查 Docker 服务状态

# macOS/Linux
sudo systemctl status docker

# 如果服务未运行，启动它
sudo systemctl start docker
sudo systemctl enable docker  # 设置开机自启

3. 检查 Docker Compose

# 检查 Docker Compose 版本
docker compose --version
# 或
docker-compose --version

# 如果命令不存在，需要安装 Docker Compose

4. 检查端口占用

# 检查 MySQL 端口
lsof -i :3306

# 检查 Redis 端口
lsof -i :6379

# 如果端口被占用，停止占用端口的服务或修改 Docker 配置

5. 查看 Docker 日志

# 查看容器日志
docker-compose logs

# 查看特定服务日志
docker-compose logs mysql
docker-compose logs redis

6. 重启 Docker 服务

# macOS/Linux
sudo systemctl restart docker

# 或重启 Docker Desktop（macOS/Windows）

Q8: 环境变量配置错误

错误信息：应用启动失败或功能异常。

原因：.env 文件配置错误或缺失。

解决：

1. 检查 .env 文件是否存在

# 后端环境变量
cd apps/node-express-mysql
ls -la .env

# 如果不存在，从模板复制
cp .env.example .env

2. 检查必需的环境变量

# 检查数据库配置
cat .env | grep -E "DB_DEV_|DB_PRO_"

# 检查 JWT 配置
cat .env | grep -E "JWT_SECRET|REFRESH_SECRET|SESSION_SECRET"

# 确保所有必需变量都已配置

3. 验证环境变量格式

# 检查是否有语法错误
# .env 文件格式：
# KEY=value
# 不要有多余的空格或引号（除非值中包含空格）

# ✅ 正确
DB_DEV_HOST=localhost
DB_DEV_PASSWORD=my_password

# ❌ 错误
DB_DEV_HOST = localhost  # 等号两边不要有空格
DB_DEV_PASSWORD="my_password"  # 值不需要引号（除非值中包含空格）

4. 重新加载环境变量

# 修改 .env 文件后，需要重启应用
# 后端服务
cd apps/node-express-mysql
pnpm dev

# 或使用 PM2
pm2 restart node-express-mysql

Q9: 依赖安装后项目无法启动

错误信息：Module not found 或 Cannot find module

原因：依赖安装不完整或 workspace 依赖解析失败。

解决：

1. 检查依赖安装

# 检查 node_modules 是否存在
ls -la node_modules/

# 检查关键依赖是否安装
ls -la node_modules/express/
ls -la node_modules/react/

2. 重新安装依赖

# 清理后重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

3. 检查 workspace 依赖

# 如果项目使用 workspace 依赖，确保在根目录安装
cd /Volumes/Work/Template/project_root
pnpm install

# 检查 workspace 依赖是否正确链接
ls -la node_modules/@packages/

4. 检查 Node.js 版本

# 确保 Node.js 版本符合要求
node --version  # 应该 >= 20.19.0

# 如果版本不对，切换版本
nvm use 20

Q10: 如何单独运行某个应用？

方式一：使用 filter 参数（推荐）

# 在项目根目录执行
pnpm dev --filter doc-next-ts        # 只启动文档站
pnpm dev --filter react-antd-webpack # 只启动 Web 前端
pnpm dev --filter node-express-mysql # 只启动后端服务

方式二：进入应用目录

# 启动文档站
cd apps/doc-next-ts
pnpm dev

# 启动 Web 前端
cd apps/react-antd-webpack
pnpm dev

# 启动后端服务
cd apps/node-express-mysql
pnpm dev

方式三：使用根目录脚本

# 在项目根目录
pnpm dev:doc        # 只启动文档站
pnpm dev:frontend   # 只启动 Web 前端
pnpm dev:backend    # 只启动后端服务

Q11: 前端无法连接后端 API

错误信息：Network Error 或 CORS error

原因：后端服务未启动、CORS 配置错误或 API 地址配置错误。

解决：

1. 检查后端服务是否启动

# 检查后端服务状态
curl http://localhost:8888/health

# 如果返回错误，检查后端服务
cd apps/node-express-mysql
pnpm dev

2. 检查 API 地址配置

# 检查前端 API 配置
cd apps/react-antd-webpack
cat src/config/api.config.ts
# 或
cat src/utils/api/request.js

# 确保 API 地址正确：
# http://localhost:8888

3. 检查 CORS 配置

# 检查后端 CORS 配置
cd apps/node-express-mysql
cat config/base/cors.js

# 确保允许前端域名访问

4. 检查浏览器控制台

打开浏览器开发者工具（F12），查看 Network 面板和 Console 面板的错误信息。

Q12: 数据库初始化脚本执行失败

错误信息：SQL 脚本执行报错

原因：脚本执行顺序错误、数据库已存在数据或 SQL 语法错误。

解决：

1. 确保按顺序执行脚本

# 必须按以下顺序执行：
# 1. 建表.sql
mysql -u root -p wladmin < sql/sqlinit/建表.sql

# 2. 监控数据相关表.sql
mysql -u root -p wladmin < sql/sqlinit/监控数据相关表.sql

# 3. 省市区数据.sql
mysql -u root -p wladmin < sql/sqlinit/省市区数据.sql

# 4. 预制数据.sql
mysql -u root -p wladmin < sql/sqlinit/预制数据.sql

2. 如果数据库已有数据

# 方式一：删除数据库后重新创建（谨慎使用）
mysql -u root -p
DROP DATABASE wladmin;
CREATE DATABASE wladmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit;

# 然后重新执行初始化脚本

3. 检查 SQL 脚本语法

# 检查 SQL 脚本是否有语法错误
mysql -u root -p wladmin < sql/sqlinit/建表.sql 2>&1 | grep -i error

# 如果有错误，查看具体错误信息

Q13: 文件权限问题（macOS/Linux）

错误信息：EACCES: permission denied

原因：文件或目录权限不足。

解决：

# 检查文件权限
ls -la apps/node-express-mysql/

# 修复权限
chmod -R 755 apps/node-express-mysql/
chmod +x scripts/*.sh

# 如果涉及上传目录
chmod -R 755 apps/node-express-mysql/data/uploads/

Q14: Windows 环境特殊问题

Git Bash 中命令执行失败

问题：在 Git Bash 中执行 pnpm 命令失败。

解决：

# 使用 PowerShell 或 CMD 执行命令
# 或安装 Git for Windows 的完整版本

路径分隔符问题

问题：Windows 使用反斜杠 \，可能导致路径问题。

解决：

# 使用 Git Bash 或 WSL（Windows Subsystem for Linux）
# 或确保路径使用正斜杠 `/`

Q15: 其他问题

如果遇到其他问题，可以：

查看日志：

# 后端日志
cd apps/node-express-mysql
tail -f logs/output/*.log

# 前端构建日志
cd apps/react-antd-webpack
pnpm dev  # 查看控制台输出

清理后重新开始：

# 清理所有依赖和缓存
./scripts/clean-all-dependencies.sh

# 重新安装依赖
pnpm install

终于搭建好了！ 🎉

1. 环境要求#

必需环境#

可选环境#

⚠️ 重要提示#

2. 基础环境安装#

1. 安装 Node.js#

macOS#

Windows#

Linux#

2. 安装 PNPM#

使用 npm 全局安装（推荐）#

使用 Homebrew 安装（macOS）#

使用独立安装脚本#

3. 安装 MySQL#

macOS#

Windows#

Linux#

验证 MySQL 安装#

4. 安装 Git#

macOS#

Windows#

Linux#

3. 项目克隆与依赖安装#

1. 克隆项目#

2. 安装项目依赖#

3. 验证安装#

4. 数据库配置#

1. 创建数据库#

2. 初始化数据库表和数据#

3. 验证数据库初始化#

5. 环境变量配置#

1. 后端环境变量配置#

2. 文档站环境变量配置（可选）#

3. 前端环境变量配置（可选）#

6. 启动项目#

方式一：在根目录统一启动（推荐）#

方式二：在各自应用目录启动#

启动成功标志#

访问应用#

7. Docker 环境（可选）#

1. 安装 Docker 和 Docker Compose#

macOS#

Windows#

Linux#

2. 启动基础设施服务（MySQL + Redis）#

3. Redis 配置说明#

4. 停止 Docker 服务#

8. 常见问题#

Q1: 安装依赖时出现 ERR_PNPM_WORKSPACE_PKG_NOT_FOUND 错误#

Q2: Node.js 版本不兼容#

方式一：使用 NVM（推荐）#

方式二：使用 Homebrew（macOS）#

方式三：从官网下载安装#

Q3: 数据库连接失败（开发环境）#

1. 检查 MySQL 服务状态#

2. 启动 MySQL 服务#

3. 检查数据库配置#

4. 测试数据库连接#

5. 检查数据库是否已创建#

6. Docker 环境数据库连接问题（本地开发）#

Q4: 端口被占用（开发环境）#

方式一：使用项目提供的脚本（推荐）#

方式二：手动查找并杀死进程#

方式三：修改端口配置#

Q5: PNPM 安装速度慢或失败#

方式一：使用国内镜像（推荐）#

方式二：临时使用镜像#

方式三：清理缓存后重新安装#

方式四：检查网络连接#

Q6: MySQL 密码忘记或无法登录#

macOS/Linux#

Windows#

Q7: Docker 服务无法启动#

1. 检查 Docker 是否安装#

2. 检查 Docker 服务状态#

3. 检查 Docker Compose#

4. 检查端口占用#

5. 查看 Docker 日志#

6. 重启 Docker 服务#

Q8: 环境变量配置错误#

1. 环境要求

必需环境

可选环境

⚠️ 重要提示

2. 基础环境安装

1. 安装 Node.js

macOS

Windows

Linux

2. 安装 PNPM

使用 npm 全局安装（推荐）

使用 Homebrew 安装（macOS）

使用独立安装脚本

3. 安装 MySQL

macOS

Windows

Linux

验证 MySQL 安装

4. 安装 Git

macOS

Windows

Linux

3. 项目克隆与依赖安装

1. 克隆项目

2. 安装项目依赖

3. 验证安装

4. 数据库配置

1. 创建数据库

2. 初始化数据库表和数据

3. 验证数据库初始化

5. 环境变量配置

1. 后端环境变量配置

2. 文档站环境变量配置（可选）

3. 前端环境变量配置（可选）

6. 启动项目

方式一：在根目录统一启动（推荐）

方式二：在各自应用目录启动

启动成功标志

访问应用

7. Docker 环境（可选）

1. 安装 Docker 和 Docker Compose

macOS

Windows

Linux

2. 启动基础设施服务（MySQL + Redis）

3. Redis 配置说明

4. 停止 Docker 服务

8. 常见问题

Q1: 安装依赖时出现 `ERR_PNPM_WORKSPACE_PKG_NOT_FOUND` 错误

Q2: Node.js 版本不兼容

方式一：使用 NVM（推荐）

方式二：使用 Homebrew（macOS）

方式三：从官网下载安装

Q3: 数据库连接失败（开发环境）

1. 检查 MySQL 服务状态

2. 启动 MySQL 服务

3. 检查数据库配置

4. 测试数据库连接

5. 检查数据库是否已创建

6. Docker 环境数据库连接问题（本地开发）

Q4: 端口被占用（开发环境）

方式一：使用项目提供的脚本（推荐）

方式二：手动查找并杀死进程

方式三：修改端口配置

Q5: PNPM 安装速度慢或失败

方式一：使用国内镜像（推荐）

方式二：临时使用镜像

方式三：清理缓存后重新安装

方式四：检查网络连接

Q6: MySQL 密码忘记或无法登录

macOS/Linux

Windows

Q7: Docker 服务无法启动

1. 检查 Docker 是否安装

2. 检查 Docker 服务状态

3. 检查 Docker Compose

4. 检查端口占用

5. 查看 Docker 日志

6. 重启 Docker 服务

Q8: 环境变量配置错误