30分钟上线企业级任务系统：full-stack-fastapi-postgresql实战指南
项目地址: https://gitcode.com/GitHub_Trending/fu/full-stack-fastapi-postgresql 你还在为搭建全栈项目耗费数周时间？从数据库设计到前后端联调，从认证授权到部署上线，每个环节都可能踩坑。本文将带你用full-stack-fastapi-postgresql框架，从零开始构建一个支持用户管理、权限控制、数据持久化的企业级任务管理系统，全程仅需30分钟。读完本文你将掌握：Docker一键部署全栈应用、FastAPI后端接口开发、React前端组件复用、PostgreSQL数据建模的核心技能。
为什么选择full-stack-fastapi-postgresql？
该框架是GitHub热门开源项目，集成了现代Web开发的最佳实践。后端基于FastAPI构建，提供自动生成的交互式API文档和高性能异步支持；前端采用React+TypeScript+Chakra UI，实现了响应式设计和深色模式；数据库使用PostgreSQL，通过SQLModel实现类型安全的ORM操作。项目架构如图所示：
核心技术栈亮点：
- 自动API客户端：前端通过openapi-ts自动生成API调用代码，避免手动编写HTTP请求
- 完整认证流程：支持JWT令牌认证、密码重置邮件、角色权限管理
- 容器化部署：Docker Compose配置支持开发/生产环境一键切换
- 测试覆盖：Pytest后端测试+Playwright端到端测试确保代码质量
项目完整文档可参考：README.md，开发指南：development.md
环境准备与项目初始化
快速启动项目
首先克隆仓库并进入项目目录：
git clone https://gitcode.com/GitHub_Trending/fu/full-stack-fastapi-postgresql.git task-management-system
cd task-management-system
生成安全密钥（用于JWT签名和数据库密码）：
python -c "import secrets; print(secrets.token_urlsafe(32))"
配置环境变量
复制示例环境变量文件并修改关键配置：
cp .env.example .env
需要修改的核心配置项：
SECRET_KEY：刚才生成的安全密钥FIRST_SUPERUSER：管理员邮箱（如admin@example.com）FIRST_SUPERUSER_PASSWORD：管理员密码POSTGRES_PASSWORD：PostgreSQL数据库密码
详细配置说明可参考：deployment.md
启动服务
使用Docker Compose一键启动所有服务：
docker compose up -d
该命令会启动5个容器：FastAPI后端、React前端、PostgreSQL数据库、Traefik反向代理和Adminer数据库管理工具。首次启动会自动初始化数据库结构和默认管理员账户。
后端开发：从数据模型到API接口
任务数据模型设计
修改backend/app/models.py文件，添加任务模型：
class TaskBase(SQLModel):
title: str = Field(index=True)
description: Optional[str] = Field(default=None)
status: str = Field(default="pending", index=True)
owner_id: UUID = Field(foreign_key="user.id", index=True)
class Task(TaskBase, table=True):
id: UUID = Field(default_factory=uuid4, primary_key=True)
created_at: datetime = Field(default_factory=datetime.utcnow)
updated_at: datetime = Field(default_factory=datetime.utcnow, sa_column_kwargs={"onupdate": datetime.utcnow})
创建任务CRUD接口
在backend/app/crud.py中添加任务的增删改查操作：
def create_task(db: Session, *, task_in: TaskCreate, owner_id: UUID) -> Task:
db_obj = Task.from_orm(task_in)
db_obj.owner_id = owner_id
db.add(db_obj)
db.commit()
db.refresh(db_obj)
return db_obj
def get_tasks_by_owner(db: Session, *, owner_id: UUID, skip: int = 0, limit: int = 100) -> list[Task]:
return db.query(Task).filter(Task.owner_id == owner_id).offset(skip).limit(limit).all()
注册API路由
创建backend/app/api/routes/tasks.py文件，定义任务相关接口：
@router.post("/tasks/", response_model=TaskRead)
def create_task(
*,
task_in: TaskCreate,
db: Session = Depends(deps.get_db),
current_user: User = Depends(deps.get_current_active_user),
) -> Any:
"""Create new task."""
return crud.task.create(db=db, task_in=task_in, owner_id=current_user.id)
@router.get("/tasks/", response_model=list[TaskRead])
def read_tasks(
db: Session = Depends(deps.get_db),
current_user: User = Depends(deps.get_current_active_user),
skip: int = 0,
limit: int = 100,
) -> Any:
"""Retrieve tasks."""
return crud.task.get_multi_by_owner(db=db, owner_id=current_user.id, skip=skip, limit=limit)
后端源码目录结构：backend/app/，API路由定义：backend/app/api/routes/
前端开发：任务管理界面实现
使用自动生成的API客户端
框架已通过openapi-ts自动生成前端API客户端，位于frontend/src/client/sdk.gen.ts。无需手动编写Axios请求，直接调用类型安全的API方法：
import { tasksApi } from "src/client/sdk.gen";
// 获取任务列表
const fetchTasks = async () => {
setLoading(true);
try {
const response = await tasksApi.readTasks();
setTasks(response.data);
} catch (error) {
toast({ title: "获取任务失败", status: "error" });
} finally {
setLoading(false);
}
};
创建任务列表组件
在frontend/src/components/Tasks/TaskList.tsx中实现任务列表：
import { Box, Table, Thead, Tbody, Tr, Th, Td, Button } from "@chakra-ui/react";
import { Task } from "src/client/schemas.gen";
interface TaskListProps {
tasks: Task[];
onEdit: (task: Task) => void;
onDelete: (task: Task) => void;
}
export const TaskList = ({ tasks, onEdit, onDelete }: TaskListProps) => {
return (
<Box overflowX="auto">
<Table variant="simple">
<Thead>
<Tr>
<Th>标题</Th>
<Th>状态</Th>
<Th>创建时间</Th>
<Th>操作</Th>
</Tr>
</Thead>
<Tbody>
{tasks.map((task) => (
<Tr key={task.id}>
<Td>{task.title}</Td>
<Td>{task.status}</Td>
<Td>{new Date(task.created_at).toLocaleString()}</Td>
<Td>
<Button size="sm" onClick={() => onEdit(task)}>编辑</Button>
<Button size="sm" colorScheme="red" onClick={() => onDelete(task)} ml={2}>删除</Button>
</Td>
</Tr>
))}
</Tbody>
</Table>
</Box>
);
};
添加路由和页面
修改frontend/src/routes/_layout/目录下的路由配置，添加任务管理页面：
// 在_layout/index.tsx中添加导航项
<LinkButton as={NavLink} to="/tasks" name="任务管理" />
// 创建任务管理页面 routes/_layout/tasks.tsx
import { TaskList } from "src/components/Tasks/TaskList";
import { TaskForm } from "src/components/Tasks/TaskForm";
export default function TasksPage() {
// 页面逻辑实现...
return (
<Box p={4}>
<TaskForm onTaskCreated={fetchTasks} />
<TaskList tasks={tasks} onEdit={openEditModal} onDelete={handleDelete} />
</Box>
);
}
前端组件库参考：frontend/src/components/，路由配置：frontend/src/routes/
系统功能演示
用户认证流程
系统提供完整的注册、登录、密码重置流程。用户登录界面支持JWT令牌认证，登录后令牌存储在localStorage中，有效期24小时。
任务管理功能
已实现的核心功能：
- 任务创建/编辑/删除
- 任务状态切换（待办/进行中/已完成）
- 任务搜索和过滤
- 分页加载任务列表
管理员功能
超级管理员可以管理系统用户，包括创建用户、分配角色、修改权限等操作。
深色模式支持
框架内置Chakra UI的深色模式切换功能，一键切换界面主题：
部署上线与系统维护
生产环境配置
修改docker-compose.yml文件，配置生产环境参数：
- 禁用开发工具和热重载
- 启用Traefik自动HTTPS证书
- 配置数据库持久化存储
详细部署步骤参考：deployment.md
数据库备份
创建定时任务备份PostgreSQL数据：
# 添加到crontab，每天凌晨3点执行备份
0 3 * * * docker exec task-management-system_db_1 pg_dump -U postgres app > /backup/$(date +\%Y\%m\%d).sql
系统监控
通过Traefik Dashboard监控系统状态和请求 metrics：
总结与扩展方向
本文展示了如何基于full-stack-fastapi-postgresql快速构建企业级任务管理系统。框架提供的不仅仅是代码模板，更是一套完整的开发规范和最佳实践。通过Docker容器化部署，我们实现了开发环境与生产环境的一致性；通过自动生成的API客户端，消除了前后端协作的沟通成本；通过完整的认证授权系统，保障了应用的安全性。
后续扩展方向：
- 集成Redis实现任务缓存和消息队列
- 添加WebSocket支持实现任务实时推送
- 接入第三方存储服务（如MinIO）存储任务附件
- 使用Celery实现异步任务处理（如邮件通知、报表生成）
项目源码地址：https://gitcode.com/GitHub_Trending/fu/full-stack-fastapi-postgresql，欢迎Star收藏并贡献代码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
