public/FastapiAdmin
1
0
Fork 0
mirror of https://github.com/fastapiadmin/FastapiAdmin.git synced 2026-10-02 16:37:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): 重构文档结构并更新内容

Browse Source 
refactor(docs): 迁移文档到src目录并优化配置

style(docs): 统一代码格式和样式

chore(docs): 移除不必要的配置文件和依赖

fix(docs): 修正锁屏对话框的翻译和占位符

feat(components): 添加ElDescriptions组件支持

perf(docs): 优化文档图片加载和缩放功能
This commit is contained in:
zhangtao
2026-05-01 22:48:13 +08:00
parent ab460ec9f6
commit e44f96740f
63 changed files with 284 additions and 3223 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/docs/src/guide/api-docs.md
+440
View File
@@ -0,0 +1,440 @@
---
outline: "deep"
title: API 文档说明
---
# API 文档说明
## 📚API 文档概述
FastapiAdmin 项目提供了完善的 API 文档，便于开发者了解和使用系统提供的接口。本文档将详细介绍如何使用和调用这些 API。
## 🔧后端 API 文档
### 1. 访问方式
后端 API 文档基于 FastAPI 自动生成，支持 Swagger 和 Redoc 两种格式：
- **Swagger UI**：<http://localhost:8001/api/v1/docs>（本地开发环境）
- **Redoc**：<http://localhost:8001/api/v1/redoc>（本地开发环境）
- **在线演示**：<https://service.fastapiadmin.com/api/v1/docs>（生产环境）
### 2. 使用方法
#### 2.1 认证登录
1. 打开 Swagger UI 文档页面
2. 点击页面右上角的 "Authorize" 按钮
3. 在弹出的对话框中输入用户名和密码
4. 点击 "Authorize" 按钮完成认证
5. 认证成功后，所有 API 调用都会自动携带认证信息
#### 2.2 接口测试
1. 在 Swagger UI 中找到需要测试的接口
2. 点击接口名称展开详细信息
3. 点击 "Try it out" 按钮
4. 填写必要的参数
5. 点击 "Execute" 按钮执行请求
6. 查看响应结果
### 3. API 接口分类
后端 API 接口主要分为以下几类：
- **系统管理**：用户、角色、菜单、部门、岗位等管理接口
- **监控管理**：在线用户、服务器监控、缓存监控等接口
- **任务管理**：定时任务管理接口
- **日志管理**：操作日志查询接口
- **开发工具**：代码生成、表单构建等接口
## 📱前端 API 调用
### 1. 前端 API 封装
前端项目使用 TypeScript 封装了 API 调用，主要位于 `frontend/src/api` 目录下，按模块分类组织：
```
frontend/src/api/
├── module_example/ # 示例模块
│ └── demo.ts
├── module_monitor/ # 监控模块
│ ├── cache.ts
│ ├── online.ts
│ └── server.ts
└── module_system/ # 系统模块
├── auth.ts
├── dept.ts
├── dict.ts
├── log.ts
├── menu.ts
├── notice.ts
├── params.ts
├── role.ts
└── user.ts
```
### 2. API 调用示例
#### 2.1 导入 API 模块
```typescript
import { authApi } from '@/api/module_system/auth';
import { userApi } from '@/api/module_system/user';
```
#### 2.2 调用登录接口
```typescript
import { authApi } from '@/api/module_system/auth';
import { useUserStore } from '@/store/modules/user.store';
const userStore = useUserStore();
const login = async (username: string, password: string) => {
try {
const res = await authApi.login({
username,
password
});
// 保存 token
userStore.setToken(res.data.token);
// 获取用户信息
await userStore.getUserInfo();
// 跳转到首页
router.push('/');
} catch (error) {
console.error('登录失败：', error);
}
};
```
#### 2.3 调用用户管理接口
```typescript
import { userApi } from '@/api/module_system/user';
// 获取用户列表
const getUserList = async () => {
try {
const res = await userApi.getList({
page: 1,
pageSize: 10,
username: 'admin'
});
console.log('用户列表：', res.data);
} catch (error) {
console.error('获取用户列表失败：', error);
}
};
// 获取用户详情
const getUserDetail = async (userId: number) => {
try {
const res = await userApi.getDetail(userId);
console.log('用户详情：', res.data);
} catch (error) {
console.error('获取用户详情失败：', error);
}
};
// 创建用户
const createUser = async (userData: any) => {
try {
const res = await userApi.create(userData);
console.log('创建用户成功：', res.data);
} catch (error) {
console.error('创建用户失败：', error);
}
};
// 更新用户
const updateUser = async (userId: number, userData: any) => {
try {
const res = await userApi.update(userId, userData);
console.log('更新用户成功：', res.data);
} catch (error) {
console.error('更新用户失败：', error);
}
};
// 删除用户
const deleteUser = async (userId: number) => {
try {
const res = await userApi.delete(userId);
console.log('删除用户成功：', res.data);
} catch (error) {
console.error('删除用户失败：', error);
}
};
```
## 📱FastApp 移动端 API 调用
### 1. 移动端 API 封装
FastApp 移动端项目同样封装了 API 调用，主要位于 `src/api` 目录下：
```
FastApp/src/api/
├── auth.ts # 认证相关接口
├── file.ts # 文件相关接口
└── user.ts # 用户相关接口
```
### 2. API 调用示例
#### 2.1 导入 API 模块
```typescript
import { authApi } from '@/api/auth';
import { userApi } from '@/api/user';
```
#### 2.2 调用登录接口
```typescript
import { authApi } from '@/api/auth';
import { useUserStore } from '@/store/modules/user.store';
const userStore = useUserStore();
const login = async (username: string, password: string) => {
try {
const res = await authApi.login({
username,
password
});
// 保存 token
userStore.setToken(res.data.token);
// 获取用户信息
await userStore.getUserInfo();
// 跳转到首页
uni.switchTab({ url: '/pages/index/index' });
} catch (error) {
console.error('登录失败：', error);
}
};
```
#### 2.3 调用用户信息接口
```typescript
import { userApi } from '@/api/user';
// 获取用户信息
const getUserInfo = async () => {
try {
const res = await userApi.getUserInfo();
console.log('用户信息：', res.data);
return res.data;
} catch (error) {
console.error('获取用户信息失败：', error);
return null;
}
};
// 更新用户信息
const updateUserInfo = async (userData: any) => {
try {
const res = await userApi.updateUserInfo(userData);
console.log('更新用户信息成功：', res.data);
return true;
} catch (error) {
console.error('更新用户信息失败：', error);
return false;
}
};
```
## 🛠️API 调用最佳实践
### 1. 错误处理
在调用 API 时，应该合理处理可能出现的错误：
```typescript
try {
const res = await apiCall();
// 处理成功响应
} catch (error: any) {
// 处理错误
if (error.response) {
// 服务器返回错误状态码
console.error('服务器错误：', error.response.data);
uni.showToast({
title: error.response.data.message || '服务器错误',
icon: 'none'
});
} else if (error.request) {
// 请求已发送但没有收到响应
console.error('网络错误：', error.request);
uni.showToast({
title: '网络错误，请检查网络连接',
icon: 'none'
});
} else {
// 请求配置出错
console.error('请求错误：', error.message);
uni.showToast({
title: '请求错误',
icon: 'none'
});
}
}
```
### 2. 加载状态
在调用 API 时，应该显示加载状态，提升用户体验：
```typescript
const loading = ref(false);
const fetchData = async () => {
loading.value = true;
try {
const res = await apiCall();
// 处理数据
} catch (error) {
// 处理错误
} finally {
loading.value = false;
}
};
```
### 3. 缓存策略
对于不常变化的数据，可以使用缓存策略，减少网络请求：
```typescript
import { ref, onMounted } from 'vue';
import { userApi } from '@/api/user';
import { useStorage } from '@/utils/storage';
const userList = ref([]);
const loading = ref(false);
const storage = useStorage();
const fetchUserList = async () => {
// 尝试从缓存获取
const cachedData = storage.get('userList');
if (cachedData) {
userList.value = cachedData;
return;
}
loading.value = true;
try {
const res = await userApi.getList({ page: 1, pageSize: 100 });
userList.value = res.data.items;
// 缓存数据，有效期 5 分钟
storage.set('userList', res.data.items, 5 * 60 * 1000);
} catch (error) {
console.error('获取用户列表失败：', error);
} finally {
loading.value = false;
}
};
onMounted(() => {
fetchUserList();
});
```
## 📝API 设计规范
### 1. URL 规范
- 接口 URL 使用小写字母和下划线
- 资源路径使用复数形式
- 版本号放在 URL 前缀（如 `/api/v1/`）
### 2. HTTP 方法
- `GET`：获取资源
- `POST`：创建资源
- `PUT`：更新资源
- `DELETE`：删除资源
- `PATCH`：部分更新资源
### 3. 响应格式
所有 API 响应采用统一的格式：
```json
{
"code": 200,
"message": "success",
"data": {...}
}
```
- `code`：状态码，200 表示成功，其他表示失败
- `message`：响应消息，成功时为 "success"，失败时为错误信息
- `data`：响应数据，根据接口不同返回不同的数据结构
### 4. 分页响应
分页接口的响应格式：
```json
{
"code": 200,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"pageSize": 10,
"pages": 10
}
}
```
- `items`：当前页的数据列表
- `total`：总记录数
- `page`：当前页码
- `pageSize`：每页大小
- `pages`：总页数
## 💡常见问题及解决方案
### 1. 认证失败
**问题**：API 调用返回 401 错误
**解决方案**：检查是否已登录，登录状态是否过期，重新登录获取新的认证信息。
### 2. 权限不足
**问题**：API 调用返回 403 错误
**解决方案**：检查当前用户是否有足够的权限执行该操作，联系管理员分配权限。
### 3. 参数错误
**问题**：API 调用返回 422 错误
**解决方案**：检查请求参数是否正确，是否缺少必要参数，参数格式是否符合要求。
### 4. 网络错误
**问题**：API 调用超时或无法连接
**解决方案**：检查网络连接是否正常，API 地址是否正确，服务器是否正常运行。
### 5. 服务器错误
**问题**：API 调用返回 500 错误
**解决方案**：检查服务器日志，查看具体错误原因，联系后端开发人员解决。
## 📚参考文档
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Swagger UI 官方文档](https://swagger.io/docs/open-source-tools/swagger-ui/)
- [Redoc 官方文档](https://redocly.com/docs/redoc/)
通过本文档的介绍，相信您已经了解了如何使用和调用 FastapiAdmin 项目的 API。如果您在使用过程中遇到任何问题，请参考常见问题及解决方案，或联系项目维护人员获取帮助。
frontend/docs/src/guide/backend.md
+1072
View File
File diff suppressed because it is too large Load Diff
frontend/docs/src/guide/custom-development.md
+213
View File
@@ -0,0 +1,213 @@
# Custom Development Guide
## Overview
This guide provides instructions for customizing and extending FastapiAdmin to meet your specific business needs.
## Backend Customization
### Adding New Models
```python
from sqlalchemy import Column, Integer, String, Text
from fastapi_admin.database import Base
class Product(Base):
__tablename__ = "products"
id = Column(Integer, primary_key=True, index=True)
name = Column(String(255), nullable=False)
description = Column(Text)
price = Column(Integer, nullable=False)
```
### Creating Custom APIs
```python
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession
from fastapi_admin.database import get_db
from .models import Product
router = APIRouter(prefix="/api/v1/products", tags=["products"])
@router.get("/")
async def get_products(db: AsyncSession = Depends(get_db)):
products = await db.query(Product).all()
return {"products": products}
@router.post("/")
async def create_product(product: Product, db: AsyncSession = Depends(get_db)):
db.add(product)
await db.commit()
await db.refresh(product)
return {"product": product}
```
## Frontend Customization
### Adding New Components
```vue
<template>
<div class="product-form">
<h2>Add New Product</h2>
<form @submit.prevent="submitForm">
<div class="form-group">
<label>Product Name</label>
<input v-model="product.name" type="text" required>
</div>
<div class="form-group">
<label>Description</label>
<textarea v-model="product.description"></textarea>
</div>
<div class="form-group">
<label>Price</label>
<input v-model.number="product.price" type="number" required>
</div>
<button type="submit">Save</button>
</form>
</div>
</template>
<script setup>
import { ref } from 'vue'
const product = ref({
name: '',
description: '',
price: 0
})
const submitForm = async () => {
const response = await fetch('/api/v1/products', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(product.value)
})
if (response.ok) {
alert('Product created successfully!')
}
}
</script>
```
### Customizing the Dashboard
```vue
<template>
<div class="custom-dashboard">
<h1>Custom Dashboard</h1>
<div class="stats-grid">
<div class="stat-card">
<h3>Total Products</h3>
<p>{{ productCount }}</p>
</div>
<div class="stat-card">
<h3>Total Orders</h3>
<p>{{ orderCount }}</p>
</div>
</div>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const productCount = ref(0)
const orderCount = ref(0)
onMounted(async () => {
// Fetch dashboard data
const productsResponse = await fetch('/api/v1/products')
const productsData = await productsResponse.json()
productCount.value = productsData.products.length
const ordersResponse = await fetch('/api/v1/orders')
const ordersData = await ordersResponse.json()
orderCount.value = ordersData.orders.length
})
</script>
```
## Miniprogram Customization
### Adding New Pages
```vue
<template>
<view class="product-list">
<view class="product-item" v-for="product in products" :key="product.id">
<text class="product-name">{{ product.name }}</text>
<text class="product-price">¥{{ product.price }}</text>
<button @click="viewDetails(product.id)">View Details</button>
</view>
</view>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const products = ref([])
onMounted(async () => {
const response = await uni.request({
url: '/api/v1/products'
})
products.value = response.data.products
})
const viewDetails = (productId) => {
uni.navigateTo({
url: `/pages/product/detail?id=${productId}`
})
}
</script>
```
## Best Practices
1. **Modular Development**: Organize your code into modules based on functionality
2. **Version Control**: Use Git to track changes and collaborate with team members
3. **Testing**: Write unit tests for critical functionality
4. **Documentation**: Keep your code well-documented
5. **Security**: Follow security best practices for API development
## Deployment
After customizing your FastapiAdmin application, you can deploy it using the same deployment methods described in the deployment guide.
```bash
# Build the frontend
cd frontend
npm run build
# Build the backend (if using Docker)
docker build -t fastapiadmin-backend .
# Start all services
docker-compose up -d
```
## Troubleshooting
### Common Issues
1. **API Endpoints Not Found**: Check your router configuration and ensure endpoints are properly registered
2. **Database Connection Errors**: Verify your database credentials and network connectivity
3. **Frontend Build Failures**: Check for syntax errors in your Vue components
4. **CORS Issues**: Ensure your CORS configuration allows requests from your frontend domain
### Debugging Tips
1. **Enable Debug Mode**: Set `DEBUG=True` in your backend configuration
2. **Check Logs**: Monitor backend and frontend logs for error messages
3. **Use Browser DevTools**: Inspect network requests and console errors
4. **Test APIs Directly**: Use tools like Postman to test API endpoints
## Conclusion
FastapiAdmin provides a flexible foundation for building custom backend systems. By following this guide, you can extend the platform to meet your specific business requirements while maintaining a clean and maintainable codebase.
frontend/docs/src/guide/deployment.md
+855
View File
@@ -0,0 +1,855 @@
---
outline: "deep"
title: 部署指南
---
# 部署指南
## 🚀部署概述
FastapiAdmin 项目支持多种部署方式，包括：
- **Docker Compose 部署**：推荐的部署方式，快速、便捷、可移植
- **手动部署**：适用于特殊场景或需要高度定制的情况
- **云服务部署**：可以部署到阿里云、腾讯云等云服务提供商
本指南将详细介绍 FastapiAdmin 主工程和 FastApp 移动端的部署步骤。
## 🐳Docker Compose 部署
### 1. 环境准备
- **服务器**：推荐使用 Ubuntu 20.04+、CentOS 7+ 等 Linux 系统
- **Docker**：版本 >= 20.0
- **Docker Compose**：版本 >= 1.29.0
- **网络**：确保服务器可以访问互联网，并且开放所需端口
### 2. 安装 Docker 和 Docker Compose
#### Ubuntu/Debian
```sh
# 更新系统
sudo apt update
sudo apt upgrade -y
# 安装 Docker
sudo apt install docker.io -y
# 安装 Docker Compose
sudo apt install docker-compose -y
# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker
# 添加当前用户到 docker 组（可选）
sudo usermod -aG docker $USER
newgrp docker
```
#### CentOS/RHEL
```sh
# 更新系统
sudo yum update -y
# 安装 Docker
sudo yum install docker -y
# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker
# 添加当前用户到 docker 组（可选）
sudo usermod -aG docker $USER
newgrp docker
```
### 3. 部署步骤
#### 1. 获取代码
```sh
# 克隆代码到服务器
cd /opt
git clone https://github.com/fastapiadmin/FastapiAdmin.git
cd FastapiAdmin
```
#### 2. 配置环境变量
```sh
# 配置后端环境变量
cd backend
cp env/.env.prod.example env/.env.prod
# 编辑 env/.env.prod 文件，配置数据库、Redis 等信息
# 配置前端环境变量
cd ../frontend
cp .env.production.example .env.production
# 编辑 .env.production 文件，配置 API 地址等信息
cd ..
```
#### 3. 配置 Docker Compose
Docker Compose 配置文件位于 `docker-compose.yaml`，包含了所有服务的配置：
```yaml
# docker-compose.yaml 示例
version: '3'
services:
# 后端服务
backend:
build:
context: ./backend
dockerfile: ../devops/backend/Dockerfile
container_name: fastapiadmin-backend
ports:
- "8001:8001"
volumes:
- ./backend:/app
- ./backend/logs:/app/logs
environment:
- ENV=prod
depends_on:
- mysql
- redis
networks:
- fastapiadmin-network
restart: always
# 前端服务
frontend:
build:
context: ./frontend
dockerfile: Dockerfile
container_name: fastapiadmin-frontend
ports:
- "5173:80"
volumes:
- ./frontend/dist:/usr/share/nginx/html
networks:
- fastapiadmin-network
restart: always
# MySQL 数据库
mysql:
image: mysql:8.0
container_name: fastapiadmin-mysql
ports:
- "3306:3306"
volumes:
- ./devops/mysql/data:/var/lib/mysql
- ./devops/mysql/conf:/etc/mysql/conf.d
environment:
- MYSQL_ROOT_PASSWORD=your_root_password
- MYSQL_DATABASE=fastapiadmin
- MYSQL_USER=fastapiadmin
- MYSQL_PASSWORD=your_password
networks:
- fastapiadmin-network
restart: always
# Redis 缓存
redis:
image: redis:7.0
container_name: fastapiadmin-redis
ports:
- "6379:6379"
volumes:
- ./devops/redis/data:/data
- ./devops/redis/conf/redis.conf:/etc/redis/redis.conf
networks:
- fastapiadmin-network
restart: always
# Nginx 反向代理
nginx:
image: nginx:1.21
container_name: fastapiadmin-nginx
ports:
- "80:80"
- "443:443"
volumes:
- ./devops/nginx/nginx.conf:/etc/nginx/nginx.conf
- ./devops/nginx/ssl:/etc/nginx/ssl
networks:
- fastapiadmin-network
restart: always
networks:
fastapiadmin-network:
driver: bridge
```
#### 4. 配置 Nginx
Nginx 配置文件位于 `devops/nginx/nginx.conf`，用于反向代理和 SSL 配置：
```nginx
# devops/nginx/nginx.conf 示例
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;
include /usr/share/nginx/modules/*.conf;
events {
worker_connections 1024;
}
http {
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
types_hash_max_size 2048;
include /etc/nginx/mime.types;
default_type application/octet-stream;
# 前端服务
upstream frontend {
server frontend:80;
}
# 后端服务
upstream backend {
server backend:8001;
}
# 主站点
server {
listen 80;
server_name service.fastapiadmin.com;
# 重定向到 HTTPS
return 301 https://$host$request_uri;
}
# HTTPS 站点
server {
listen 443 ssl http2;
server_name service.fastapiadmin.com;
# SSL 配置
ssl_certificate /etc/nginx/ssl/fullchain.pem;
ssl_certificate_key /etc/nginx/ssl/privkey.pem;
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 10m;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# 前端路由
location /web {
proxy_pass http://frontend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 后端 API
location /api {
proxy_pass http://backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 静态文件
location /static {
alias /usr/share/nginx/html/static;
expires 30d;
}
# 健康检查
location /health {
return 200 "OK";
}
}
}
```
#### 5. 启动服务
```sh
# 执行部署脚本
chmod +x start.sh
./start.sh
# 或手动启动
# 构建镜像
docker-compose build
# 启动服务
docker-compose up -d
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
```
### 4. 部署后配置
#### 1. 初始化数据库
```sh
# 进入后端容器
docker exec -it fastapiadmin-backend bash
# 初始化数据库
python main.py init
# 退出容器
exit
```
#### 2. 配置域名
1. 在域名注册商处添加 A 记录，指向服务器 IP 地址
2. 等待 DNS 解析生效
#### 3. 配置 SSL 证书
推荐使用 Let's Encrypt 免费 SSL 证书：
```sh
# 安装 Certbot
# Ubuntu/Debian
sudo apt install certbot python3-certbot-nginx
# CentOS/RHEL
sudo yum install certbot python3-certbot-nginx
# 获取证书
certbot --nginx -d service.fastapiadmin.com
# 自动续期
echo "0 0 1 * * certbot renew --quiet" | sudo crontab -
```
## 📦手动部署
### 1. 后端部署
#### 1. 环境准备
- Python 3.10+
- MySQL 8.0+
- Redis 7.0+
#### 2. 安装依赖
```sh
# 进入后端目录
cd FastapiAdmin/backend
# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
```
#### 3. 配置环境变量
```sh
cp env/.env.prod.example env/.env.prod
# 编辑 env/.env.prod 文件，配置数据库、Redis 等信息
```
#### 4. 初始化数据库
```sh
# 生成迁移文件
python main.py revision "初始化迁移" --env=prod
# 应用迁移
python main.py upgrade --env=prod
# 初始化系统数据
python main.py init
```
#### 5. 启动后端服务
```sh
# 使用 Gunicorn 启动（推荐）
pip install gunicorn uvloop
# 启动服务
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8001 --daemon
# 或使用 systemd 管理服务
# 创建 systemd 服务文件
```
### 2. 前端部署
#### 1. 环境准备
- Node.js 20.0+
- Nginx
#### 2. 构建前端
```sh
# 进入前端目录
cd FastapiAdmin/frontend
# 安装依赖
pnpm install
# 构建前端
pnpm run build
```
#### 3. 配置 Nginx
```nginx
# /etc/nginx/conf.d/fastapiadmin.conf
server {
listen 80;
server_name service.fastapiadmin.com;
# 前端静态文件
location /web {
root /path/to/FastapiAdmin/frontend;
index index.html;
try_files $uri $uri/ /web/index.html;
}
# 后端 API
location /api {
proxy_pass http://localhost:8001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
#### 4. 重启 Nginx
```sh
sudo nginx -t
sudo systemctl restart nginx
```
## ☁️云服务部署
### 1. 阿里云部署
#### 1. 创建 ECS 实例
1. 登录阿里云控制台
2. 创建 ECS 实例，选择 Ubuntu 20.04 或 CentOS 7+
3. 配置安全组，开放 80、443、8001 等端口
#### 2. 部署步骤
参考前面的 Docker Compose 部署或手动部署步骤。
### 2. 腾讯云部署
#### 1. 创建 CVM 实例
1. 登录腾讯云控制台
2. 创建 CVM 实例，选择 Ubuntu 20.04 或 CentOS 7+
3. 配置安全组，开放 80、443、8001 等端口
#### 2. 部署步骤
参考前面的 Docker Compose 部署或手动部署步骤。
## 🔧常见部署问题及解决方案
### 1. Docker 相关问题
**问题**：Docker 构建失败
**解决方案**：检查 Dockerfile 是否正确，依赖是否可用，网络连接是否正常。
**问题**：容器启动失败
**解决方案**：查看容器日志 `docker logs <容器名>`，检查配置是否正确，端口是否被占用。
**问题**：Docker -compose 命令不执行
**解决方案**：检查 Docker Compose 版本是否正确，配置文件格式是否正确。
### 2. 数据库相关问题
**问题**：数据库连接失败
**解决方案**：检查数据库服务是否正常运行，用户名密码是否正确，防火墙是否开放 3306 端口。
**问题**：数据库初始化失败
**解决方案**：检查数据库权限是否足够，SQL 语句是否正确，查看错误日志。
### 3. Nginx 相关问题
**问题**：Nginx 启动失败
**解决方案**：检查 Nginx 配置文件是否正确 `nginx -t`，端口是否被占用。
**问题**：前端页面无法访问
**解决方案**：检查 Nginx 配置是否正确，前端文件是否存在，权限是否正确。
**问题**：API 请求失败
**解决方案**：检查后端服务是否正常运行，Nginx 反向代理配置是否正确，防火墙是否开放 8001 端口。
### 4. 网络相关问题
**问题**：服务器无法访问互联网
**解决方案**：检查服务器网络连接，防火墙配置，DNS 设置。
**问题**：域名无法访问
**解决方案**：检查 DNS 解析是否生效，服务器防火墙是否开放 80、443 端口，Nginx 配置是否正确。
### 5. 性能优化
**问题**：服务响应缓慢
**解决方案**：
- 优化数据库查询，添加索引
- 配置 Redis 缓存
- 调整 Nginx 配置，增加并发连接数
- 调整后端服务的 worker 数量
- 使用 CDN 加速静态文件
**问题**：服务器负载过高
**解决方案**：
- 监控服务器资源使用情况
- 优化代码，减少资源消耗
- 考虑使用负载均衡，增加服务器数量
## 📊监控与维护
### 1. 监控
#### 1. 服务监控
- **Prometheus + Grafana**：监控服务器和容器状态
- **ELK Stack**：收集和分析日志
- **Uptime Robot**：监控网站可用性
#### 2. 日志管理
- **后端日志**：位于 `backend/logs` 目录
- **前端日志**：使用浏览器控制台查看
- **Nginx 日志**：位于 `/var/log/nginx` 目录
### 2. 维护
#### 1. 定期备份
```sh
# 备份数据库
mysqldump -u root -p fastapiadmin > fastapiadmin_$(date +%Y%m%d).sql
# 备份代码
zip -r fastapiadmin_$(date +%Y%m%d).zip FastapiAdmin/
# 备份配置文件
cp -r FastapiAdmin/backend/env /backup/env
cp -r FastapiAdmin/frontend/.env* /backup/frontend
```
#### 2. 定期更新
```sh
# 更新代码
git pull
# 更新依赖
cd FastapiAdmin/backend
source .venv/bin/activate
pip install -r requirements.txt
cd ../frontend
pnpm install
pnpm run build
# 重启服务
docker-compose up -d --build
```
#### 3. 故障排查
1. **查看日志**：`docker logs <容器名>`、`tail -f /var/log/nginx/error.log`
2. **检查服务状态**：`systemctl status <服务名>`、`docker ps`
3. **检查网络连接**：`ping <域名>`、`curl -I <URL>`
4. **检查资源使用**：`top`、`df -h`、`free -m`
## 📚参考文档
- **Docker 官方文档**：[https://docs.docker.com/](https://docs.docker.com/)
- **Docker Compose 官方文档**：[https://docs.docker.com/compose/](https://docs.docker.com/compose/)
- **Nginx 官方文档**：[https://nginx.org/en/docs/](https://nginx.org/en/docs/)
- **FastAPI 官方文档**：[https://fastapi.tiangolo.com/](https://fastapi.tiangolo.com/)
- **Vue 官方文档**：[https://vuejs.org/](https://vuejs.org/)
- **Let's Encrypt 官方文档**：[https://letsencrypt.org/docs/](https://letsencrypt.org/docs/)
## 🤝常见问题
### 1. 部署后无法访问
**解决方案**：
1. 检查服务器防火墙是否开放 80、443 端口
2. 检查 Nginx 服务是否正常运行
3. 检查 DNS 解析是否生效
4. 检查 Docker 容器是否正常运行
### 2. API 请求返回 500 错误
**解决方案**：
1. 查看后端日志，了解具体错误信息
2. 检查数据库连接是否正常
3. 检查 Redis 连接是否正常
4. 检查环境变量配置是否正确
### 3. 前端页面显示空白
**解决方案**：
1. 检查浏览器控制台是否有错误信息
2. 检查前端构建是否成功
3. 检查 Nginx 配置是否正确
4. 检查 API 地址是否配置正确
### 4. 部署脚本执行失败
**解决方案**：
1. 检查脚本权限是否正确 `chmod +x start.sh`
2. 检查 Docker 和 Docker Compose 是否正确安装
3. 检查网络连接是否正常
4. 查看脚本执行日志，了解具体错误信息
## �FastApp 移动端部署
### 1. H5 部署
#### 1.1 构建 H5 版本
```bash
# 进入 FastApp 目录
cd FastApp
# 安装依赖
pnpm install
# 构建 H5 版本
pnpm run build:h5
# 构建产物在 dist/build/h5 目录
```
#### 1.2 部署到服务器
1. 将 `dist/build/h5` 目录复制到 Web 服务器的静态文件目录
2. 配置 Nginx 支持 SPA 路由：
```nginx
# /etc/nginx/conf.d/fastapp.conf
server {
listen 80;
server_name service.fastapiadmin.com;
# FastApp H5
location /app {
alias /path/to/FastApp/dist/build/h5;
index index.html;
try_files $uri $uri/ /app/index.html;
}
# 其他配置...
}
```
3. 重启 Nginx：
```bash
sudo nginx -t
sudo systemctl restart nginx
```
#### 1.3 访问方式
部署完成后，可以通过以下地址访问 FastApp H5 版本：
- `http://service.fastapiadmin.com/app`
### 2. 微信小程序部署
#### 2.1 构建微信小程序版本
```bash
# 进入 FastApp 目录
cd FastApp
# 构建微信小程序版本
pnpm run build:mp-weixin
# 构建产物在 dist/build/mp-weixin 目录
```
#### 2.2 发布到微信小程序平台
1. 打开微信开发者工具
2. 点击「导入项目」
3. 选择 `dist/build/mp-weixin` 目录
4. 填写小程序 AppID（如果没有 AppID，可以使用测试号）
5. 点击「导入」按钮
6. 等待项目加载完成后，点击「上传」按钮
7. 填写版本号和更新日志
8. 点击「上传」按钮
9. 登录微信公众平台（mp.weixin.qq.com）
10. 进入「版本管理」页面
11. 找到刚刚上传的版本，点击「提交审核」
12. 等待审核通过后，点击「发布」按钮
### 3. 支付宝小程序部署
#### 3.1 构建支付宝小程序版本
```bash
# 进入 FastApp 目录
cd FastApp
# 构建支付宝小程序版本
pnpm run build:mp-alipay
# 构建产物在 dist/build/mp-alipay 目录
```
#### 3.2 发布到支付宝小程序平台
1. 打开支付宝小程序开发者工具
2. 点击「导入项目」
3. 选择 `dist/build/mp-alipay` 目录
4. 填写小程序 AppID
5. 点击「导入」按钮
6. 等待项目加载完成后，点击「上传」按钮
7. 填写版本号和更新日志
8. 点击「上传」按钮
9. 登录支付宝开放平台
10. 进入「小程序管理」页面
11. 找到刚刚上传的版本，点击「提交审核」
12. 等待审核通过后，点击「发布」按钮
### 4. App 部署
#### 4.1 使用 HBuilderX 打包
1. 下载并安装 [HBuilderX](https://www.dcloud.io/hbuilderx.html)
2. 打开 HBuilderX
3. 点击「文件」->「导入」->「从本地目录导入」
4. 选择 FastApp 项目目录
5. 等待项目加载完成后，点击「发行」->「原生 App-云打包」
6. 填写 App 名称、版本号等信息
7. 选择打包平台（Android、iOS 或两者都选）
8. 配置证书信息（如果没有证书，可以使用测试证书）
9. 点击「打包」按钮
10. 等待打包完成后，下载安装包
#### 4.2 发布到应用商店
##### Android 应用商店
1. 登录 [Google Play 开发者控制台](https://play.google.com/console/) 或其他 Android 应用商店
2. 创建应用
3. 填写应用信息
4. 上传 APK 文件
5. 提交审核
6. 等待审核通过后，应用会在应用商店上线
##### iOS App Store
1. 登录 [Apple Developer](https://developer.apple.com/) 网站
2. 进入 App Store Connect
3. 创建新应用
4. 填写应用信息
5. 上传 IPA 文件（需要使用 Xcode 进行签名）
6. 提交审核
7. 等待审核通过后，应用会在 App Store 上线
### 5. 部署注意事项
#### 5.1 API 地址配置
在部署 FastApp 之前，需要确保 API 地址配置正确：
```bash
# FastApp/.env.production
# API 基础地址
VITE_API_BASE_URL=https://service.fastapiadmin.com
# API 前缀
VITE_APP_BASE_API=/api
```
#### 5.2 跨域配置
如果 FastApp 部署在不同的域名下，需要确保后端服务支持跨域请求：
```python
# FastapiAdmin/backend/app/core/middlewares.py
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 在生产环境中应该设置具体的域名
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
#### 5.3 性能优化
- **压缩静态文件**：使用 gzip 压缩静态文件，减少传输大小
- **启用缓存**：配置浏览器缓存，减少重复请求
- **使用 CDN**：将静态资源部署到 CDN，提高访问速度
- **优化图片**：压缩图片大小，使用适当的图片格式
### 6. 常见问题及解决方案
#### 6.1 H5 部署问题
**问题**：H5 页面刷新后显示 404
**解决方案**：配置 Nginx 支持 SPA 路由，使用 `try_files` 指令
**问题**：H5 页面无法调用 API
**解决方案**：检查 API 地址配置是否正确，确保后端服务支持跨域请求
#### 6.2 小程序部署问题
**问题**：小程序审核失败
**解决方案**：根据审核反馈修改代码，确保符合小程序平台的规范
**问题**：小程序无法调用 API
**解决方案**：在微信公众平台设置合法域名，或在开发者工具中开启「不校验合法域名」选项
#### 6.3 App 部署问题
**问题**：App 打包失败
**解决方案**：检查证书配置是否正确，确保打包环境网络连接正常
**问题**：App 无法调用 API
**解决方案**：检查 API 地址配置是否正确，确保网络连接正常
## �📄许可协议
FastapiAdmin 项目采用 MIT 许可协议，详见 [LICENSE](https://github.com/fastapiadmin/FastapiAdmin/blob/master/LICENSE) 文件。
frontend/docs/src/guide/examples.md
+129
View File
@@ -0,0 +1,129 @@
# Examples
## Basic Usage
### Backend API Examples
#### User Authentication
```python
from fastapi import APIRouter, Depends, HTTPException
from fastapi_admin.models import User
from fastapi_admin.depends import get_current_user
router = APIRouter()
@router.get("/profile")
async def get_profile(current_user: User = Depends(get_current_user)):
return {"user": current_user}
```
#### CRUD Operations
```python
from fastapi import APIRouter, Depends, HTTPException
from fastapi_admin.models import Role
from fastapi_admin.depends import get_current_user
from sqlalchemy.ext.asyncio import AsyncSession
from fastapi_admin.database import get_db
router = APIRouter()
@router.get("/roles")
async def get_roles(
db: AsyncSession = Depends(get_db),
current_user: User = Depends(get_current_user)
):
roles = await db.query(Role).all()
return {"roles": roles}
```
### Frontend Examples
#### Vue Component
```vue
<template>
<div class="user-profile">
<h2>{{ user.name }}</h2>
<p>{{ user.email }}</p>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const user = ref({})
onMounted(async () => {
const response = await fetch('/api/v1/profile')
user.value = await response.json()
})
</script>
```
## Advanced Examples
### Custom Dashboard
```vue
<template>
<div class="dashboard">
<div class="stats">
<div class="stat-card">
<h3>Total Users</h3>
<p>{{ userCount }}</p>
</div>
<div class="stat-card">
<h3>Active Roles</h3>
<p>{{ roleCount }}</p>
</div>
</div>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
const userCount = ref(0)
const roleCount = ref(0)
onMounted(async () => {
// Fetch statistics
const response = await fetch('/api/v1/stats')
const data = await response.json()
userCount.value = data.userCount
roleCount.value = data.roleCount
})
</script>
```
### Docker Compose
```yaml
version: '3'
services:
backend:
build: ./backend
ports:
- "8000:8000"
depends_on:
- db
- redis
frontend:
build: ./frontend
ports:
- "80:80"
depends_on:
- backend
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: fastapiadmin
redis:
image: redis:7.0
```
frontend/docs/src/guide/frontend.md
+3182
View File
File diff suppressed because it is too large Load Diff
frontend/docs/src/guide/guidelines.md
+451
View File
@@ -0,0 +1,451 @@
---
outline: "deep"
title: 开发规范
---
# 开发规范
## 📚规范概述
为了保证项目代码的一致性、可读性和可维护性，FastapiAdmin 项目制定了以下开发规范。所有参与项目开发的开发者都应该遵循这些规范。
## 🎨前端开发规范
### 1. 代码风格
#### 1.1 TypeScript 规范
- 使用 TypeScript 严格模式（`"strict": true`）
- 为所有变量、函数、接口添加类型注解
- 避免使用 `any` 类型，除非确实无法确定类型
- 使用接口定义对象类型，而不是类型别名
- 使用枚举定义常量集合
- 使用 `type` 定义联合类型和交叉类型
- 使用 `as const` 断言确保类型安全
- 使用 `readonly` 修饰符保护不可变数据
- 使用 `unknown` 类型处理不确定类型的数据
#### 1.2 Vue 规范
- 使用 Composition API
- 使用 `<script setup lang="ts">` 语法
- 组件命名使用 PascalCase
- 变量和函数命名使用 camelCase
- 常量命名使用 UPPER_SNAKE_CASE
- 使用 `ref()` 定义响应式变量
- 使用 `computed()` 定义计算属性
- 使用 `watch()` 或 `watchEffect()` 监听变化
- 使用 `onMounted()`、`onUnmounted()` 等生命周期钩子
- 组件 props 使用 `defineProps()` 定义并添加类型
- 组件事件使用 `defineEmits()` 定义并添加类型
- 组件暴露的属性和方法使用 `defineExpose()` 定义
#### 1.3 CSS 规范
- 使用 UnoCSS 原子化 CSS
- 避免使用内联样式
- 使用 BEM 命名规范（如果不使用 UnoCSS）
- 类名使用 kebab-case
- 避免使用 ID 选择器
- 使用 CSS 变量管理主题
- 避免使用 `!important` 修饰符
- 使用 flexbox 布局确保跨平台一致性
- 合理使用 CSS Grid 布局
- 优化 CSS 选择器优先级
### 2. 组件开发最佳实践
- **单一职责原则**：每个组件只负责一个功能
- **props 设计**：
- 使用 `required` 和 `default` 明确 props 要求
- 为复杂 props 添加验证
- 使用 `withDefaults()` 为 props 设置默认值
- **事件设计**：
- 使用 kebab-case 命名事件
- 事件参数类型明确
- 避免在事件中传递过多参数
- **插槽设计**：
- 使用具名插槽提高可读性
- 为插槽添加默认内容
- 使用作用域插槽传递数据
- **样式设计**：
- 使用 `scoped` 样式避免冲突
- 合理使用 `:deep()` 选择器
- 避免在组件中使用全局样式
### 3. 状态管理最佳实践
- **模块化设计**：按功能模块拆分 store
- **状态定义**：
- 使用 `interface` 定义 state 类型
- 初始化所有状态
- 避免使用嵌套过深的状态结构
- **Actions 设计**：
- 处理异步操作
- 使用 try/catch 捕获错误
- 提交多个 mutations 时使用事务
- **Getters 设计**：
- 缓存计算结果
- 避免在 getters 中修改状态
- 合理使用参数化 getters
### 4. API 调用最佳实践
- **模块化管理**：按功能模块组织 API 接口
- **请求封装**：
- 统一处理请求头
- 统一处理错误
- 统一处理 loading 状态
- **响应处理**：
- 类型定义响应数据结构
- 统一处理响应状态码
- 合理处理空数据和边界情况
- **请求优化**：
- 使用防抖和节流
- 缓存频繁请求的结果
- 合理使用并发请求
### 5. 性能优化建议
- **代码分割**：使用路由懒加载和组件懒加载
- **资源优化**：
- 压缩图片和静态资源
- 使用 WebP 格式图片
- 合理使用 CDN
- **渲染优化**：
- 使用 `v-memo` 缓存计算结果
- 合理使用 `v-if` 和 `v-show`
- 避免在模板中使用复杂表达式
- **网络优化**：
- 使用 HTTP/2 或 HTTP/3
- 启用 Gzip 或 Brotli 压缩
- 合理设置缓存策略
### 6. 测试最佳实践
- **测试分层**：单元测试、集成测试、端到端测试
- **测试覆盖率**：
- 核心功能 100% 覆盖
- 复杂逻辑 80% 以上覆盖
- 简单功能 50% 以上覆盖
- **测试工具**：
- 使用 Vitest 进行单元测试
- 使用 Playwright 进行端到端测试
- 使用 Vue Test Utils 进行组件测试
### 7. 代码审查要点
- **类型安全**：检查 TypeScript 类型定义是否正确
- **代码质量**：检查代码是否简洁、清晰
- **性能问题**：检查是否存在性能瓶颈
- **安全问题**：检查是否存在安全漏洞
- **规范遵循**：检查是否遵循项目开发规范
## 🐍后端开发规范
### 1. 代码风格
#### 1.1 Python 规范
- 遵循 PEP 8 代码风格
- 使用 4 个空格缩进
- 行长度不超过 100 字符
- 函数和类之间空两行
- 方法之间空一行
- 导入语句按标准库、第三方库、本地库分组
#### 1.2 FastAPI 规范
- 使用 FastAPI 装饰器定义路由
- 使用 Pydantic 模型定义请求和响应数据
- 使用依赖注入处理认证和权限
- 使用路径参数和查询参数
- 使用 HTTPException 处理错误
- 使用 Depends 注入依赖
### 2. 目录结构
```
backend/app/
├── api/ # API 接口
├── common/ # 公共代码
├── config/ # 配置管理
├── core/ # 核心功能
├── plugin/ # 插件系统
├── scripts/ # 脚本工具
└── utils/ # 工具函数
```
### 3. 插件开发规范
- 插件目录应该以 `module_` 开头
- 插件应该包含 `controller.py`、`model.py`、`schema.py`、`service.py`、`crud.py` 等文件
- 控制器应该使用 `APIRouter` 定义路由
- 路由前缀应该与模块名对应（module_xxx -> /xxx）
- 控制器应该使用 `OperationLogRoute` 记录操作日志
- 接口应该使用 `AuthPermission` 进行权限控制
### 4. 数据库规范
- 使用 SQLAlchemy 2.0 ORM
- 使用 Alembic 进行数据库迁移
- 模型类应该继承自 `Base`
- 模型类应该定义 `__tablename__` 属性
- 字段命名应该使用 snake_case
- 表名应该使用 snake_case 复数形式
- 外键应该使用 `ForeignKey` 定义
- 关系应该使用 `relationship` 定义
### 5. 认证和权限规范
- 使用 JWT 进行身份认证
- 使用 RBAC 模型进行权限管理
- 接口应该添加权限控制装饰器
- 权限字符串格式：`module:controller:action`
- 权限应该在角色管理中配置
### 6. 错误处理规范
- 使用 `HTTPException` 处理 HTTP 错误
- 使用自定义异常处理全局错误
- 错误响应应该有统一的格式
- 错误应该记录到日志
### 7. 日志规范
- 使用 Python 标准库 `logging` 模块
- 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL
- 日志应该包含时间、级别、模块、消息等信息
- 关键操作应该记录日志
- 错误应该记录详细信息
## 📦FastApp 移动端开发规范
### 1. 代码风格
- 遵循前端开发规范
- 使用 TypeScript 严格模式
- 使用 Vue 3 Composition API
- 使用 `<script setup lang="ts">` 语法
- 组件命名使用 PascalCase
- 变量和函数命名使用 camelCase
### 2. 目录结构
```
FastApp/src/
├── api/ # API 接口
├── components/ # 组件
├── composables/ # 组合式函数
├── constants/ # 常量定义
├── enums/ # 枚举定义
├── layouts/ # 布局组件
├── pages/ # 页面文件
├── router/ # 路由配置
├── static/ # 静态资源
├── store/ # 状态管理
├── styles/ # 样式文件
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
├── App.vue # 应用根组件
└── main.ts # 应用入口文件
```
### 3. 页面开发规范
- 页面组件应该放在 `pages` 目录下
- 页面目录应该使用 kebab-case
- 页面组件应该包含 `index.vue` 文件
- 页面组件可以包含 `data.ts`、`types.ts` 等辅助文件
- 页面组件应该使用 `onLoad()`、`onShow()` 等生命周期钩子
- 页面跳转应该使用 `uni.navigateTo()`、`uni.switchTab()` 等 API
### 4. API 调用规范
- 遵循前端 API 调用规范
- 使用封装的 `request.ts` 工具
- API 接口应该按模块分类
- API 调用应该处理错误情况
- API 调用应该显示加载状态
### 5. 跨平台适配规范
- 使用条件编译处理平台差异
- 使用 `#ifdef`、`#ifndef`、`#endif` 指令
- 平台特有 API 应该添加条件编译
- 样式应该考虑不同平台的差异
- 布局应该使用 flexbox 确保跨平台一致性
## 🎯Git 提交规范
### 1. 分支管理
- `master`：主分支，用于发布生产版本
- `dev`：开发分支，用于集成开发
- `feature/xxx`：功能分支，用于开发新功能
- `bugfix/xxx`：修复分支，用于修复 bug
- `hotfix/xxx`：热修复分支，用于紧急修复生产环境问题
### 2. 提交信息规范
提交信息应该遵循以下格式：
```
<type>(<scope>): <subject>
<body>
<footer>
```
#### 2.1 Type
- `feat`：新功能
- `fix`：修复 bug
- `docs`：文档修改
- `style`：代码风格修改
- `refactor`：代码重构
- `test`：测试代码修改
- `chore`：构建工具或依赖修改
- `revert`：回滚提交
#### 2.2 Scope
- 可选，用于指定修改的范围
- 例如：`api`、`component`、`page`、`store` 等
#### 2.3 Subject
- 简短的提交信息，不超过 50 个字符
- 使用祈使句，动词开头
- 首字母小写
- 不需要句号结尾
#### 2.4 Body
- 可选，详细的提交信息
- 每行不超过 72 个字符
- 解释为什么修改，而不是如何修改
#### 2.5 Footer
- 可选，用于引用 issue 或 BUG
- 例如：`Closes #123`、`Fixes #456`
### 3. 提交示例
```
feat(api): 添加用户登录接口
- 实现用户登录功能
- 添加 JWT 认证
- 处理登录错误情况
Closes #123
```
```
fix(frontend): 修复首页轮播图显示问题
- 修复轮播图高度计算错误
- 优化轮播图切换动画
Fixes #456
```
```
docs: 更新开发文档
- 添加 API 文档说明
- 完善部署指南
```
### 4. Pull Request 规范
- Pull Request 应该从功能分支合并到 dev 分支
- Pull Request 标题应该清晰、语义化
- Pull Request 描述应该详细说明修改内容
- Pull Request 应该包含相关的 issue 链接
- Pull Request 应该通过所有测试
- Pull Request 应该由至少一个 reviewer 审核
## 🔧工具链规范
### 1. 前端工具链
- 使用 Vite 作为构建工具
- 使用 ESLint 进行代码检查
- 使用 Prettier 进行代码格式化
- 使用 Stylelint 进行样式检查
- 使用 Husky 进行 Git 钩子管理
- 使用 Commitlint 进行提交信息检查
### 2. 后端工具链
- 使用 Poetry 或 pip 管理依赖
- 使用 Pylint 或 Flake8 进行代码检查
- 使用 Black 进行代码格式化
- 使用 MyPy 进行类型检查
- 使用 pytest 进行测试
## 💡开发流程规范
### 1. 需求分析
- 明确功能需求
- 分析业务逻辑
- 确定技术方案
### 2. 设计阶段
- 设计数据库表结构
- 设计 API 接口
- 设计前端页面
- 设计组件结构
### 3. 开发阶段
- 创建分支
- 实现功能
- 编写测试
- 运行测试
### 4. 测试阶段
- 单元测试
- 集成测试
- 端到端测试
- 性能测试
### 5. 部署阶段
- 构建生产版本
- 部署到测试环境
- 进行回归测试
- 部署到生产环境
### 6. 维护阶段
- 监控系统运行状态
- 处理 bug 和问题
- 进行性能优化
- 进行功能迭代
## 📚参考资料
- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)
- [Vue 官方文档](https://vuejs.org/docs/)
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/)
- [PEP 8 代码风格指南](https://peps.python.org/pep-0008/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [ESLint 官方文档](https://eslint.org/docs/)
- [Prettier 官方文档](https://prettier.io/docs/en/)
## 🤝贡献指南
如果您对开发规范有任何建议或改进意见，欢迎提交 Issue 或 Pull Request。我们会认真考虑每一个建议，不断完善开发规范。
## 📄许可协议
本开发规范文档采用 MIT 许可协议，与 FastapiAdmin 项目保持一致。
frontend/docs/src/guide/miniprogram.md
+815
View File
@@ -0,0 +1,815 @@
---
outline: "deep"
title: FastApp 移动端开发指南
---
# FastApp 移动端开发指南
## 📱项目概述
**FastApp** 是 FastapiAdmin 项目的移动端应用，基于 **Uni App** 框架开发，支持一套代码多端运行（包括 H5、微信小程序、支付宝小程序、App 等）。采用 Vue 3 + TypeScript + Vite 等现代化技术栈，集成了完善的代码规范和开发工具链，为开发者提供开箱即用的移动端开发解决方案。
### 核心功能
- **用户认证**：登录、注册、密码重置、权限管理
- **首页展示**：轮播图、快捷导航、通知公告、数据统计
- **工作台**：业务功能入口，支持权限控制
- **个人中心**：个人信息、设置、FAQ、问题反馈
- **数据统计**：实时访客数、浏览量等数据展示
- **主题切换**：支持深色/浅色主题切换
### 系统功能特性
- 🔐 **用户管理** - 支持用户注册、登录、权限管理等功能，提供完善的用户体系
- 📊 **数据统计** - 提供实时数据分析和可视化报表，帮助您更好地了解业务状况
- 📁 **文件管理** - 支持文件上传、下载、分类管理，提供安全的文件存储服务
- 🔔 **消息通知** - 实时消息推送和系统通知，确保您不会错过重要信息
- 🛡️ **权限控制** - 基于RBAC的权限管理模型，灵活控制用户访问权限
- 📝 **日志审计** - 完整的操作日志记录，便于追踪和审计用户行为
## 🛠️技术栈
| 技术 | 版本 | 说明 |
|------|------|------|
| Uni App | 3.0.0+ | 跨平台移动端开发框架 |
| Vue3 | 3.5.22+ | 前端框架（Composition API） |
| TypeScript | 5.9.2+ | 类型系统 |
| Vite | 6.0+ | 构建工具 |
| Pinia | 2.1+ | 状态管理 |
| Wot Design Uni | 1.9.1+ | UI 组件库 |
| UnoCSS | 0.58+ | 原子化 CSS 引擎 |
| VueUse | 10.7+ | Vue Composition API 工具集合 |
| @stomp/stompjs | 7.0+ | WebSocket 消息协议库 |
## 📁项目结构
```
FastApp/
├─ public/ # 静态资源
│ └─ favicon.png # 网站图标
├─ src/ # 源代码
│ ├─ api/ # API 接口
│ │ ├─ auth.ts # 认证相关接口
│ │ ├─ file.ts # 文件相关接口
│ │ └─ user.ts # 用户相关接口
│ ├─ components/ # 组件
│ │ ├─ cu-date-query/ # 日期查询组件
│ │ ├─ cu-picker/ # 选择器组件
│ │ ├─ qiun-error/ # 错误提示组件
│ │ └─ qiun-loading/ # 加载组件
│ ├─ composables/ # 组合式函数
│ │ ├─ useNavigationBar.ts # 导航栏管理
│ │ ├─ useStomp.ts # WebSocket 管理
│ │ └─ useTabbar.ts # 标签栏管理
│ ├─ constants/ # 常量定义
│ │ ├─ index.ts # 常量定义
│ │ └─ storage.constant.ts # 存储键名
│ ├─ enums/ # 枚举定义
│ │ ├─ api-code.enum.ts # API 错误码
│ │ └─ api-header.enum.ts # API 头部
│ ├─ layouts/ # 布局组件
│ │ ├─ default.vue # 默认布局
│ │ └─ tabbar.vue # 标签栏布局
│ ├─ pages/ # 页面文件
│ │ ├─ index/ # 首页
│ │ │ ├─ data.ts # 数据定义
│ │ │ ├─ index.vue # 首页组件
│ │ │ └─ types.ts # 类型定义
│ │ ├─ login/ # 登录页
│ │ │ └─ index.vue # 登录组件
│ │ ├─ mine/ # 个人中心
│ │ │ ├─ about/ # 关于页面
│ │ │ ├─ faq/ # FAQ页面
│ │ │ ├─ feedback/ # 反馈页面
│ │ │ ├─ profile/ # 个人资料
│ │ │ ├─ settings/ # 设置页面
│ │ │ └─ index.vue # 个人中心组件
│ │ └─ work/ # 工作台
│ │ ├─ data.ts # 数据定义
│ │ ├─ index.vue # 工作台组件
│ │ └─ types.ts # 类型定义
│ ├─ router/ # 路由配置
│ │ └─ index.ts # 路由配置文件
│ ├─ static/ # 静态资源
│ │ ├─ icons/ # 图标
│ │ ├─ images/ # 图片
│ │ └─ logo.png # Logo
│ ├─ store/ # 状态管理
│ │ ├─ modules/ # 模块
│ │ │ ├─ theme.store.ts # 主题管理
│ │ │ └─ user.store.ts # 用户管理
│ │ └─ index.ts # 状态管理配置
│ ├─ styles/ # 样式文件
│ │ └─ index.scss # 全局样式
│ ├─ types/ # TypeScript 类型定义
│ ├─ utils/ # 工具函数
│ │ ├─ auth.ts # 认证工具
│ │ ├─ color.ts # 颜色工具
│ │ ├─ index.ts # 工具函数
│ │ ├─ request.ts # 请求工具
│ │ └─ storage.ts # 存储工具
│ ├─ App.vue # 应用根组件
│ ├─ main.ts # 应用入口文件
│ ├─ manifest.json # 应用配置文件
│ ├─ pages.json # 页面路由配置
│ └─ theme.json # 主题配置
├─ .env.development # 开发环境配置
├─ .env.production # 生产环境配置
├─ package.json # 项目依赖
├─ pages.config.ts # 页面配置
├─ tsconfig.json # TypeScript 配置
├─ unocss.config.ts # UnoCSS 配置
└─ vite.config.ts # Vite 配置
```
## 🔧环境搭建
### 1. 环境要求
- **Node.js** >= 22
- **pnpm** >= 9
### 2. 安装依赖
```sh
# 进入项目目录
cd FastApp
# 安装项目依赖
pnpm install
```
### 3. 配置环境变量
在项目根目录创建 `.env` 文件配置环境变量：
```bash
# API 基础地址
VITE_API_BASE_URL=http://localhost:8001
# API 前缀
VITE_APP_BASE_API=/api
# 开发服务器端口
VITE_APP_PORT=5180
```
## 🚀开发流程
### 1. 启动开发服务器
#### H5 开发
```sh
# 启动 H5 开发服务器
pnpm run dev:h5
# 访问地址
# http://localhost:5180/app
```
#### 微信小程序开发
```sh
# 启动微信小程序开发服务器
pnpm run dev:mp-weixin
# 在微信开发者工具中导入项目目录：FastApp/dist/dev/mp-weixin
```
#### 其他平台开发
```sh
# 启动支付宝小程序开发服务器
pnpm run dev:mp-alipay
# 启动百度小程序开发服务器
pnpm run dev:mp-baidu
# 启动字节跳动小程序开发服务器
pnpm run dev:mp-toutiao
# 启动 QQ 小程序开发服务器
pnpm run dev:mp-qq
```
## 📚页面开发
### 1. 创建新页面
1. **在 `pages.json` 中添加页面配置**：
```json
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页"
}
},
// 其他页面...
]
}
```
2. **创建页面文件**：
```
FastApp/src/pages/
└─ new-page/
├─ index.vue # 页面组件
├─ data.ts # 数据定义（可选）
└─ types.ts # 类型定义（可选）
```
3. **页面示例**：
```vue
<template>
<view class="page">
<view class="title">新页面</view>
<view class="content">
<text>{{ message }}</text>
</view>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const message = ref('Hello FastApp!');
</script>
<style scoped>
.page {
padding: 20rpx;
}
.title {
font-size: 32rpx;
font-weight: bold;
margin-bottom: 20rpx;
}
.content {
font-size: 28rpx;
color: #666;
}
</style>
```
### 2. 路由管理
#### 页面跳转
```typescript
// 普通跳转
uni.navigateTo({
url: '/pages/new-page/index'
});
// 带参数跳转
uni.navigateTo({
url: '/pages/new-page/index?id=1&name=test'
});
// 重定向跳转
uni.redirectTo({
url: '/pages/new-page/index'
});
// 跳转到 tabBar 页面
uni.switchTab({
url: '/pages/index/index'
});
// 关闭所有页面，打开新页面
uni.reLaunch({
url: '/pages/new-page/index'
});
```
#### 接收参数
```typescript
// 在页面 onLoad 生命周期中接收参数
import { onLoad } from '@dcloudio/uni-app';
onLoad((options) => {
console.log('参数：', options);
// options.id, options.name
});
```
## 📡API 调用
### 1. 封装的 API 工具
FastApp 使用封装的 `request.ts` 工具进行 API 调用，支持自动添加认证 token、错误处理等功能。
### 2. API 接口定义
API 接口定义在 `src/api` 目录下，按模块分类：
```typescript
// src/api/user.ts 示例
import request from '../utils/request';
export const userApi = {
// 获取用户信息
getUserInfo: () => {
return request({
url: '/api/v1/user/info',
method: 'GET'
});
},
// 更新用户信息
updateUserInfo: (data: any) => {
return request({
url: '/api/v1/user/update',
method: 'POST',
data
});
}
};
```
### 3. 调用 API
```typescript
import { userApi } from '../api/user';
// 调用 API
const getUserInfo = async () => {
try {
const res = await userApi.getUserInfo();
console.log('用户信息：', res.data);
} catch (error) {
console.error('获取用户信息失败：', error);
}
};
// 调用更新用户信息 API
const updateUser = async () => {
try {
const res = await userApi.updateUserInfo({
name: '新名字',
avatar: '新头像'
});
console.log('更新成功：', res.data);
} catch (error) {
console.error('更新失败：', error);
}
};
```
### 4. WebSocket 实时通信
FastApp 集成了 `@stomp/stompjs` 库，支持 WebSocket 实时通信，通过封装的 `useStomp` 组合式函数可以方便地使用：
```typescript
// 使用 WebSocket
import { useStomp } from '../composables/useStomp';
const {
connect,
disconnect,
subscribe,
send,
isConnected
} = useStomp();
// 连接 WebSocket
const initWebSocket = () => {
connect({
url: 'ws://localhost:8001/ws',
onConnect: () => {
console.log('WebSocket 连接成功');
// 订阅消息
subscribe('/topic/messages', (message) => {
console.log('收到消息：', message);
});
},
onError: (error) => {
console.error('WebSocket 连接失败：', error);
}
});
};
// 发送消息
const sendMessage = () => {
if (isConnected.value) {
send('/app/message', {
content: 'Hello WebSocket!'
});
}
};
// 断开连接
const closeWebSocket = () => {
disconnect();
};
```
## 🔐认证管理
### 1. 登录流程
```typescript
import { authApi } from '../api/auth';
import { useUserStore } from '../store/modules/user.store';
const userStore = useUserStore();
const login = async (username: string, password: string) => {
try {
const res = await authApi.login({
username,
password
});
// 保存 token
userStore.setToken(res.data.token);
// 获取用户信息
await userStore.getUserInfo();
// 跳转到首页
uni.switchTab({ url: '/pages/index/index' });
} catch (error) {
console.error('登录失败：', error);
}
};
```
### 2. 登出流程
```typescript
import { useUserStore } from '../store/modules/user.store';
const userStore = useUserStore();
const logout = () => {
// 清除 token 和用户信息
userStore.logout();
// 跳转到登录页
uni.redirectTo({ url: '/pages/login/index' });
};
```
### 3. 权限控制
可以使用全局路由守卫或页面级权限检查来实现权限控制：
```typescript
// 在页面 onLoad 中检查权限
import { onLoad } from '@dcloudio/uni-app';
import { useUserStore } from '../store/modules/user.store';
const userStore = useUserStore();
onLoad(() => {
// 检查是否登录
if (!userStore.token) {
uni.redirectTo({ url: '/pages/login/index' });
return;
}
// 检查用户权限
if (!userStore.hasPermission('required_permission')) {
uni.showToast({
title: '权限不足',
icon: 'none'
});
uni.navigateBack();
}
});
```
## 🎨UI 组件
### 1. 使用 Wot Design Uni
FastApp 使用 **Wot Design Uni** 作为 UI 组件库，提供了丰富的移动端组件：
```vue
<template>
<view class="page">
<!-- 按钮 -->
<wd-button type="primary" @click="handleClick">主要按钮</wd-button>
<!-- 输入框 -->
<wd-input v-model="value" placeholder="请输入内容" />
<!-- 列表 -->
<wd-list>
<wd-list-item title="标题" value="值" />
<wd-list-item title="标题2" value="值2" />
</wd-list>
<!-- 弹窗 -->
<wd-popup v-model:visible="popupVisible" title="弹窗标题">
<view>弹窗内容</view>
</wd-popup>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue';
const value = ref('');
const popupVisible = ref(false);
const handleClick = () => {
popupVisible.value = true;
};
</script>
```
### 2. 使用 UnoCSS
FastApp 集成了 UnoCSS 原子化 CSS 引擎，支持类名方式快速开发：
```vue
<template>
<view class="flex flex-col items-center p-4">
<view class="text-xl font-bold mb-4">Hello FastApp</view>
<view class="w-full max-w-md bg-white rounded-lg shadow-md p-4">
<view class="text-gray-700">Welcome to FastApp</view>
</view>
</view>
</template>
```
### 3. 自定义组件
可以在 `src/components` 目录下创建自定义组件：
```vue
<!-- src/components/custom-button.vue -->
<template>
<view class="custom-button" @click="$emit('click')">
<slot></slot>
</view>
</template>
<script setup lang="ts">
defineEmits(['click']);
</script>
<style scoped>
.custom-button {
padding: 12rpx 24rpx;
background-color: #007aff;
color: #fff;
border-radius: 8rpx;
text-align: center;
}
</style>
```
## 📱多平台适配
### 1. 条件编译
使用 Uni App 的条件编译语法，可以为不同平台编写不同的代码：
```vue
<template>
<view>
<!-- #ifdef H5 -->
<view>这是 H5 平台的内容</view>
<!-- #endif -->
<!-- #ifdef MP-WEIXIN -->
<view>这是微信小程序平台的内容</view>
<!-- #endif -->
<!-- #ifdef APP-PLUS -->
<view>这是 App 平台的内容</view>
<!-- #endif -->
</view>
</template>
<script setup lang="ts">
// #ifdef H5
console.log('H5 平台');
// #endif
// #ifdef MP-WEIXIN
console.log('微信小程序平台');
// #endif
</script>
<style scoped>
/* #ifdef H5 */
.view {
font-size: 16px;
}
/* #endif */
/* #ifdef MP-WEIXIN */
.view {
font-size: 28rpx;
}
/* #endif */
</style>
```
### 2. 平台特有 API
使用平台特有 API 时，需要注意添加条件编译：
```typescript
// 调用微信小程序特有 API
// #ifdef MP-WEIXIN
wx.getLocation({
type: 'wgs84',
success: (res) => {
console.log('位置信息：', res);
}
});
// #endif
// 调用 App 特有 API
// #ifdef APP-PLUS
plus.device.getInfo({
success: (info) => {
console.log('设备信息：', info);
}
});
// #endif
```
## 🚀性能优化
### 1. 代码优化
- **减少页面层级**：尽量减少页面嵌套层级，最多不超过 5 层
- **按需加载**：使用分包加载、组件按需导入等方式减少初始包大小
- **避免频繁更新**：使用 `nextTick` 合并更新，避免频繁触发渲染
- **使用虚拟列表**：长列表使用虚拟列表，避免一次性渲染过多数据
### 2. 网络优化
- **缓存数据**：使用本地存储缓存不常变化的数据
- **请求合并**：合并多个请求，减少网络请求次数
- **延迟加载**：非关键资源延迟加载
- **使用 WebSocket**：实时数据使用 WebSocket，减少轮询
### 3. 存储优化
- **合理使用本地存储**：根据数据类型选择合适的存储方式（localStorage、sessionStorage、IndexedDB）
- **清理过期数据**：定期清理过期或无用的数据
- **加密敏感数据**：敏感数据（如 token）进行加密存储
## 📦打包发布
### 1. 构建生产版本
#### H5 构建
```bash
pnpm run build:h5
# 构建产物在 dist/build/h5 目录
```
#### 微信小程序构建
```bash
pnpm run build:mp-weixin
# 构建产物在 dist/build/mp-weixin 目录
```
#### 其他平台构建
```bash
# 构建支付宝小程序
pnpm run build:mp-alipay
# 构建百度小程序
pnpm run build:mp-baidu
# 构建字节跳动小程序
pnpm run build:mp-toutiao
# 构建 QQ 小程序
pnpm run build:mp-qq
```
### 2. 发布流程
#### H5 部署
1. 执行构建命令：`pnpm run build:h5`
2. 将 `dist/build/h5` 目录部署到 Web 服务器
3. 配置服务器支持 SPA 路由（如 Nginx 的 `try_files`）
#### 小程序发布
1. 执行对应平台的构建命令
2. 使用对应平台的开发者工具打开构建产物目录
3. 在开发者工具中上传代码并提交审核
#### App 打包
1. 使用 HBuilderX 打开项目
2. 配置 App 相关信息（图标、启动页等）
3. 选择云打包或本地打包
4. 下载安装包并发布到应用商店
## 🐛常见问题及解决方案
### 1. 开发环境问题
**问题**：H5 开发时跨域错误
**解决方案**：在 `vite.config.ts` 中配置代理：
```typescript
// vite.config.ts
proxy: {
[env.VITE_APP_BASE_API]: {
changeOrigin: true,
target: env.VITE_API_BASE_URL,
},
}
```
**问题**：微信小程序开发时 API 请求失败
**解决方案**：在微信公众平台设置合法域名，或在开发者工具中开启「不校验合法域名」选项。
### 2. 运行时问题
**问题**：页面白屏
**解决方案**：检查是否有语法错误、API 调用错误，查看控制台日志。
**问题**：数据加载失败
**解决方案**：检查网络连接，API 地址是否正确，后端服务是否正常。
**问题**：样式错乱
**解决方案**：检查样式代码，使用条件编译适配不同平台。
### 3. 发布问题
**问题**：微信小程序审核失败
**解决方案**：根据审核反馈修改代码，确保符合微信小程序规范。
**问题**：包大小超过限制
**解决方案**：使用分包加载、按需导入组件、压缩资源等方式减少包大小。
## 📚代码规范
项目集成了完善的代码规范工具：
```bash
# ESLint 检查并自动修复
pnpm run lint:eslint
# Prettier 格式化
pnpm run lint:prettier
# Stylelint 检查样式
pnpm run lint:stylelint
# TypeScript 类型检查
pnpm run type-check
```
## 📚自动导入
项目配置了自动导入，以下内容无需手动导入：
- Vue 3 API（`ref`, `computed`, `watch` 等）
- uni-app API（`uni.request`, `uni.navigateTo` 等）
- Pinia（`defineStore`, `storeToRefs` 等）
- 路由（`useRouter`, `useRoute` 等）
- 组件库工具（`useToast`, `useMessage` 等）
- `src/composables` 目录下的组合式函数
- `src/utils` 目录下的工具函数
- `src/api` 目录下的 API 函数
## 📚参考文档
- **Uni App 官方文档**：[https://uniapp.dcloud.io/](https://uniapp.dcloud.io/)
- **Wot Design Uni 文档**：[https://wot-design-uni.webapp.plus/](https://wot-design-uni.webapp.plus/)
- **Vue3 官方文档**：[https://cn.vuejs.org/](https://cn.vuejs.org/)
- **TypeScript 官方文档**：[https://www.typescriptlang.org/](https://www.typescriptlang.org/)
- **微信小程序开发文档**：[https://developers.weixin.qq.com/miniprogram/dev/framework/](https://developers.weixin.qq.com/miniprogram/dev/framework/)
## 🤝贡献指南
欢迎为 FastApp 项目贡献代码！请遵循以下步骤：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
## 📄许可协议
FastApp 项目采用 MIT 许可协议，详见 [LICENSE](https://github.com/fastapiadmin/FastApp/blob/master/LICENSE) 文件。
frontend/docs/src/guide/overview.md
+254
View File
@@ -0,0 +1,254 @@
---
title: 项目概述
outline: "deep"
---
<div style="text-align: center;">
<div align="center">
<img src="/logo.png" width="150" height="150" alt="logo" />
</div>
<h1>FastApiAdmin <sup style="background-color: #28a745; color: white; padding: 2px 6px; border-radius: 3px; font-size: 0.4em; vertical-align: super; margin-left: 5px;">v2.0.0</sup></h1>
<h3>一套现代、开源、全栈融合的中后台快速开发平台</h3>
<p>如果你喜欢这个项目，给个 ⭐️ 支持一下吧！</p>
<p align="center" style="display: flex; justify-content: center; align-items: center; margin-top: 10px;">
<a href="https://gitee.com/fastapiadmin/FastapiAdmin"><img src="https://gitee.com/fastapiadmin/FastapiAdmin/badge/star.svg?theme=dark" alt="Gitee Stars"></a>
<a href="https://github.com/fastapiadmin/FastapiAdmin"><img src="https://img.shields.io/github/stars/fastapiadmin/FastapiAdmin?style=social" alt="GitHub Stars"></a>
<a href="https://github.com/fastapiadmin/FastApp"><img src="https://img.shields.io/github/stars/fastapiadmin/FastApp?style=social" alt="FastApp Stars"></a>
<a href="https://github.com/fastapiadmin/FastDocs"><img src="https://img.shields.io/github/stars/fastapiadmin/FastDocs?style=social" alt="FastDocs Stars"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-orange.svg" alt="License"></a>
<img src="https://img.shields.io/badge/Python-≥3.10-blue" alt="Python">
<img src="https://img.shields.io/badge/NodeJS-≥20.0-blue" alt="NodeJS">
<img src="https://img.shields.io/badge/MySQL-≥8.0-blue" alt="MySQL">
<img src="https://img.shields.io/badge/Redis-≥7.0-blue" alt="Redis">
</p>
</div>
## 📘项目介绍
**FastApiAdmin** 是一套 **完全开源、高度模块化、技术先进的现代化快速开发平台**，旨在帮助开发者高效搭建高质量的企业级中后台系统。该项目采用 **前后端分离架构**，融合 Python 后端框架 `FastAPI` 和前端主流框架 `Vue3` 实现多端统一开发，提供了一站式开箱即用的开发体验。
> **设计初心**: 以模块化、松耦合为核心，追求丰富的功能模块、简洁易用的接口、详尽的开发文档和便捷的维护方式。通过统一框架和组件，降低技术选型成本，遵循开发规范和设计模式，构建强大的代码分层模型，搭配完善的本地中文化支持，专为团队和企业开发场景量身定制。
## 📦工程结构概览
项目已拆分为三个独立的仓库，便于独立开发和维护：
### 1. FastapiAdmin 主工程
```sh
FastapiAdmin/
├─ backend/ # 后端工程
│ ├─ app/ # 应用核心代码
│ │ ├─ api/ # API 接口
│ │ │ └─ v1/ # API 版本
│ │ │ ├─ module_common/ # 公共模块
│ │ │ ├─ module_monitor/ # 监控模块
│ │ │ └─ module_system/ # 系统模块
│ │ ├─ common/ # 公共代码
│ │ ├─ config/ # 配置管理
│ │ ├─ core/ # 核心功能
│ │ ├─ plugin/ # 插件系统
│ │ │ ├─ module_application/ # 应用模块
│ │ │ ├─ module_example/ # 示例模块
│ │ │ └─ module_generator/ # 代码生成模块
│ │ ├─ scripts/ # 脚本工具
│ │ └─ utils/ # 工具函数
│ ├─ alembic/ # 数据库迁移
│ ├─ env/ # 环境配置
│ ├─ static/ # 静态资源
│ ├─ tests/ # 测试代码
│ ├─ README.md # 后端文档
│ ├─ main.py # 后端入口
│ └─ requirements.txt # Python 依赖
├─ frontend/ # 前端工程
│ ├─ src/ # 源代码
│ │ ├─ api/ # API 接口
│ │ ├─ assets/ # 资源文件
│ │ ├─ components/ # 组件
│ │ ├─ composables/ # 组合式函数
│ │ ├─ constants/ # 常量定义
│ │ ├─ directives/ # 指令
│ │ ├─ enums/ # 枚举定义
│ │ ├─ lang/ # 国际化
│ │ ├─ layouts/ # 布局
│ │ ├─ plugins/ # 插件
│ │ ├─ router/ # 路由
│ │ ├─ store/ # 状态管理
│ │ ├─ styles/ # 样式
│ │ ├─ types/ # 类型定义
│ │ ├─ utils/ # 工具函数
│ │ └─ views/ # 页面
│ ├─ public/ # 静态资源
│ ├─ package.json # 前端依赖
│ └─ README.md # 前端文档
├─ devops/ # 部署工程
│ ├─ backend/ # 后端部署配置
│ ├─ nginx/ # Nginx 配置
│ └─ redis/ # Redis 配置
├─ docker-compose.yaml # 部署文件
├─ deploy.sh # 部署脚本
├─ LICENSE # 许可协议
└─ README.md # 项目文档
```
### 2. FastApp 移动端
```sh
FastApp/
├─ src/ # 源代码目录
│ ├─ api/ # API 接口
│ │ ├─ auth.ts # 认证相关接口
│ │ ├─ file.ts # 文件相关接口
│ │ └─ user.ts # 用户相关接口
│ ├─ components/ # 组件
│ │ ├─ cu-date-query/ # 日期查询组件
│ │ ├─ cu-picker/ # 选择器组件
│ │ ├─ qiun-error/ # 错误提示组件
│ │ └─ qiun-loading/ # 加载组件
│ ├─ composables/ # 组合式函数
│ │ ├─ useNavigationBar.ts # 导航栏管理
│ │ ├─ useStomp.ts # WebSocket 管理
│ │ └─ useTabbar.ts # 标签栏管理
│ ├─ constants/ # 常量定义
│ │ ├─ index.ts # 常量定义
│ │ └─ storage.constant.ts # 存储键名
│ ├─ enums/ # 枚举定义
│ │ ├─ api-code.enum.ts # API 错误码
│ │ └─ api-header.enum.ts # API 头部
│ ├─ layouts/ # 布局组件
│ │ ├─ default.vue # 默认布局
│ │ └─ tabbar.vue # 标签栏布局
│ ├─ pages/ # 页面文件
│ │ ├─ index/ # 首页
│ │ │ ├─ data.ts # 数据定义
│ │ │ ├─ index.vue # 首页组件
│ │ │ └─ types.ts # 类型定义
│ │ ├─ login/ # 登录页
│ │ │ └─ index.vue # 登录组件
│ │ ├─ mine/ # 个人中心
│ │ │ ├─ about/ # 关于页面
│ │ │ ├─ faq/ # FAQ页面
│ │ │ ├─ feedback/ # 反馈页面
│ │ │ ├─ profile/ # 个人资料
│ │ │ ├─ settings/ # 设置页面
│ │ │ └─ index.vue # 个人中心组件
│ │ └─ work/ # 工作台
│ │ ├─ data.ts # 数据定义
│ │ ├─ index.vue # 工作台组件
│ │ └─ types.ts # 类型定义
│ ├─ router/ # 路由配置
│ │ └─ index.ts # 路由配置文件
│ ├─ static/ # 静态资源
│ │ ├─ icons/ # 图标
│ │ ├─ images/ # 图片
│ │ └─ logo.png # Logo
│ ├─ store/ # 状态管理
│ │ ├─ modules/ # 模块
│ │ │ ├─ theme.store.ts # 主题管理
│ │ │ └─ user.store.ts # 用户管理
│ │ └─ index.ts # 状态管理配置
│ ├─ styles/ # 样式文件
│ │ └─ index.scss # 全局样式
│ ├─ types/ # TypeScript 类型定义
│ ├─ utils/ # 工具函数
│ │ ├─ auth.ts # 认证工具
│ │ ├─ color.ts # 颜色工具
│ │ ├─ index.ts # 工具函数
│ │ ├─ request.ts # 请求工具
│ │ └─ storage.ts # 存储工具
│ ├─ App.vue # 应用根组件
│ ├─ main.ts # 应用入口文件
│ ├─ manifest.json # 应用配置文件
│ ├─ pages.json # 页面路由配置
│ └─ theme.json # 主题配置
├─ public/ # 静态资源
├─ .env.development # 开发环境配置
├─ .env.production # 生产环境配置
├─ package.json # 项目依赖
├─ pages.config.ts # 页面配置
├─ tsconfig.json # TypeScript 配置
├─ unocss.config.ts # UnoCSS 配置
└─ vite.config.ts # Vite 配置
```
### 3. FastDocs 官网文档
```sh
FastDocs/
├─ docs/ # 文档源码
│ ├─ development/ # 开发文档
│ ├─ en/ # 英文文档
│ ├─ overview/ # 概述文档
│ ├─ quickstart/ # 快速开始
│ ├─ public/ # 静态资源
│ └─ index.md # 首页
├─ .vitepress/ # VitePress 配置
│ ├─ theme/ # 主题配置
│ └─ config.ts # 站点配置
├─ package.json # 项目依赖
└─ README.md # 项目文档
```
## ✨核心亮点
| 特性 | 描述 |
| ---- | ---- |
| 🔭 快速开发 | 一套完全开源的现代化快速开发平台，旨在帮助开发者高效搭建高质量的企业级中后台系统。 |
| 🌐 全栈整合 | 前后端分离，融合 Python (FastAPI) + Vue3 多端开发，支持 Web 端和移动端。 |
| 🧱 模块化设计 | 系统功能高度解耦，插件化架构，支持自动路由发现和注册，便于扩展和维护。 |
| ⚡️ 高性能异步 | 使用 FastAPI 异步框架 + Redis 缓存优化接口响应速度。 |
| 🔒 安全认证 | 支持 JWT OAuth2 认证机制，保障系统安全。 |
| 📊 权限管理 | RBAC 模型实现菜单、按钮、数据级别的细粒度权限控制。 |
| 🚀 快速部署 | 支持 Docker/Docker Compose/Nginx 一键部署。 |
| 📄 开发友好 | 提供完善的中文文档 + 中文化界面 + 可视化工具链，降低学习成本。 |
| 🧩 快速接入 | 基于 Vue3、Vite5、Pinia、ElementPlus 等主流前端技术栈，开箱即用。 |
| 📱 移动端支持 | 基于 UniApp 开发的 FastApp 移动端，支持多端运行（H5、微信小程序、支付宝小程序、App 等）。 |
| 🤖 智能体框架 | 集成智能体框架，提供 AI 能力。 |
| 🎨 主题定制 | 支持深色/浅色主题切换，提供个性化界面体验。 |
| 🌍 国际化支持 | 内置国际化框架，支持多语言切换。 |
| 📈 数据可视化 | 集成图表库，提供丰富的数据可视化能力。 |
| 🛠️ 代码生成 | 内置代码生成工具，提升开发效率。 |
## 🛠️技术栈概览
| 类型 | 技术选型 | 描述 |
|----------|---------------------|---------------------|
| 后端框架 | FastAPI / Uvicorn / Pydantic 2.0 / Alembic | 现代、高性能的异步框架，强制类型约束，数据迁移。 |
| ORM | SQLAlchemy 2.0 | 强大的 ORM 库。 |
| 定时任务 | APScheduler | 轻松实现定时任务。 |
| 权限认证 | PyJWT | 实现 JWT 认证。 |
| 前端框架 | Vue3 / Vite5 / Pinia / TypeScript | 快速开发 Vue3 应用。 |
| 前端工具 | ESLint / Prettier / Stylelint | 代码质量和风格工具。 |
| 移动端框架 | UniApp / Vue3 / TypeScript | 跨平台移动应用开发。 |
| UI 库 | ElementPlus (Web) / Wot Design Uni (移动端) | 企业级 UI 组件库。 |
| CSS 框架 | UnoCSS / SCSS | 原子化 CSS 和预处理器。 |
| 数据库 | MySQL / PostgreSQL / SQLite | 关系型数据库支持。 |
| 缓存 | Redis | 强大的缓存数据库。 |
| 文档 | Swagger / Redoc | 自动生成 API 文档。 |
| 部署 | Docker / Nginx / Docker Compose | 快速部署项目。 |
| 监控 | 内置服务器监控 / 缓存监控 | 系统运行状态监控。 |
| 国际化 | i18n | 多语言支持。 |
| 数据可视化 | ECharts | 图表库。 |
## 📌内置模块
### FastapiAdmin 主工程模块
| 模块名 | 子模块名 | 描述 |
|----------|---------------------|---------------------|
| 仪表盘 | 工作台、分析页 | 系统概览和数据分析 |
| 系统管理 | 用户、角色、菜单、部门、岗位、字典、配置、公告 | 核心系统管理功能 |
| 监控管理 | 在线用户、服务器监控、缓存监控 | 系统运行状态监控 |
| 任务管理 | 定时任务 | 异步任务调度管理 |
| 日志管理 | 操作日志 | 用户行为审计 |
| 开发工具 | 代码生成、表单构建、接口文档 | 提升开发效率的工具 |
### FastApp 移动端模块
| 模块名 | 子模块名 | 描述 |
|----------|---------------------|---------------------|
| 首页 | 轮播图、快捷导航、通知公告、数据统计 | 移动端首页展示 |
| 工作台 | 业务功能入口，支持权限控制 | 移动端核心功能区 |
| 个人中心 | 个人信息、设置、FAQ、问题反馈 | 用户个人相关功能 |
| 用户认证 | 登录、注册、密码重置 | 用户身份验证 |
| 数据统计 | 实时访客数、浏览量等数据展示 | 业务数据可视化 |
frontend/docs/src/guide/start.md
+510
View File
@@ -0,0 +1,510 @@
---
outline: "deep"
title: 快速开始
---
# 快速开始
## 🍪演示环境
- 官网地址：<https://service.fastapiadmin.com>
- 演示地址：<https://service.fastapiadmin.com/web>
- 小程序地址：<https://service.fastapiadmin.com/app>
- 管理员账号：`admin` 密码：`123456`
- 演示账号：`demo` 密码：`123456`
## 👷安装和使用
### 版本说明
| 类型 | 技术栈 | 版本 |
|----------|------------|------------|
| 后端 | Python | >=3.10 |
| 后端 | FastAPI | 0.109+ |
| 前端 | Node.js | >= 20.0（推荐使用最新版）|
| 前端 | pnpm | >= 9.0 |
| 前端 | Vue3 | 3.5.22+ |
| Web UI | ElementPlus | 2.10.4+ |
| 移动端 | Uni App | 3.0.0+ |
| App UI | Wot Design Uni | 1.9.1+ |
| 数据库 | MySQL | 8.0+ （推荐使用最新版）|
| 中间件 | Redis | 7.0+ （推荐使用最新版）|
### 环境准备
#### 1. 安装 Python
```sh
# macOS
brew install python@3.10
# Ubuntu/Debian
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev
# CentOS/RHEL
sudo dnf install python3.10 python3.10-venv python3.10-devel
```
#### 2. 安装 Node.js
```sh
# 使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
# 或使用包管理器
# macOS
brew install node@20
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm
# CentOS/RHEL
sudo dnf install nodejs npm
# 安装 pnpm
npm install -g pnpm
```
#### 3. 安装数据库和缓存
```sh
# 安装 MySQL
# macOS
brew install mysql
brew services start mysql
# Ubuntu/Debian
sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
# 安装 Redis
# macOS
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis
```
### 获取代码
```sh
# 克隆代码到本地
# FastapiAdmin 主工程
git clone https://github.com/fastapiadmin/FastapiAdmin.git
# 或使用 Gitee
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
# FastApp 移动端
git clone https://github.com/fastapiadmin/FastApp.git
# 或使用 Gitee
git clone https://gitee.com/fastapiadmin/FastApp.git
# FastDocs 官网文档
git clone https://github.com/fastapiadmin/FastDocs.git
# 或使用 Gitee
git clone https://gitee.com/fastapiadmin/FastDocs.git
```
### 本地后端启动（FastapiAdmin 主工程）
#### 1. 配置环境变量
```sh
# 进入后端工程目录
cd FastapiAdmin/backend
# 复制环境配置文件
cp env/.env.dev.example env/.env.dev
# 编辑环境配置文件（根据实际情况修改）
# 主要配置项说明：
# - DATABASE_URL: 数据库连接地址
# - REDIS_URL: Redis连接地址
# - SECRET_KEY: JWT签名密钥
# - ACCESS_TOKEN_EXPIRE_MINUTES: 访问令牌过期时间
# - REFRESH_TOKEN_EXPIRE_DAYS: 刷新令牌过期时间
# - API_PREFIX: API前缀
# - CORS_ORIGINS: 跨域来源
```
#### 2. 安装依赖
```sh
# 使用 uv 管理项目（推荐）
uv add -r requirements.txt
# 或使用传统 pip 方式
# 创建虚拟环境（可选但推荐）
python3 -m venv .venv
# 激活虚拟环境
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
```
#### 3. 数据库初始化
```sh
# 生成迁移文件
python main.py revision "初始化迁移" --env=dev
# 应用迁移
python main.py upgrade --env=dev
# 初始化系统数据
python main.py init
```
#### 4. 启动后端服务
```sh
# 使用 uv 启动
uv run main.py run
# 或使用传统方式
# 开发环境启动
python main.py run --env=dev
# 或使用默认环境（dev）
python main.py run
# 生产环境启动
python main.py run --env=prod
```
### 本地前端启动（FastapiAdmin 主工程）
#### 1. 配置环境变量
```sh
# 进入前端工程目录
cd FastapiAdmin/frontend
# 复制环境配置文件
cp .env.development.example .env.development
# 编辑环境配置文件（根据实际情况修改）
# 主要配置项说明：
# - VITE_API_BASE_URL: 后端API基础地址
# - VITE_APP_BASE_API: API前缀
# - VITE_APP_TITLE: 应用标题
# - VITE_APP_VERSION: 应用版本
```
#### 2. 安装依赖
```sh
# 安装前端依赖
pnpm install
```
#### 3. 启动前端服务
```sh
# 开发环境启动
pnpm run dev
# 构建前端, 生成 `dist` 目录
pnpm run build
```
### 本地移动端启动（FastApp 移动端）
#### 1. 环境要求
- **Node.js** >= 22
- **pnpm** >= 9
#### 2. 配置环境变量
```sh
# 进入移动端工程目录
cd FastApp
# 复制环境配置文件
cp .env.development.example .env.development
cp .env.production.example .env.production
# 编辑环境配置文件（根据实际情况修改）
# 主要配置项说明：
# - VITE_APP_ENV: 环境模式
# - VITE_APP_TITLE: 应用标题
# - VITE_API_BASE_URL: 后端API基础地址
# - VITE_APP_BASE_API: API前缀（/api/v1）
# - VITE_APP_PORT: 开发服务器端口
# - VITE_TIMEOUT: 请求超时时间
# - VITE_APP_WS_ENDPOINT: WebSocket服务器地址
```
#### 3. 安装依赖
```sh
# 进入移动端工程目录
cd FastApp
# 安装前端依赖
pnpm install
```
#### 4. 启动开发服务器
##### H5 开发
```bash
# 启动 H5 开发服务器
pnpm run dev:h5
# 访问地址
# http://localhost:5180/app
```
##### 微信小程序开发
```bash
# 启动微信小程序开发服务器
pnpm run dev:mp-weixin
# 在微信开发者工具中导入项目目录：FastApp/dist/dev/mp-weixin
```
##### 其他平台开发
```bash
# 启动支付宝小程序开发服务器
pnpm run dev:mp-alipay
# 启动百度小程序开发服务器
pnpm run dev:mp-baidu
# 启动字节跳动小程序开发服务器
pnpm run dev:mp-toutiao
# 启动 QQ 小程序开发服务器
pnpm run dev:mp-qq
```
### 本地项目官网启动（FastDocs 官网文档）
```sh
# 进入 FastDocs 官网文档目录
cd FastDocs
# 安装依赖
pnpm install
# 运行文档工程
pnpm run docs:dev
# 构建文档工程, 生成 `dist` 目录
pnpm run docs:build
```
---
### 本地访问地址
- FastDocs 文档地址: <http://127.0.0.1:5180>
- FastapiAdmin 前端地址: <http://127.0.0.1:5173>
- FastAPI 接口文档: <http://127.0.0.1:8001/api/v1/docs>
- FastApp H5地址: <http://127.0.0.1:5180/app>
### 默认账号密码
- 管理员账号：`admin` 密码：`123456`
- 演示账号：`demo` 密码：`123456`
## 🐳 Docker 部署
### 1. 准备工作
- 服务器需安装 Docker 和 Docker Compose
- 确保服务器端口 80（Nginx）、8001（后端）可用
### 2. 部署步骤
```sh
# 进入 FastapiAdmin 主工程目录
cd FastapiAdmin
# 复制环境配置文件
cp backend/env/.env.prod.example backend/env/.env.prod
cp frontend/.env.production.example frontend/.env.production
# 编辑环境配置文件（根据实际服务器情况修改）
# 主要配置项：数据库连接、Redis连接、JWT密钥、API基础URL等
# 赋予脚本执行权限
chmod +x deploy.sh
# 执行部署脚本
./deploy.sh
# 查看部署状态
docker compose ps
# 查看日志
docker logs -f fastapiadmin-backend
```
### 3. 部署文件说明
| 配置文件 | 说明 | 路径 |
|---------|------|------|
| 后端环境配置 | 生产环境数据库、Redis等配置 | `FastapiAdmin/backend/env/.env.prod` |
| 前端环境配置 | 生产环境API地址等配置 | `FastapiAdmin/frontend/.env.production` |
| Docker配置 | 容器编排配置 | `FastapiAdmin/docker-compose.yaml` |
| Nginx配置 | 反向代理配置 | `FastapiAdmin/devops/nginx/nginx.conf` |
### 4. 常用 Docker 命令
```sh
# 查看镜像
docker images
# 查看容器
docker compose ps
# 停止服务
docker compose down
# 重启服务
docker compose up -d
# 查看容器日志
docker logs -f <容器名>
# 进入容器
docker exec -it <容器名> bash
```
## 🔧模块展示
### web 端
| 模块名 <div style="width:60px"/> | 截图 |
|----------|------|
| 仪表盘 | ![仪表盘](/dashboard.png) |
| 代码生成 | ![代码生成](/gencode.png) |
| 智能助手 | ![智能助手](/ai.png) |
### 移动端
| 登录 <div style="width:60px"/> | 首页 <div style="width:60px"/> | 个人中心 <div style="width:60px"/> |
|----------|----------|----------|
| ![移动端登录](/app_login.png) | ![移动端首页](/app_home.png) | ![移动端个人中心](/app_mine.png) |
## 🚀二开教程
### 后端部分（FastapiAdmin 主工程）
项目采用**插件化架构设计**，二次开发建议在 `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. **创建插件模块**：在 `backend/app/plugin/` 目录下创建新的模块目录，如 `module_yourfeature`
2. **编写数据模型**：在 `model.py` 中定义数据库模型
3. **编写数据验证**：在 `schema.py` 中定义数据验证模型
4. **编写数据访问层**：在 `crud.py` 中编写数据库操作逻辑
5. **编写业务逻辑层**：在 `service.py` 中编写业务逻辑
6. **编写控制器**：在 `controller.py` 中定义路由和处理函数
7. **自动注册**：系统会自动扫描并注册所有路由，无需手动配置
### 前端部分（FastapiAdmin 主工程）
1. **配置前端API**：在 `frontend/src/api/` 目录下创建对应的API文件
2. **编写页面组件**：在 `frontend/src/views/` 目录下创建页面组件
3. **注册路由**：在 `frontend/src/router/index.ts` 中注册路由
### 移动端部分（FastApp 移动端）
1. **配置移动端API**：在 `FastApp/src/api/` 目录下创建对应的API文件
2. **编写移动端页面**：在 `FastApp/src/pages/` 目录下创建页面组件
3. **配置页面路由**：在 `FastApp/src/pages.json` 中配置页面路由
## 💡常见问题及解决方案
### 1. 后端启动失败
**问题**：数据库连接失败
**解决方案**：检查环境配置文件中的数据库连接信息是否正确，确保数据库服务正在运行，且用户名密码正确。
**问题**：Redis连接失败
**解决方案**：检查环境配置文件中的Redis连接信息是否正确，确保Redis服务正在运行。
**问题**：依赖安装失败
**解决方案**：确保Python版本正确（>=3.10），可以尝试使用虚拟环境重新安装依赖。
### 2. 前端启动失败
**问题**：依赖安装失败
**解决方案**：确保Node.js版本正确（>=20.0），可以尝试清除缓存后重新安装：`pnpm cache clean && pnpm install`。
**问题**：API请求失败
**解决方案**：检查前端环境配置文件中的API基础URL是否正确，确保后端服务正在运行。
### 3. 移动端启动失败
**问题**：依赖安装失败
**解决方案**：确保Node.js版本正确（>=22.0），pnpm版本正确（>=9.0），可以尝试清除缓存后重新安装：`pnpm cache clean && pnpm install`。
**问题**：H5页面空白
**解决方案**：检查浏览器控制台是否有错误信息，确保API基础URL配置正确，后端服务正在运行。
### 4. 部署问题
**问题**：Docker部署失败
**解决方案**：确保服务器已安装Docker和Docker Compose，检查端口是否被占用，查看容器日志了解具体错误信息。
**问题**：Nginx配置错误
**解决方案**：检查Nginx配置文件中的反向代理设置是否正确，确保后端服务地址配置正确。
### 5. 其他问题
**问题**：系统初始化失败
**解决方案**：确保数据库已正确初始化，且迁移已应用，可以尝试重新执行初始化命令：`python main.py init`。
**问题**：权限不足
**解决方案**：检查用户角色权限设置，确保当前用户有足够的权限访问所需功能。
**问题**：代码生成失败
**解决方案**：确保数据库表结构正确，代码生成配置参数填写完整。
frontend/docs/src/guide/why.md
+81
View File
@@ -0,0 +1,81 @@
---
title: 为什么选择FastapiAdmin?
---
# 为什么是FastapiAdmin？
## 💡你在执着于寻找什么？
- 找一群志同道合的朋友，做一件有意义的事？
- 寻找一个亦师亦友的领路人，指引我们前行的方向？
- 圆梦一个顶级丝滑先进的、完全开源的、容易上手的、长期维护有人答疑的全栈web系统?
- 在这里，一个开源的FastapiAdmin统统包揽(你会收获技术，你会收获朋友，你会收获老师。甚至你可以看到凌晨3点大哥依旧在奋笔疾书，凌晨两点技术群讨论问题的欢呼雀跃)!
## 🏗️ 系统架构
```mermaid
graph TB
A[前端 Vue3] --> B[API网关]
C[小程序 UniApp] --> B
B --> D[后端 FastAPI]
D --> E[MySQL]
D --> F[Redis]
D --> G[MongoDB]
```
## 📡技术我们有
### 🚀 现代化全栈技术栈
- 后端基于**FastAPI**（高性能异步框架），前端基于**Vue3 + TypeScript**，技术选型主流、先进。
- 支持**Web + 小程序**多端开发，一套代码多处运行，降低开发与维护成本，容易上手。
### 🧩 高度模块化设计
- 前后端完全分离，功能模块解耦，结构清晰，易于定制和扩展。
- 提供详细二次开发教程与文档，适合中大型项目快速迭代。
### ⚡ 高性能与高安全性
- 基于**异步框架 + Redis缓存**，接口响应速度快。
- 支持**JWT + OAuth2 认证**与**RBAC权限控制**，系统安全有保障。
### 🛠️ 开箱即用，功能丰富
- 内置用户管理、权限控制、日志监控、任务调度等常见中后台功能。
- 提供主题切换、锁屏、可视化工具等细节功能，提升用户体验。
### 📦 部署简单灵活
- 支持**Docker Compose一键部署**，快速搭建生产环境。
- 也支持传统部署方式（Nginx + 手动部署），适应不同运维需求。
### 📘 中文友好，文档详尽
- 全中文开发文档 + 中文化界面，降低学习成本。
- 社区活跃，提供微信交流群，及时获取帮助与支持。
## 🤝 贡献指南
欢迎任何形式的贡献，包括但不限于：
- 提交代码修复
- 改进文档
- 提交新功能建议
- 报告bug
请查看我们的[贡献指南](/about/contributing)了解详情。
## 💪团队我们有
### ⚓项目的"定海神针"
[@fastapiadmin](https://gitee.com/fastapiadmin)深耕高精尖技术行业数十年，有着丰富的代码经验，作为团队的核心带头人，他不仅是技术深耕者，更是开源精神的践行者，常常凌晨仍在代码库中打磨功能、优化架构，为项目锚定清晰的发展方向。面对开发者的疑问，他总能耐心答疑、分享经验，从技术选型到难题攻克全程把关；同时，他也积极营造活跃的交流氛围，让团队与社区的每一次探讨都能转化为项目迭代的动力。
### 🛠️高性能架构的"搭建者"与"塑造者"
团队专注于打造高性能、高安全的异步架构，将大哥的思想进行逐步落实。把流畅交互与友好体验融入架构设计，小到主题切换细节，大到多端适配逻辑，都力求精准呈现产品价值。在完成代码开发的同时，团队更主动肩负社群答疑责任 —— 无论是技术群里开发者遇到的二次开发难题，还是使用过程中碰到的功能适配问题，成员都会及时响应、分享解决方案，用专业与耐心搭建起项目与用户之间的信任桥梁，**让开源不仅是代码的共享，更是技术与经验的互助传递。**
---
> ✅ 如果你需要一个技术先进、功能丰富、易于扩展、容易上手、且完全开源的中后台快速开发平台，**Fastapi-Vue3-Admin** 是一个绝佳的选择。尤其适合 Python + Vue3 技术栈的团队或个人快速构建企业级管理系统。
📌 **项目地址**：
- **GitHub**：
- [FastapiAdmin 主工程](https://github.com/fastapiadmin/FastapiAdmin.git)
- [FastApp 移动端](https://github.com/fastapiadmin/FastApp.git)
- [FastDocs 官网文档](https://github.com/fastapiadmin/FastDocs.git)
- **Gitee**：[https://gitee.com/fastapiadmin/FastapiAdmin](https://gitee.com/fastapiadmin/FastapiAdmin)
- [联系 or 加入我们](/about/about)
🙌 **无论你是否喜欢这个项目，都希望你能够给个 ⭐ Star 支持！小小的种子蕴含着大大的能量，终有一天星星之火，可以燎原。**
🙌 **如果你对 Fastapi-Vue3-Admin 技术有浓厚的兴趣，也欢迎你加入我们一起学习一起进步。**