full-stack-fastapi-template postgres 管理系统安装指南

本项目基于 full-stack-fastapi-template 模板开发

1. 环境准备

请确保您的系统已安装以下软件：

• Python 3.9+
• Node.js 16+
• PostgreSQL 13+
• Git
• Docker (可选，用于容器化部署)

2. 获取代码

# 2.1 克隆代码
git clone https://github.com/fastapi/full-stack-fastapi-template.git
cd full-stack-fastapi-template# 2.2 创建Python虚拟环境
python -m venv venv# 2.3 激活虚拟环境
# Windows:
.\venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

3. 后端配置

# 3.1 进入后端目录
cd backend# 3.2 安装包管理工具和依赖
pip install uv alembic# 3.3 安装项目依赖
uv pip install -e .

修改 .env 文件中的以下配置：

# 3.4 必要的配置项
PROJECT_NAME=修仙Xianxia管理器
STACK_NAME=full-stack-fastapi-project
SECRET_KEY=你的密钥
POSTGRES_USER=postgres用户名
POSTGRES_PASSWORD=数据库密码
POSTGRES_DB=xianxia
FIRST_SUPERUSER=超级管理员邮箱
FIRST_SUPERUSER_PASSWORD=超级管理员密码

4. 数据库设置

# 4.1 登录PostgreSQL
psql -U postgres# 4.2 创建数据库
CREATE DATABASE xianxia;
\q# 4.3 执行数据库迁移
alembic upgrade head
python app/initial_data.py # 创建初始数据

5. 运行服务

5.1 启动后端

# 启动开发服务器
uvicorn app.main:app --reload

5.2 启动前端

# 进入前端目录
cd frontend# 安装依赖
npm install# 启动开发服务器
npm run dev

6. 访问系统

• 后端API: http://localhost:8000
• API文档: http://localhost:8000/docs
• 前端页面: http://localhost:5173

Docker部署（可选）

如果您想使用Docker部署，可以使用以下命令：

# 构建并启动所有服务
docker-compose up -d# 查看服务状态
docker-compose ps# 查看日志
docker-compose logs

常见问题排查

数据库连接问题

1. 检查PostgreSQL服务是否启动
2. 验证数据库用户名和密码是否正确
3. 确认数据库名称是否正确

依赖安装问题

1. 确保pip和npm是最新版本
2. 尝试清除缓存后重新安装

   # Python缓存清理
   pip cache purge
   # NPM缓存清理
   npm cache clean --force
   

运行错误

1. 检查端口是否被占用
2. 查看日志输出
3. 确认环境变量配置正确

技术栈说明

• 后端：FastAPI (Python)
• 前端：Vue.js + Vite
• 数据库：PostgreSQL
• 文档：Swagger UI
• 迁移：Alembic
• 容器化：Docker & Docker Compose

参考资料

• FastAPI官方文档
• Vue.js官方文档
• 项目模板来源