模板说明：本模板基于 Vue3（Vite）+ Python（FastAPI）+ Docker + docker-compose 构建，适配全栈开发场景，包含用户认证、基础接口、文件上传、容器化部署等核心功能，可直接复制初始化项目，快速启动开发。贴合10年全栈前端技术栈（Vue3/Node.js/Python/FastAPI/Docker），兼顾工程化规范与可扩展性，支持后续对接AI流式接口、地图模块。
一、项目总目录结构（完整可直接复制）
fullstack-template/ # 项目根目录
├── frontend/ # Vue3 前端项目（Vite）
├── backend/ # Python 后端项目（FastAPI）
├── docker-compose.yml # 多服务编排配置（前端+后端+MySQL）
├── .gitignore # 全局忽略文件（git提交过滤）
└── README.md # 项目启动、部署说明文档
二、前端项目模板（frontend/）
1. 前端目录结构
frontend/
├── public/ # 静态资源（不参与打包，直接访问）
│ └── favicon.ico
├── src/
│ ├── api/ # 接口请求（与后端FastAPI接口一一对应）
│ │ ├── index.js # Axios 全局配置（拦截器、基础地址）
│ │ ├── auth.js # 登录/鉴权相关接口
│ │ ├── user.js # 用户管理相关接口
│ │ └── upload.js # 文件上传相关接口
│ ├── assets/ # 静态资源（参与打包）
│ │ ├── img/ # 图片资源
│ │ └── css/ # 全局样式
│ ├── components/ # 通用组件
│ │ ├── common/ # 公共组件（按钮、输入框、弹窗等）
│ │ ├── auth/ # 认证相关组件（登录表单等）
│ │ └── layout/ # 布局组件（头部、侧边栏、底部）
│ ├── pages/ # 页面组件
│ │ ├── Login.vue # 登录页
│ │ ├── Home.vue # 首页
│ │ ├── User/ # 用户管理模块
│ │ │ ├── UserList.vue
│ │ │ └── UserEdit.vue
│ │ └── Upload.vue # 文件上传页
│ ├── pinia/ # 状态管理（替代Vuex）
│ │ ├── index.js # Pinia 初始化
│ │ └── userStore.js # 用户状态（Token、用户信息）
│ ├── router/ # 路由配置
│ │ └── index.js # 路由定义、导航守卫（鉴权）
│ ├── utils/ # 工具函数
│ │ ├── request.js # Axios 封装（请求/响应拦截）
│ │ └── common.js # 通用工具（格式转换、本地存储等）
│ ├── App.vue # 根组件
│ └── main.js # 入口文件（初始化Vue、Pinia、Router）
├── .dockerignore # Docker 忽略文件（不打包无关内容）
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── Dockerfile # 前端Docker打包配置
├── index.html # 入口HTML
├── package.json # 前端依赖配置
└── vite.config.js # Vite 配置（代理、别名、端口）
2. 前端核心配置文件（可直接复制使用）
（1）package.json
{
"name": "frontend-template",
"private": true,
"version": "0.1.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"axios": "^1.6.8",
"element-plus": "^2.7.2",
"pinia": "^2.1.7",
"vue": "^3.4.21",
"vue-router": "^4.3.0"
},
"devDependencies": {
"@vitejs/plugin-vue": "^5.0.4",
"vite": "^5.2.8"
}
}
（2）vite.config.js（配置代理，解决开发跨域）
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
resolve: {
// 别名配置，@ 指向 src 目录
alias: {
'@': path.resolve(__dirname, 'src')
}
},
server: {
port: 8080, // 前端开发端口
open: true, // 启动自动打开浏览器
proxy: {
// 代理后端接口，避免开发跨域
'/api': {
target: 'http://localhost:8000', // 后端服务地址
changeOrigin: true, // 允许跨域
rewrite: (path) => path.replace(/^\/api/, '') // 重写路径（可选）
}
}
},
build: {
// 打包配置，优化打包体积
minify: 'terser',
rollupOptions: {
output: {
chunkFileNames: 'js/[name]-[hash].js',
entryFileNames: 'js/[name]-[hash].js',
assetFileNames: '[ext]/[name]-[hash].[ext]'
}
}
}
})
（3）src/utils/request.js（Axios封装，对接后端统一响应）
import axios from 'axios'
import { useUserStore } from '@/pinia/userStore'
import { ElMessage } from 'element-plus'
// 创建Axios实例
const service = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
timeout: 10000,
headers: {
'Content-Type': 'application/json;charset=utf-8'
}
})
// 请求拦截器（添加Token，鉴权）
service.interceptors.request.use(
(config) => {
const userStore = useUserStore()
// 若有Token，添加到请求头（Bearer 格式）
if (userStore.token) {
config.headers.Authorization = `Bearer ${userStore.token}`
}
return config
},
(error) => {
ElMessage.error('请求发起失败，请检查网络')
return Promise.reject(error)
}
)
// 响应拦截器（统一处理响应，错误提示）
service.interceptors.response.use(
(response) => {
const res = response.data
// 对接后端统一响应格式（code/msg/data）
if (res.code !== 200) {
// 401：Token失效，跳转登录页
if (res.code === 401) {
const userStore = useUserStore()
userStore.logout() // 清除Token
window.location.href = '/login'
}
// 其他错误，提示错误信息
ElMessage.error(res.msg || '操作失败，请重试')
return Promise.reject(res)
}
// 成功响应，返回数据
return res.data
},
(error) => {
ElMessage.error(error.message || '网络错误，请检查连接')
return Promise.reject(error)
}
)
export default service
（4）Dockerfile（前端Docker打包，适配Nginx）
# 第一阶段：构建前端项目（依赖安装 + 打包）
FROM node:18-alpine as build-stage
# 设置工作目录
WORKDIR /app
# 复制依赖配置文件
COPY package.json package-lock.json ./
# 安装依赖（国内源加速）
RUN npm install --registry=https://registry.npm.taobao.org
# 复制项目所有文件
COPY . .
# 打包前端项目（生成dist目录）
RUN npm run build
# 第二阶段：部署（基于Nginx，轻量运行）
FROM nginx:alpine as production-stage
# 复制打包后的dist目录到Nginx静态目录
COPY --from=build-stage /app/dist /usr/share/nginx/html
# 复制自定义Nginx配置（可选，解决前端路由刷新404）
COPY nginx.conf /etc/nginx/conf.d/default.conf
# 暴露80端口（Nginx默认端口）
EXPOSE 80
# 启动Nginx服务
CMD ["nginx", "-g", "daemon off;"]
（5）.env.development（开发环境变量）
# 开发环境
NODE_ENV=development
# 后端接口基础地址（配合vite代理）
VITE_API_BASE_URL=/api
三、后端项目模板（backend/）
1. 后端目录结构（FastAPI）
backend/
├── app/ # 核心应用代码（类似前端src）
│ ├── __init__.py # 包初始化文件（空文件即可）
│ ├── main.py # FastAPI入口文件（启动、路由注册、跨域）
│ ├── api/ # 接口路由（模块化拆分）
│ │ ├── __init__.py
│ │ └── v1/ # 接口版本管理（v1版本，便于迭代）
│ │ ├── __init__.py
│ │ ├── auth.py # 登录/鉴权接口（JWT）
│ │ ├── user.py # 用户管理接口（CURD）
│ │ └── upload.py # 文件上传接口
│ ├── core/ # 核心配置
│ │ ├── __init__.py
│ │ ├── config.py # 全局配置（数据库、JWT、跨域，从环境变量读取）
│ │ └── dependencies.py # 依赖注入（数据库会话、Token鉴权）
│ ├── models/ # 数据库模型（类似前端schema）
│ │ ├── __init__.py
│ │ └── user.py # 用户表模型（MySQL）
│ ├── schemas/ # 数据校验模型（请求/响应参数校验）
│ │ ├── __init__.py
│ │ └── user.py # 用户相关参数校验
│ ├── crud/ # 数据库操作（CURD，类似前端api请求）
│ │ ├── __init__.py
│ │ └── user.py # 用户表CURD操作
│ ├── utils/ # 工具函数
│ │ ├── __init__.py
│ │ ├── jwt.py # JWT工具（生成、解析Token）
│ │ └── password.py # 密码加密工具（bcrypt）
│ └── static/ # 静态文件（存储上传的文件）
│ └── uploads/
├── .dockerignore # Docker忽略文件
├── .env # 本地开发环境变量（不上传git）
├── .env.example # 环境变量示例（上传git，标注必填项）
├── Dockerfile # 后端Docker打包配置
├── requirements.txt # 后端依赖清单
└── uvicorn_config.py # uvicorn启动配置（可选）
2. 后端核心配置文件（可直接复制使用）
（1）requirements.txt（后端依赖，包含FastAPI核心依赖）
fastapi>=0.104.1 # 核心框架
uvicorn>=0.24.0 # 运行服务器
pydantic-settings>=2.0.0 # 环境变量配置
pymysql>=1.1.0 # MySQL连接
sqlalchemy>=2.0.23 # ORM工具（数据库操作）
python-jose[cryptography]>=3.3.0 # JWT鉴权
passlib[bcrypt]>=1.7.4 # 密码加密
python-multipart>=0.0.6 # 文件上传
aiohttp>=3.9.0 # 异步请求（后续对接AI API可用）
python-dotenv>=1.0.0 # 读取.env文件
（2）app/core/config.py（全局配置，从环境变量读取）
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
"""全局配置类，从.env文件读取环境变量，默认值作为 fallback"""
# 项目基础配置
PROJECT_NAME: str = "FastAPI 全栈模板"
API_V1_STR: str = "/api/v1" # 接口版本前缀
# 数据库配置（MySQL）
DATABASE_URL: str = "mysql+pymysql://root:123456@mysql:3306/fullstack_db"
# 格式：mysql+pymysql://用户名:密码@数据库地址:端口/数据库名
# JWT鉴权配置
SECRET_KEY: str = "your-secret-key-123456" # 生产环境用随机字符串
ALGORITHM: str = "HS256" # 加密算法
ACCESS_TOKEN_EXPIRE_MINUTES: int = 30 # Token过期时间（分钟）
# 跨域配置
CORS_ORIGINS: list = ["*"] # 开发环境允许所有域名，生产环境替换为前端域名
# 静态文件配置（文件上传）
STATIC_DIR: str = "app/static"
UPLOAD_DIR: str = "app/static/uploads"
# 加载.env文件（优先级：环境变量 > .env文件 > 默认值）
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
# 全局配置实例（整个项目统一使用）
settings = Settings()
（3）app/main.py（FastAPI入口文件，注册路由、跨域）
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
from app.api.v1 import auth, user, upload
from app.core.config import settings
# 初始化FastAPI应用
app = FastAPI(
title=settings.PROJECT_NAME,
description="前端 + Python + Docker 全栈项目模板接口文档",
version="1.0.0",
openapi_url=f"{settings.API_V1_STR}/openapi.json", # 接口文档地址
docs_url="/docs", # Swagger文档地址（前端联调必备）
redoc_url="/redoc"
)
# 1. 配置跨域（解决前端联调跨域问题）
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS,
allow_credentials=True, # 允许携带Cookie
allow_methods=["*"], # 允许所有请求方法
allow_headers=["*"], # 允许所有请求头
)
# 2. 注册接口路由（模块化拆分，便于维护）
app.include_router(auth.router, prefix=settings.API_V1_STR, tags=["认证"])
app.include_router(user.router, prefix=settings.API_V1_STR, tags=["用户管理"])
app.include_router(upload.router, prefix=settings.API_V1_STR, tags=["文件上传"])
# 3. 挂载静态文件（用于访问上传的文件，如图片）
app.mount("/static", StaticFiles(directory=settings.STATIC_DIR), name="static")
# 4. 根路由（测试服务是否启动）
@app.get("/")
def root():
return {
"message": "FastAPI 全栈服务已启动",
"docs_url": "/docs", # 接口文档地址（前端联调查看）
"api_version": "v1"
}
（4）Dockerfile（后端Docker打包，适配FastAPI）
# 基础镜像（轻量Python，减少镜像体积）
FROM python:3.11-slim
# 设置工作目录
WORKDIR /app
# 安装系统依赖（可选，解决某些依赖安装失败问题）
RUN apt-get update && apt-get install -y --no-install-recommends \
gcc \
&& rm -rf /var/lib/apt/lists/*
# 复制依赖配置文件
COPY requirements.txt .
# 安装后端依赖（国内源加速，--no-cache-dir 不缓存，减少体积）
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 复制项目所有文件
COPY . .
# 暴露后端服务端口（与uvicorn启动端口一致）
EXPOSE 8000
# 启动命令（生产环境，不使用--reload热更新）
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
（5）.env.example（环境变量示例，上传git）
# 数据库配置（必填）
DATABASE_URL=mysql+pymysql://root:123456@mysql:3306/fullstack_db
# JWT配置（必填，生产环境请修改为随机字符串）
SECRET_KEY=your-secret-key-123456
ACCESS_TOKEN_EXPIRE_MINUTES=30
# 跨域配置（生产环境替换为前端域名）
CORS_ORIGINS=["*"]
# 项目名称（可选）
PROJECT_NAME=FastAPI 全栈模板
四、全局配置文件（项目根目录）
1. docker-compose.yml（多服务编排，一键启动前端+后端+MySQL）
version: '3.8' # docker-compose版本
# 定义所有服务
services:
# 1. 前端服务
frontend:
build:
context: ./frontend # 前端项目目录
dockerfile: Dockerfile # 前端Dockerfile路径
container_name: frontend-template # 容器名称（自定义，便于管理）
ports:
- "8080:80" # 端口映射：宿主机8080端口 → 容器80端口（Nginx）
depends_on:
- backend # 依赖后端服务，后端启动后再启动前端
restart: always # 容器挂掉自动重启
networks:
- fullstack-network # 加入自定义网络，便于服务间通信
# 2. 后端服务
backend:
build:
context: ./backend # 后端项目目录
dockerfile: Dockerfile # 后端Dockerfile路径
container_name: backend-template
ports:
- "8000:8000" # 端口映射：宿主机8000端口 → 后端8000端口
depends_on:
- mysql # 依赖MySQL服务，数据库启动后再启动后端
environment:
# 环境变量（覆盖.env文件，适配Docker环境）
- DATABASE_URL=mysql+pymysql://root:123456@mysql:3306/fullstack_db
- SECRET_KEY=your-secret-key-123456
- CORS_ORIGINS=["*"]
restart: always
networks:
- fullstack-network
# 3. MySQL数据库服务（直接使用官方镜像，无需自己构建）
mysql:
image: mysql:8.0 # 官方MySQL镜像（8.0版本，稳定）
container_name: mysql-template
ports:
- "3306:3306" # 端口映射：宿主机3306端口 → 数据库3306端口
environment:
- MYSQL_ROOT_PASSWORD=123456 # 根密码（自定义）
- MYSQL_DATABASE=fullstack_db # 自动创建数据库（与后端配置一致）
- MYSQL_CHARSET=utf8mb4 # 字符集（支持中文、表情）
- MYSQL_COLLATION=utf8mb4_unicode_ci
volumes:
- mysql-data:/var/lib/mysql # 数据卷：持久化数据库数据（容器删除数据不丢失）
restart: always
networks:
- fullstack-network
# 自定义网络（所有服务在同一网络，可通过服务名访问）
networks:
fullstack-network:
driver: bridge # 桥接模式，默认即可
# 数据卷（持久化数据，避免容器删除后数据丢失）
volumes:
mysql-data: # 自动创建数据卷，存储MySQL数据
2. .gitignore（全局忽略文件，git提交过滤）
# 后端忽略文件
backend/__pycache__/ # Python编译缓存
backend/.env # 本地环境变量（不上传）
backend/venv/ # Python虚拟环境
backend/app/static/uploads/ # 上传的文件（不上传）
backend/*.log # 日志文件
backend/.pytest_cache/ # 测试缓存
# 前端忽略文件
frontend/node_modules/ # 前端依赖
frontend/dist/ # 打包后的文件
frontend/.env # 前端环境变量
frontend/.vscode/ # VSCode配置
frontend/package-lock.json # 依赖锁文件（可选，建议上传）
frontend/.npmrc # npm配置
frontend/.gitignore
# Docker忽略文件
*.dockerignore
.docker-compose.override.yml
.docker-compose.yml.bak
# 通用忽略文件
.DS_Store # Mac系统文件
*.log # 所有日志文件
.vscode/ # VSCode配置
.idea/ # PyCharm配置
.gitignore # git忽略文件
*.zip # 压缩包
*.tar.gz
3. README.md（项目说明，便于团队协作与部署）
# 前端 + Python + Docker 全栈项目模板
基于 Vue3（Vite）+ Python（FastAPI）+ Docker + MySQL 构建的全栈项目模板，包含用户认证、文件上传、容器化部署等核心功能，可直接初始化项目，快速启动开发。
## 技术栈
- 前端：Vue3、Vite、Pinia、VueRouter、Element Plus
- 后端：Python、FastAPI、SQLAlchemy（ORM）、JWT鉴权
- 数据库：MySQL 8.0
- 工程化&部署：Docker、docker-compose
- 其他：Axios、bcrypt（密码加密）
## 快速启动（Docker一键启动）
1. 克隆项目到本地
git clone [项目地址]
cd fullstack-template
2. 启动所有服务（后端+前端+MySQL）
docker-compose up -d --build
3. 访问地址
- 前端：http://localhost:8080
- 后端接口文档：http://localhost:8000/docs
- MySQL：localhost:3306（用户名root，密码123456）
## 本地开发（不使用Docker）
### 后端开发
1. 进入后端目录
cd backend
2. 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate # Mac/Linux
venv\Scripts\activate # Windows
3. 安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
4. 复制.env.example为.env，修改配置（数据库地址等）
cp .env.example .env
5. 启动后端服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
### 前端开发
1. 进入前端目录
cd frontend
2. 安装依赖
npm install
3. 启动前端服务
npm run dev
## 项目结构说明
- frontend/：Vue3前端项目
- backend/：FastAPI后端项目
- docker-compose.yml：多服务编排配置
- .gitignore：全局忽略文件
## 核心功能
1. 用户认证：登录、JWT鉴权
2. 用户管理：用户列表、新增、编辑、删除
3. 文件上传：文件上传、静态文件访问
4. 容器化部署：一键启动、自动重启、数据持久化
## 注意事项
1. 生产环境需修改SECRET_KEY为随机字符串，避免泄露
2. 生产环境需修改CORS_ORIGINS，只允许指定前端域名
3. MySQL数据通过数据卷持久化，删除容器不丢失数据
4. 前端打包后通过Nginx部署，后端通过uvicorn运行
五、模板使用说明（关键步骤）
复制上述所有目录结构和文件，创建本地项目文件夹，粘贴对应文件；
修改基础配置：
- 后端：修改backend/.env文件，配置数据库密码、SECRET_KEY等；
- 前端：修改frontend/.env.development，配置后端接口地址（如需）；
- docker-compose.yml：修改MySQL密码、容器名称等自定义配置。
启动项目：在项目根目录执行
docker-compose up -d --build，一键启动前端、后端、MySQL；开发扩展：
- 新增接口：在backend/app/api/v1/目录下新增路由文件，注册到main.py；
- 新增页面：在frontend/src/pages/目录下新增页面，配置路由；
- 对接AI流式接口：在backend/app/api/v1/新增ai.py，添加流式接口（复用之前的AI流式代码）；
- 添加地图模块：在前端引入Mapbox GL/OpenLayers，后端新增地图相关接口。
六、适配性说明
本模板完全贴合你的10年全栈技术栈（Vue3/Node.js/Python/FastAPI/Docker），可直接扩展：
对接AI流式接口：在backend/app/api/v1/新增ai.py，复制之前的AI流式代码，修改路由即可；
添加地图模块：前端引入Mapbox GL/Cesium，后端新增地图相关接口（如坐标转换、轨迹查询）；
扩展Node.js服务：如需保留Node.js后端，可在docker-compose.yml中新增Node.js服务，与Python服务协同。
