478 lines
11 KiB
Markdown
478 lines
11 KiB
Markdown
# 环境准备
|
||
|
||
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `FastAPI` 后端、`Vue3` + `ElementPlus` 前端的分离架构，本地开发需准备以下软件。
|
||
|
||
安装软件：`Python(3.12+)`、`MySQL(8.0+)`、`Redis(3.2+)`、`Node.js(22+)`、`pnpm` 等。
|
||
|
||
:::tip 温馨提示
|
||
1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。
|
||
2. `Node.js` 安装后还需另外安装 `pnpm` 包管理器，要求 Node.js 22+ 版本以上。
|
||
3. `MySQL 8.0+` 安装启动服务后，可以安装可视化工具 `Navicat` 并连接数据库。
|
||
4. 非 Java/Spring 技术栈，无需安装 JDK 和 Maven。
|
||
:::
|
||
|
||
## 安装 Python
|
||
|
||
`Python` 是后端的核心运行环境，`FastAPI` 框架要求 `Python 3.12` 或更高版本。
|
||
|
||
+ 下载 Python
|
||
|
||
访问 [Python 官方网站](https://www.python.org/downloads/)，选择适合你操作系统的 `Python 3.12+` 版本（推荐最新稳定版）。
|
||
|
||
|
||
|
||
|
||
|
||
点击 `Download` 按钮，下载对应平台的安装包。
|
||
|
||
+ 安装 Python
|
||
|
||
**Windows 系统**
|
||
|
||
双击下载的 `.exe` 文件启动安装程序。
|
||
|
||
:::danger 重要提示
|
||
安装时务必勾选 **`Add Python to PATH`** 选项，将 Python 添加到系统环境变量。否则后续命令无法识别 `python` 和 `pip` 指令。
|
||
:::
|
||
|
||
选择 `Customize installation`，确认以下选项已勾选：
|
||
|
||
```
|
||
pip - Python 包管理器
|
||
tcl/tk and IDLE - 图形界面支持（可选）
|
||
py launcher - Python 启动器
|
||
```
|
||
|
||
点击 `Install` 开始安装，等待安装完成。
|
||
|
||
**macOS 系统**
|
||
|
||
双击下载的 `.pkg` 文件，按照安装向导完成安装。macOS 通常自带 Python，但建议安装官方版本以确保版本一致。
|
||
|
||
**Linux 系统**
|
||
|
||
大多数 Linux 发行版自带 Python，但版本可能较低，建议通过包管理器安装 `Python 3.12+`。
|
||
|
||
Ubuntu / Debian：
|
||
|
||
```bash
|
||
# 更新包索引
|
||
sudo apt update
|
||
|
||
# 安装 Python 3.12 及 pip
|
||
sudo apt install -y python3.12 python3.12-venv python3-pip
|
||
|
||
# 设置 python3 指向 3.12（可选，部分系统默认已是）
|
||
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1
|
||
```
|
||
|
||
CentOS / RHEL / Fedora：
|
||
|
||
```bash
|
||
# CentOS / RHEL 8+ / Fedora
|
||
sudo dnf install -y python3.12 python3.12-pip
|
||
|
||
# CentOS 7（需先启用 EPEL 和 IUS 源）
|
||
sudo yum install -y epel-release
|
||
sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
|
||
sudo yum install -y python312 python312-pip
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 部分系统需使用 `python3` 和 `pip3` 命令而非 `python` 和 `pip`，可通过 `alias python=python3` 简化。
|
||
2. 推荐使用 `python3 -m venv` 创建虚拟环境隔离项目依赖：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
:::
|
||
|
||
+ 验证安装
|
||
|
||
打开终端或命令提示符，输入以下命令确认 `Python` 和 `pip` 安装成功：
|
||
|
||
```bash
|
||
# 查看 Python 版本
|
||
python --version
|
||
Python 3.12.7
|
||
|
||
# 查看 pip 版本
|
||
pip --version
|
||
pip 24.2 from ... (python 3.12)
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
如果显示版本号，说明 `Python` 和 `pip` 安装成功。推荐使用 `Python 3.12` 或更高版本。
|
||
:::
|
||
|
||
+ 配置 pip 镜像源（可选）
|
||
|
||
国内网络环境建议配置 `pip` 镜像源，加速依赖包下载：
|
||
|
||
```bash
|
||
# 设置阿里云镜像源
|
||
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
|
||
|
||
# 设置信任主机
|
||
pip config set global.trusted-host mirrors.aliyun.com
|
||
```
|
||
|
||
## 安装 MySQL
|
||
|
||
`MySQL` 是默认的关系型数据库，要求 `8.0` 或更高版本。项目同时支持 `PostgreSQL`、`SQL Server`、`SQLite`、`Oracle` 等数据库驱动。
|
||
|
||
+ 下载软件
|
||
|
||
访问 [MySQL 官方网站](https://dev.mysql.com/downloads/mysql/)，选择适合你操作系统的 `MySQL 8.0+` 版本（推荐最新稳定版）。
|
||
|
||
|
||
|
||
点击 `Download` 按钮，选择合适的安装包下载。
|
||
|
||
+ 安装软件
|
||
|
||
**Windows 系统**
|
||
|
||
双击下载的 `.msi` 文件启动安装向导，按照提示完成安装。安装过程中需要设置 `root` 用户密码，请牢记此密码，后续配置 `.env` 文件时需要使用。
|
||
|
||
**macOS 系统**
|
||
|
||
推荐使用 `Homebrew` 安装：
|
||
|
||
```bash
|
||
brew install mysql
|
||
brew services start mysql
|
||
```
|
||
|
||
**Linux 系统**
|
||
|
||
Ubuntu / Debian：
|
||
|
||
```bash
|
||
# 更新包索引
|
||
sudo apt update
|
||
|
||
# 安装 MySQL 8.0+
|
||
sudo apt install -y mysql-server
|
||
|
||
# 启动并设置开机自启
|
||
sudo systemctl start mysql
|
||
sudo systemctl enable mysql
|
||
|
||
# 安全初始化（设置 root 密码、移除匿名用户等）
|
||
sudo mysql_secure_installation
|
||
```
|
||
|
||
CentOS / RHEL / Fedora：
|
||
|
||
```bash
|
||
# CentOS / RHEL 8+ / Fedora
|
||
sudo dnf install -y mysql-server
|
||
|
||
# CentOS 7
|
||
sudo yum install -y mysql-server
|
||
|
||
# 启动并设置开机自启
|
||
sudo systemctl start mysqld
|
||
sudo systemctl enable mysqld
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. CentOS / RHEL 8+ 默认安装 `mysql-server`（即 MySQL 8.0 社区版）。
|
||
2. CentOS 7 安装后需通过 `grep 'temporary password' /var/log/mysqld.log` 获取临时 root 密码。
|
||
3. 部分发行版可使用 `mariadb-server` 作为 MySQL 兼容替代，但建议使用官方 MySQL 以确保兼容性。
|
||
:::
|
||
|
||
+ 验证安装
|
||
|
||
打开命令提示符或终端，输入以下命令登录 `MySQL`：
|
||
|
||
```bash
|
||
# 登录本地 MySQL 服务
|
||
mysql -uroot -p
|
||
|
||
# 输入密码后显示如下信息
|
||
Enter password: ****
|
||
Welcome to the MySQL monitor. Commands end with ; or \g.
|
||
Your MySQL connection id is 14
|
||
Server version: 8.0.41 MySQL Community Server - GPL
|
||
|
||
mysql>
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
输入之前设置的 `root` 密码，成功登录后显示 `MySQL` 提示符即代表安装成功。
|
||
:::
|
||
|
||
+ 创建数据库（可选）
|
||
|
||
在 `MySQL` 提示符中，可提前创建项目数据库：
|
||
|
||
```sql
|
||
-- 创建数据库（UTF-8 编码）
|
||
CREATE DATABASE `djangoadmin.fastapi.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||
|
||
-- 查看数据库
|
||
SHOW DATABASES;
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
也可以不手动建库，后续执行 `python scripts/init_db.py` 会自动创建数据库并导入初始数据。
|
||
:::
|
||
|
||
## 安装 Redis
|
||
|
||
`Redis` 是必需的缓存服务，用于验证码存储、JWT 令牌黑名单、登录限流等功能。要求 `3.2` 或更高版本。
|
||
|
||
+ 下载软件
|
||
|
||
**Windows 系统**
|
||
|
||
访问 [Microsoft Archive for Redis](https://github.com/microsoftarchive/redis/tags)，下载适用于 Windows 的安装包（推荐 `Redis-x64-3.2.100.msi`）。
|
||
|
||
**macOS 系统**
|
||
|
||
```bash
|
||
brew install redis
|
||
brew services start redis
|
||
```
|
||
|
||
**Linux 系统**
|
||
|
||
Ubuntu / Debian：
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y redis-server
|
||
|
||
# 启动并设置开机自启
|
||
sudo systemctl start redis-server
|
||
sudo systemctl enable redis-server
|
||
```
|
||
|
||
CentOS / RHEL / Fedora：
|
||
|
||
```bash
|
||
# CentOS / RHEL 8+ / Fedora
|
||
sudo dnf install -y redis
|
||
|
||
# CentOS 7
|
||
sudo yum install -y redis
|
||
|
||
# 启动并设置开机自启
|
||
sudo systemctl start redis
|
||
sudo systemctl enable redis
|
||
```
|
||
|
||
+ 验证安装
|
||
|
||
在终端或命令提示符中，执行以下命令启动客户端并测试：
|
||
|
||
```bash
|
||
# 启动 Redis 客户端
|
||
redis-cli
|
||
|
||
# 测试连接
|
||
127.0.0.1:6379> ping
|
||
PONG
|
||
|
||
# 设置键值对
|
||
127.0.0.1:6379> set name django_admin
|
||
OK
|
||
|
||
# 获取键值
|
||
127.0.0.1:6379> get name
|
||
"django_admin"
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
输入 `ping` 命令，如果返回 `PONG`，说明 Redis 客户端已成功连接到服务器。
|
||
:::
|
||
|
||
:::tip 常见问题与解决方法
|
||
1. 服务无法启动：确保 Redis 安装目录正确，并且具有读取权限。检查端口 `6379` 是否被占用。
|
||
2. 连接被拒绝：确保 Redis 服务器正在运行。验证防火墙设置，确保 Redis 端口（默认 `6379`）允许通过。
|
||
:::
|
||
|
||
## 安装 Node.js
|
||
|
||
`Node.js` 是前端项目的运行环境，要求 `22` 或更高版本。前端基于 `Vue3` + `ElementPlus` 构建。
|
||
|
||
+ 下载 Node.js
|
||
|
||
访问 [Node.js 官方网站](https://nodejs.org/zh-cn)，选择 `LTS` 版本（推荐 `v22.x` 或更高），下载适合你操作系统的安装包。
|
||
|
||
|
||
|
||
+ 安装 Node.js
|
||
|
||
**Windows 系统**
|
||
|
||
双击下载的 `.msi` 文件启动安装程序，按照提示完成安装。安装时建议勾选以下选项：
|
||
|
||
```
|
||
Automatically install the necessary tools - 自动安装所需工具
|
||
Add to PATH - 将 Node.js 添加到系统环境变量
|
||
```
|
||
|
||
**macOS 系统**
|
||
|
||
双击下载的 `.pkg` 文件，按照安装向导完成安装。
|
||
|
||
**Linux 系统**
|
||
|
||
推荐使用 `nvm`（Node Version Manager）安装，便于管理多版本：
|
||
|
||
```bash
|
||
# 安装 nvm
|
||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
|
||
|
||
# 重新加载 shell 配置
|
||
source ~/.bashrc
|
||
|
||
# 安装 Node.js 22+
|
||
nvm install 22
|
||
|
||
# 设置为默认版本
|
||
nvm alias default 22
|
||
```
|
||
|
||
或通过 NodeSource 源直接安装：
|
||
|
||
```bash
|
||
# 添加 NodeSource 源（以 Node.js 22 为例）
|
||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||
|
||
# Ubuntu / Debian
|
||
sudo apt install -y nodejs
|
||
|
||
# CentOS / RHEL / Fedora
|
||
sudo dnf install -y nodejs
|
||
```
|
||
|
||
+ 验证安装
|
||
|
||
打开终端或命令提示符，输入以下命令：
|
||
|
||
```bash
|
||
# 查看 Node.js 版本
|
||
node -v
|
||
v22.14.0
|
||
|
||
# 查看 npm 版本
|
||
npm -v
|
||
10.9.2
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
如果显示版本号，说明 `Node.js` 和 `npm` 安装成功。如需同时管理多个 Node 版本，可以使用 `nvm` 工具。
|
||
:::
|
||
|
||
## 安装 pnpm
|
||
|
||
`pnpm` 是推荐的前端包管理器，相比 `npm` 和 `yarn` 具有更快的安装速度和更小的磁盘占用。
|
||
|
||
+ 安装 pnpm
|
||
|
||
通过 `npm` 全局安装 `pnpm`：
|
||
|
||
```bash
|
||
npm install pnpm -g
|
||
```
|
||
|
||
+ 验证安装
|
||
|
||
```bash
|
||
# 查看 pnpm 版本
|
||
pnpm -v
|
||
9.15.0
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`pnpm` 安装成功后，后续进入前端项目目录即可使用 `pnpm install` 安装依赖。
|
||
:::
|
||
|
||
+ 设置镜像源（可选）
|
||
|
||
国内网络环境建议配置 `pnpm` 镜像源，加速依赖包下载：
|
||
|
||
```bash
|
||
# 设置阿里云镜像源
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
|
||
# 查看当前镜像源
|
||
pnpm config get registry
|
||
```
|
||
|
||
## 安装 Git
|
||
|
||
`Git` 是必需的版本控制工具，用于代码的拉取和管理。
|
||
|
||
+ 下载 Git
|
||
|
||
访问 [Git 官方网站](https://git-scm.com/downloads)，下载适合你操作系统的安装包。
|
||
|
||
+ 安装 Git
|
||
|
||
**Windows 系统**
|
||
|
||
双击下载的 `.exe` 文件，按照安装向导完成安装。安装过程中保持默认选项即可。
|
||
|
||
**macOS 系统**
|
||
|
||
```bash
|
||
# 使用 Homebrew 安装
|
||
brew install git
|
||
```
|
||
|
||
**Linux 系统**
|
||
|
||
```bash
|
||
# Ubuntu / Debian
|
||
sudo apt update
|
||
sudo apt install -y git
|
||
|
||
# CentOS / RHEL / Fedora
|
||
sudo dnf install -y git
|
||
```
|
||
|
||
+ 验证安装
|
||
|
||
```bash
|
||
# 查看 Git 版本
|
||
git --version
|
||
git version 2.43.0
|
||
```
|
||
|
||
## 环境验证清单
|
||
|
||
完成以上所有软件安装后，打开终端依次执行以下命令，确认所有环境就绪：
|
||
|
||
```bash
|
||
# 1. Python 环境
|
||
python --version # 期望: Python 3.12+
|
||
pip --version # 期望: pip 对应 Python 版本
|
||
|
||
# 2. 数据库
|
||
mysql --version # 期望: mysql Ver 8.0+
|
||
|
||
# 3. 缓存
|
||
redis-cli --version # 期望: redis-cli 8.10+
|
||
|
||
# 4. 前端运行时
|
||
node -v # 期望: v22+
|
||
pnpm -v # 期望: 11.x+
|
||
|
||
# 5. 版本控制
|
||
git --version # 期望: git version 2.x+
|
||
```
|
||
|
||
:::tip 全部就绪
|
||
以上命令均能正确输出版本号，即表示本地开发环境已准备完毕，可以进入下一步：[后端启动](/zh/volume1/backend)。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
本章节介绍了本地开发环境所需的全部基础软件及其安装配置步骤。通过以上步骤，你已经完成了 `Python`、`MySQL`、`Redis`、`Node.js`、`pnpm`、`Git` 的安装和验证。这些是运行项目的基础环境，后续章节将基于这些环境进行项目的启动和调试。如果在安装过程中遇到问题，可参考各软件的官方文档或查阅 [常见问题FAQ](/zh/volume1/faq) 章节。
|