# FastapiVueUniAppX **Repository Path**: Jopfree/FastapiVueUniAppX ## Basic Information - **Project Name**: FastapiVueUniAppX - **Description**: 基于 FastAPI + Vue3 + UniApp X 的全栈后台管理系统，整合常用开源方案，便于自用二次开发。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-28 - **Last Updated**: 2026-08-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Fastapi-Admin-Unix 基于 FastAPI + Vue3 + UniApp X 的全栈后台管理系统，整合常用开源方案，便于自用二次开发。 | 模块 | 目录 | 技术栈 | 上游来源 | |------|------|--------|----------| | 后端 API | [`fastapi/`](./fastapi) | FastAPI · SQLAlchemy · Redis · Celery | [fastapiwebadmin](https://github.com/rebort-hub/fastapiwebadmin) | | 管理后台 | [`web/`](./web) | Vue3 · TypeScript · Vite · Element Plus | [Geeker-Admin](https://gitee.com/HalseySpicy/Geeker-Admin) | | 移动端 | [`uniappx/`](./uniappx) | UniApp X · UTS · UnoCSS | [jomo-unix](https://gitee.com/Jopfree/jomo-unix) | --- ## 架构概览 ```text ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ web (管理端) │ │ uniappx (移动端) │ │ 第三方 / OAuth │ │ Vue3 + Vite │ │ UniApp X │ │ GitHub/Gitee等 │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ └────────────────────┼────────────────────┘ ▼ ┌──────────────────┐ │ fastapi (API) │ :8100 │ JWT / RBAC / 日志 │ └────────┬─────────┘ ┌─────────────┼─────────────┐ ▼ ▼ ▼ MySQL Redis Celery ``` --- ## 功能特性 ### 后端 (`fastapi`) - JWT 认证、验证码、用户注册（可选邮箱验证码） - RBAC：用户 / 角色 / 菜单 / 部门 / 数据字典 - 登录日志、操作日志、IP 归属地 - 文件上传（本地 / 阿里云 OSS / 腾讯 COS / 七牛 / MinIO） - OAuth：GitHub、Gitee、微信开放平台、QQ - Alembic 迁移、启动自动建表与种子数据 - Celery 异步任务与定时调度（插件） - 插件化扩展（`fea_celery`、`fea_project`） ### 管理后台 (`web`) - 动态路由、按钮级权限、KeepAlive 多级缓存 - ProTable、主题切换、暗黑模式、i18n - Axios 封装、常用指令（权限 / 复制 / 水印 / 防抖等） - ESLint · Prettier · Stylelint · husky · commitlint ### 移动端 (`uniappx`) - 页面路由自动生成、自定义 TabBar - OpenAPI 接口代码生成、请求与路由封装 - UnoCSS 原子化、主题色、字体大小、i18n - Iconify / SVG / iconfont、ECharts --- ## 环境要求 | 组件 | 版本建议 | |------|----------| | Python | ≥ 3.10（推荐 3.11） | | Node.js | ≥ 18 | | 包管理 | [uv](https://github.com/astral-sh/uv)（后端）、pnpm（前端） | | MySQL | ≥ 5.7 / 8.x | | Redis | ≥ 6.x | | HBuilderX | 开发 UniApp X 时需要 | --- ## 快速开始 ### 1. 克隆仓库 ```bash git clone <你的仓库地址> cd Fastapi-Admin-Unix ``` ### 2. 启动后端 前置：已安装 [uv](https://github.com/astral-sh/uv)，本机 MySQL / Redis 可用（或沿用 Docker 中的 `fastapiwebadmin-mysql` / `fastapiwebadmin-redis`）。 ```bash cd fastapi # 配置环境（首次） # Windows: copy env\.env.dev.example env\.env.dev cp env/.env.dev.example env/.env.dev # 按需修改 MySQL / Redis / SECRET_KEY 等（默认端口 8100） ``` #### Windows：`run_win.bat` 双击 `fastapi/run_win.bat`，或在 **CMD** 中： ```bat cd fastapi run_win.bat ``` 菜单为中文。`run_win.bat` 使用 **GBK** 编码以适配系统 CMD；请勿用编辑器另存为 UTF-8，否则会出现乱码。若已乱码，从仓库重新检出该文件即可。 首次若没有 `env\.env.dev`，脚本会从示例复制并提示你先编辑再重新运行。 出现菜单后按数字选择： | 选项 | 作用 | |------|------| | `0` | 安装/同步依赖（`uv sync`） | | `1` | 启动开发服务（热重载，默认 `http://127.0.0.1:8100`） | | `2` | 生成 Alembic 迁移脚本 | | `3` | 应用迁移到数据库 | | `4` | 重置数据库并导入种子（会删表，慎用） | | `5` | 导出生产依赖到 `requirements.txt` | | `9` | 退出 | 推荐首次流程：`0` → 确认 `env\.env.dev` → `1`。 服务起来后打开：http://127.0.0.1:8100/docs 也可不进菜单，直接执行等价命令： ```bat uv sync uv run main.py run --env=dev ``` #### Linux / macOS：`run_linux.sh` ```bash chmod +x run_linux.sh ./run_linux.sh # 交互菜单 ./run_linux.sh sync # 安装依赖 ./run_linux.sh run # 启动开发服务 ``` 常用命令： ```bash uv sync uv run main.py run --env=dev # 启动，默认 http://127.0.0.1:8100 uv run main.py revision -m "描述" # 生成迁移 uv run main.py upgrade # 应用迁移 uv run main.py reset --env=dev # 重置库并导入种子（危险） ``` - API 文档：`http://127.0.0.1:8100/docs` - 默认账号：`admin` / `123456`（种子数据导入后） Docker： ```bash cd fastapi docker build -t fastapi-admin . docker run -p 8100:8100 --env-file env/.env.prod fastapi-admin ``` 生产进程示例（见 `start.sh`）： ```bash ./start.sh app 8101 # Gunicorn + Uvicorn ./start.sh celery-worker ./start.sh celery-beat ``` ### 3. 启动管理后台 ```bash cd web pnpm install pnpm dev # 默认 http://127.0.0.1:8848 ``` 对接本地后端时，修改 `web/.env.development` 中的代理，例如： ```env VITE_API_URL = /api VITE_PROXY = [["/api","http://127.0.0.1:8100/api"]] ``` 构建： ```bash pnpm build:dev pnpm build:test pnpm build:pro ``` ### 4. 启动移动端 使用 HBuilderX 打开 `uniappx/` 目录运行到浏览器 / 模拟器 / 真机。 辅助脚本（需先 `pnpm install`）： ```bash cd uniappx pnpm pages # 根据 pages.config.mjs 生成 pages.json pnpm openapi # 从 OpenAPI 生成接口类型/代码 pnpm icons # 生成图标字体 ``` 接口地址在 `uniappx/config/env.uts` 中按环境配置。 --- ## 目录结构 ```text Fastapi-Admin-Unix/ ├── fastapi/ # 后端 │ ├── app/ │ │ ├── api/v1/ # 路由：common / system │ │ ├── core/ # 数据库、权限、依赖注入 │ │ ├── plugin/ # 插件（Celery、业务示例） │ │ ├── models/ # ORM 基类 │ │ ├── scripts/ # 启动初始化、种子数据 │ │ └── utils/ # 工具 │ ├── db_script/ # MySQL / Redis 配置样例、初始化 SQL │ ├── env/ # 环境变量示例 │ ├── main.py # 入口与 CLI │ ├── Dockerfile │ └── requirements.txt ├── web/ # Vue3 管理后台 │ └── src/ │ ├── api/ # 接口 │ ├── components/ # 公共组件（ProTable 等） │ ├── layouts/ # 布局 │ ├── routers/ # 路由 │ ├── stores/ # Pinia │ └── views/ # 页面 ├── uniappx/ # UniApp X 客户端 │ ├── api/ # 请求封装、OpenAPI │ ├── pages/ # 业务页 │ ├── pages-sys/ # 登录/设置等系统页 │ ├── router/ # 路由拦截 │ ├── store/ # 状态 │ └── scripts/ # 代码生成脚本 ├── Dockerfile # 根目录镜像（与 fastapi 一致） └── README.md ``` --- ## 后端主要模块 | 模块 | 说明 | |------|------| | `auth` | 登录、注册、验证码、Token、OAuth | | `user` | 用户管理 | | `roles` | 角色与权限 | | `menu` | 菜单 / 路由 | | `department` | 部门树 | | `lookup` | 数据字典 | | `id_center` | ID 中心 | | `login_record` | 登录记录 | | `operation_log` | 操作日志 | | `file` | 文件上传 | | `health` | 健康检查 | --- ## 开发约定 - 后端依赖用 **uv** 管理（`pyproject.toml` / `uv.lock`），生产导出 `requirements.txt` - 前端 / UniApp X 使用 **pnpm** - Git 提交信息建议 Conventional Commits，中文描述，例如：`feat: 完善用户登录逻辑` - 各子项目可有独立 `.cursorrules`，以子目录规则为准 --- ## 致谢 本仓库在以下开源项目基础上整合与定制，感谢原作者： - [Geeker-Admin](https://gitee.com/HalseySpicy/Geeker-Admin) — Web 管理端 - [fastapiwebadmin](https://github.com/rebort-hub/fastapiwebadmin) — FastAPI 后端 - [jomo-unix](https://gitee.com/Jopfree/jomo-unix) — UniApp X 客户端 --- ## License 各子模块遵循其上游开源协议；本仓库整体按自用整合项目处理。二次分发前请核对上游 License。