小蚂蚁云

Appearance

Become a sponsor
企业级中台解决方案
企业级中台解决方案

环境准备 ​

本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 Python + FastAPI 后端、Vue3 + ElementPlus 前端的分离架构，本地开发需准备以下软件。

安装软件：Python(3.12+)、MySQL(8.0+)、Redis(3.2+)、Node.js(22+)、pnpm 等。

温馨提示

  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 官方网站，选择适合你操作系统的 Python 3.12+ 版本（推荐最新稳定版）。

点击 Download 按钮，下载对应平台的安装包。

  • 安装 Python

Windows 系统

双击下载的 .exe 文件启动安装程序。

重要提示

安装时务必勾选 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

温馨提示

  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)

温馨提示

如果显示版本号，说明 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 官方网站，选择适合你操作系统的 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

温馨提示

  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>

温馨提示

输入之前设置的 root 密码，成功登录后显示 MySQL 提示符即代表安装成功。

  • 创建数据库（可选）

在 MySQL 提示符中，可提前创建项目数据库：

sql
-- 创建数据库（UTF-8 编码）
CREATE DATABASE `djangoadmin.fastapi.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

-- 查看数据库
SHOW DATABASES;

温馨提示

也可以不手动建库，后续执行 python scripts/init_db.py 会自动创建数据库并导入初始数据。

安装 Redis ​

Redis 是必需的缓存服务，用于验证码存储、JWT 令牌黑名单、登录限流等功能。要求 3.2 或更高版本。

  • 下载软件

Windows 系统

访问 Microsoft Archive for Redis，下载适用于 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"

温馨提示

输入 ping 命令，如果返回 PONG，说明 Redis 客户端已成功连接到服务器。

常见问题与解决方法

  1. 服务无法启动：确保 Redis 安装目录正确，并且具有读取权限。检查端口 6379 是否被占用。
  2. 连接被拒绝：确保 Redis 服务器正在运行。验证防火墙设置，确保 Redis 端口（默认 6379）允许通过。

安装 Node.js ​

Node.js 是前端项目的运行环境，要求 22 或更高版本。前端基于 Vue3 + ElementPlus 构建。

  • 下载 Node.js

访问 Node.js 官方网站，选择 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

温馨提示

如果显示版本号，说明 Node.js 和 npm 安装成功。如需同时管理多个 Node 版本，可以使用 nvm 工具。

安装 pnpm ​

pnpm 是推荐的前端包管理器，相比 npm 和 yarn 具有更快的安装速度和更小的磁盘占用。

  • 安装 pnpm

通过 npm 全局安装 pnpm：

bash
npm install pnpm -g
  • 验证安装
bash
# 查看 pnpm 版本
pnpm -v
9.15.0

温馨提示

pnpm 安装成功后，后续进入前端项目目录即可使用 pnpm install 安装依赖。

  • 设置镜像源（可选）

国内网络环境建议配置 pnpm 镜像源，加速依赖包下载：

bash
# 设置阿里云镜像源
pnpm config set registry https://registry.npmmirror.com

# 查看当前镜像源
pnpm config get registry

安装 Git ​

Git 是必需的版本控制工具，用于代码的拉取和管理。

  • 下载 Git

访问 Git 官方网站，下载适合你操作系统的安装包。

  • 安装 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+

全部就绪

以上命令均能正确输出版本号，即表示本地开发环境已准备完毕，可以进入下一步：后端启动。

总结 ​

本章节介绍了本地开发环境所需的全部基础软件及其安装配置步骤。通过以上步骤，你已经完成了 Python、MySQL、Redis、Node.js、pnpm、Git 的安装和验证。这些是运行项目的基础环境，后续章节将基于这些环境进行项目的启动和调试。如果在安装过程中遇到问题，可参考各软件的官方文档或查阅 常见问题FAQ 章节。

小蚂蚁云团队 · 提供技术支持

Copyright © 2020~2026 www.djangoadmin.cn. All rights reserved.