FastAPI Template

5 分钟搭好企业级 FastAPI 后台 — 认证、RBAC、审计、文件、队列、Docker、CI 全部就绪。

English | 在线文档 | 快速开始 | 核心特性 | 功能矩阵 | 贡献

目录

• 5 分钟快速体验
• 适合谁用
• 核心差异
• 项目预览
• 快速开始
• 功能矩阵
• 架构说明
• 项目结构
• 常用命令
• 配置参考
• API 文档
• 安全清单
• Roadmap
• 贡献
• Star History
• License

5 分钟快速体验

用最小步骤看到完整效果：

git clone https://github.com/JiayuXu0/FastAPI-Template.git
cd FastAPI-Template
uv sync
cp .env.example .env
uv run aerich init-db
uv run uvicorn src:app --reload --host 0.0.0.0 --port 8000

打开 http://localhost:8000/docs，用默认账号登录：

username: admin
password: abcd1234

你将看到 用户管理、角色管理、菜单管理、API 权限、部门管理、文件管理、审计日志 的完整 Swagger 接口，开箱可用。

也可以用脚手架一行创建：npx create-fastapi-app@latest my-backend → create-fastapi-app

适合谁用

具体场景：

核心差异

很多 FastAPI template 只解决"项目能跑起来"。这个模板更关注业务开始后不会很快重写基础设施。

如果它帮你少写一套后台脚手架，欢迎点一个 Star。Star 越多，后续会优先补更多企业后台常见能力。

项目预览

核心特性

技术栈

快速开始

方式一：脚手架创建

npx create-fastapi-app@latest my-backend
cd my-backend
uv run uvicorn src:app --reload --host 0.0.0.0 --port 8000

适合想快速生成新项目名、少改模板元信息的场景。脚手架项目：create-fastapi-app

方式二：克隆模板

git clone https://github.com/JiayuXu0/FastAPI-Template.git
cd FastAPI-Template

uv sync
cp .env.example .env
uv run aerich init-db
uv run uvicorn src:app --reload --host 0.0.0.0 --port 8000

启动后可用入口：

默认管理员：

username: admin
password: abcd1234

重要：首次启动后请立即修改默认密码，并在生产环境替换 SECRET_KEY、SWAGGER_UI_PASSWORD 和数据库密码。

Docker Compose

cp .env.example .env
# 使用 compose 中的 PostgreSQL 时，将 .env 里的 DB_ENGINE 改为 postgres
docker compose up --build

Compose 会启动：

• web: FastAPI 应用
• postgres: PostgreSQL
• redis: 缓存与 arq 队列
• worker: arq 后台任务 worker

功能矩阵

认证与权限

后台基础模块

工程能力

架构说明

flowchart TD
    Client["Client / Frontend"] --> API["API Layer\nsrc/api/v1"]
    API --> Service["Service Layer\nsrc/services"]
    Service --> Repo["Repository Layer\nsrc/repositories"]
    Repo --> Model["Model Layer\nsrc/models"]
    Model --> DB[("SQLite / PostgreSQL")]

    API --> Auth["Auth & Permission\nJWT / RBAC"]
    Service --> Cache[("Redis Cache")]
    API --> Metrics["Prometheus Metrics"]
    Service --> Queue["arq Task Queue"]
    Queue --> Worker["Worker Process"]
    Worker --> DB

核心约定：

1. 路由保持薄：只处理参数、依赖和响应。
2. 业务放 Service：权限、校验、编排逻辑集中在服务层。
3. 数据访问走 Repository：避免在 Service 里散落 ORM 查询。
4. 模型只描述数据结构：Tortoise model 与 schema 分离。
5. 所有 I/O async-first：数据库、缓存、任务队列都使用异步接口。

项目结构

FastAPI-Template/
├── src/
│   ├── api/v1/              # API routes
│   │   ├── users/           # User APIs
│   │   ├── roles/           # Role APIs
│   │   ├── menus/           # Menu APIs
│   │   ├── tasks/           # arq job status APIs
│   │   └── ...
│   ├── services/            # Business logic
│   ├── repositories/        # Data access
│   ├── models/              # Tortoise ORM models
│   ├── schemas/             # Pydantic schemas
│   ├── core/                # Middlewares, metrics, dependencies
│   ├── tasks/               # arq worker, queue, jobs
│   ├── utils/               # Cache, JWT, password, helpers
│   └── settings/            # Runtime configuration
├── migrations/              # Aerich migrations
├── tests/                   # pytest test suite
├── docs/                    # MkDocs documentation
├── docker-compose.yml
├── Dockerfile
└── pyproject.toml

常用命令

开发

uv sync
uv run uvicorn src:app --reload --host 0.0.0.0 --port 8000

数据库

uv run aerich init-db
uv run aerich migrate --name "describe_change"
uv run aerich upgrade
uv run aerich history

测试与质量

uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run pytest
uv run pytest --cov=src --cov-report=html

后台任务

PYTHONPATH=src uv run arq tasks.worker.WorkerSettings

任务示例：

• send_email_task
• cleanup_audit_logs_task

配置参考

.env.example 已包含常用配置。生产环境至少检查这些项：

API 文档

启动服务后：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json（受文档账号保护）

项目还包含 MkDocs 文档系统：

uv sync --group docs
uv run mkdocs serve
uv run mkdocs build

在线文档：jiayuxu0.github.io/FastAPI-Template

安全清单

• 修改默认管理员密码
• 生成强 SECRET_KEY
• 设置强 SWAGGER_UI_PASSWORD
• 生产环境关闭 DEBUG
• 使用 PostgreSQL 而不是 SQLite
• 配置精确 CORS_ORIGINS
• 使用 HTTPS
• 限制 /metrics 访问来源
• 配置日志采集与 Sentry
• 为文件上传设置合理大小和类型白名单

Roadmap

• 三层架构与 RBAC
• 用户、角色、菜单、API、部门、文件、审计日志
• JWT access/refresh token
• Redis 缓存与权限缓存失效
• Prometheus metrics、健康检查、trace id
• Sentry 集成
• arq 任务队列与 worker
• Dockerfile + docker-compose
• 更完整的任务管理 UI/API
• 多租户隔离示例
• OpenTelemetry tracing
• 更高覆盖率的端到端测试

贡献

欢迎提交 Issue、Discussion 和 Pull Request。

git checkout -b feature/your-feature
uv run ruff check src/ tests/
uv run pytest
git commit -m "feat: add your feature"

更多说明：

• 贡献指南
• 开发指南
• Pre-commit Hooks 指南

Star History

如果这个项目帮你节省了搭建后台基础设施的时间，请给一个 Star。它会帮助更多 FastAPI 开发者发现这个模板。

License

MIT