FastApiAdmin ^v2.0.0

| |----------|----------|----------| |  |  |  | ## 🚀 快速开始 ### 第一次本地运行（按顺序） 1. **安装运行时**：Python ≥ 3.10、Node.js ≥ 20、[pnpm](https://pnpm.io/zh/)（前端包管理）、本机 **MySQL 或 PostgreSQL**（或改用 SQLite 需在 `backend/env/.env.dev` 中配置）、**Redis**（与 `.env.dev` 中一致）。 2. **获取代码**：见下方「获取代码」。 3. **配置环境变量**：将 `backend/env/.env.dev.example` 复制为 `backend/env/.env.dev`，将 `frontend/.env.development.example` 复制为 `frontend/.env.development`，按注释填写 **数据库连接、Redis、JWT 密钥** 等（须先在本机创建空数据库）。 4. **安装后端依赖**：进入 `backend`，推荐使用 **`uv sync`**（见下「后端启动」）；或使用 `pip install -r requirements.txt`。 5. **启动后端**：`uv run main.py run --env=dev`。**首次启动会自动初始化数据库表结构及基础数据**，一般**无需**事先执行 `upgrade` 迁移命令。 6. **安装前端依赖并启动**：进入 `frontend` 执行 `pnpm install` 与 `pnpm run dev`。 7. **打开浏览器**：按模板一般为 **`http://127.0.0.1:5180`**（`VITE_APP_PORT=5180`）；使用管理员账号登录（与 [演示环境](#-演示环境) 一致，若你导入的是初始 SQL 则以后台为准）。 > **说明**：若你**修改了 ORM 模型**并需用 Alembic 管理变更，再使用 `python main.py revision` / `upgrade`（见下文「常见问题」）。 ### 环境要求 | 类型 | 技术栈 | 版本 | |------|--------|------| | 后端 | Python | ≥ 3.10（推荐 3.12） | | 后端 | FastAPI | 0.109+ | | 前端 | Node.js | ≥ 20.0 | | 前端 | Vue3 | 3.3+ | | 数据库 | MySQL / PostgreSQL / SQLite | 见 `backend/env` 配置 | | 缓存 | Redis | 建议 6.x / 7.x（与 `.env` 一致） | ### 获取代码 ```bash # 克隆代码到本地 git clone https://gitee.com/fastapiadmin/FastapiAdmin.git # 或者 git clone https://github.com/fastapiadmin/FastapiAdmin.git ``` > **后端注意**：克隆下的代码需要修改 `backend/env` 目录下的 `.env.dev.example` 文件为 `.env.dev`，修改 `backend/env` 目录下的 `.env.prod.example` 文件为 `.env.prod`，然后根据实际情况修改数据库连接信息、Redis连接信息等。 > **前端注意**：克隆下的代码需要修改 `frontend` 目录下的 `.env.development.example` 文件为 `.env.development`，修改 `frontend` 目录下的 `.env.production.example` 文件为 `.env.production`，然后根据实际情况修改接口地址等。 ### 后端启动 #### 使用 uv（推荐，与 `backend/pyproject.toml` 一致） ```bash cd backend uv sync # 启动：请先保证已创建空数据库、Redis 已启动且与 .env.dev 一致 # 首次启动会自动初始化表与基础数据，无需先执行 upgrade uv run main.py run --env=dev # 生产环境示例 # uv run main.py run --env=prod ``` > 若未使用 `uv`：`pip install -r requirements.txt` 后直接 `python main.py run --env=dev`。模型变更需走 Alembic 时再执行 `upgrade`。 #### 使用传统 pip / venv ```bash cd backend python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate pip install -r requirements.txt python main.py run --env=dev ``` ### 前端启动 #### Web前端 (Vue3) ```bash cd frontend/web pnpm install pnpm run dev # 构建生产版本 pnpm run build ``` #### 移动端 (UniApp) ```bash cd frontend/app pnpm install pnpm run dev:h5 # 启动H5开发服务器 # 构建生产版本 pnpm run build:h5 ``` #### 文档网站 (VitePress) ```bash cd frontend/docs pnpm install pnpm run dev # 构建生产版本 pnpm run build ``` ### 启动后访问 与 **`.env.dev.example` / `.env.development`** 对齐时： | 服务 | 地址（示例） | |------|----------------| | Web前端 (Vite) | `http://127.0.0.1:5173` | | 移动端H5 (UniApp) | `http://127.0.0.1:8080` | | 文档网站 (VitePress) | `http://127.0.0.1:5174` | | 后端 API 根 | `http://127.0.0.1:8001` | | Swagger | `http://127.0.0.1:8001/docs` | | 业务接口前缀 | `http://127.0.0.1:8001/api/v1`（与 `ROOT_PATH` 一致） | ### 🐳 Docker 部署 #### 使用 deploy.sh 脚本（推荐） ```bash # 1. 克隆代码到服务器 git clone https://gitee.com/fastapiadmin/FastapiAdmin.git cd FastapiAdmin # 2. 赋予执行权限并部署 chmod +x deploy.sh ./deploy.sh # 查看容器日志 ./deploy.sh logs # 停止服务 ./deploy.sh stop # 重启服务 ./deploy.sh restart # 仅更新代码并重启（不重新构建镜像） ./deploy.sh update # 跳过前端构建（使用已上传的静态文件） ./deploy.sh --skip-frontend # 启用前端构建（在服务器上构建） ./deploy.sh --build-frontend ``` > **注意**： > - 首次部署时会自动拉取代码并构建镜像 > - 前端使用本地构建的 dist 目录，如需更新前端请先本地构建并提交到仓库 > - 确保 `devops/nginx/ssl/` 目录包含 SSL 证书文件（如使用 HTTPS） ## 🛠️ 二开教程 ### 后端开发 项目采用**插件化架构设计**，二次开发建议在 `backend/app/plugin` 目录下进行，系统会**自动发现并注册**所有符合规范的路由，便于模块管理和升级维护。 #### 插件化架构特性 - **自动路由发现**：系统会自动扫描 `backend/app/plugin/` 目录下所有 `controller.py` 文件 - **自动路由注册**：所有路由会被自动注册到对应的前缀路径 (module_xxx -> /xxx) - **模块化管理**：按功能模块组织代码，便于维护和扩展 - **支持多层级嵌套**：支持模块内部多层级嵌套结构 #### 插件目录结构 ```sh backend/app/plugin/ ├── module_application/ # 应用模块（自动映射为 /application） │ └── ai/ # AI子模块 │ ├── controller.py # 控制器文件 │ ├── model.py # 数据模型文件 │ ├── schema.py # 数据验证文件 │ ├── service.py # 业务逻辑文件 │ └── crud.py # 数据访问文件 ├── module_example/ # 示例模块（自动映射为 /example） │ └── demo/ # 子模块 │ ├── controller.py # 控制器文件 │ ├── model.py # 数据模型文件 │ ├── schema.py # 数据验证文件 │ ├── service.py # 业务逻辑文件 │ └── crud.py # 数据访问文件 ├── module_generator/ # 代码生成模块（自动映射为 /generator） └── init_app.py # 插件初始化文件 ``` #### 自动路由注册机制 系统会**自动发现并注册**所有符合以下条件的路由： 1. 控制器文件必须命名为 `controller.py` 2. 路由会自动映射：`module_xxx` -> `/xxx` 3. 支持多个 `APIRouter` 实例 4. 自动处理路由去重 #### 二次开发步骤 1. **创建插件模块**：在 `backend/app/plugin/` 目录下创建新的模块目录，如 `module_yourfeature` 2. **编写数据模型**：在 `model.py` 中定义数据库模型 3. **编写数据验证**：在 `schema.py` 中定义数据验证模型 4. **编写数据访问层**：在 `crud.py` 中编写数据库操作逻辑 5. **编写业务逻辑层**：在 `service.py` 中编写业务逻辑 6. **编写控制器**：在 `controller.py` 中定义路由和处理函数 7. **自动注册**：系统会自动扫描并注册所有路由，无需手动配置 #### 控制器示例 ```python # backend/app/plugin/module_yourfeature/yourcontroller/controller.py from fastapi import APIRouter, Depends, Path from fastapi.responses import JSONResponse from app.common.response import SuccessResponse from app.core.router_class import OperationLogRoute from app.core.dependencies import AuthPermission from app.api.v1.module_system.auth.schema import AuthSchema from .service import YourFeatureService # 创建路由实例 YourFeatureRouter = APIRouter( route_class=OperationLogRoute, prefix="/yourcontroller", tags=["你的功能模块"] ) @YourFeatureRouter.get("/detail/{id}", summary="获取详情") async def get_detail( id: int = Path(..., description="功能ID"), auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:detail"])) ) -> JSONResponse: result = await YourFeatureService.detail_service(id=id, auth=auth) return SuccessResponse(data=result) @YourFeatureRouter.get("/list", summary="获取列表") async def get_list( auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:list"])) ) -> JSONResponse: result = await YourFeatureService.list_service(auth=auth) return SuccessResponse(data=result) ``` #### 开发规范 1. **命名规范**：模块名采用 `module_xxx` 格式，控制器名采用驼峰命名法 2. **权限控制**：所有API接口必须添加权限控制装饰器 3. **日志记录**：使用 `OperationLogRoute` 类自动记录操作日志 4. **返回格式**：统一使用 `SuccessResponse` 或 `ErrorResponse` 返回响应 5. **代码注释**：为所有API接口添加详细的文档字符串 #### 注意事项 - 插件模块名必须以 `module_` 开头 - 控制器文件必须命名为 `controller.py` - 路由会自动映射到对应的前缀路径 - 无需手动注册路由，系统会自动发现并注册 ### 前端部分 1. **配置前端API**：在 `frontend/src/api/` 目录下创建对应的API文件 2. **编写页面组件**：在 `frontend/src/views/` 目录下创建页面组件 3. **注册路由**：在 `frontend/src/router/index.ts` 中注册路由 ### 代码生成器使用 项目内置代码生成器，可以根据数据库表结构自动生成前后端代码，大幅提升开发效率。 #### 生成步骤 1. **登录系统**：使用管理员账号登录系统 2. **进入代码生成模块**：在左侧菜单中点击"代码生成" 3. **导入表结构**：选择要生成代码的数据库表 4. **配置生成参数**：填写模块名称、功能名称等 5. **生成代码**：点击"生成代码"按钮 6. **下载或写入**：选择下载代码包或直接写入项目目录 #### 生成文件结构 ```sh # 后端文件 backend/app/plugin/module_yourmodule/ └── yourfeature/ ├── controller.py # 控制器文件 ├── model.py # 数据模型文件 ├── schema.py # 数据验证文件 ├── service.py # 业务逻辑文件 └── crud.py # 数据访问文件 # 前端文件 frontend/src/ ├── api/module_yourmodule/ │ └── yourfeature.ts # API调用文件 └── views/module_yourmodule/ └── yourfeature/ └── index.vue # 页面组件 ``` #### 生成代码示例 ```python # 生成的控制器代码示例 from fastapi import APIRouter, Depends from fastapi.responses import JSONResponse from app.common.response import SuccessResponse from app.core.router_class import OperationLogRoute from app.core.dependencies import AuthPermission from app.api.v1.module_system.auth.schema import AuthSchema from .service import YourFeatureService from .schema import ( YourFeatureCreateSchema, YourFeatureUpdateSchema, YourFeatureQueryParam ) YourFeatureRouter = APIRouter( route_class=OperationLogRoute, prefix="/yourfeature", tags=["你的功能模块"] ) @YourFeatureRouter.get("/detail/{id}") async def get_detail( id: int, auth: AuthSchema = Depends(AuthPermission(["module_yourmodule:yourfeature:detail"])) ) -> JSONResponse: result = await YourFeatureService.detail_service(id=id, auth=auth) return SuccessResponse(data=result) ``` ### 开发工具 - **代码生成器**：自动生成前后端CRUD代码 - **API文档**：自动生成Swagger/Redoc API文档 - **数据库**：首次启动自动初始化表与基础数据；结构演进可配合 Alembic - **日志系统**：内置日志记录和查询功能 - **监控系统**：内置服务器监控和缓存监控功能 ### 开发流程 1. **需求分析**：明确功能需求和业务逻辑 2. **数据库设计**：设计数据库表结构 3. **代码生成**：使用代码生成器生成基础代码 4. **业务逻辑开发**：完善业务逻辑和接口 5. **前端开发**：开发前端页面和交互 6. **测试**：进行单元测试和集成测试 7. **部署**：部署到生产环境 ### 开发注意事项 1. **权限控制**：所有API接口必须添加权限控制 2. **数据验证**：所有输入数据必须进行验证 3. **异常处理**：统一处理API异常 4. **日志记录**：关键操作必须记录日志 5. **性能优化**：注意API性能优化，避免慢查询 6. **代码规范**：遵循PEP8和项目代码规范 ### 常见问题 #### Q：如何添加新功能模块？ A：按照二次开发步骤，在 `backend/app/plugin/` 目录下创建新的模块目录，编写相关代码即可。 #### Q：如何配置数据库？ A：在 `backend/env/.env.dev` 或 `backend/env/.env.prod` 文件中配置数据库连接信息。 #### Q：如何配置Redis？ A：在 `backend/env/.env.dev` 或 `backend/env/.env.prod` 文件中配置Redis连接信息。 #### Q：如何生成数据库迁移文件？ A：使用 `python main.py revision --env=dev` 命令生成迁移文件。 #### Q：如何应用数据库迁移？ A：在**需要执行 Alembic 迁移**时使用 `python main.py upgrade --env=dev`（或 `uv run ...`）。**首次启动一般不必先执行**，由应用自动初始化。 #### Q：如何启动开发服务器？ A：在 `backend` 目录执行 `uv run main.py run --env=dev`（或 `python main.py run --env=dev`）。**首次启动会自动初始化数据库与基础数据**，无需先手动执行 `upgrade`。 #### Q：首次启动要先做数据库迁移吗？ A：**一般不需要**。首次启动后端会自动完成库表与初始数据；仅在你**自行修改模型**并需用 Alembic 时再使用 `revision` / `upgrade`。 #### Q：如何构建前端生产版本？ A：使用 `pnpm run build` 命令构建前端生产版本。 #### Q：如何部署到生产环境？ A：使用 `./deploy.sh` 脚本一键部署到生产环境。 ## ℹ️ 帮助 更多详情请查看 [官方文档](https://service.fastapiadmin.com) ## 👥 贡献者 ## 🙏 特别鸣谢 感谢以下开源项目的贡献和支持： - [FastAPI](https://fastapi.tiangolo.com/) - [Pydantic](https://docs.pydantic.dev/) - [SQLAlchemy](https://www.sqlalchemy.org/) - [APScheduler](https://github.com/agronholm/apscheduler) - [Vue3](https://cn.vuejs.org/) - [TypeScript](https://www.typescriptlang.org/) - [Vite](https://github.com/vitejs/vite) - [Element Plus](https://element-plus.org/) - [UniApp](https://uniapp.dcloud.net.cn/) - [Wot-Design-UI](https://wot-ui.cn/) ## 🎨 社区交流 | 群组二维码 | 微信支付二维码 | | --- | --- | |  |  | ## ❤️ 支持项目 如果你喜欢这个项目，请给我一个 ⭐️ Star 支持一下吧！非常感谢！ [](https://starchart.cc/fastapiadmin/FastapiAdmin)