Full Stack FastAPI Template

技术栈与功能

• ⚡ FastAPI 用于 Python 后端 API。
  • 🧰 SQLModel 用于 Python SQL 数据库交互（ORM）。
  • 🔍 Pydantic，被 FastAPI 使用，用于数据校验和配置管理。
  • 💾 PostgreSQL 作为 SQL 数据库。
• 🚀 React 用于前端开发。
  • 💃 使用 TypeScript、hooks、Vite 及其他现代前端技术栈。
  • 🎨 Chakra UI 用于前端组件。
  • 🤖 自动生成的前端客户端。
  • 🧪 Playwright 用于端到端测试。
  • 🦇 支持暗黑模式。
• 🐋 Docker Compose 用于开发和生产环境。
• 🔒 默认安全的密码哈希。
• 🔑 JWT（JSON Web Token）认证。
• 📫 基于邮箱的密码找回。
• ✅ 使用 Pytest 进行测试。
• 📞 Traefik 作为反向代理 / 负载均衡器。
• 🚢 使用 Docker Compose 的部署说明，包括如何设置前端 Traefik 代理以自动处理 HTTPS 证书。
• 🏭 基于 GitHub Actions 的 CI（持续集成）和 CD（持续部署）。

Dashboard Login

Dashboard - Admin

Dashboard - Create User

Dashboard - Items

Dashboard - User Settings

Dashboard - Dark Mode

Interactive API Documentation

如何使用

你可以直接 Fork 或克隆本仓库并直接使用。

✨ 开箱即用。✨

如何使用私有仓库

如果你想拥有一个私有仓库，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

• 添加本仓库为另一个 "remote"，方便后续获取更新：

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

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

git push -u origin master

从原模板更新

克隆仓库并做了修改后，你可能希望获取原模板的最新更改。

• 确认已添加原仓库为 remote，可以用以下命令检查：

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

你可以（并且应该）通过 secrets 作为环境变量传递这些值。

有关更多详细信息，请参阅 deployment.md 文档。

生成密钥

.env 文件中的某些环境变量默认值为 changethis。

你必须将它们更改为密钥，要生成密钥，你可以运行以下命令：

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

复制内容并将其用作密码/密钥。然后再次运行以生成另一个安全密钥。

如何使用 - 使用 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 选项是必需的，以便能够执行 post-creation script 来更新你的 .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 服务器用户，您可以稍后在 .env 中设置。
• smtp_password：（默认值：""）发送电子邮件的 SMTP 服务器密码，您可以稍后在 .env 中设置。
• emails_from_email：（默认值："info@example.com"）用于发送电子邮件的电子邮件帐户，您可以稍后在 .env 中设置。
• postgres_password：（默认值："changethis"）PostgreSQL 数据库的密码，存储在 .env 中，您可以使用上述方法生成。
• sentry_dsn：（默认值：""）如果您正在使用 Sentry，则为 Sentry 的 DSN，您可以稍后在 .env 中设置。

后端开发

后端文档：backend/README.md。

前端开发

前端文档：frontend/README.md。

部署

部署文档：deployment.md。

开发

通用开发文档：development.md。

包括如何使用 Docker Compose、自定义本地域名、.env 配置等。

更新日志

请查阅文件 release-notes.md。

许可证

Full Stack FastAPI Template 采用 MIT 许可证授权