中文汉化

2025-12-18 09:40:41 +08:00
parent 6a91475bf6
commit db867dcbe5
41 changed files with 671 additions and 666 deletions
@@ -1,233 +1,233 @@
-# Full Stack FastAPI Template
+# 全栈 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>

-## Technology Stack and Features
+## 技术栈与特性

- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API.
-  - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM).
-  - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management.
-  - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database.
- 🚀 [React](https://react.dev) for the frontend.
-  - 💃 Using TypeScript, hooks, [Vite](https://vitejs.dev), and other parts of a modern frontend stack.
-  - 🎨 [Tailwind CSS](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) for the frontend components.
-  - 🤖 An automatically generated frontend client.
-  - 🧪 [Playwright](https://playwright.dev) for End-to-End testing.
-  - 🦇 Dark mode support.
- 🐋 [Docker Compose](https://www.docker.com) for development and production.
- 🔒 Secure password hashing by default.
- 🔑 JWT (JSON Web Token) authentication.
- 📫 Email based password recovery.
- 📬 [Mailcatcher](https://mailcatcher.me) for local email testing during development.
- ✅ Tests with [Pytest](https://pytest.org).
- 📞 [Traefik](https://traefik.io) as a reverse proxy / load balancer.
- 🚢 Deployment instructions using Docker Compose, including how to set up a frontend Traefik proxy to handle automatic HTTPS certificates.
- 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.
+- ⚡ [**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（持续集成与持续部署）配置。

-### Dashboard Login
+### 仪表盘登录页

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

-### Dashboard - Admin
+### 仪表盘 - 管理后台

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

-### Dashboard - Items
+### 仪表盘 - Items

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

-### Dashboard - Dark Mode
+### 仪表盘 - 暗黑模式

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

-### Interactive API Documentation
+### 交互式 API 文档

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

-## How To Use It
+## 如何使用本模板

-You can **just fork or clone** this repository and use it as is.
+你可以**直接 fork 或 clone** 本仓库，然后在此基础上开发。

-✨ It just works. ✨
+✨ 开箱即用。✨

-### How to Use a Private Repository
+### 在私有仓库中使用

-If you want to have a private repository, GitHub won't allow you to simply fork it as it doesn't allow changing the visibility of forks.
+如果你希望代码在私有仓库中，GitHub 不允许直接将一个公开仓库 fork 成私有仓库（fork 无法更改可见性）。

-But you can do the following:
+你可以按以下步骤操作：

- Create a new GitHub repo, for example `my-full-stack`.
- Clone this repository manually, set the name with the name of the project you want to use, for example `my-full-stack`:
+- 在 GitHub 上创建一个新的仓库，例如 `my-full-stack`。
+- 在本地手动克隆本模板仓库，并将目录名设置为你想要的项目名，例如 `my-full-stack`：

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

- Enter into the new directory:
+- 进入新目录：

 ```bash
 cd my-full-stack
 ```

- Set the new origin to your new repository, copy it from the GitHub interface, for example:
+- 将远程仓库地址改为你自己的仓库（在 GitHub 页面中复制地址），例如：

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

- Add this repo as another "remote" to allow you to get updates later:
+- 将本模板仓库作为另一个远程仓库添加进来，方便后续同步更新：

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

- Push the code to your new repository:
+- 将代码推送到你自己的仓库：

 ```bash
 git push -u origin master
 ```

-### Update From the Original Template
+### 从原始模板同步更新

-After cloning the repository, and after doing changes, you might want to get the latest changes from this original template.
+在你克隆并修改项目之后，可能希望定期从原始模板仓库获取最新改动。

- Make sure you added the original repository as a remote, you can check it with:
+- 确认已经添加了原始模板仓库作为远程仓库，可以通过下面的命令检查：

 ```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)
+upstream  git@github.com:fastapi/full-stack-fastapi-template.git (fetch)
+upstream  git@github.com:fastapi/full-stack-fastapi-template.git (push)
 ```

- Pull the latest changes without merging:
+- 在本地拉取上游模板的最新改动（不自动提交）：

 ```bash
 git pull --no-commit upstream master
 ```

-This will download the latest changes from this template without committing them, that way you can check everything is right before committing.
+这会拉取模板最新改动但不会立刻生成提交，方便你在提交前检查是否一切正常。

- If there are conflicts, solve them in your editor.
+- 如果有冲突，请在编辑器中解决。

- Once you are done, commit the changes:
+- 解决完冲突后，继续合并并提交：

 ```bash
 git merge --continue
 ```

-### Configure
+### 配置

-You can then update configs in the `.env` files to customize your configurations.
+你可以在 `.env` 文件中修改配置来定制你的项目。

-Before deploying it, make sure you change at least the values for:
+在部署之前，至少要修改以下值：

 - `SECRET_KEY`
 - `FIRST_SUPERUSER_PASSWORD`
 - `POSTGRES_PASSWORD`

-You can (and should) pass these as environment variables from secrets.
+推荐将这些值作为环境变量从机密管理系统中注入。

-Read the [deployment.md](./deployment.md) docs for more details.
+更多细节请阅读 [deployment.md](./deployment.md)。

-### Generate Secret Keys
+### 生成密钥

-Some environment variables in the `.env` file have a default value of `changethis`.
+`.env` 中有一些环境变量的默认值为 `changethis`，需要替换为真正的随机密钥。

-You have to change them with a secret key, to generate secret keys you can run the following command:
+可以使用下面的命令生成一个安全随机密钥：

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

-Copy the content and use that as password / secret key. And run that again to generate another secure key.
+复制输出内容，作为密码 / 密钥使用。需要多个密钥时，多运行几次即可。

-## How To Use It - Alternative With Copier
+## 使用 Copier 生成项目（可选方式）

-This repository also supports generating a new project using [Copier](https://copier.readthedocs.io).
+本仓库也支持使用 [Copier](https://copier.readthedocs.io) 来生成新项目。

-It will copy all the files, ask you configuration questions, and update the `.env` files with your answers.
+Copier 会复制所有文件、询问你一系列配置问题，并根据你的回答更新 `.env` 文件。

-### Install Copier
+### 安装 Copier

-You can install Copier with:
+你可以通过以下命令安装 Copier：

 ```bash
 pip install copier
 ```

-Or better, if you have [`pipx`](https://pipx.pypa.io/), you can run it with:
+或（推荐）如果你已经安装了 [`pipx`](https://pipx.pypa.io/)，可以使用：

 ```bash
 pipx install copier
 ```

-**Note**: If you have `pipx`, installing copier is optional, you could run it directly.
+**注意**：如果有 `pipx`，也可以不先安装 Copier，直接运行它。

-### Generate a Project With Copier
+### 使用 Copier 生成项目

-Decide a name for your new project's directory, you will use it below. For example, `my-awesome-project`.
+先决定一个新项目目录名，例如 `my-awesome-project`。

-Go to the directory that will be the parent of your project, and run the command with your project's name:
+进入想要存放项目的父级目录，然后执行：

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

-If you have `pipx` and you didn't install `copier`, you can run it directly:
+如果你安装了 `pipx` 但没有单独安装 `copier`，也可以直接运行：

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

-**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files.
+**注意**：`--trust` 选项用于允许执行一个 [创建后的脚本](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py)，该脚本会自动更新你的 `.env` 文件。

-### Input Variables
+### 输入变量

-Copier will ask you for some data, you might want to have at hand before generating the project.
+Copier 会在生成项目时询问一些配置项，你可以提前准备好这些信息。

-But don't worry, you can just update any of that in the `.env` files afterwards.
+不过不用担心，这些值之后都可以在 `.env` 文件中再次修改。

-The input variables, with their default values (some auto generated) are:
+输入变量及其默认值（有些会自动生成）如下：

- `project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env).
- `stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env).
- `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above.
- `first_superuser`: (default: `"admin@example.com"`) The email of the first superuser (in .env).
- `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env).
- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env.
- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env.
- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env.
- `emails_from_email`: (default: `"info@example.com"`) The email account to send emails from, you can set it later in .env.
- `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above.
- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .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 Development
+## 后端开发

-Backend docs: [backend/README.md](./backend/README.md).
+后端开发文档参见：[`backend/README.md`](./backend/README.md)。

-## Frontend Development
+## 前端开发

-Frontend docs: [frontend/README.md](./frontend/README.md).
+前端开发文档参见：[`frontend/README.md`](./frontend/README.md)。

-## Deployment
+## 部署

-Deployment docs: [deployment.md](./deployment.md).
+部署相关文档参见：[`deployment.md`](./deployment.md)。

-## Development
+## 开发说明

-General development docs: [development.md](./development.md).
+通用开发说明参见：[`development.md`](./development.md)。

-This includes using Docker Compose, custom local domains, `.env` configurations, etc.
+其中包括 Docker Compose 使用方式、自定义本地域名、`.env` 配置等内容。

-## Release Notes
+## 发布日志

-Check the file [release-notes.md](./release-notes.md).
+发布记录请查看 [`release-notes.md`](./release-notes.md)。

-## License
+## 许可证

-The Full Stack FastAPI Template is licensed under the terms of the MIT license.
+Full Stack FastAPI Template 使用 MIT 许可证发布。