vue-fastapi-admin

The project is split into two main directories: app (Backend) and web (Frontend).

Backend (app/)

• api/v1/: Contains versioned API interfaces (users, roles, menus, etc.).
• controllers/: Logic for handling requests.
• models/: Database models.
• schemas/: Data structure definitions (Pydantic models).
• settings/: Configuration settings.
• core/: Core application functionality.

Frontend (web/)

• src/api/: API interface definitions.
• src/components/: Reusable UI components (common, icon, page, query-bar, table).
• src/layout/: Layout components.
• src/router/: Routing definitions and guards.
• src/store/: State management using Pinia.
• src/views/: Page-level components (login, profile, system, workbench).

The project is divided into two main directories: app (Backend) and web (Frontend).

Backend (app/) structure:

• api/: API interface directory (v1 includes apis, base, menus, roles, and users).
• controllers/: Controller directory.
• core/: Core functional modules.
• models/: Data models.
• schemas/: Data schema/structure definitions.
• settings/: Configuration settings.
• utils/: Utility classes.

Frontend (web/) structure:

• src/api/: API interface definitions.
• src/components/: UI components (common, icon, page, query-bar, table).
• src/layout/: Layout components.
• src/router/: Routing (guards and routes).
• src/store/: State management using Pinia.
• src/views/: Page views (login, profile, system, workbench, etc.).
• src/utils/: Utilities (auth, http/axios, storage).

The frontend requires Node.js v18.8.0+. It is recommended to use pnpm as the package manager.

1. Navigate to the frontend directory: cd web
2. Install dependencies: pnpm i (or npm i)
3. Start the development server: pnpm dev

The backend requires Python 3.11. You can set it up using either uv (recommended for speed) or standard pip.

Using uv (Recommended)

1. Install uv via pip.
2. Create and activate a virtual environment.
3. Install dependencies using the pyproject.toml file.
4. Run the service.

Using pip

1. Create and activate a standard Python virtual environment.
2. Install dependencies from requirements.txt.
3. Run the service.

Once running, you can access the interactive API documentation at http://localhost:9999/docs.

# Method 1: Using uv (Recommended)
pip install uv
uv venv
source .venv/bin/activate  # Linux/Mac
# or
.\.venv\Scripts\activate  # Windows
uv add pyproject.toml
python run.py

# Method 2: Using pip
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate  # Windows
pip install -r requirements.txt
python run.py

The frontend requires Node.js v18.8.0 or higher. It is recommended to use pnpm as the package manager.

1. Navigate to the web directory.
2. Install dependencies using pnpm i (or npm i).
3. Start the development server using pnpm dev.

cd web
npm i -g pnpm
pnpm i
pnpm dev

You can quickly deploy the entire application using Docker Hub or by building a custom image from the provided Dockerfile.

Option 1: Pull from Docker Hub

Use the pre-built image for immediate deployment.

Option 2: Build from Dockerfile

Clone the repository and build the image locally to allow for potential customizations.

Default Credentials:

• URL: http://localhost:9999
• Username: admin
• Password: 123456

# Method 1: Docker Hub
docker pull mizhexiaoxiao/vue-fastapi-admin:latest 
docker run -d --restart=always --name=vue-fastapi-admin -p 9999:80 mizhexiaoxiao/vue-fastapi-admin

# Method 2: Build from source
git clone https://github.com/mizhexiaoxiao/vue-fastapi-admin.git
cd vue-fastapi-admin
docker build --no-cache . -t vue-fastapi-admin
docker run -d --restart=always --name=vue-fastapi-admin -p 9999:80 vue-fastapi-admin

The backend requires Python 3.11. You can use uv (recommended) or standard pip to manage dependencies.

Using uv (Recommended):

1. Install uv: pip install uv
2. Create and activate a virtual environment: uv venv and then source .venv/bin/activate (Linux/Mac) or .\.venv\Scripts\activate (Windows).
3. Install dependencies: uv add pyproject.toml
4. Start the service: python run.py

Using Pip:

1. Create a virtual environment: python3 -m venv venv
2. Activate it: source venv/bin/activate (Linux/Mac) or .\venv\Scripts\activate (Windows).
3. Install dependencies: pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
4. Start the service: python run.py

Once running, the API documentation is available at http://localhost:9999/docs.

The response interceptor automatically validates the API response.

1. Success: If data.code is 200, the interceptor resolves the promise with the data object.
2. Business Logic Errors: If data.code is not 200, the interceptor uses resolveResError to determine a user-friendly message, displays an error message via window.$message.error, and rejects the promise with an object containing { code, message, error }.
3. Network/HTTP Errors: If the request fails at the network level or returns a non-2xx status, resReject handles the error, displays the message, and rejects the promise.

The createAuthGuard function sets up a global navigation guard using router.beforeEach. It manages access control based on the presence of a token retrieved via getToken().

Logic Flow:

1. No Token Present: If the token is null or whitespace, the guard checks if the destination path is in the WHITE_LIST (['/login', '/404']). If it is, access is granted. Otherwise, the user is redirected to the /login page, and the original destination is preserved in the redirect query parameter.
2. Token Present: If a token exists and the user attempts to access the /login page, they are automatically redirected to the root path (/). For all other paths, access is granted.