# 全栈 FastAPI 模板（Full Stack FastAPI Template）
## 技术栈与特性
- ⚡ [**FastAPI**](https://fastapi.tiangolo.com)：Python 后端 API 框架。
- 🧰 [SQLModel](https://sqlmodel.tiangolo.com)：用于 Python 与 SQL 数据库交互的 ORM。
- 🔍 [Pydantic](https://docs.pydantic.dev)：被 FastAPI 使用，用于数据校验与配置管理。
- 💾 [PostgreSQL](https://www.postgresql.org)：关系型数据库。
- 🚀 [React](https://react.dev)：前端框架。
- 💃 使用 TypeScript、Hooks、[Vite](https://vitejs.dev) 等现代前端技术栈。
- 🎨 [Tailwind CSS](https://tailwindcss.com) 与 [shadcn/ui](https://ui.shadcn.com) 作为前端组件系统。
- 🤖 自动生成的前端 API 客户端。
- 🧪 使用 [Playwright](https://playwright.dev) 做端到端测试。
- 🦇 支持暗黑模式。
- 🐋 使用 [Docker Compose](https://www.docker.com) 进行开发与生产部署。
- 🔒 默认安全的密码哈希。
- 🔑 JWT（JSON Web Token）认证。
- 📫 基于邮箱的密码找回功能。
- 📬 使用 [Mailcatcher](https://mailcatcher.me) 做本地邮件测试。
- ✅ 使用 [Pytest](https://pytest.org) 编写与运行测试。
- 📞 使用 [Traefik](https://traefik.io) 作为反向代理 / 负载均衡器。
- 🚢 提供基于 Docker Compose 的部署说明，包括如何配置 Traefik 代理与自动 HTTPS 证书。
- 🏭 提供基于 GitHub Actions 的 CI/CD（持续集成与持续部署）配置。
### 仪表盘登录页
[](https://github.com/fastapi/full-stack-fastapi-template)
### 仪表盘 - 管理后台
[](https://github.com/fastapi/full-stack-fastapi-template)
### 仪表盘 - Items
[](https://github.com/fastapi/full-stack-fastapi-template)
### 仪表盘 - 暗黑模式
[](https://github.com/fastapi/full-stack-fastapi-template)
### 交互式 API 文档
[](https://github.com/fastapi/full-stack-fastapi-template)
## 如何使用本模板
你可以**直接 fork 或 clone** 本仓库，然后在此基础上开发。
✨ 开箱即用。✨
### 在私有仓库中使用
如果你希望代码在私有仓库中，GitHub 不允许直接将一个公开仓库 fork 成私有仓库（fork 无法更改可见性）。
你可以按以下步骤操作：
- 在 GitHub 上创建一个新的仓库，例如 `my-full-stack`。
- 在本地手动克隆本模板仓库，并将目录名设置为你想要的项目名，例如 `my-full-stack`：
```bash
git clone git@github.com:fastapi/full-stack-fastapi-template.git my-full-stack
```
- 进入新目录：
```bash
cd my-full-stack
```
- 将远程仓库地址改为你自己的仓库（在 GitHub 页面中复制地址），例如：
```bash
git remote set-url origin git@github.com:octocat/my-full-stack.git
```
- 将本模板仓库作为另一个远程仓库添加进来，方便后续同步更新：
```bash
git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git
```
- 将代码推送到你自己的仓库：
```bash
git push -u origin master
```
### 从原始模板同步更新
在你克隆并修改项目之后，可能希望定期从原始模板仓库获取最新改动。
- 确认已经添加了原始模板仓库作为远程仓库，可以通过下面的命令检查：
```bash
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)
```
- 在本地拉取上游模板的最新改动（不自动提交）：
```bash
git pull --no-commit upstream master
```
这会拉取模板最新改动但不会立刻生成提交，方便你在提交前检查是否一切正常。
- 如果有冲突，请在编辑器中解决。
- 解决完冲突后，继续合并并提交：
```bash
git merge --continue
```
### 配置
你可以在 `.env` 文件中修改配置来定制你的项目。
在部署之前，至少要修改以下值：
- `SECRET_KEY`
- `FIRST_SUPERUSER_PASSWORD`
- `POSTGRES_PASSWORD`
推荐将这些值作为环境变量从机密管理系统中注入。
更多细节请阅读 [deployment.md](./deployment.md)。
### 生成密钥
`.env` 中有一些环境变量的默认值为 `changethis`，需要替换为真正的随机密钥。
可以使用下面的命令生成一个安全随机密钥：
```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
复制输出内容，作为密码 / 密钥使用。需要多个密钥时，多运行几次即可。
## 使用 Copier 生成项目（可选方式）
本仓库也支持使用 [Copier](https://copier.readthedocs.io) 来生成新项目。
Copier 会复制所有文件、询问你一系列配置问题，并根据你的回答更新 `.env` 文件。
### 安装 Copier
你可以通过以下命令安装 Copier：
```bash
pip install copier
```
或（推荐）如果你已经安装了 [`pipx`](https://pipx.pypa.io/)，可以使用：
```bash
pipx install copier
```
**注意**：如果有 `pipx`，也可以不先安装 Copier，直接运行它。
### 使用 Copier 生成项目
先决定一个新项目目录名，例如 `my-awesome-project`。
进入想要存放项目的父级目录，然后执行：
```bash
copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
```
如果你安装了 `pipx` 但没有单独安装 `copier`，也可以直接运行：
```bash
pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
```
**注意**：`--trust` 选项用于允许执行一个 [创建后的脚本](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py)，该脚本会自动更新你的 `.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`](./backend/README.md)。
## 前端开发
前端开发文档参见：[`frontend/README.md`](./frontend/README.md)。
## 部署
部署相关文档参见：[`deployment.md`](./deployment.md)。
## 开发说明
通用开发说明参见：[`development.md`](./development.md)。
其中包括 Docker Compose 使用方式、自定义本地域名、`.env` 配置等内容。
## 发布日志
发布记录请查看 [`release-notes.md`](./release-notes.md)。
## 许可证
Full Stack FastAPI Template 使用 MIT 许可证发布。