FastAPI Web Admin

FastAPI Web Admin 是一套开箱即用的后台管理脚手架，后端采用 系统模块 + 业务插件 分离架构，前端基于 Vue3 + Element Plus。

核心能力：

• RBAC 权限（菜单 / 按钮 / 接口）
• 动态路由与菜单配置
• 业务插件自动发现与注册
• Alembic 数据库版本管理
• uv 依赖管理与统一 CLI
• 开发环境自动建表与种子数据

默认账号： admin / 123456

fastapiwebadmin/
├── backend/                 # 后端（Python / FastAPI）
│   ├── main.py              # 唯一入口：create_app + CLI
│   ├── pyproject.toml       # 依赖声明（uv 源）
│   ├── uv.lock
│   ├── alembic.ini
│   ├── env/                 # 环境配置（唯一配置目录）
│   │   ├── .env.dev.example
│   │   └── .env.prod.example
│   ├── db_script/           # 种子 SQL（db_init.sql）
│   ├── app/
│   │   ├── api/v1/          # 系统 API（controller / service / schema / model）
│   │   ├── plugin/          # 业务插件（fea_project、fea_celery 等）
│   │   ├── orm/             # 仅 base.py 公共 ORM 基类
│   │   ├── shared/          # 跨模块共享：常量、异常、Schema、枚举、路由
│   │   ├── infrastructure/  # 持久化 / Redis / 建表
│   │   ├── bootstrap/       # 启动装配：异常处理、限流器
│   │   ├── core/            # 横切能力：权限、依赖、日志、插件发现
│   │   ├── config/          # setting.py / path_conf.py
│   │   ├── scripts/         # init_app.py、initialize.py
│   │   └── alembic/         # 迁移脚本
│   ├── run_win.bat          # Windows 开发菜单
│   └── run_linux.sh         # Linux 开发脚本
│
├── frontend/                # 前端（Vue3）
│   └── src/
│       ├── api/             # 接口封装
│       ├── views/           # 页面
│       ├── components/      # 公共组件（synrebort-table 等）
│       └── ...
│
└── README.md

注意： 旧版 app/apis/、app/services/、app/schemas/、config.py、cli.py 已移除。所有开发请遵循下方规范，勿在废弃路径下新增代码。

每个业务模块固定四层文件，目录即模块边界：

<module>/
├── controller.py    # 接口层：路由、入参校验、调用 service
├── service.py       # 业务层：业务逻辑、事务编排
├── schema.py        # 契约层：Pydantic 请求/响应/查询模型
└── model.py         # 数据层：SQLAlchemy ORM 模型（继承 Base）

调用链（单向）：

HTTP 请求 → controller → service → model → 数据库
              ↑            ↑
           schema       schema（入参/出参类型）

系统模块示例：

app/api/v1/system/user/
├── controller.py
├── service.py
├── schema.py
└── model.py          # User 表

业务插件示例：

app/plugin/fea_project/project/
├── controller.py
├── service.py
├── schema.py
└── model.py          # ProjectInfo 等

model.py 会被 ImportUtil 自动扫描，启动时 create_all 自动建表，无需注册到 Alembic。

除 app/orm/base.py 公共基类外，所有业务定义必须在模块目录内完成，禁止集中到 system_models.py 等共享文件。

<module>/
├── controller.py
├── service.py
├── schema.py
└── model.py

允许仅保留的公共层：

禁止：

• 在 backend/ 根目录新建 config.py 或第二套配置
• 新建 apis/、services/ 平级目录
• 新功能把 ORM 写进集中式 *_models.py 文件
• 通过 re-export shim 做「兼容旧路径」

• 系统 API：在 app/api/v1/system/router.py 聚合，前缀 /api
• 业务插件：discover.py 扫描 fea_*/**/controller.py，自动挂载

插件目录名必须以 fea_ 开头：

app/plugin/fea_project/
├── plugin.toml
└── project/                 # 子模块，遵循四层约定
    ├── controller.py
    ├── service.py
    ├── schema.py
    ├── model.py

fea_celery（后台任务插件，无 HTTP 四层中的 controller）：

app/plugin/fea_celery/
├── plugin.toml
├── worker.py
├── model.py
├── schema.py
├── tasks/
└── scheduler/

# 开发
cp backend/env/.env.dev.example backend/env/.env.dev

# 生产
cp backend/env/.env.prod.example backend/env/.env.prod

通过 ENVIRONMENT 切换：dev / prod。配置只读 backend/env/.env.{env}，不使用根目录 .env。

关键项：

• 控制台 + backend/logs/info.log + backend/logs/error.log
• 使用 from app.core.logger import log, logger

• Python 3.10+，函数与公共方法加类型注解
• 遵循 PEP 8
• Schema 继承 app.shared.schemas.BaseSchema
• API 响应统一走 app.utils.response.HttpResponse

• Python 3.10+
• Node.js 18+
• MySQL 8.0+
• Redis 6+（限流 / Celery 需要）
• uv

CREATE DATABASE fastapiwebadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

cd backend

# 安装依赖
uv sync

# 配置环境（首次）
cp env/.env.dev.example env/.env.dev
# 编辑 env/.env.dev：数据库、Redis 等

# 方式 A：开发菜单（Windows）
run_win.bat

# 方式 B：命令行
uv run main.py run --env=dev

服务地址：

• API：http://127.0.0.1:8100
• 文档：http://127.0.0.1:8100/docs

Linux 快捷脚本：

./run_linux.sh sync    # 安装依赖
./run_linux.sh dev     # 启动开发服务

cd frontend
yarn install    # 或 npm install
yarn dev        # 开发：http://localhost:3000

开发模式下 Vite 将 /api 代理到 http://127.0.0.1:8100，无需改接口路径。

开发环境（推荐）： 启动时若库为空，会自动建表并导入 db_script/db_init.sql。

也可手动重置（会删表重建）：

cd backend
uv run main.py reset --env=dev

生产环境： 关闭 AUTO_CREATE_TABLES 与 AUTO_SEED_DATA，使用 Alembic（见下文）。

所有命令在 backend/ 目录执行：

uv run main.py <command> --env=dev|prod

开启 AUTO_CREATE_TABLES=True 后，每次启动会自动：

1. 扫描全项目各模块下的 model.py
2. 对缺失表执行 create_all（含新业务插件）

新增业务模块时：写好 model.py 重启服务即可，不必改 Alembic 配置。

关闭自动建表，使用 Alembic 显式迁移：

AUTO_CREATE_TABLES = False
AUTO_SEED_DATA = False

迁移目录：backend/app/alembic/versions/。执行 revision 时同样通过 ImportUtil 自动发现模型，无需手动注册。

1. 修改 ORM 模型（各业务模块 model.py，基类在 app/orm/）
2. 生成迁移脚本

cd backend
uv run main.py revision --env=dev -m "add xxx column"

3. 检查生成的文件（app/alembic/versions/xxxx_*.py），确认 upgrade() / downgrade() 无误
4. 应用迁移

uv run main.py upgrade --env=dev

5. 提交迁移文件到 Git（与模型变更同一 PR）

# 1. 部署代码
# 2. 备份数据库
# 3. 应用迁移
uv run main.py upgrade --env=prod
# 4. 重启服务

生产环境请设置：

AUTO_CREATE_TABLES = False
AUTO_SEED_DATA = False

避免 create_all 与 Alembic 状态不一致。

uv run main.py downgrade --env=dev        # 回滚 1 个版本
uv run main.py downgrade --env=dev -r -2  # 回滚 2 个版本
uv run main.py history --env=dev          # 查看版本链

当本地库混乱、种子数据异常时：

uv run main.py reset --env=dev

等价于：删表 → create_tables() → 导入 db_init.sql。

• 在对应模块下创建 model.py，模型继承 Base
• 开发环境重启服务，确认表已自动创建
• 生产环境再执行 revision → upgrade

cd backend
uv sync --no-dev
cp env/.env.prod.example env/.env.prod
# 编辑生产配置

uv run main.py upgrade --env=prod

gunicorn "main:create_app()" \
  --factory \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8100

或使用 start.sh：

./start.sh app 8100

异步任务已作为业务插件 app/plugin/fea_celery/ 提供，不启用时不影响主服务。

cd backend

# Worker（Windows 使用 --pool=solo）
celery -A app.plugin.fea_celery.worker.celery worker --pool=solo -l INFO

# Beat（数据库调度器）
celery -A app.plugin.fea_celery.worker.celery beat \
  -S app.plugin.fea_celery.scheduler.schedulers:DatabaseScheduler -l INFO

或使用 start.sh：

./start.sh celery-worker 8100
./start.sh celery-beat 8100

新增任务：在 app/plugin/fea_celery/tasks/ 下编写，并在 plugin.toml 的 [celery].tasks 中注册。

cd frontend
yarn build
# 将 dist/ 部署到 Nginx 等静态服务器

Nginx 需将 /api 反向代理到后端 8100 端口。

frontend/src/
├── api/              # 按模块封装 HTTP 请求
├── views/            # 页面（system/ 为系统管理）
├── components/       # 公共组件（synrebort-table、synrebort-card）
├── router/           # 路由与守卫
├── stores/           # Pinia 状态
└── utils/request.ts  # Axios 封装

• 组件目录使用 kebab-case（如 synrebort-table/）
• 全局组件在 utils/other.ts 注册
• 权限按钮使用 v-permission 指令

Q: 登录失败 / 用户不存在？

开发环境执行 uv run main.py reset --env=dev 重新导入种子数据。

Q: Redis 报错 AUTH but no password is set？

本地 Redis 无密码时，将 env/.env.dev 中 REDIS_PASSWORD 留空，REDIS_URI 不要带密码段。

Q: 前端请求不到后端？

确认后端已启动在 8100，且 frontend/vite.config.ts 代理 /api → 8100。

Q: bcrypt 密码错误？

项目固定 bcrypt==4.0.1（与 passlib 兼容），请使用 uv sync 安装锁定版本。

Q: 新人误改旧目录？

app/apis、app/services、config.py、cli.py 已删除。只按本文「后端开发规范」在 api/v1 或 plugin 下开发。

cd backend
uv run pytest

本项目采用 MIT 协议。

• FastAPI 文档
• Vue 3 文档
• Element Plus
• uv 文档