djangoadmin/djangoadmin-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
gitadmin
2026-09-16 10:11:44 +08:00
parent bf08cf1248
commit 20d8a85989
205 changed files with 34363 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DjangoAdmin_Tornado_EleVue/zh/volume1/backend.md
+339
View File
@@ -0,0 +1,339 @@
# 后端启动
本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 `Python` + `Tornado` 框架，采用分层架构设计（Handler 层 → Service 层 → Repository 层 → Model 层）。后端要求 Python 3.12+ 版本。
:::tip 温馨提示
启动后端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的所有软件安装。
:::
## 获取源码
前往 [官方网站](https://www.djangoadmin.cn) 购买授权后，按以下步骤获取源码：
```
1. 登录官方网站，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。
```
```bash
# 进入项目根目录（以实际解压路径为准）
cd DjangoAdmin_Tornado_EleVue
```
:::tip 温馨提示
1. 源码包请务必从官方网站订单中心下载，确保获取的是正版授权的最新版本。
2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
:::
项目目录结构如下：
```
├── app.py # 启动入口（__main__）
├── src/ # 后端源码
│ ├── app.py # 应用工厂（create_app）
│ ├── bootstrap.py # 启动引导（信号处理、优雅关闭）
│ ├── config/ # 配置模块
│ ├── core/ # 核心基类
│ ├── common/ # 公共模块
│ ├── modules/ # 业务模块
│ ├── api/v1/ # 路由定义
│ └── extensions/ # 扩展注册（sqlalchemy/redis）
├── ui/ # 前端源码（Vue3 + Element Plus）
├── scripts/ # 脚本工具（数据库初始化、数据迁移等）
├── document/ # 数据库脚本
├── tests/ # 测试代码
├── .env.example # 环境变量示例文件
├── pyproject.toml # Poetry 依赖配置
├── poetry.lock # Poetry 依赖锁定
├── Dockerfile # Docker 镜像构建
├── docker-compose.yml # Docker 编排文件
└── Makefile # 常用命令集合
```
## 安装依赖
进入项目根目录，使用 `Poetry` 安装后端依赖包：
```bash
# 安装 Poetry（如果尚未安装）
pip install poetry
# 安装项目依赖
poetry install
```
:::tip 温馨提示
如果网络较慢，可先配置 pip 镜像源（参见 [环境准备](/zh/volume1/environment)），或使用 Poetry 镜像：
```bash
poetry config repositories.mirror https://mirrors.aliyun.com/pypi/simple/
```
:::
+ 验证依赖安装
```bash
# 检查 Tornado 是否安装成功
poetry run python -c "import tornado; print(tornado.version)"
6.4.2
# 检查 SQLAlchemy 是否安装成功
poetry run python -c "import sqlalchemy; print(sqlalchemy.__version__)"
2.0.51
```
:::tip 温馨提示
依赖安装完成后，如果上述命令输出版本号，说明核心依赖已正确安装。
:::
## 配置环境变量
项目通过 `.env` 文件管理所有配置参数。首次使用需要从示例文件复制并修改：
```bash
# 复制环境变量示例文件
cp .env.example .env # Linux / macOS
copy .env.example .env # Windows CMD
```
+ 编辑 `.env` 文件
使用文本编辑器打开 `.env` 文件，修改以下关键配置：
```bash
# ============================================================
# 基础配置
# ============================================================
TORNADO_NAME=Tornado+EleVue旗舰版
TORNADO_VERSION=v3.0.0
TORNADO_HOST=127.0.0.1
TORNADO_PORT=8041
TORNADO_ENV=development
TORNADO_DEBUG=True
# ============================================================
# 数据库配置（根据实际情况修改）
# ============================================================
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=root
DB_PASSWORD=your_mysql_password # 修改为真实密码
DB_PREFIX=tornado_
# ============================================================
# Redis 缓存配置（根据实际情况修改）
# ============================================================
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password # 修改为真实密码
REDIS_AUTH=True
# ============================================================
# JWT 令牌配置（必填项）
# ============================================================
# 生成方式：python -c "import secrets; print(secrets.token_urlsafe(48))"
JWT_SECRET=your_jwt_secret_key_at_least_32_bytes
JWT_EXPIRE_MINUTES=20
```
:::danger 重要提示
1. `JWT_SECRET` 是 JWT 令牌的签名密钥，**必须设置**且至少 32 字节。留空或过弱会导致应用拒绝启动（fail-close）。可使用以下命令生成：
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
2. `DB_PASSWORD` 和 `REDIS_PASSWORD` 请填写真实的服务密码。
3. 生产环境务必设置 `TORNADO_DEBUG=False`，避免泄漏内部错误信息。
:::
## 初始化数据库
首次启动前，需要初始化数据库结构和种子数据。
### 方式一：手动导入（推荐）
```bash
# 1. 登录 MySQL，创建数据库
mysql -uroot -p
CREATE DATABASE `djangoadmin.tornado.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
# 2. 导入数据库脚本
mysql -uroot -p djangoadmin.tornado.elevue < document/djangoadmin.tornado.elevue.sql
```
### 方式二：Alembic 迁移（备选）
```bash
# 自动建表
poetry run alembic upgrade head
# 导入业务字典种子数据
python scripts/seed_dict.py
```
:::tip 温馨提示
项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等数据库。通过 `.env` 中的 `DB_DRIVER` 切换驱动（默认 `mysql`）。非 MySQL 数据库请使用 Alembic + seed 脚本初始化。详细的多数据库初始化步骤请参考 [数据库初始化](/zh/volume1/database) 章节。
:::
初始化完成后，数据库中包含以下默认数据：
```
管理员账号：admin / 123456（超级管理员，ID=1，跳过权限校验）
默认角色：超级管理员角色
默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
数据字典：系统内置字典数据
系统配置：系统默认配置项
```
## 启动后端服务
一切准备就绪后，执行以下命令启动后端服务：
```bash
# 使用 Poetry 启动（推荐）
poetry run python app.py --port=8041
# 或直接 python 启动
python app.py --port=8041
```
:::tip 启动入口说明
启动流程：`app.py`（__main__） → `src/bootstrap.py:main()` → `src/app.py:create_app()`
`bootstrap.py` 负责解析命令行参数（`--port`）、创建应用、注册 SIGINT/SIGTERM 信号实现优雅关闭。
`create_app()` 是应用工厂函数（位于 `src/app.py`），负责组装路由、配置模板/静态目录、初始化扩展。
:::
启动成功后，终端将输出类似以下信息：
```
____ _ _
| _ \ _ _ __ _ _ __ ___ (_) _ __ __ _ _ __ __| |
| | | || | | | / _` || '__| / __|| || '_ \ / _` || '__| / _` |
| |_| || |_| || (_| || | | (__ | || |_) || (_| || | | (_| |
|____/ \__,_| \__,_||_| \___||_|| .__/ \__,_||_| \__,_|
|_|
Tornado + EleVue 企业级管理框架
[INFO] 服务启动成功 → http://127.0.0.1:8041
```
:::tip 默认端口
后端服务默认监听端口为 `8041`，可通过 `--port` 参数或 `.env` 文件中的 `TORNADO_PORT` 参数修改。
:::
## 验证后端服务
+ 测试接口连通性
使用 `curl` 或浏览器访问健康检查接口：
```bash
# 测试服务是否正常响应
curl http://127.0.0.1:8041/api/v1/health
```
返回以下 JSON 即表示服务正常运行：
```json
{
"code": 0,
"data": {
"status": "ok"
},
"msg": "操作成功",
"ok": true
}
```
+ 测试验证码接口
```bash
curl http://127.0.0.1:8041/api/v1/captcha
```
返回类似以下 JSON：
```json
{
"code": 0,
"data": {
"captcha": "data:image/png;base64,...",
"key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
},
"msg": "操作成功",
"ok": true
}
```
+ 查看日志输出
在终端中观察后端日志输出，确认无异常错误信息。如果出现连接数据库或 `Redis` 失败的错误，请检查 `.env` 配置和相关服务是否正常运行。
## Makefile 常用命令
项目根目录的 `Makefile` 提供了常用命令的快捷方式。
:::tip Windows 用户注意
`make` 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户可直接执行表格中"对应命令"列所示的原始命令。
:::
| 命令 | 对应命令 | 说明 |
|:----|:----|:----|
| `make install` | `poetry install` | 安装依赖 |
| `make dev` | `poetry run python app.py --port=8041` | 启动开发服务 |
| `make test` | `poetry run pytest` | 运行全部测试 |
| `make test-unit` | `poetry run pytest tests/unit` | 运行单元测试 |
| `make lint` | `poetry run ruff check src tests` | 代码规范检查 |
| `make seed-dict` | `python scripts/seed_dict.py` | 初始化业务字典数据 |
## 常见问题
+ 端口被占用
如果启动时报错 `Address already in use`，说明端口 `8041` 已被其他程序占用：
```bash
# Windows 查看端口占用
netstat -ano | findstr 8041
# Linux / macOS 查看端口占用
lsof -i :8041
```
解决方式：终止占用进程，或使用 `--port` 参数指定其他端口。
+ JWT_SECRET 未配置
如果启动时报错 `JWT_SECRET` 相关错误，说明未配置 JWT 签名密钥或密钥过弱。请在 `.env` 文件中设置：
```bash
JWT_SECRET=your_generated_secret_key_here_at_least_32_bytes
```
生成方式：
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
+ 数据库连接失败
如果启动时报错数据库连接失败，请检查：
```
1. MySQL 服务是否已启动
2. .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
3. 防火墙是否放行了数据库端口
```
## 总结
本章节介绍了后端项目的完整启动流程：拉取代码 → 安装依赖 → 配置环境变量 → 初始化数据库 → 启动服务 → 验证接口。通过以上步骤，你已经成功将后端服务运行在本地 `8041` 端口。下一步可以进入 [前端启动](/zh/volume1/frontend) 章节，启动前端项目并登录系统。
DjangoAdmin_Tornado_EleVue/zh/volume1/database.md
+197
View File
@@ -0,0 +1,197 @@
# 数据库初始化
本章节介绍如何初始化项目数据库，包括建库、建表、导入种子数据以及后续的数据库迁移管理。
项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等多种数据库，通过 `.env` 中的 `DB_DRIVER` 切换驱动。
:::tip 温馨提示
数据库初始化前，请确保已完成以下准备工作：
1. 目标数据库服务已启动（如 MySQL 8.0+）
2. `.env` 文件中的 `DB_DRIVER` 和数据库连接信息已正确配置
3. Python 依赖已安装（`poetry install`）
:::
## 方式一：手动初始化（推荐）
手动初始化是最直接、最可控的方式，适合开发环境和生产环境。
### 第一步：创建数据库
根据你使用的数据库类型，手动创建数据库。
**MySQL**：
```sql
CREATE DATABASE `djangoadmin.tornado.elevue`
DEFAULT CHARACTER SET utf8mb4
COLLATE utf8mb4_general_ci;
```
**PostgreSQL**：
```sql
CREATE DATABASE "djangoadmin.tornado.elevue"
WITH ENCODING 'UTF8'
LC_COLLATE = 'zh_CN.UTF-8'
LC_CTYPE = 'zh_CN.UTF-8';
```
**SQL Server**：
```sql
CREATE DATABASE [djangoadmin.tornado.elevue];
```
### 第二步：导入数据库脚本
MySQL 数据库脚本位于 `document/` 目录下：
```bash
# 登录 MySQL
mysql -uroot -p
# 导入脚本
mysql -uroot -p djangoadmin.tornado.elevue < document/djangoadmin.tornado.elevue.sql
```
:::tip 温馨提示
`document/djangoadmin.tornado.elevue.sql` 是 MySQL 专用脚本。对于 PostgreSQL / SQL Server / SQLite / Oracle，建议使用 Alembic 方式初始化。
:::
### 第三步：导入字典种子数据
```bash
# 导入业务字典数据（性别、友链类型、通知来源等）
python scripts/seed_dict.py
```
:::tip 温馨提示
`seed_dict.py` 是幂等脚本，可重复执行不会产生重复数据。
:::
## 方式二：Alembic 迁移初始化
适合非 MySQL 数据库，或需要版本化管理数据库结构的场景。
### 第一步：创建数据库
同方式一的手动建库步骤。
### 第二步：执行迁移
```bash
# 根据 models 定义自动建表
poetry run alembic upgrade head
```
### 第三步：导入种子数据
```bash
python scripts/seed_dict.py
```
## 方式三：脚本初始化（备选）
```bash
# 自动完成建库、建表、导入种子数据
python scripts/init_db.py
```
:::tip 温馨提示
`init_db.py` 会根据 `.env` 中的 `DB_DRIVER` 配置自动初始化数据库。适合快速搭建开发环境。
:::
## 多数据库驱动配置
项目通过 `DB_DRIVER` 环境变量切换数据库驱动：
| DB_DRIVER | 别名 | Python 驱动 | 安装方式 |
|:----------|:-----|:------------|:---------|
| `mysql` | — | pymysql | 默认已安装 |
| `postgresql` | `postgres` | psycopg2-binary | `poetry install -E postgresql` |
| `mssql` | `sqlserver` | pymssql | `poetry install -E mssql` |
| `sqlite` | `sqlite3` | sqlite3 | 内置，无需额外安装 |
| `oracle` | — | oracledb | `poetry install -E oracle` |
### SQLite 配置示例
```bash
# .env
DB_DRIVER=sqlite
DB_DATABASE=/path/to/djangoadmin.db
```
:::tip SQLite 说明
当 `DB_DRIVER=sqlite` 时，`DB_DATABASE` 为数据库文件的完整路径（相对或绝对路径），`DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD` 均被忽略。
:::
### PostgreSQL 配置示例
```bash
# .env
DB_DRIVER=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=postgres
DB_PASSWORD=your_password
```
### Oracle 配置示例
```bash
# .env
DB_DRIVER=oracle
DB_HOST=127.0.0.1
DB_PORT=1521
DB_DATABASE=XEPDB1 # SERVICE_NAME
DB_USERNAME=system
DB_PASSWORD=your_password
```
## 初始化完成后
数据库初始化完成后，系统包含以下默认数据：
| 数据 | 说明 |
|:-----|:-----|
| 管理员账号 | admin / 123456（超级管理员，ID=1，跳过权限校验） |
| 默认角色 | 超级管理员角色 |
| 默认菜单 | 系统管理、内容管理、监控管理等菜单及权限节点 |
| 数据字典 | 性别、状态、类型等系统内置字典数据 |
| 系统配置 | 系统默认配置项 |
## 跨库数据迁移
项目提供 `scripts/migrate_db.py` 脚本，支持在不同数据库之间迁移数据（如 MySQL → PostgreSQL）。详细说明请参考 [跨库数据迁移](/zh/volume6/db-cross-migrate) 章节。
## 常见问题
+ 数据库连接失败
```
1. 检查数据库服务是否已启动
2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
3. 检查防火墙是否放行了数据库端口
4. 检查数据库用户是否有建库/建表权限
```
+ 导入脚本报错
```
1. 确认数据库字符集为 utf8mb4（MySQL）
2. 确认数据库版本符合要求（MySQL 8.0+）
3. 检查脚本文件是否完整（未被截断）
```
+ Alembic 迁移失败
```
1. 确认 alembic.ini 中的数据库连接配置正确
2. 检查是否存在版本冲突：poetry run alembic history
3. 如需重置：poetry run alembic downgrade base，然后 poetry run alembic upgrade head
```
## 总结
本章节介绍了三种数据库初始化方式：手动导入 SQL 脚本（推荐）、Alembic 迁移、脚本自动初始化。项目支持 MySQL / PostgreSQL / SQL Server / SQLite / Oracle 五种数据库，通过 `DB_DRIVER` 环境变量切换。初始化完成后即可启动后端服务。
DjangoAdmin_Tornado_EleVue/zh/volume1/docker.md
+516
View File
@@ -0,0 +1,516 @@
# Docker 快速部署
本章节介绍如何使用 Docker 快速部署后端服务，无需手动安装 Python、MySQL、Redis 等环境。
:::tip 温馨提示
Docker 部署适合快速体验和生产环境。本地开发建议使用 [后端启动](/zh/volume1/backend) 章节的方式。
:::
## 前置条件
确保已安装 Docker 和 Docker Compose：
```bash
# 验证 Docker 安装
docker --version
# Docker version 24.0.x
# 验证 Docker Compose 安装
docker compose version
# Docker Compose version v2.x.x
```
## 快速启动
### 1. 准备环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑 .env，配置数据库密码、Redis 密码、JWT 密钥等
```
:::danger 重要提示
Docker 部署时，`.env` 中的 `DB_HOST` 和 `REDIS_HOST` 应指向 Docker 网络中的服务名称（如 `mysql`、`redis`），而非 `127.0.0.1`。
:::
### 2. 使用 Docker Compose 启动
```bash
# 构建并启动所有服务
docker compose up -d --build
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f app
```
### 3. 访问服务
```
后端 API: http://127.0.0.1:8041/api/v1/health
```
## Dockerfile 说明
项目使用多阶段构建，减小镜像体积：
```dockerfile
# ======================================================================
# Stage 1: 构建依赖
# 使用一个临时镜像来解析 Poetry 依赖，避免把 Poetry 本身
# 和构建缓存带入最终运行镜像，从而减小镜像体积。
# ======================================================================
FROM python:3.12-slim AS builder
# 设置构建阶段的工作目录
WORKDIR /build
# 只拷贝依赖描述文件（先拷这些可以利用 Docker 层缓存：
# 只要依赖没变，后续 poetry export 就不会重新执行）
COPY pyproject.toml poetry.lock* ./
# 安装 Poetry，并把 pyproject.toml / poetry.lock 中的依赖
# 导出为普通的 requirements.txt，方便运行阶段用 pip 安装。
# --without-hashes：不写入哈希校验，简化后续安装。
RUN pip install --no-cache-dir poetry \
&& poetry export -f requirements.txt -o requirements.txt --without-hashes
# ======================================================================
# Stage 2: 运行
# 基于干净的 python:3.12-slim 构建最终镜像，只保留运行所需内容。
# ======================================================================
FROM python:3.12-slim AS runtime
# 环境变量配置：
# PYTHONUNBUFFERED=1 → 不缓冲 stdout/stderr，日志实时输出
# PYTHONDONTWRITEBYTECODE=1 → 不生成 .pyc 文件，保持镜像干净
# TZ=Asia/Shanghai → 设置容器时区为上海
ENV PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 \
TZ=Asia/Shanghai
# 设置应用运行的工作目录
WORKDIR /data/apps
# 从构建阶段拷贝导出的 requirements.txt
COPY --from=builder /build/requirements.txt ./
# 安装运行所需的 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt
# 拷贝应用代码和资源文件到镜像中
COPY src ./src # 源码目录
COPY app.py ./ # 应用入口
COPY alembic ./alembic # 数据库迁移脚本
COPY alembic.ini ./ # 数据库迁移配置
COPY .env.example ./.env # 环境变量示例（默认作为 .env 使用）
COPY scripts ./scripts # 辅助脚本
COPY templates ./templates # 模板文件
COPY static ./static # 静态资源
# 创建运行时需要的上传目录和日志目录
RUN mkdir -p uploads logs
# 声明容器对外暴露的端口
EXPOSE 8041
# 容器启动命令：运行 Tornado 应用入口
CMD ["python", "app.py"]
```
### 多阶段构建原理
```
┌─────────────────────────────────────────────────────────────┐
│ Stage 1: builder │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ python:3.12-slim │ │
│ │ + Poetry │ │
│ │ + pyproject.toml / poetry.lock │ │
│ │ ─────────────────────────────────────────────────────── │ │
│ │ → poetry export → requirements.txt │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ 仅拷贝 requirements.txt │
│ Stage 2: runtime │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ python:3.12-slim │ │
│ │ + pip install -r requirements.txt │ │
│ │ + 应用源码 + 配置 + 脚本 │ │
│ │ ─────────────────────────────────────────────────────── │ │
│ │ → 最终镜像（不含 Poetry、不含构建缓存） │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## docker-compose.yml 说明
### 基础版（仅应用服务）
项目自带的 `docker-compose.yml` 仅包含应用服务，适用于数据库和 Redis 已有外部实例的场景：
```yaml
# ======================================================================
# Docker Compose 编排文件（基础版）
# 仅包含应用服务，适用于数据库和 Redis 已有外部实例的场景
# 使用方式：docker compose up -d
# 依赖根目录下的 .env 提供环境变量
# ======================================================================
services:
# ====================================================================
# 应用服务：构建并运行本项目
# ====================================================================
tornado_elevue:
image: tornado_elevue:latest # 镜像名称
container_name: tornado_elevue # 容器名称
build:
context: ./ # 构建上下文为项目根目录
dockerfile: Dockerfile # 使用项目根目录的 Dockerfile
restart: always # 总是自动重启（生产环境推荐）
ports:
- "8041:8041" # 宿主机端口:容器端口
environment:
- TORNADO_PORT=8041 # 应用监听端口
- TORNADO_ENV=production # 运行环境设为生产模式
env_file:
- .env # 从 .env 文件加载数据库密码等环境变量
volumes:
- ./uploads:/data/apps/uploads # 持久化上传文件到宿主机
- ./logs:/data/apps/logs # 持久化日志（与 Dockerfile WORKDIR 对应）
command: python app.py # 启动命令
logging:
driver: "json-file" # 日志驱动：JSON 文件
options:
max-size: "500m" # 单个日志文件最大 500MB
max-file: "10" # 最多保留 10 个日志文件
```
### 完整版（应用 + MySQL + Redis）
快速体验或小型部署推荐使用包含 MySQL 和 Redis 的完整版：
```yaml
# ======================================================================
# Docker Compose 编排文件（完整版）
# 包含三个服务：app（应用）、mysql（数据库）、redis（缓存）
# 使用方式：docker compose up -d
# 依赖根目录下的 .env 提供密码等环境变量
# ======================================================================
services:
# ====================================================================
# 应用服务：构建并运行本项目
# ====================================================================
app:
build: . # 使用当前目录的 Dockerfile 构建镜像
ports:
- "8041:8041" # 宿主机端口:容器端口（供外部访问）
env_file:
- .env # 从 .env 文件加载环境变量（数据库密码等）
environment:
- TORNADO_ENV=production # 运行环境设为生产模式
- DB_HOST=mysql # 数据库地址指向 Docker 网络中的 mysql 服务
- REDIS_HOST=redis # Redis 地址指向 Docker 网络中的 redis 服务
volumes:
- ./uploads:/data/apps/uploads # 持久化上传文件到宿主机
- ./logs:/data/apps/logs # 持久化日志（与 Dockerfile WORKDIR 对应）
depends_on:
- mysql # 声明依赖，但不保证 mysql 已就绪
- redis
restart: unless-stopped # 除非手动停止，否则总是自动重启
# ====================================================================
# MySQL 数据库
# ====================================================================
mysql:
image: mysql:8.0 # 官方 MySQL 8.0 镜像
environment:
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD} # root 密码，从 .env 读取
MYSQL_DATABASE: ${DB_DATABASE} # 初始化时自动创建的数据库名
ports:
- "3306:3306" # 暴露到宿主机（生产环境建议去掉）
volumes:
- mysql_data:/var/lib/mysql # 命名卷持久化数据库数据
restart: unless-stopped
# ====================================================================
# Redis 缓存
# ====================================================================
redis:
image: redis:7-alpine # 轻量级 Redis 7 镜像
command: redis-server --requirepass ${REDIS_PASSWORD} # 启动时设置访问密码
ports:
- "6379:6379" # 暴露到宿主机（生产环境建议去掉）
volumes:
- redis_data:/data # 持久化 Redis 数据
restart: unless-stopped
# ======================================================================
# 命名卷：由 Docker 管理，数据存放在宿主机 /var/lib/docker/volumes 下
# ======================================================================
volumes:
mysql_data: # MySQL 数据持久化卷
redis_data: # Redis 数据持久化卷
```
### 完整版 .env 配置示例
使用完整版 docker-compose.yml 时，`.env` 文件中的数据库和 Redis 地址应指向 Docker 服务名称：
```bash
# ============================================================
# 数据库配置（指向 Docker 网络中的 mysql 服务）
# ============================================================
DB_DRIVER=mysql
DB_HOST=mysql # Docker 服务名称，不是 127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=root
DB_PASSWORD=your_mysql_password # 与 MYSQL_ROOT_PASSWORD 一致
DB_PREFIX=tornado_
# ============================================================
# Redis 配置（指向 Docker 网络中的 redis 服务）
# ============================================================
REDIS_HOST=redis # Docker 服务名称，不是 127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_AUTH=True
# ============================================================
# JWT 配置（必填）
# ============================================================
JWT_SECRET=your_jwt_secret_key_at_least_32_bytes
# ============================================================
# 应用配置
# ============================================================
TORNADO_ENV=production
TORNADO_DEBUG=False
```
## 常用 Docker 命令
```bash
# 构建镜像
docker compose build
# 启动服务（后台运行）
docker compose up -d
# 停止服务
docker compose down
# 停止服务并删除数据卷（⚠️ 会丢失数据）
docker compose down -v
# 查看日志（实时跟踪）
docker compose logs -f app
# 查看所有服务日志
docker compose logs -f
# 进入容器
docker compose exec app bash
# 重启服务
docker compose restart app
# 查看容器状态
docker compose ps
# 查看容器资源占用
docker stats
```
## 数据持久化
Docker Compose 使用命名卷和绑定挂载持久化数据：
| 存储方式 | 卷名/路径 | 说明 |
|:---------|:----------|:-----|
| 命名卷 | `mysql_data` | MySQL 数据文件（由 Docker 管理） |
| 命名卷 | `redis_data` | Redis 数据文件（由 Docker 管理） |
| 绑定挂载 | `./uploads` | 上传文件（映射到宿主机） |
| 绑定挂载 | `./logs` | 日志文件（映射到宿主机） |
:::warning 数据备份
生产环境定期备份数据库：
```bash
# 备份 MySQL
docker compose exec mysql mysqldump -uroot -p${DB_PASSWORD} ${DB_DATABASE} > backup_$(date +%Y%m%d).sql
# 恢复 MySQL
docker compose exec -T mysql mysql -uroot -p${DB_PASSWORD} ${DB_DATABASE} < backup.sql
```
:::
## 生产环境部署建议
### 1. 关闭调试模式
```bash
# .env
TORNADO_DEBUG=False
TORNADO_ENV=production
```
### 2. 使用强密钥
```bash
# 生成 JWT 密钥
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
### 3. 配置 Nginx 反向代理
```nginx
server {
# 监听 80 端口（HTTP）
listen 80;
# 域名配置（替换为实际域名）
server_name your-domain.com;
# 反向代理配置：将所有请求转发到 Tornado 应用
location / {
# 转发目标：Tornado 应用监听的地址和端口
proxy_pass http://127.0.0.1:8041;
# 传递原始请求头，让后端获取真实的客户端信息
proxy_set_header Host $host; # 原始域名
proxy_set_header X-Real-IP $remote_addr; # 客户端真实 IP
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 代理链 IP 列表
proxy_set_header X-Forwarded-Proto $scheme; # 原始协议（http/https）
# 超时配置（根据业务需求调整）
proxy_connect_timeout 60s; # 连接后端超时时间
proxy_send_timeout 60s; # 发送请求超时时间
proxy_read_timeout 60s; # 读取响应超时时间
# 缓冲配置
proxy_buffering on; # 开启响应缓冲，减轻后端压力
proxy_buffer_size 4k; # 响应头缓冲区大小
proxy_buffers 8 4k; # 响应体缓冲区数量和大小
}
# 静态文件直接由 Nginx 提供（可选，提升性能）
location /static/ {
alias /data/apps/static/; # 映射到容器内的静态文件目录
expires 7d; # 浏览器缓存 7 天
access_log off; # 关闭静态文件访问日志
}
# 上传文件直接由 Nginx 提供（可选）
location /uploads/ {
alias /data/apps/uploads/; # 映射到容器内的上传文件目录
expires 1d; # 浏览器缓存 1 天
access_log off;
}
# 安全配置：拒绝访问隐藏文件
location ~ /\. {
deny all;
access_log off;
log_not_found off;
}
}
```
:::tip HTTPS 配置
生产环境建议启用 HTTPS。可使用 Let's Encrypt 免费证书：
```bash
# 安装 certbot
apt install certbot python3-certbot-nginx
# 申请证书并自动配置 Nginx
certbot --nginx -d your-domain.com
```
:::
### 4. 限制端口暴露
生产环境建议不暴露 MySQL 和 Redis 端口到宿主机：
```yaml
# docker-compose.yml
mysql:
# ports: # 注释掉或删除
# - "3306:3306" # 生产环境不暴露
...
redis:
# ports: # 注释掉或删除
# - "6379:6379" # 生产环境不暴露
...
```
### 5. 配置日志轮转
```yaml
# docker-compose.yml
services:
app:
logging:
driver: "json-file"
options:
max-size: "500m" # 单个日志文件最大 500MB
max-file: "10" # 最多保留 10 个日志文件
```
## 常见问题
### 容器启动失败
```bash
# 查看容器日志
docker compose logs app
# 常见原因：
# 1. .env 配置错误（数据库密码、Redis 密码）
# 2. 端口被占用（修改 docker-compose.yml 中的端口映射）
# 3. 磁盘空间不足
# 4. JWT_SECRET 未配置或过短
```
### 数据库连接失败
```
1. 确认 MySQL 容器已启动：docker compose ps
2. 确认 .env 中 DB_HOST=mysql（Docker 服务名称，不是 127.0.0.1）
3. 确认 DB_PASSWORD 与 MYSQL_ROOT_PASSWORD 一致
4. 确认 MySQL 已就绪：docker compose logs mysql
```
### Redis 连接失败
```
1. 确认 Redis 容器已启动：docker compose ps
2. 确认 .env 中 REDIS_HOST=redis（Docker 服务名称，不是 127.0.0.1）
3. 确认 REDIS_PASSWORD 与 docker-compose.yml 中的密码一致
```
### 容器内时区不对
Dockerfile 已设置 `TZ=Asia/Shanghai`，如果仍有时区问题：
```bash
# 进入容器检查时区
docker compose exec app date
# 手动设置时区（docker-compose.yml）
environment:
- TZ=Asia/Shanghai
```
## 总结
Docker 部署通过 Docker Compose 一键启动应用、MySQL、Redis 三个服务。多阶段构建减小镜像体积，命名卷保证数据持久化。生产环境建议关闭调试模式、使用强密钥、配置 Nginx 反向代理、限制端口暴露、配置日志轮转。
DjangoAdmin_Tornado_EleVue/zh/volume1/env-vars.md
+196
View File
@@ -0,0 +1,196 @@
# 环境变量速查表
本章节汇总了项目 `.env` 文件中所有可配置的环境变量，按功能分类整理。所有变量均可在 `.env.example` 中找到示例。
:::tip 温馨提示
1. `.env.example` 是环境变量模板文件，已提交到版本控制。真实 `.env` 文件已被 `.gitignore` 忽略。
2. 首次使用请执行 `cp .env.example .env` 复制模板后修改。
3. 带有 `必填` 标记的变量必须设置，否则应用无法正常启动。
:::
## 基础配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| TORNADO_NAME | Tornado+EleVue旗舰版 | 应用名称，用于界面显示和系统标识 |
| TORNADO_VERSION | v3.0.0 | 应用版本号 |
| TORNADO_HOST | 127.0.0.1 | 应用监听地址。`127.0.0.1` 仅本地访问；容器/生产建议 `0.0.0.0` |
| TORNADO_PORT | 8041 | 应用监听端口 |
| TORNADO_APP | app.py | 应用启动文件名 |
| TORNADO_ENV | development | 运行环境：`development` / `production` / `testing` |
| TORNADO_DEBUG | True | 是否开启调试模式。`True` 时输出详细错误堆栈和 SQL 日志，生产环境务必设为 `False` |
| TORNADO_DEMO | False | 是否开启演示模式。`True` 时所有写操作（add/update/delete/status/batchDelete）返回"演示环境，暂无操作权限" |
| TORNADO_CORS_ORIGINS | （空） | CORS 允许的源白名单，逗号分隔。留空则允许所有来源 |
| TORNADO_TRUST_PROXY | False | 是否信任反向代理的 X-Forwarded-For 头。为 True 时取 XFF 最左侧 IP 作为客户端真实 IP |
| TORNADO_FILE_URL | （空） | 文件访问域名，用于拼接上传文件的访问 URL |
| UPLOAD_ALLOWED_EXTS | .jpg,.jpeg,.png,...,.zip | 允许上传的文件扩展名，逗号分隔（带点号） |
| UPLOAD_MAX_SIZE_MB | 10 | 上传文件大小上限（MB） |
:::tip 安全提示
生产环境务必设置 `TORNADO_DEBUG=False`，调试模式会输出详细的错误堆栈信息，可能泄漏内部实现细节。
:::
## 数据库配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| DB_DRIVER | mysql | 数据库驱动。可选：`mysql` / `postgresql` / `mssql` / `oracle` / `sqlite` |
| DB_HOST | 127.0.0.1 | 数据库地址（`sqlite` 时忽略） |
| DB_PORT | 3306 | 数据库端口（`sqlite` 时忽略） |
| DB_DATABASE | djangoadmin.tornado.elevue | 数据库名称。`sqlite` 时作为数据库文件完整路径 |
| DB_USERNAME | root | 数据库账号（`sqlite` 时忽略） |
| DB_PASSWORD | （空） | 数据库密码（`sqlite` 除外） |
| DB_PREFIX | tornado_ | 数据表前缀，所有业务表名自动添加此前缀 |
| DB_DEBUG | False | 是否开启 SQL 调试日志（对应 SQLAlchemy `echo` 参数）。生产环境务必设为 `False` |
| READ_DATABASE_URL | （空） | 读库地址（读写分离，可选；留空则读写同库） |
:::tip 多数据库支持
`DB_DRIVER` 支持别名：`postgres` → `postgresql`、`sqlserver` → `mssql`、`sqlite3` → `sqlite`。切换驱动后需安装对应的 Python 驱动包（`poetry install -E postgresql` / `-E mssql` / `-E oracle`）。
:::
## Redis 缓存配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| REDIS_HOST | 127.0.0.1 | Redis 服务地址 |
| REDIS_PORT | 6379 | Redis 服务端口 |
| REDIS_PASSWORD | （空） | Redis 密码。`REDIS_AUTH=True` 时必填 |
| REDIS_INDEX | 0 | Redis 库索引（0-15） |
| REDIS_AUTH | True | 是否启用 Redis 认证。设为 `False` 时无需密码 |
| REDIS_DECODE_RESPONSES | True | 是否自动解码响应（bytes → str） |
:::tip 温馨提示
Redis 用于存储验证码、JWT 令牌黑名单和登录防爆破数据，是项目正常运行的必需服务。
:::
## JWT 令牌配置（必填）
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| JWT_SECRET | （空） | JWT 签名密钥，**必填**。至少 32 字节强随机值，留空或过弱应用会拒绝启动（fail-close） |
| JWT_EXPIRE_MINUTES | 20 | JWT 令牌过期时间（分钟） |
| LOGIN_FAIL_MAX | 5 | 登录失败次数上限，超过后锁定账号（防暴力破解） |
| LOGIN_LOCK_SECONDS | 300 | 登录锁定时间（秒） |
:::danger 重要提示
`JWT_SECRET` 是安全关键配置，必须设置。推荐使用以下命令生成：
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
生成后请妥善保管，泄漏会导致令牌被伪造。已知不安全的默认值（如空字符串、`change-me`、`secret` 等）会在启动时被拦截。
:::
## 验证码配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| CAPTCHA_LENGTH | 6 | 验证码字符长度（4-6 位） |
| CAPTCHA_EXPIRE | 300 | 验证码过期时间（秒） |
| CAPTCHA_RATE_WINDOW | 60 | 验证码防刷窗口期（秒） |
| CAPTCHA_RATE_LIMIT | 20 | 窗口期内最大获取次数 |
| CAPTCHA_CHARS | 346789ABCDEFGHJKMNPQRTUVWXY | 验证码字符集（已去除易混淆字符） |
| CAPTCHA_IMAGE_WIDTH | 200 | 验证码图片宽度（像素） |
| CAPTCHA_IMAGE_HEIGHT | 60 | 验证码图片高度（像素） |
| CAPTCHA_FONT_SIZE | 30 | 验证码字体大小 |
| CAPTCHA_NOISE_LINES | 10 | 干扰线数量 |
| CAPTCHA_NOISE_DOTS | 60 | 噪点数量 |
| CAPTCHA_BYPASS_CODE | 618618 | 万能验证码（仅 TORNADO_DEMO=True 时生效） |
## 邮件配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| MAIL_MAILER | smtp | 邮件传输协议 |
| MAIL_SERVER | smtp.163.com | SMTP 服务器地址 |
| MAIL_PORT | 465 | SMTP 服务端口 |
| MAIL_USE_SSL | True | 是否启用 SSL 加密 |
| MAIL_USERNAME | （空） | 授权邮箱用户名 |
| MAIL_PASSWORD | （空） | 授权邮箱密码/授权码 |
| MAIL_ENCRYPTION | （空） | 邮件加密串（可选） |
| MAIL_FROM_NAME | （空） | 发件人显示名称 |
| MAIL_FROM_ADDRESS | （空） | 发件人邮箱地址 |
:::tip 温馨提示
邮件功能为预留扩展功能，暂未实现。
:::
## 日志配置
| 变量名 | 默认值 | 说明 |
|:----|:----|:----|
| LOG_LEVEL | INFO | 日志级别：DEBUG / INFO / WARNING / ERROR |
| LOG_DIR | logs | 日志输出目录 |
## 环境变量配置示例
以下是一个开发环境的 `.env` 文件示例（基于 `.env.example` 模板修改）：
```bash
# ============================================================
# 基础配置
# ============================================================
TORNADO_NAME=Tornado+EleVue旗舰版
TORNADO_VERSION=v3.0.0
TORNADO_HOST=127.0.0.1
TORNADO_PORT=8041
TORNADO_ENV=development
TORNADO_DEBUG=True
TORNADO_DEMO=False
# ============================================================
# 数据库配置
# ============================================================
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=djangoadmin.tornado.elevue
DB_USERNAME=root
DB_PASSWORD=your_password
DB_PREFIX=tornado_
DB_DEBUG=False
# ============================================================
# Redis 配置
# ============================================================
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_INDEX=0
REDIS_AUTH=True
# ============================================================
# JWT 配置（必填）
# ============================================================
JWT_SECRET=your_generated_secret_key_here_at_least_32_bytes
JWT_EXPIRE_MINUTES=20
LOGIN_FAIL_MAX=5
LOGIN_LOCK_SECONDS=300
# ============================================================
# 验证码配置
# ============================================================
CAPTCHA_LENGTH=6
CAPTCHA_EXPIRE=300
# ============================================================
# 上传配置
# ============================================================
UPLOAD_ALLOWED_EXTS=.jpg,.jpeg,.png,.gif,.bmp,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z
UPLOAD_MAX_SIZE_MB=10
```
:::tip 配置来源
所有配置变量在 `src/config/` 目录下的各模块中读取：`app.py`（基础配置）、`database.py`（数据库）、`auth.py`（JWT）、`redis.py`（Redis）、`captcha.py`（验证码）、`email.py`（邮件）。通过 `python-dotenv` 从 `.env` 文件加载。
:::
:::danger 安全提醒
1. 真实 `.env` 文件包含敏感信息（数据库密码、JWT 密钥等），已被 `.gitignore` 忽略，请勿提交到版本控制。
2. 生产环境务必设置 `TORNADO_DEBUG=False` 和 `DB_DEBUG=False`。
3. 定期轮换 `JWT_SECRET` 密钥，提高系统安全性。
:::
## 总结
本章节汇总了项目所有可配置的环境变量，涵盖基础配置、数据库、Redis、JWT、验证码、上传、邮件和日志等功能模块。通过合理配置这些变量，可以灵活调整项目的运行参数，适应不同的开发、测试和生产环境需求。建议首次使用时以 `.env.example` 为模板，仅修改必需项，其余保持默认值即可快速启动项目。
DjangoAdmin_Tornado_EleVue/zh/volume1/environment.md
+477
View File
@@ -0,0 +1,477 @@
# 环境准备
本章节介绍在本地搭建项目所需的基础环境和软件安装。项目采用 `Python` + `Tornado` 后端、`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` 是后端的核心运行环境，`Tornado` 框架要求 `Python 3.12` 或更高版本。
+ 下载 Python
访问 [Python 官方网站](https://www.python.org/downloads/)，选择适合你操作系统的 `Python 3.12+` 版本（推荐最新稳定版）。
![](/volume1/environment/1.png)
![](/volume1/environment/2.png)
点击 `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+` 版本（推荐最新稳定版）。
![](/volume1/environment/3.png)
点击 `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.tornado.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` 或更高），下载适合你操作系统的安装包。
![](/volume1/environment/4.png)
+ 安装 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 3.2+
# 4. 前端运行时
node -v # 期望: v22+
pnpm -v # 期望: 12.x+
# 5. 版本控制
git --version # 期望: git version 2.x+
```
:::tip 全部就绪
以上命令均能正确输出版本号，即表示本地开发环境已准备完毕，可以进入下一步：[后端启动](/zh/volume1/backend)。
:::
## 总结
本章节介绍了本地开发环境所需的全部基础软件及其安装配置步骤。通过以上步骤，你已经完成了 `Python`、`MySQL`、`Redis`、`Node.js`、`pnpm`、`Git` 的安装和验证。这些是运行项目的基础环境，后续章节将基于这些环境进行项目的启动和调试。如果在安装过程中遇到问题，可参考各软件的官方文档或查阅 [常见问题FAQ](/zh/volume1/faq) 章节。
DjangoAdmin_Tornado_EleVue/zh/volume1/faq.md
+424
View File
@@ -0,0 +1,424 @@
# 常见问题FAQ
本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。
:::tip 温馨提示
遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
:::
## 1. 端口被占用
**现象**
启动后端服务时报错：
```
OSError: [Errno 98] Address already in use
```
或：
```
ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次
```
**原因**
端口 `8041`（或配置的其他端口）已被其他程序占用。
**解决方案**
```bash
# Windows 查看端口占用
netstat -ano | findstr 8041
# 找到 PID 后终止进程
taskkill /PID <进程ID> /F
# Linux / macOS 查看端口占用
lsof -i :8041
# 终止进程
kill -9 <进程ID>
```
或者修改 `.env` 中的端口号：
```bash
TORNADO_PORT=8042
```
:::tip 温馨提示
前端开发服务器端口冲突同理，修改 `ui/.env.development` 中的 `VITE_PORT` 即可。
:::
## 2. 数据库连接失败
**现象**
启动时报错：
```
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")
```
或：
```
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1045, "Access denied")
```
**排查步骤**
```
1. 检查 MySQL 服务是否已启动
2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
3. 检查数据库用户是否有远程连接权限
4. 检查防火墙是否放行了数据库端口
```
**解决方案**
```bash
# 测试数据库连接
mysql -h127.0.0.1 -P3306 -uroot -p
# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.tornado.elevue2`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
```
:::tip 温馨提示
确认 `.env` 中的 `DB_PASSWORD` 没有多余的空格或引号。密码中的特殊字符可能需要转义。
:::
## 3. Redis 连接失败
**现象**
启动时报错：
```
redis.exceptions.ConnectionError: Error connecting to 127.0.0.1:6379
```
或：
```
redis.exceptions.AuthenticationError: Authentication required
```
**排查步骤**
```
1. 检查 Redis 服务是否已启动
2. 检查 .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
3. 检查 REDIS_AUTH 配置是否与 Redis 实际配置一致
```
**解决方案**
```bash
# 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
# Windows 启动 Redis 服务
net start Redis
# Linux 启动 Redis 服务
sudo systemctl start redis
# macOS 启动 Redis 服务
brew services start redis
```
:::tip 温馨提示
如果 Redis 未设置密码，请将 `.env` 中的 `REDIS_AUTH` 设为 `False`。
:::
## 4. pip install 安装失败
**现象**
执行 `pip install -r requirements.txt` 时报错：
```
ERROR: Could not find a version that satisfies the requirement xxx
```
或：
```
ERROR: Failed building wheel for xxx
```
**解决方案**
```bash
# 方案一：使用国内镜像源
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
# 方案二：升级 pip 后重试
python -m pip install --upgrade pip
pip install -r requirements.txt
# 方案三：配置全局镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com
```
:::tip 温馨提示
Windows 用户如果遇到 C 编译错误（如安装 `mysqlclient` 时），可尝试安装 Visual C++ Build Tools，或使用预编译的 wheel 包。
:::
## 5. JWT_SECRET 未配置
**现象**
启动时报错：
```
ValueError: JWT_SECRET must be set
```
或类似的安全配置错误。
**原因**
`.env` 文件中 `JWT_SECRET` 变量为空或未设置。JWT 签名密钥是安全关键配置，应用在 fail-close 模式下会拒绝启动。
**解决方案**
```bash
# 生成 JWT 密钥
python -c "import secrets; print(secrets.token_urlsafe(48))"
# 将生成的密钥写入 .env
JWT_SECRET=your_generated_secret_key_here
```
:::danger 重要提示
`JWT_SECRET` 至少需要 32 字节的强随机值。请勿使用简单字符串（如 `123456` 或 `secret`）作为密钥。
:::
## 6. pnpm install 安装失败
**现象**
执行 `pnpm install` 时报错：
```
ERR_PNPM_NO_MATCHING_VERSION
```
或：
```
GET https://registry.npmjs.org/xxx error
```
**解决方案**
```bash
# 方案一：切换淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install
# 方案二：清除缓存后重试
pnpm store prune
rm -rf node_modules
pnpm install
# 方案三：使用 --shamefully-hoist 模式
pnpm install --shamefully-hoist
```
:::tip 温馨提示
如果网络环境受限，可以尝试使用 VPN 或配置代理：
```bash
pnpm config set proxy http://127.0.0.1:7890
pnpm config set https-proxy http://127.0.0.1:7890
```
:::
## 7. API 请求返回 404
**现象**
调用接口时返回：
```json
{
"detail": "Not Found"
}
```
**原因**
可能是请求路径不正确，或后端路由未正确注册。
**排查步骤**
```
1. 检查请求路径是否以 /api/v1/ 开头
2. 检查 Swagger UI（http://127.0.0.1:8041/docs）中是否存在该接口
3. 检查前端代理配置中的后端地址是否正确
```
**解决方案**
```bash
# 测试后端服务是否正常
curl http://127.0.0.1:8041/api/v1/captcha
# 检查前端代理配置
# ui/.env.development
VITE_PROXY=[["/api","http://127.0.0.1:8041/api"]]
```
:::tip 温馨提示
所有业务接口都在 `/api/v1/` 前缀下。登录和验证码接口在 `/api/v1/` 下无需认证，其他接口需要携带 JWT Token。
:::
## 8. 验证码图片不显示
**现象**
登录页面验证码图片区域空白，或显示加载失败图标。
**排查步骤**
```
1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
2. 检查 /api/v1/captcha 接口是否返回正常
3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）
```
**解决方案**
```bash
# 1. 测试验证码接口
curl http://127.0.0.1:8041/api/v1/captcha
# 2. 测试 Redis 连接
redis-cli ping
# 应返回 PONG
# 3. 检查验证码字体文件是否存在
ls static/fonts/Vera.ttf
# 4. 如果字体文件缺失，检查 .env 中的 CAPTCHA_FONT_PATH 配置
```
:::tip 温馨提示
验证码生成依赖 `Pillow` 库和字体文件。如果字体文件缺失，可从项目仓库重新拉取，或修改 `CAPTCHA_FONT_PATH` 指向系统字体。
:::
## 9. 接口返回 403 权限不足
**现象**
调用接口返回：
```json
{
"code": 1,
"data": null,
"msg": "权限不足",
"ok": false
}
```
**原因**
当前登录用户没有该接口的访问权限。项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 `sys:user:list`）。
**解决方案**
```
1. 使用 admin 账号登录（ID=1 的管理员绕过所有权限检查）
2. 检查当前用户的角色是否包含该接口的权限
3. 在系统管理 > 菜单管理中，确认接口对应的权限节点已正确配置
4. 在系统管理 > 角色管理中，确认角色已分配该权限
```
:::tip 温馨提示
`admin` 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 `admin` 账号。
:::
## 10. 文件上传失败
**现象**
上传文件时返回错误：
```json
{
"code": 1,
"data": null,
"msg": "文件上传失败",
"ok": false
}
```
或：
```
413 Request Entity Too Large
```
**排查步骤**
```
1. 检查上传文件扩展名是否在 ALLOWED_EXTS 白名单中
2. 检查文件大小是否超过 UPLOAD_MAX_SIZE_MB 限制
3. 检查上传目录是否有写入权限
4. 检查 .env 中的 TORNADO_FILE_URL 配置是否正确
```
**解决方案**
```bash
# .env 中的上传配置
UPLOAD_ALLOWED_EXTS=.jpg,.jpeg,.png,.gif,.bmp,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z
UPLOAD_MAX_SIZE_MB=10
TORNADO_FILE_URL=http://file.tornado.elevue
```
:::tip 温馨提示
1. 如需上传更多文件类型，在 `UPLOAD_ALLOWED_EXTS` 中添加对应扩展名（带点号，逗号分隔）。
2. 如需上传更大文件，增大 `UPLOAD_MAX_SIZE_MB` 值。
3. 确保项目根目录下的 `uploads/` 目录存在且有写入权限。
:::
## 快速自检清单
遇到问题时，按以下清单逐项检查：
| 检查项 | 命令 | 期望结果 |
|:----|:----|:----|
| Python 版本 | `python --version` | 3.12+ |
| pip 依赖 | `poetry show tornado` | tornado 已安装 |
| MySQL 服务 | `mysql -uroot -p -e "SELECT 1"` | 返回 1 |
| Redis 服务 | `redis-cli ping` | PONG |
| .env 文件 | `cat .env \| grep JWT_SECRET` | 非空值 |
| 后端服务 | `curl http://127.0.0.1:8041/api/v1/captcha` | 返回 JSON |
| Node.js 版本 | `node -v` | v22+ |
| pnpm 版本 | `pnpm -v` | 11.x+ |
| 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 |
:::tip 温馨提示
如果以上检查项均正常但仍无法运行，建议查看完整错误日志：
```bash
# 后端日志
python app.py 2>&1 | tee backend.log
# 前端日志
cd ui && pnpm dev 2>&1 | tee frontend.log
```
:::
## 总结
本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。
DjangoAdmin_Tornado_EleVue/zh/volume1/first-api.md
+256
View File
@@ -0,0 +1,256 @@
# 第一个接口调试
本章节介绍如何使用 `curl` 或 `Postman` 等工具调试后端 API 接口，通过完整的登录流程（获取验证码 → 登录 → 获取令牌 → 调用业务接口）帮助你快速理解项目的接口调用方式。
:::tip 温馨提示
开始调试前，请确保已完成以下步骤：
1. 后端服务已启动（参见 [后端启动](/zh/volume1/backend)）
2. 数据库已初始化（参见 [数据库初始化](/zh/volume1/database)）
3. Redis 服务已启动
:::
## 接口调试工具
本项目后端基于 Tornado 框架，不提供内置的 Swagger 文档。推荐使用以下工具进行接口调试：
| 工具 | 说明 |
|:-----|:-----|
| `curl` | 命令行 HTTP 客户端，适合快速测试 |
| `Postman` | 图形化 API 调试工具，支持集合管理和环境变量 |
| 浏览器开发者工具 | 适合调试 GET 请求 |
## 第一步：获取验证码
登录前需要先获取图形验证码：
```bash
curl http://127.0.0.1:8041/api/v1/captcha
```
+ 响应示例
```json
{
"code": 0,
"data": {
"captcha": "data:image/png;base64,iVBORw0KG...",
"key": "sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ"
},
"msg": "操作成功",
"ok": true
}
```
:::tip 温馨提示
响应中的 `key` 是验证码的唯一标识，后续登录时需要使用。`captcha` 是 Base64 编码的验证码图片，可以在浏览器中直接查看。
:::
+ 记录关键信息
```
key: sl1dhi-ejqV2PWH8tYDE1pVNaRiccsrQ
验证码图片中的文字: （查看图片获取）
```
## 第二步：登录获取 Token
使用验证码和账号信息进行登录，获取 JWT 访问令牌：
```bash
curl -X POST "http://127.0.0.1:8041/api/v1/login" \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "123456",
"code": "图片中的验证码文字",
"key": "第一步获取的key"
}'
```
+ 成功响应
```json
{
"code": 0,
"data": {
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"msg": "登录成功",
"ok": true
}
```
+ 失败响应示例
```json
{
"code": 1,
"data": null,
"msg": "验证码错误或已过期",
"ok": false
}
```
:::danger 常见登录失败原因
| 错误信息 | 原因 | 解决方式 |
|:----|:----|:----|
| 验证码错误或已过期 | 验证码输入错误或超过 5 分钟有效期 | 重新获取验证码 |
| 账号或密码错误 | 用户名或密码不正确 | 使用默认账号 `admin/123456` |
| 账号已被锁定 | 连续登录失败超过 5 次 | 等待 5 分钟后重试 |
| 登录失败次数过多 | 同一 IP+用户名连续失败 | 等待锁定时间后重试 |
:::
+ 记录 Token
```
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
:::tip 温馨提示
Token 是后续所有认证接口的通行证，请妥善保存。默认有效期为 20 分钟（可通过 `.env` 中的 `JWT_EXPIRE_MINUTES` 修改）。
:::
## 第三步：使用 Token 调用业务接口
Token 获取后，在后续请求的 `Authorization` 头中携带即可调用需要认证的接口：
```bash
# 获取用户列表
curl -X GET "http://127.0.0.1:8041/api/v1/user/page?page=1&limit=10" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
+ 成功响应
```json
{
"code": 0,
"data": {
"list": [
{
"id": 1,
"username": "admin",
"realname": "超级管理员",
"status": 0,
"dept_id": 1,
"create_time": "2024-01-01 00:00:00"
}
],
"total": 1
},
"msg": "操作成功",
"ok": true
}
```
## 接口调用流程图
```
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ 获取验证码 │───▶│ 用户登录 │───▶│ 携带 Token 请求 │───▶│ 业务数据响应 │
│ GET /captcha │ │ POST /login │ │ Authorization: │ │ GET/POST │
└──────────────┘ └──────────────┘ │ Bearer <token> │ └──────────────┘
└──────────────────┘
│ │ │
▼ ▼ ▼
key JWT Token 业务数据
captcha (20分钟有效)
```
## 更多接口示例
```bash
# 获取验证码
curl http://127.0.0.1:8041/api/v1/captcha
# 登录
curl -X POST "http://127.0.0.1:8041/api/v1/login" \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456","code":"验证码","key":"key值"}'
# 健康检查（无需认证）
curl http://127.0.0.1:8041/api/v1/health
# 获取用户列表（需要认证）
curl -X GET "http://127.0.0.1:8041/api/v1/user/page?page=1&limit=10" \
-H "Authorization: Bearer <token>"
# 刷新 Token
curl -X POST "http://127.0.0.1:8041/api/v1/token/refresh" \
-H "Authorization: Bearer <token>"
# 获取字典下拉数据（需要认证）
curl -X GET "http://127.0.0.1:8041/api/v1/dict/data/link_type" \
-H "Authorization: Bearer <token>"
```
## API 响应格式说明
所有接口统一返回以下 JSON 格式：
```json
// 成功响应
{
"code": 0,
"data": {},
"msg": "操作成功",
"ok": true
}
// 失败响应
{
"code": 1,
"data": null,
"msg": "错误信息",
"ok": false
}
// 分页响应
{
"code": 0,
"data": {
"list": [],
"total": 100
},
"msg": "操作成功",
"ok": true
}
```
:::tip HTTP 状态码
业务成功时 HTTP 状态码为 `200`，通过 `code` 字段区分业务状态：`0` 表示成功，非 `0` 表示失败。认证失败（401）、权限不足（403）等会返回对应的 HTTP 状态码。
:::
## 常见问题
+ 接口返回 401 Unauthorized
```
原因：未提供 Token 或 Token 已过期
解决：重新登录获取 Token，检查 Authorization 头格式是否正确（Bearer <token>）
```
+ 接口返回 403 Forbidden
```
原因：当前用户无该接口的访问权限
解决：使用 admin 账号（ID=1 拥有全部权限），或检查角色权限配置
```
+ Token 过期
```
原因：Token 超过有效期（默认 20 分钟）
解决：重新登录获取新 Token，或调用 POST /api/v1/token/refresh 刷新
```
+ 接口返回演示模式限制
```
原因：.env 中 TORNADO_DEMO=True，写操作被禁止
解决：开发环境设置 TORNADO_DEMO=False
```
## 总结
本章节通过完整的登录流程演示了如何调试后端 API 接口：获取验证码 → 登录获取 Token → 携带 Token 调用业务接口。通过这个流程，你已经掌握了项目接口的基本调用方式和认证机制。如果遇到问题，请参见 [常见问题FAQ](/zh/volume1/faq) 章节。
DjangoAdmin_Tornado_EleVue/zh/volume1/frontend.md
+236
View File
@@ -0,0 +1,236 @@
# 前端启动
本章节介绍如何将前端项目安装依赖并启动开发服务器。前端基于 `Vue3` + `ElementPlus` + `TypeScript`+`Vite` 构建，采用组件化开发模式，支持热更新和代理配置。
:::tip 温馨提示
启动前端前，请确保已完成 [环境准备](/zh/volume1/environment) 章节中的 `Node.js` 和 `pnpm` 安装，并已启动后端服务（参见 [后端启动](/zh/volume1/backend)）。
:::
## 前端目录结构
前端源码位于项目根目录的 `ui/` 文件夹中：
```
ui/
├── public/ # 静态资源
├── src/
│ ├── api/ # 接口请求封装
│ ├── assets/ # 资源文件（图片、样式等）
│ ├── components/ # 公共组件
│ ├── layout/ # 布局组件
│ ├── router/ # 路由配置
│ ├── store/ # 状态管理（Pinia）
│ ├── utils/ # 工具函数
│ ├── views/ # 页面视图
│ ├── App.vue # 根组件
│ └── main.js # 入口文件
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── vite.config.ts # Vite 构建配置
├── package.json # 依赖清单
└── tsconfig.json # TypeScript 配置
```
## 安装依赖
进入前端项目目录，使用 `pnpm` 安装依赖：
```bash
# 进入前端目录
cd ui
# 安装依赖
pnpm install
```
安装过程如下：
```
$ pnpm install
Lockfile is up to date, resolution step is skipped
Packages: +1200
++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 1200, reused 1200, downloaded 0, added 1200, done
Done in 15.2s
```
:::tip 温馨提示
依赖安装完毕后，在 `ui/` 目录下会生成 `node_modules` 文件夹，此文件夹包含了项目全部的前端依赖包。首次安装可能需要较长时间，请耐心等待。
:::
+ 验证依赖安装
```bash
# 检查 Vue 版本
npx vue --version
# 检查 Vite 版本
npx vite --version
```
:::tip 常见问题
如果 `pnpm install` 失败，可尝试以下解决方案：
```bash
# 清除缓存后重新安装
pnpm store prune
pnpm install
# 删除 node_modules 后重新安装
rm -rf node_modules
pnpm install
```
:::
## 配置代理
前端开发服务器通过 `Vite` 代理将 API 请求转发到后端服务。代理配置位于 `vite.config.ts` 文件中。
+ 开发环境变量
前端开发环境的变量配置在 `.env.development` 文件中：
```bash
# 开发服务器端口
VITE_PORT = 8001
# 网站根目录
VITE_PUBLIC_PATH = /
# 跨域代理配置（指向后端服务地址）
VITE_PROXY=[["/api","http://127.0.0.1:8041/api"]]
# 接口前缀
VITE_GLOB_API_URL_PREFIX = /api
```
:::tip 代理说明
`VITE_PROXY` 配置项中，`/api` 是前端请求的路径前缀，`http://127.0.0.1:8041/api` 是后端服务的实际地址。前端所有以 `/api` 开头的请求都会被代理到后端的 `8041` 端口。
:::
+ 修改代理地址
如果后端服务运行在不同的地址或端口，需要修改 `.env.development` 中的代理配置：
```bash
# 示例：后端运行在 192.168.1.100 的 8041 端口
VITE_PROXY=[["/api","http://192.168.1.100:8041/api"]]
```
## 启动开发服务器
确保后端服务已启动后，在 `ui/` 目录下执行以下命令：
```bash
# 启动前端开发服务器
pnpm dev
```
启动成功后，终端将输出类似以下信息：
```
$ vite
VITE v3.2.10 ready in 943 ms
➜ Local: http://localhost:8001/
➜ Network: http://192.168.1.100:8001/
```
:::tip 默认端口
前端开发服务器默认运行在 `http://localhost:8001/`，可通过 `.env.development` 中的 `VITE_PORT` 参数修改端口。
:::
## 访问系统
在浏览器中打开以下地址：
```
http://localhost:8001/
```
![](/demo/1.png)
+ 默认登录账号
| 类型 | 账号 | 密码 | 说明 |
|:----|:----|:----|:----|
| 管理员 | `admin` | `123456` | 超管账号，默认拥有全部权限 |
| 普通用户 | `admin2` | `123456` | 普通账号，具有角色权限 |
:::tip 登录验证
1. 打开登录页面后，应能看到验证码图片正常显示，说明前后端通信正常。
2. 输入账号 `admin` 和密码 `123456`，点击登录按钮。
3. 成功登录后将进入系统主界面，表示前后端均已正确启动。
:::
:::danger 注意事项
如果验证码图片无法显示，请检查：
1. 后端服务是否已启动（`http://127.0.0.1:8041`）
2. 代理配置是否正确（`.env.development` 中的 `VITE_PROXY`）
3. Redis 服务是否正常运行（验证码存储依赖 Redis）
:::
## 前端构建与部署
+ 开发环境构建
```bash
# 开发环境打包
pnpm build:dev
```
+ 生产环境构建
```bash
# 生产环境打包
pnpm build
```
构建完成后，会在 `ui/` 目录下生成 `dist/` 文件夹，包含打包后的静态资源文件。将 `dist/` 目录部署到 `Nginx` 或其他 Web 服务器即可。
+ 预览构建结果
```bash
# 本地预览打包结果
pnpm preview
```
## 常见问题
+ pnpm install 失败
```bash
# 清除 pnpm 缓存
pnpm store prune
# 使用淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install
```
+ 端口被占用
如果启动时报端口冲突，可修改 `.env.development` 中的 `VITE_PORT`：
```bash
VITE_PORT = 8002
```
+ API 请求 404
检查后端服务是否启动，以及 `.env.development` 中的 `VITE_PROXY` 代理地址是否与后端实际地址一致。
+ 验证码不显示
```
1. 确认后端服务已启动
2. 确认 Redis 服务已启动并可连接
3. 检查浏览器控制台（F12）是否有跨域错误
4. 检查 .env 中 CORS_ALLOWED_ORIGINS 是否包含前端地址
```
## 总结
本章节介绍了前端项目的完整启动流程：安装依赖 → 配置代理 → 启动开发服务器 → 访问登录页面。通过以上步骤，你已经成功将前端应用运行在本地 `8001` 端口，并使用默认账号 `admin/123456` 登录系统。下一步可以进入 [第一个接口调试](/zh/volume1/first-api) 章节，学习如何使用 Swagger UI 调试后端 API 接口。