小蚂蚁云

Appearance

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

后端启动 ​

本章节介绍如何将后端项目从官网下载到本地并成功启动运行。后端基于 Python + Tornado 框架，采用分层架构设计（Handler 层 → Service 层 → Repository 层 → Model 层）。后端要求 Python 3.12+ 版本。

温馨提示

启动后端前，请确保已完成 环境准备 章节中的所有软件安装。

获取源码 ​

前往 官方网站 购买授权后，按以下步骤获取源码：

1. 登录官方网站，进入「个人中心」→「我的订单」页面。
2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
4. 将压缩包解压到本地开发目录（如 E:\Projects\ 或 ~/Projects/）。
bash
# 进入项目根目录（以实际解压路径为准）
cd DjangoAdmin_Tornado_AntdVue

温馨提示

  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 + AntDesign）
├── 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

温馨提示

如果网络较慢，可先配置 pip 镜像源（参见 环境准备），或使用 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

温馨提示

依赖安装完成后，如果上述命令输出版本号，说明核心依赖已正确安装。

配置环境变量 ​

项目通过 .env 文件管理所有配置参数。首次使用需要从示例文件复制并修改：

bash
# 复制环境变量示例文件
cp .env.example .env # Linux / macOS
copy .env.example .env # Windows CMD
  • 编辑 .env 文件

使用文本编辑器打开 .env 文件，修改以下关键配置：

bash
# ============================================================
# 基础配置
# ============================================================
TORNADO_NAME=Tornado+AntdVue旗舰版
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.antdvue
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

重要提示

  1. JWT_SECRET 是 JWT 令牌的签名密钥，必须设置且至少 32 字节。留空或过弱会导致应用拒绝启动（fail-close）。可使用以下命令生成：
bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
  1. DB_PASSWORD 和 REDIS_PASSWORD 请填写真实的服务密码。
  2. 生产环境务必设置 TORNADO_DEBUG=False，避免泄漏内部错误信息。

初始化数据库 ​

首次启动前，需要初始化数据库结构和种子数据。

方式一：手动导入（推荐） ​

bash
# 1. 登录 MySQL，创建数据库
mysql -uroot -p
CREATE DATABASE `djangoadmin.tornado.antdvue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# 2. 导入数据库脚本
mysql -uroot -p djangoadmin.tornado.antdvue < document/djangoadmin.tornado.antdvue.sql

方式二：Alembic 迁移（备选） ​

bash
# 自动建表
poetry run alembic upgrade head

# 导入业务字典种子数据
python scripts/seed_dict.py

温馨提示

项目支持 MySQL、PostgreSQL、SQL Server、SQLite、Oracle 等数据库。通过 .env 中的 DB_DRIVER 切换驱动（默认 mysql）。非 MySQL 数据库请使用 Alembic + seed 脚本初始化。详细的多数据库初始化步骤请参考 数据库初始化 章节。

初始化完成后，数据库中包含以下默认数据：

管理员账号：admin / 123456（超级管理员，ID=1，跳过权限校验）
默认角色：超级管理员角色
默认菜单：系统管理、内容管理、监控管理等菜单及权限节点
数据字典：系统内置字典数据
系统配置：系统默认配置项

启动后端服务 ​

一切准备就绪后，执行以下命令启动后端服务：

bash
# 使用 Poetry 启动（推荐）
poetry run python app.py --port=8041

# 或直接 python 启动
python app.py --port=8041

启动入口说明

启动流程：app.py（main） → src/bootstrap.py:main() → src/app.py:create_app()

bootstrap.py 负责解析命令行参数（--port）、创建应用、注册 SIGINT/SIGTERM 信号实现优雅关闭。

create_app() 是应用工厂函数（位于 src/app.py），负责组装路由、配置模板/静态目录、初始化扩展。

启动成功后，终端将输出类似以下信息：

  ____                              _                         _
 |  _ \  _   _   __ _  _ __   ___ (_) _ __    __ _  _ __   __| |
 | | | || | | | / _` || '__| / __|| || '_ \  / _` || '__| / _` |
 | |_| || |_| || (_| || |    | (__ | || |_) || (_| || |   | (_| |
 |____/  \__,_| \__,_||_|     \___||_|| .__/  \__,_||_|    \__,_|
                                       |_|
 Tornado + AntdVue 企业级管理框架

[INFO] 服务启动成功 → http://127.0.0.1:8041

默认端口

后端服务默认监听端口为 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 提供了常用命令的快捷方式。

Windows 用户注意

make 命令是 Linux / macOS 系统自带的构建工具，Windows 系统默认不包含。Windows 用户可直接执行表格中"对应命令"列所示的原始命令。

命令对应命令说明
make installpoetry install安装依赖
make devpoetry run python app.py --port=8041启动开发服务
make testpoetry run pytest运行全部测试
make test-unitpoetry run pytest tests/unit运行单元测试
make lintpoetry run ruff check src tests代码规范检查
make seed-dictpython 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 端口。下一步可以进入 前端启动 章节，启动前端项目并登录系统。

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

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