FastApiAdmin

| |----------|----------|----------| |  |  |  | ## 🚀 Quick Start ### First-time local setup (in order) 1. **Install runtimes**: Python ≥ 3.10, Node.js ≥ 20, [pnpm](https://pnpm.io/), local **MySQL or PostgreSQL** (or SQLite if configured in `backend/env/.env.dev`), and **Redis** matching your `.env.dev`. 2. **Clone the repo**: see “Get the Code” below. 3. **Env files**: copy `backend/env/.env.dev.example` → `backend/env/.env.dev`, and `frontend/.env.development.example` → `frontend/.env.development`; fill in **DB, Redis, JWT secret**, etc. Create an empty database first. 4. **Backend dependencies**: `cd backend`, run **`uv sync`** (recommended) or `pip install -r requirements.txt`. 5. **Start backend**: `uv run main.py run --env=dev`. **The first start automatically initializes tables and seed data**—you usually **do not** need to run `upgrade` first. 6. **Frontend**: `cd frontend`, `pnpm install`, `pnpm run dev`. 7. **Browser**: with the template env, open **`http://127.0.0.1:5180`** (`VITE_APP_PORT=5180`); log in with the admin account (same as [Demo Environment](#-demo-environment) unless you changed seed data). > Use **`revision` / `upgrade`** only when you change ORM models and manage migrations with Alembic (see FAQ below). ### Environment Requirements | Type | Technology Stack | Version | |------|------------------|---------| | Backend | Python | ≥ 3.10 (3.12 recommended) | | Backend | FastAPI | 0.109+ | | Frontend | Node.js | ≥ 20.0 | | Frontend | Vue3 | 3.3+ | | Database | MySQL / PostgreSQL / SQLite | As in `backend/env` | | Cache | Redis | 6.x / 7.x (match `.env`) | ### Get the Code ```bash # Clone the repository to your local machine git clone https://gitee.com/fastapiadmin/FastapiAdmin.git # Or git clone https://github.com/fastapiadmin/FastapiAdmin.git ``` > **Backend Note**: After cloning the code, you need to rename the `.env.dev.example` file in the `backend/env` directory to `.env.dev`, and rename the `.env.prod.example` file in the `backend/env` directory to `.env.prod`. Then modify the database connection information, Redis connection information, etc., according to the actual situation. > **Frontend Note**: After cloning the code, you need to rename the `.env.development.example` file in the `frontend` directory to `.env.development`, and rename the `.env.production.example` file in the `frontend` directory to `.env.production`. Then modify the interface address, etc., according to the actual situation. ### Backend Setup #### Using uv (recommended, matches `backend/pyproject.toml`) ```bash cd backend uv sync # First start auto-inits schema & data; no need to run upgrade beforehand uv run main.py run --env=dev # uv run main.py run --env=prod ``` > Without `uv`: `pip install -r requirements.txt`, then `python main.py run --env=dev`. Use `upgrade` when you need Alembic after model changes. #### Using 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 ``` ### Frontend Setup #### Web Frontend (Vue3) ```bash cd frontend/web pnpm install pnpm run dev # Build production version pnpm run build ``` #### Mobile (UniApp) ```bash cd frontend/app pnpm install pnpm run dev:h5 # Start H5 development server # Build production version pnpm run build:h5 ``` #### Documentation Site (VitePress) ```bash cd frontend/docs pnpm install pnpm run dev # Build production version pnpm run build ``` ### After startup When using **`.env.dev.example` / `.env.development`** as-is: | Service | URL (example) | |---------|----------------| | Web Frontend (Vite) | `http://127.0.0.1:5173` | | Mobile H5 (UniApp) | `http://127.0.0.1:8080` | | Documentation Site (VitePress) | `http://127.0.0.1:5174` | | Backend base | `http://127.0.0.1:8001` | | Swagger | `http://127.0.0.1:8001/docs` | | API prefix | `http://127.0.0.1:8001/api/v1` (matches `ROOT_PATH`) | ### 🐳 Docker Deployment #### Method 1: Use deploy.sh script (Recommended) ```bash # 1. Clone the repository to server git clone https://gitee.com/fastapiadmin/FastapiAdmin.git cd FastapiAdmin # 2. Grant execution permissions and deploy chmod +x deploy.sh ./deploy.sh # View container logs ./deploy.sh logs # Stop services ./deploy.sh stop # Restart services ./deploy.sh restart # Only update code and restart (without rebuilding images) ./deploy.sh update # Skip frontend build (use uploaded static files) ./deploy.sh --skip-frontend # Enable frontend build (build on server) ./deploy.sh --build-frontend ``` #### Method 2: Execute script outside project ```bash # 1. Copy the deployment script to server cp deploy.sh /home/ cd /home chmod +x deploy.sh # 2. Execute one-click deployment (will auto clone project) ./deploy.sh # View container logs ./deploy.sh logs # Stop services ./deploy.sh stop # Restart services ./deploy.sh restart # Update code and restart (without rebuilding images, suitable for backend hot update) ./deploy.sh update ``` > **Note**: > - First deployment will automatically pull code and build images > - Frontend uses locally built dist directory, please build locally and commit to repository if you need to update frontend > - Ensure `devops/nginx/ssl/` directory contains SSL certificate files (if using HTTPS) ## 🛠️ Secondary Development Tutorial ### Backend Development The project adopts a **plugin-based architecture design**, and it is recommended to carry out secondary development in the `backend/app/plugin` directory. The system will **automatically discover and register** all routes that meet the specifications, facilitating module management and upgrade maintenance. #### Plugin Architecture Features - **Automatic Route Discovery**: The system automatically scans all `controller.py` files in the `backend/app/plugin/` directory - **Automatic Route Registration**: All routes are automatically registered to the corresponding prefix path (module_xxx -> /xxx) - **Modular Management**: Code is organized by functional modules for easy maintenance and extension - **Support for Multi-level Nesting**: Support for multi-level nested structures within modules #### Plugin Directory Structure ```sh backend/app/plugin/ ├── module_application/ # Application module (automatically mapped to /application) │ └── ai/ # AI submodule │ ├── controller.py # Controller file │ ├── model.py # Data model file │ ├── schema.py # Data validation file │ ├── service.py # Business logic file │ └── crud.py # Data access file ├── module_example/ # Example module (automatically mapped to /example) │ └── demo/ # Submodule │ ├── controller.py # Controller file │ ├── model.py # Data model file │ ├── schema.py # Data validation file │ ├── service.py # Business logic file │ └── crud.py # Data access file ├── module_generator/ # Code generation module (automatically mapped to /generator) └── init_app.py # Plugin initialization file ``` #### Automatic Route Registration Mechanism The system will **automatically discover and register** all routes that meet the following conditions: 1. Controller files must be named `controller.py` 2. Routes are automatically mapped: `module_xxx` -> `/xxx` 3. Support for multiple `APIRouter` instances 4. Automatic route deduplication #### Secondary Development Steps 1. **Create Plugin Module**: Create a new module directory under `backend/app/plugin/`, such as `module_yourfeature` 2. **Write Data Model**: Define database models in `model.py` 3. **Write Data Validation**: Define data validation models in `schema.py` 4. **Write Data Access Layer**: Write database operation logic in `crud.py` 5. **Write Business Logic Layer**: Write business logic in `service.py` 6. **Write Controller**: Define routes and handling functions in `controller.py` 7. **Automatic Registration**: The system automatically scans and registers all routes, no manual configuration required #### Controller Example ```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 # Create route instance YourFeatureRouter = APIRouter( route_class=OperationLogRoute, prefix="/yourcontroller", tags=["Your Feature Module"] ) @YourFeatureRouter.get("/detail/{id}", summary="Get Detail") async def get_detail( id: int = Path(..., description="Feature ID"), auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:detail"])) ) -> JSONResponse: """ Get feature detail Parameters: - id (int): Feature ID - auth (AuthSchema): Authentication information model Returns: - JSONResponse: JSON response containing feature detail """ result = await YourFeatureService.detail_service(id=id, auth=auth) return SuccessResponse(data=result) @YourFeatureRouter.get("/list", summary="Get List") async def get_list( auth: AuthSchema = Depends(AuthPermission(["module_yourfeature:yourcontroller:list"])) ) -> JSONResponse: """ Get feature list Parameters: - auth (AuthSchema): Authentication information model Returns: - JSONResponse: JSON response containing feature list """ result = await YourFeatureService.list_service(auth=auth) return SuccessResponse(data=result) ``` #### Development Specifications 1. **Naming Convention**: Module names use `module_xxx` format, controller names use camelCase naming 2. **Permission Control**: All API interfaces must add permission control decorators 3. **Log Recording**: Use `OperationLogRoute` class to automatically record operation logs 4. **Return Format**: Use `SuccessResponse` or `ErrorResponse` uniformly for responses 5. **Code Comments**: Add detailed docstrings for all API interfaces #### Notes - Plugin module names must start with `module_` - Controller files must be named `controller.py` - Routes are automatically mapped to corresponding prefix paths - No manual route registration required, the system automatically discovers and registers ### Frontend Part 1. **Configure Frontend API**: Create corresponding API files in `frontend/src/api/` directory 2. **Write Page Components**: Create page components in `frontend/src/views/` directory 3. **Register Routes**: Register routes in `frontend/src/router/index.ts` ### Code Generator Usage The project has a built-in code generator that can automatically generate front-end and back-end code based on database table structures, greatly improving development efficiency. #### Generation Steps 1. **Login System**: Login to the system using an administrator account 2. **Enter Code Generation Module**: Click "Code Generation" in the left menu 3. **Import Table Structure**: Select the database table to generate code for 4. **Configure Generation Parameters**: Fill in module name, function name, etc. 5. **Generate Code**: Click the "Generate Code" button 6. **Download or Write**: Choose to download the code package or write directly to the project directory #### Generated File Structure ```sh # Backend files backend/app/plugin/module_yourmodule/ └── yourfeature/ ├── controller.py # Controller file ├── model.py # Data model file ├── schema.py # Data validation file ├── service.py # Business logic file └── crud.py # Data access file # Frontend files frontend/src/ ├── api/module_yourmodule/ │ └── yourfeature.ts # API call file └── views/module_yourmodule/ └── yourfeature/ └── index.vue # Page component ``` #### Generated Code Example ```python # Generated controller code example 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=["Your Feature Module"] ) @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) ``` ### Development Tools - **Code Generator**: Automatically generate front-end and back-end CRUD code - **API Documentation**: Automatically generate Swagger/Redoc API documentation - **Database**: Auto schema & seed on first start; Alembic supported for schema evolution - **Log System**: Built-in log recording and query functions - **Monitoring System**: Built-in server monitoring and cache monitoring functions ### Development Process 1. **Requirement Analysis**: Clarify functional requirements and business logic 2. **Database Design**: Design database table structure 3. **Code Generation**: Use code generator to generate basic code 4. **Business Logic Development**: Perfect business logic and interfaces 5. **Frontend Development**: Develop frontend pages and interactions 6. **Testing**: Conduct unit testing and integration testing 7. **Deployment**: Deploy to production environment ### Development Notes 1. **Permission Control**: All API interfaces must add permission control 2. **Data Validation**: All input data must be validated 3. **Exception Handling**: Uniformly handle API exceptions 4. **Log Recording**: Key operations must be logged 5. **Performance Optimization**: Pay attention to API performance optimization, avoid slow queries 6. **Code Specification**: Follow PEP8 and project code specifications ### Common Questions #### Q: How to add a new functional module? A: Follow the secondary development steps, create a new module directory under `backend/app/plugin/` directory, and write related code. #### Q: How to configure the database? A: Configure database connection information in `backend/env/.env.dev` or `backend/env/.env.prod` files. #### Q: How to configure Redis? A: Configure Redis connection information in `backend/env/.env.dev` or `backend/env/.env.prod` files. #### Q: How to generate database migration files? A: Use the command `python main.py revision --env=dev` to generate migration files. #### Q: How to apply database migrations? A: Run `python main.py upgrade --env=dev` (or `uv run ...`) when you **need Alembic migrations**. **First start usually does not require this**—the app initializes automatically. #### Q: How to start the development server? A: From `backend`, run `uv run main.py run --env=dev` (or `python main.py run --env=dev`). **First start auto-initializes the database and seed data**; no manual `upgrade` is required beforehand. #### Q: Do I need to run migrations before the first start? A: **Usually no.** The first backend start initializes schema and data. Use `revision` / `upgrade` only when you change models and use Alembic. #### Q: How to build the frontend production version? A: Use the command `pnpm run build` to build the frontend production version. #### Q: How to deploy to production environment? A: Use the `./deploy.sh` script for one-click deployment to production environment. ## ℹ️ Help For more details, please check the [Official Documentation](https://service.fastapiadmin.com) ## 👥 Contributors ## 🙏 Special Thanks Thanks to the contributions and support of the following open-source projects: - [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/) ## 🎨 Community | Group QR Code | WeChat Pay QR Code | | --- | --- | |  |  | ## ❤️ Support the Project If you like this project, please give it a ⭐️ Star to show your support! Thank you very much! [](https://starchart.cc/fastapiadmin/FastapiAdmin)