全栈 FastAPI 模板（Full Stack FastAPI Template）

技术栈与特性

• ⚡ FastAPI：Python 后端 API 框架。
  • 🧰 SQLModel：用于 Python 与 SQL 数据库交互的 ORM。
  • 🔍 Pydantic：被 FastAPI 使用，用于数据校验与配置管理。
  • 💾 PostgreSQL：关系型数据库。
• 🚀 React：前端框架。
  • 💃 使用 TypeScript、Hooks、Vite 等现代前端技术栈。
  • 🎨 Tailwind CSS 与 shadcn/ui 作为前端组件系统。
  • 🤖 自动生成的前端 API 客户端。
  • 🧪 使用 Playwright 做端到端测试。
  • 🦇 支持暗黑模式。
• 🐋 使用 Docker Compose 进行开发与生产部署。
• 🔒 默认安全的密码哈希。
• 🔑 JWT（JSON Web Token）认证。
• 📫 基于邮箱的密码找回功能。
• 📬 使用 Mailcatcher 做本地邮件测试。
• ✅ 使用 Pytest 编写与运行测试。
• 📞 使用 Traefik 作为反向代理 / 负载均衡器。
• 🚢 提供基于 Docker Compose 的部署说明，包括如何配置 Traefik 代理与自动 HTTPS 证书。
• 🏭 提供基于 GitHub Actions 的 CI/CD（持续集成与持续部署）配置。

仪表盘登录页

仪表盘 - 管理后台

仪表盘 - Items

仪表盘 - 暗黑模式

交互式 API 文档

如何使用本模板

你可以直接 fork 或 clone 本仓库，然后在此基础上开发。

✨ 开箱即用。✨

在私有仓库中使用

如果你希望代码在私有仓库中，GitHub 不允许直接将一个公开仓库 fork 成私有仓库（fork 无法更改可见性）。

你可以按以下步骤操作：

• 在 GitHub 上创建一个新的仓库，例如 my-full-stack。
• 在本地手动克隆本模板仓库，并将目录名设置为你想要的项目名，例如 my-full-stack：

git clone git@github.com:fastapi/full-stack-fastapi-template.git my-full-stack

• 进入新目录：

cd my-full-stack

• 将远程仓库地址改为你自己的仓库（在 GitHub 页面中复制地址），例如：

git remote set-url origin git@github.com:octocat/my-full-stack.git

• 将本模板仓库作为另一个远程仓库添加进来，方便后续同步更新：

git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git

• 将代码推送到你自己的仓库：

git push -u origin master

从原始模板同步更新

在你克隆并修改项目之后，可能希望定期从原始模板仓库获取最新改动。

• 确认已经添加了原始模板仓库作为远程仓库，可以通过下面的命令检查：

git remote -v

origin    git@github.com:octocat/my-full-stack.git (fetch)
origin    git@github.com:octocat/my-full-stack.git (push)
upstream  git@github.com:fastapi/full-stack-fastapi-template.git (fetch)
upstream  git@github.com:fastapi/full-stack-fastapi-template.git (push)

• 在本地拉取上游模板的最新改动（不自动提交）：

git pull --no-commit upstream master

这会拉取模板最新改动但不会立刻生成提交，方便你在提交前检查是否一切正常。

• 如果有冲突，请在编辑器中解决。

• 解决完冲突后，继续合并并提交：

git merge --continue

配置

你可以在 .env 文件中修改配置来定制你的项目。

在部署之前，至少要修改以下值：

• SECRET_KEY
• FIRST_SUPERUSER_PASSWORD
• POSTGRES_PASSWORD

推荐将这些值作为环境变量从机密管理系统中注入。

更多细节请阅读 deployment.md。

生成密钥

.env 中有一些环境变量的默认值为 changethis，需要替换为真正的随机密钥。

可以使用下面的命令生成一个安全随机密钥：

python -c "import secrets; print(secrets.token_urlsafe(32))"

复制输出内容，作为密码 / 密钥使用。需要多个密钥时，多运行几次即可。

使用 Copier 生成项目（可选方式）

本仓库也支持使用 Copier 来生成新项目。

Copier 会复制所有文件、询问你一系列配置问题，并根据你的回答更新 .env 文件。

安装 Copier

你可以通过以下命令安装 Copier：

pip install copier

或（推荐）如果你已经安装了 pipx，可以使用：

pipx install copier

注意：如果有 pipx，也可以不先安装 Copier，直接运行它。

使用 Copier 生成项目

先决定一个新项目目录名，例如 my-awesome-project。

进入想要存放项目的父级目录，然后执行：

copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust

如果你安装了 pipx 但没有单独安装 copier，也可以直接运行：

pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust

注意：--trust 选项用于允许执行一个 创建后的脚本，该脚本会自动更新你的 .env 文件。

输入变量

Copier 会在生成项目时询问一些配置项，你可以提前准备好这些信息。

不过不用担心，这些值之后都可以在 .env 文件中再次修改。

输入变量及其默认值（有些会自动生成）如下：

• project_name：默认 "FastAPI Project"，展示给 API 使用者的项目名称（写入 .env）。
• stack_name：默认 "fastapi-project"，用于 Docker Compose 标签与项目名（不允许空格和句号）（写入 .env）。
• secret_key：默认 "changethis"，项目安全相关的密钥，存储在 .env 中，你应使用上文提到的方式生成真正的随机值。
• first_superuser：默认 "admin@example.com"，首个超级用户邮箱（写入 .env）。
• first_superuser_password：默认 "changethis"，首个超级用户密码（写入 .env）。
• smtp_host：默认 ""，用于发送邮件的 SMTP 服务器地址，可稍后在 .env 中配置。
• smtp_user：默认 ""，SMTP 用户名。
• smtp_password：默认 ""，SMTP 密码。
• emails_from_email：默认 "info@example.com"，发件邮箱，可稍后在 .env 中配置。
• postgres_password：默认 "changethis"，PostgreSQL 数据库密码，存储在 .env 中，也建议用上文方法生成。
• sentry_dsn：默认 ""，如果你使用 Sentry，这里填写 DSN，稍后也可以在 .env 中更新。

后端开发

后端开发文档参见：backend/README.md。

前端开发

前端开发文档参见：frontend/README.md。

部署

部署相关文档参见：deployment.md。

开发说明

通用开发说明参见：development.md。

其中包括 Docker Compose 使用方式、自定义本地域名、.env 配置等内容。

发布日志

发布记录请查看 release-notes.md。

许可证

Full Stack FastAPI Template 使用 MIT 许可证发布。