fast_api_template/README.md

# 全栈 FastAPI 模板（Full Stack FastAPI Template）

<a href="https://github.com/fastapi/full-stack-fastapi-template/actions?query=workflow%3A%22Test+Docker+Compose%22" target="_blank"><img src="https://github.com/fastapi/full-stack-fastapi-template/workflows/Test%20Docker%20Compose/badge.svg" alt="Test Docker Compose"></a>
<a href="https://github.com/fastapi/full-stack-fastapi-template/actions?query=workflow%3A%22Test+Backend%22" target="_blank"><img src="https://github.com/fastapi/full-stack-fastapi-template/workflows/Test%20Backend/badge.svg" alt="Test Backend"></a>
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/fastapi/full-stack-fastapi-template" target="_blank"><img src="https://coverage-badge.samuelcolvin.workers.dev/fastapi/full-stack-fastapi-template.svg" alt="Coverage"></a>

## 技术栈与特性

- ⚡ [**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（持续集成与持续部署）配置。

### 仪表盘登录页

[![API docs](img/login.png)](https://github.com/fastapi/full-stack-fastapi-template)

### 仪表盘 - 管理后台

[![API docs](img/dashboard.png)](https://github.com/fastapi/full-stack-fastapi-template)

### 仪表盘 - Items

[![API docs](img/dashboard-items.png)](https://github.com/fastapi/full-stack-fastapi-template)

### 仪表盘 - 暗黑模式

[![API docs](img/dashboard-dark.png)](https://github.com/fastapi/full-stack-fastapi-template)

### 交互式 API 文档

[![API docs](img/docs.png)](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 许可证发布。