-## 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
+### 仪表盘登录页
[](https://github.com/fastapi/full-stack-fastapi-template)
-### Dashboard - Admin
+### 仪表盘 - 管理后台
[](https://github.com/fastapi/full-stack-fastapi-template)
-### Dashboard - Items
+### 仪表盘 - Items
[](https://github.com/fastapi/full-stack-fastapi-template)
-### Dashboard - Dark Mode
+### 仪表盘 - 暗黑模式
[](https://github.com/fastapi/full-stack-fastapi-template)
-### Interactive API Documentation
+### 交互式 API 文档
[](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 许可证发布。
diff --git a/SECURITY.md b/SECURITY.md
index 0045fb8..6fb3e54 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,29 +1,29 @@
-# Security Policy
+# 安全政策（Security Policy）
-Security is very important for this project and its community. 🔒
+安全对于本项目及其社区非常重要。🔒
-Learn more about it below. 👇
+请阅读以下内容了解更多信息。👇
-## Versions
+## 支持的版本
-The latest version or release is supported.
+我们仅支持最新版本或最新发布版。
-You are encouraged to write tests for your application and update your versions frequently after ensuring that your tests are passing. This way you will benefit from the latest features, bug fixes, and **security fixes**.
+建议您为应用程序编写测试，并在确认测试通过后及时更新版本。这样可以享受最新的功能、Bug 修复和**安全修复**。
-## Reporting a Vulnerability
+## 报告漏洞
-If you think you found a vulnerability, and even if you are not sure about it, please report it right away by sending an email to: security@tiangolo.com. Please try to be as explicit as possible, describing all the steps and example code to reproduce the security issue.
+如果您发现了漏洞（或者不确定是否为漏洞），请立即发送邮件至 security@tiangolo.com 进行报告。请尽可能详细地描述所有步骤和示例代码，以便重现该安全问题。
-I (the author, [@tiangolo](https://twitter.com/tiangolo)) will review it thoroughly and get back to you.
+我（作者，[@tiangolo](https://twitter.com/tiangolo)）会仔细审核并尽快回复您。
-## Public Discussions
+## 公开讨论
-Please restrain from publicly discussing a potential security vulnerability. 🙊
+请避免公开讨论潜在的安全漏洞。🙊
-It's better to discuss privately and try to find a solution first, to limit the potential impact as much as possible.
+最好先私下讨论并尝试找到解决方案，以尽可能减少潜在的影响。
---
-Thanks for your help!
+感谢您的帮助！
-The community and I thank you for that. 🙇
+社区和我对此表示衷心感谢。🙇
diff --git a/backend/Dockerfile b/backend/Dockerfile
index fc672e5..700f415 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -4,24 +4,24 @@ ENV PYTHONUNBUFFERED=1
WORKDIR /app/
-# Install uv
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#installing-uv
+# 安装 uv
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#installing-uv
COPY --from=ghcr.io/astral-sh/uv:0.5.11 /uv /uvx /bin/
-# Place executables in the environment at the front of the path
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment
+# 将可执行文件放在环境路径的最前面
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment
ENV PATH="/app/.venv/bin:$PATH"
-# Compile bytecode
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#compiling-bytecode
+# 编译字节码
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#compiling-bytecode
ENV UV_COMPILE_BYTECODE=1
-# uv Cache
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#caching
+# uv 缓存
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#caching
ENV UV_LINK_MODE=copy
-# Install dependencies
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
+# 安装依赖
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
@@ -36,8 +36,8 @@ COPY ./pyproject.toml ./uv.lock ./alembic.ini /app/
COPY ./app /app/app
COPY ./tests /app/tests
-# Sync the project
-# Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
+# 同步项目
+# 参考: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync
diff --git a/backend/README.md b/backend/README.md
index c217000..43ba201 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,172 +1,182 @@
-# FastAPI Project - Backend
+# FastAPI 项目 - 后端（Backend）
-## Requirements
+## 前置要求
-* [Docker](https://www.docker.com/).
-* [uv](https://docs.astral.sh/uv/) for Python package and environment management.
+* 已安装 [Docker](https://www.docker.com/)。
+* 已安装 [uv](https://docs.astral.sh/uv/)，用于管理 Python 包与虚拟环境。
-## Docker Compose
+## 使用 Docker Compose
-Start the local development environment with Docker Compose following the guide in [../development.md](../development.md).
+按照 [../development.md](../development.md) 中的说明，使用 Docker Compose 启动本地开发环境。
-## General Workflow
+## 一般工作流
-By default, the dependencies are managed with [uv](https://docs.astral.sh/uv/), go there and install it.
+本项目默认使用 [uv](https://docs.astral.sh/uv/) 管理依赖，请先安装它。
-From `./backend/` you can install all the dependencies with:
+在 `./backend/` 目录下安装所有依赖：
```console
$ uv sync
```
-Then you can activate the virtual environment with:
+然后激活虚拟环境：
```console
$ source .venv/bin/activate
```
-Make sure your editor is using the correct Python virtual environment, with the interpreter at `backend/.venv/bin/python`.
+请确保你的编辑器使用的是该虚拟环境中的 Python 解释器：`backend/.venv/bin/python`。
-Modify or add SQLModel models for data and SQL tables in `./backend/app/models.py`, API endpoints in `./backend/app/api/`, CRUD (Create, Read, Update, Delete) utils in `./backend/app/crud.py`.
+你可以在 `./backend/app/models.py` 中修改或新增 SQLModel 模型（数据表结构），在 `./backend/app/api/` 中添加 API 路由，在 `./backend/app/crud.py` 中添加 / 修改 CRUD（创建、读取、更新、删除）工具函数。
## VS Code
-There are already configurations in place to run the backend through the VS Code debugger, so that you can use breakpoints, pause and explore variables, etc.
+项目中已经包含了 VS Code 的调试配置，你可以直接使用断点、单步调试、查看变量等功能来运行后端。
-The setup is also already configured so you can run the tests through the VS Code Python tests tab.
+测试相关配置也已就绪，可以通过 VS Code 的 Python 测试面板直接运行测试。
-## Docker Compose Override
+## Docker Compose 覆盖配置
-During development, you can change Docker Compose settings that will only affect the local development environment in the file `docker-compose.override.yml`.
+开发阶段，你可以在 `docker-compose.override.yml` 中修改仅作用于本地开发环境的 Docker Compose 配置。
-The changes to that file only affect the local development environment, not the production environment. So, you can add "temporary" changes that help the development workflow.
+这些改动只影响本地开发环境，不会影响生产环境。因此你可以在这里加入一些“临时”设置来提升本地开发效率。
-For example, the directory with the backend code is synchronized in the Docker container, copying the code you change live to the directory inside the container. That allows you to test your changes right away, without having to build the Docker image again. It should only be done during development, for production, you should build the Docker image with a recent version of the backend code. But during development, it allows you to iterate very fast.
+例如：后端代码目录会以 volume 形式挂载进容器，你在本机修改代码后会实时同步到容器中，无需重新构建镜像即可看到效果。生产环境则应该基于最新代码重新构建镜像，而不是使用挂载的源码。
-There is also a command override that runs `fastapi run --reload` instead of the default `fastapi run`. It starts a single server process (instead of multiple, as would be for production) and reloads the process whenever the code changes. Have in mind that if you have a syntax error and save the Python file, it will break and exit, and the container will stop. After that, you can restart the container by fixing the error and running again:
+配置中还包含一个覆盖命令，将默认的 `fastapi run` 改为 `fastapi run --reload`。它只启动一个进程（适合开发环境），并在检测到代码变更时自动重载。注意，如果保存了含语法错误的 Python 文件，进程会直接退出、容器也会停止。修复错误后，可以再次运行：
```console
$ docker compose watch
```
-There is also a commented out `command` override, you can uncomment it and comment the default one. It makes the backend container run a process that does "nothing", but keeps the container alive. That allows you to get inside your running container and execute commands inside, for example a Python interpreter to test installed dependencies, or start the development server that reloads when it detects changes.
+文件中还提供了一个被注释掉的 `command` 覆盖项，你可以取消注释它并注释掉默认命令。该命令会让后端容器运行一个“空转”的进程，只是保持容器存活，方便你进入容器内部执行命令，例如打开 Python 交互解释器测试依赖，或手动启动支持热重载的开发服务器。
-To get inside the container with a `bash` session you can start the stack with:
+如果你想通过 `bash` 进入容器，可以先启动整个 stack：
```console
$ docker compose watch
```
-and then in another terminal, `exec` inside the running container:
+然后在另一个终端中执行：
```console
$ docker compose exec backend bash
```
-You should see an output like:
+你会看到类似输出：
```console
root@7f2607af31c3:/app#
```
-that means that you are in a `bash` session inside your container, as a `root` user, under the `/app` directory, this directory has another directory called "app" inside, that's where your code lives inside the container: `/app/app`.
+这说明你已经以 `root` 用户进入了容器中的 `/app` 目录，该目录下还有一个 `app` 子目录，即你的后端代码在容器中的位置：`/app/app`。
-There you can use the `fastapi run --reload` command to run the debug live reloading server.
+在这里可以运行支持热重载的开发服务器：
```console
$ fastapi run --reload app/main.py
```
-...it will look like:
+终端看起来会类似：
```console
root@7f2607af31c3:/app# fastapi run --reload app/main.py
```
-and then hit enter. That runs the live reloading server that auto reloads when it detects code changes.
+然后按回车即可启动，它会在检测到代码变化时自动重载。
-Nevertheless, if it doesn't detect a change but a syntax error, it will just stop with an error. But as the container is still alive and you are in a Bash session, you can quickly restart it after fixing the error, running the same command ("up arrow" and "Enter").
+如果碰到的不是代码变更而是语法错误，进程会直接退出。不过因为容器还在且你仍在 Bash 会话中，修复错误后按方向键上翻历史命令并回车即可快速重启。
-...this previous detail is what makes it useful to have the container alive doing nothing and then, in a Bash session, make it run the live reload server.
+正是因为这一点，让“容器空转 + Bash 中手动启动热重载服务”的方式在开发中非常实用。
-## Backend tests
+## 后端测试
-To test the backend run:
+运行后端测试：
```console
$ bash ./scripts/test.sh
```
-The tests run with Pytest, modify and add tests to `./backend/tests/`.
+测试使用 Pytest，测试文件位于 `./backend/tests/`，你可以在其中新增或修改测试。
-If you use GitHub Actions the tests will run automatically.
+如果你使用 GitHub Actions，推送代码后测试会自动运行。
-### Test running stack
+### 在已运行的 stack 中执行测试
-If your stack is already up and you just want to run the tests, you can use:
+如果 Docker Compose 已经启动，只想在当前 stack 中运行测试，可以使用：
```bash
docker compose exec backend bash scripts/tests-start.sh
```
-That `/app/scripts/tests-start.sh` script just calls `pytest` after making sure that the rest of the stack is running. If you need to pass extra arguments to `pytest`, you can pass them to that command and they will be forwarded.
+`/app/scripts/tests-start.sh` 脚本会在确认依赖服务已就绪后调用 `pytest`。如果需要给 `pytest` 传额外参数，可以直接附加在命令后面，它们会被转发给 `pytest`。
-For example, to stop on first error:
+例如，遇到第一个错误就停止：
```bash
docker compose exec backend bash scripts/tests-start.sh -x
```
-### Test Coverage
+### 测试覆盖率
-When the tests are run, a file `htmlcov/index.html` is generated, you can open it in your browser to see the coverage of the tests.
+测试运行后会生成 `htmlcov/index.html` 文件，可在浏览器中打开查看覆盖率报告。
-## Migrations
+## 数据库迁移（Migrations）
-As during local development your app directory is mounted as a volume inside the container, you can also run the migrations with `alembic` commands inside the container and the migration code will be in your app directory (instead of being only inside the container). So you can add it to your git repository.
+本地开发时，应用代码目录以 volume 形式挂载到容器中，因此可以在容器内使用 `alembic` 命令生成迁移文件，这些文件会直接写入你的项目目录，方便你提交到 git 仓库。
-Make sure you create a "revision" of your models and that you "upgrade" your database with that revision every time you change them. As this is what will update the tables in your database. Otherwise, your application will have errors.
+每次修改模型后，请确保：
-* Start an interactive session in the backend container:
+1. 创建新的迁移“revision”，描述本次模型变更；
+2. 使用该 revision 升级数据库。
+
+否则数据库表结构不会更新，应用就会报错。
+
+基本流程如下：
+
+* 在后端容器中启动交互会话：
```console
$ docker compose exec backend bash
```
-* Alembic is already configured to import your SQLModel models from `./backend/app/models.py`.
+* `alembic` 已配置好从 `./backend/app/models.py` 导入 SQLModel 模型。
-* After changing a model (for example, adding a column), inside the container, create a revision, e.g.:
+* 修改模型（例如新增字段）后，在容器内创建迁移 revision，例如：
```console
$ alembic revision --autogenerate -m "Add column last_name to User model"
```
-* Commit to the git repository the files generated in the alembic directory.
+* 将 Alembic 目录中生成的 Python 迁移文件提交到 git。
-* After creating the revision, run the migration in the database (this is what will actually change the database):
+* 创建完 revision 后，在数据库中执行迁移（真正修改数据库结构）：
```console
$ alembic upgrade head
```
-If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in:
+如果你完全不想使用迁移，可以在 `./backend/app/core/db.py` 中取消注释以 `SQLModel.metadata.create_all(engine)` 结尾的代码：
```python
SQLModel.metadata.create_all(engine)
```
-and comment the line in the file `scripts/prestart.sh` that contains:
+同时在 `scripts/prestart.sh` 中注释掉包含以下内容的那一行：
```console
$ alembic upgrade head
```
-If you don't want to start with the default models and want to remove them / modify them, from the beginning, without having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`. And then create a first migration as described above.
+如果你不想从默认模型开始，而是从零开始定义自己的模型，并且不希望有任何已有迁移，可以删除 `./backend/app/alembic/versions/` 下的所有迁移文件（`.py`），然后按上述步骤创建第一条迁移。
-## Email Templates
+## 邮件模板
-The email templates are in `./backend/app/email-templates/`. Here, there are two directories: `build` and `src`. The `src` directory contains the source files that are used to build the final email templates. The `build` directory contains the final email templates that are used by the application.
+邮件模板位于 `./backend/app/email-templates/` 目录，其中：
-Before continuing, ensure you have the [MJML extension](https://marketplace.visualstudio.com/items?itemName=attilabuti.vscode-mjml) installed in your VS Code.
+- `src`：存放源模板（`.mjml` 文件等），用于生成最终 HTML 模板；
+- `build`：存放构建后的 HTML 邮件模板，实际由应用使用。
-Once you have the MJML extension installed, you can create a new email template in the `src` directory. After creating the new email template and with the `.mjml` file open in your editor, open the command palette with `Ctrl+Shift+P` and search for `MJML: Export to HTML`. This will convert the `.mjml` file to a `.html` file and now you can save it in the build directory.
+继续之前，请先在 VS Code 中安装 [MJML 扩展](https://marketplace.visualstudio.com/items?itemName=attilabuti.vscode-mjml)。
+
+安装完成后，你可以在 `src` 目录中创建新的邮件模板。创建好 `.mjml` 文件并在编辑器中打开后，按 `Ctrl+Shift+P` 打开命令面板，搜索 `MJML: Export to HTML`。该命令会将 `.mjml` 文件转换为 `.html` 文件，然后你可以将其保存到 `build` 目录中供应用使用。
diff --git a/backend/alembic.ini b/backend/alembic.ini
index 24841c2..af976ca 100755
--- a/backend/alembic.ini
+++ b/backend/alembic.ini
@@ -1,41 +1,36 @@
-# A generic, single database configuration.
+# 通用单数据库配置
[alembic]
-# path to migration scripts
+# 迁移脚本路径
script_location = app/alembic
-# template used to generate migration files
+# 用于生成迁移文件的模板
# file_template = %%(rev)s_%%(slug)s
-# timezone to use when rendering the date
-# within the migration file as well as the filename.
-# string value is passed to dateutil.tz.gettz()
-# leave blank for localtime
+# 在迁移文件和文件名中渲染日期时使用的时区
+# 字符串值传递给 dateutil.tz.gettz()
+# 留空则使用本地时间
# timezone =
-# max length of characters to apply to the
-# "slug" field
+# 应用于 "slug" 字段的最大字符长度
#truncate_slug_length = 40
-# set to 'true' to run the environment during
-# the 'revision' command, regardless of autogenerate
+# 设置为 'true' 以在 'revision' 命令期间运行环境，
+# 无论是否自动生成
# revision_environment = false
-# set to 'true' to allow .pyc and .pyo files without
-# a source .py file to be detected as revisions in the
-# versions/ directory
+# 设置为 'true' 以允许在没有源 .py 文件的情况下
+# 将 .pyc 和 .pyo 文件检测为 versions/ 目录中的修订版本
# sourceless = false
-# version location specification; this defaults
-# to alembic/versions. When using multiple version
-# directories, initial revisions must be specified with --version-path
+# 版本位置规范；默认为 alembic/versions
+# 使用多个版本目录时，必须使用 --version-path 指定初始修订版本
# version_locations = %(here)s/bar %(here)s/bat alembic/versions
-# the output encoding used when revision files
-# are written from script.py.mako
+# 从 script.py.mako 写入修订文件时使用的输出编码
# output_encoding = utf-8
-# Logging configuration
+# 日志配置
[loggers]
keys = root,sqlalchemy,alembic
diff --git a/backend/app/alembic/env.py b/backend/app/alembic/env.py
index 7f29c04..f9fd7ad 100755
--- a/backend/app/alembic/env.py
+++ b/backend/app/alembic/env.py
@@ -4,16 +4,15 @@ from logging.config import fileConfig
from alembic import context
from sqlalchemy import engine_from_config, pool
-# this is the Alembic Config object, which provides
-# access to the values within the .ini file in use.
+# 这是 Alembic 配置对象，提供对正在使用的 .ini 文件中值的访问。
config = context.config
-# Interpret the config file for Python logging.
-# This line sets up loggers basically.
+# 解析配置文件以进行 Python 日志记录。
+# 这行代码用于设置日志记录器。
fileConfig(config.config_file_name)
-# add your model's MetaData object here
-# for 'autogenerate' support
+# 在此处添加模型的 MetaData 对象
+# 以支持 'autogenerate'
# from myapp import mymodel
# target_metadata = mymodel.Base.metadata
# target_metadata = None
@@ -23,10 +22,9 @@ from app.core.config import settings # noqa
target_metadata = SQLModel.metadata
-# other values from the config, defined by the needs of env.py,
-# can be acquired:
+# 根据 env.py 的需要，可以从配置中获取其他值：
# my_important_option = config.get_main_option("my_important_option")
-# ... etc.
+# ... 等等。
def get_url():
@@ -34,15 +32,13 @@ def get_url():
def run_migrations_offline():
- """Run migrations in 'offline' mode.
+ """在"离线"模式下运行迁移。
- This configures the context with just a URL
- and not an Engine, though an Engine is acceptable
- here as well. By skipping the Engine creation
- we don't even need a DBAPI to be available.
+ 这使用 URL 而不是 Engine 来配置上下文，
+ 尽管 Engine 在这里也是可以接受的。
+ 通过跳过 Engine 的创建，我们甚至不需要 DBAPI 可用。
- Calls to context.execute() here emit the given string to the
- script output.
+ 在这里调用 context.execute() 会将给定的字符串输出到脚本输出。
"""
url = get_url()
@@ -55,10 +51,10 @@ def run_migrations_offline():
def run_migrations_online():
- """Run migrations in 'online' mode.
+ """在"在线"模式下运行迁移。
- In this scenario we need to create an Engine
- and associate a connection with the context.
+ 在这种情况下，我们需要创建一个 Engine
+ 并将连接与上下文关联。
"""
configuration = config.get_section(config.config_ini_section)
diff --git a/backend/app/api/deps.py b/backend/app/api/deps.py
index c2b83c8..ad3df68 100644
--- a/backend/app/api/deps.py
+++ b/backend/app/api/deps.py
@@ -36,13 +36,13 @@ def get_current_user(session: SessionDep, token: TokenDep) -> User:
except (InvalidTokenError, ValidationError):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
- detail="Could not validate credentials",
+ detail="无法验证凭据",
)
user = session.get(User, token_data.sub)
if not user:
- raise HTTPException(status_code=404, detail="User not found")
+ raise HTTPException(status_code=404, detail="用户未找到")
if not user.is_active:
- raise HTTPException(status_code=400, detail="Inactive user")
+ raise HTTPException(status_code=400, detail="用户未激活")
return user
@@ -52,6 +52,6 @@ CurrentUser = Annotated[User, Depends(get_current_user)]
def get_current_active_superuser(current_user: CurrentUser) -> User:
if not current_user.is_superuser:
raise HTTPException(
- status_code=403, detail="The user doesn't have enough privileges"
+ status_code=403, detail="用户权限不足"
)
return current_user
diff --git a/backend/app/api/routes/items.py b/backend/app/api/routes/items.py
index 177dc1e..ee0e54b 100644
--- a/backend/app/api/routes/items.py
+++ b/backend/app/api/routes/items.py
@@ -15,7 +15,7 @@ def read_items(
session: SessionDep, current_user: CurrentUser, skip: int = 0, limit: int = 100
) -> Any:
"""
- Retrieve items.
+ 获取 Item 列表。
"""
if current_user.is_superuser:
@@ -44,13 +44,13 @@ def read_items(
@router.get("/{id}", response_model=ItemPublic)
def read_item(session: SessionDep, current_user: CurrentUser, id: uuid.UUID) -> Any:
"""
- Get item by ID.
+ 通过 ID 获取 Item。
"""
item = session.get(Item, id)
if not item:
- raise HTTPException(status_code=404, detail="Item not found")
+ raise HTTPException(status_code=404, detail="项目未找到")
if not current_user.is_superuser and (item.owner_id != current_user.id):
- raise HTTPException(status_code=400, detail="Not enough permissions")
+ raise HTTPException(status_code=400, detail="权限不足")
return item
@@ -59,7 +59,7 @@ def create_item(
*, session: SessionDep, current_user: CurrentUser, item_in: ItemCreate
) -> Any:
"""
- Create new item.
+ 创建新的 Item。
"""
item = Item.model_validate(item_in, update={"owner_id": current_user.id})
session.add(item)
@@ -77,13 +77,13 @@ def update_item(
item_in: ItemUpdate,
) -> Any:
"""
- Update an item.
+ 更新 Item。
"""
item = session.get(Item, id)
if not item:
- raise HTTPException(status_code=404, detail="Item not found")
+ raise HTTPException(status_code=404, detail="项目未找到")
if not current_user.is_superuser and (item.owner_id != current_user.id):
- raise HTTPException(status_code=400, detail="Not enough permissions")
+ raise HTTPException(status_code=400, detail="权限不足")
update_dict = item_in.model_dump(exclude_unset=True)
item.sqlmodel_update(update_dict)
session.add(item)
@@ -97,13 +97,13 @@ def delete_item(
session: SessionDep, current_user: CurrentUser, id: uuid.UUID
) -> Message:
"""
- Delete an item.
+ 删除 Item。
"""
item = session.get(Item, id)
if not item:
- raise HTTPException(status_code=404, detail="Item not found")
+ raise HTTPException(status_code=404, detail="项目未找到")
if not current_user.is_superuser and (item.owner_id != current_user.id):
- raise HTTPException(status_code=400, detail="Not enough permissions")
+ raise HTTPException(status_code=400, detail="权限不足")
session.delete(item)
session.commit()
- return Message(message="Item deleted successfully")
+ return Message(message="项目删除成功")
diff --git a/backend/app/api/routes/login.py b/backend/app/api/routes/login.py
index 980c66f..6a6515e 100644
--- a/backend/app/api/routes/login.py
+++ b/backend/app/api/routes/login.py
@@ -26,15 +26,15 @@ def login_access_token(
session: SessionDep, form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
) -> Token:
"""
- OAuth2 compatible token login, get an access token for future requests
+ OAuth2 兼容的令牌登录，获取用于后续请求的访问令牌
"""
user = crud.authenticate(
session=session, email=form_data.username, password=form_data.password
)
if not user:
- raise HTTPException(status_code=400, detail="Incorrect email or password")
+ raise HTTPException(status_code=400, detail="邮箱或密码错误")
elif not user.is_active:
- raise HTTPException(status_code=400, detail="Inactive user")
+ raise HTTPException(status_code=400, detail="用户未激活")
access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
return Token(
access_token=security.create_access_token(
@@ -46,7 +46,7 @@ def login_access_token(
@router.post("/login/test-token", response_model=UserPublic)
def test_token(current_user: CurrentUser) -> Any:
"""
- Test access token
+ 测试访问令牌
"""
return current_user
@@ -54,14 +54,14 @@ def test_token(current_user: CurrentUser) -> Any:
@router.post("/password-recovery/{email}")
def recover_password(email: str, session: SessionDep) -> Message:
"""
- Password Recovery
+ 密码找回
"""
user = crud.get_user_by_email(session=session, email=email)
if not user:
raise HTTPException(
status_code=404,
- detail="The user with this email does not exist in the system.",
+ detail="系统中不存在该邮箱的用户。",
)
password_reset_token = generate_password_reset_token(email=email)
email_data = generate_reset_password_email(
@@ -72,30 +72,30 @@ def recover_password(email: str, session: SessionDep) -> Message:
subject=email_data.subject,
html_content=email_data.html_content,
)
- return Message(message="Password recovery email sent")
+ return Message(message="密码找回邮件已发送")
@router.post("/reset-password/")
def reset_password(session: SessionDep, body: NewPassword) -> Message:
"""
- Reset password
+ 重置密码
"""
email = verify_password_reset_token(token=body.token)
if not email:
- raise HTTPException(status_code=400, detail="Invalid token")
+ raise HTTPException(status_code=400, detail="无效的令牌")
user = crud.get_user_by_email(session=session, email=email)
if not user:
raise HTTPException(
status_code=404,
- detail="The user with this email does not exist in the system.",
+ detail="系统中不存在该邮箱的用户。",
)
elif not user.is_active:
- raise HTTPException(status_code=400, detail="Inactive user")
+ raise HTTPException(status_code=400, detail="用户未激活")
hashed_password = get_password_hash(password=body.new_password)
user.hashed_password = hashed_password
session.add(user)
session.commit()
- return Message(message="Password updated successfully")
+ return Message(message="密码更新成功")
@router.post(
@@ -105,14 +105,14 @@ def reset_password(session: SessionDep, body: NewPassword) -> Message:
)
def recover_password_html_content(email: str, session: SessionDep) -> Any:
"""
- HTML Content for Password Recovery
+ 获取密码找回邮件的 HTML 内容
"""
user = crud.get_user_by_email(session=session, email=email)
if not user:
raise HTTPException(
status_code=404,
- detail="The user with this username does not exist in the system.",
+ detail="系统中不存在该用户名的用户。",
)
password_reset_token = generate_password_reset_token(email=email)
email_data = generate_reset_password_email(
diff --git a/backend/app/api/routes/private.py b/backend/app/api/routes/private.py
index 9f33ef1..5a0d3ac 100644
--- a/backend/app/api/routes/private.py
+++ b/backend/app/api/routes/private.py
@@ -23,7 +23,7 @@ class PrivateUserCreate(BaseModel):
@router.post("/users/", response_model=UserPublic)
def create_user(user_in: PrivateUserCreate, session: SessionDep) -> Any:
"""
- Create a new user.
+ 创建新用户。
"""
user = User(
diff --git a/backend/app/api/routes/users.py b/backend/app/api/routes/users.py
index 6429818..206d558 100644
--- a/backend/app/api/routes/users.py
+++ b/backend/app/api/routes/users.py
@@ -36,7 +36,7 @@ router = APIRouter(prefix="/users", tags=["users"])
)
def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
"""
- Retrieve users.
+ 获取用户列表。
"""
count_statement = select(func.count()).select_from(User)
@@ -53,13 +53,13 @@ def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
)
def create_user(*, session: SessionDep, user_in: UserCreate) -> Any:
"""
- Create new user.
+ 创建新用户。
"""
user = crud.get_user_by_email(session=session, email=user_in.email)
if user:
raise HTTPException(
status_code=400,
- detail="The user with this email already exists in the system.",
+ detail="系统中已存在该邮箱的用户。",
)
user = crud.create_user(session=session, user_create=user_in)
@@ -80,14 +80,14 @@ def update_user_me(
*, session: SessionDep, user_in: UserUpdateMe, current_user: CurrentUser
) -> Any:
"""
- Update own user.
+ 更新当前用户信息。
"""
if user_in.email:
existing_user = crud.get_user_by_email(session=session, email=user_in.email)
if existing_user and existing_user.id != current_user.id:
raise HTTPException(
- status_code=409, detail="User with this email already exists"
+ status_code=409, detail="该邮箱已被其他用户使用"
)
user_data = user_in.model_dump(exclude_unset=True)
current_user.sqlmodel_update(user_data)
@@ -102,25 +102,25 @@ def update_password_me(
*, session: SessionDep, body: UpdatePassword, current_user: CurrentUser
) -> Any:
"""
- Update own password.
+ 更新当前用户密码。
"""
if not verify_password(body.current_password, current_user.hashed_password):
- raise HTTPException(status_code=400, detail="Incorrect password")
+ raise HTTPException(status_code=400, detail="密码错误")
if body.current_password == body.new_password:
raise HTTPException(
- status_code=400, detail="New password cannot be the same as the current one"
+ status_code=400, detail="新密码不能与当前密码相同"
)
hashed_password = get_password_hash(body.new_password)
current_user.hashed_password = hashed_password
session.add(current_user)
session.commit()
- return Message(message="Password updated successfully")
+ return Message(message="密码更新成功")
@router.get("/me", response_model=UserPublic)
def read_user_me(current_user: CurrentUser) -> Any:
"""
- Get current user.
+ 获取当前用户信息。
"""
return current_user
@@ -128,27 +128,27 @@ def read_user_me(current_user: CurrentUser) -> Any:
@router.delete("/me", response_model=Message)
def delete_user_me(session: SessionDep, current_user: CurrentUser) -> Any:
"""
- Delete own user.
+ 删除当前用户。
"""
if current_user.is_superuser:
raise HTTPException(
- status_code=403, detail="Super users are not allowed to delete themselves"
+ status_code=403, detail="超级用户不允许删除自己"
)
session.delete(current_user)
session.commit()
- return Message(message="User deleted successfully")
+ return Message(message="用户删除成功")
@router.post("/signup", response_model=UserPublic)
def register_user(session: SessionDep, user_in: UserRegister) -> Any:
"""
- Create new user without the need to be logged in.
+ 无需登录即可创建新用户（用户注册）。
"""
user = crud.get_user_by_email(session=session, email=user_in.email)
if user:
raise HTTPException(
status_code=400,
- detail="The user with this email already exists in the system",
+ detail="系统中已存在该邮箱的用户",
)
user_create = UserCreate.model_validate(user_in)
user = crud.create_user(session=session, user_create=user_create)
@@ -160,7 +160,7 @@ def read_user_by_id(
user_id: uuid.UUID, session: SessionDep, current_user: CurrentUser
) -> Any:
"""
- Get a specific user by id.
+ 通过 ID 获取指定用户。
"""
user = session.get(User, user_id)
if user == current_user:
@@ -168,7 +168,7 @@ def read_user_by_id(
if not current_user.is_superuser:
raise HTTPException(
status_code=403,
- detail="The user doesn't have enough privileges",
+ detail="用户权限不足",
)
return user
@@ -185,20 +185,20 @@ def update_user(
user_in: UserUpdate,
) -> Any:
"""
- Update a user.
+ 更新用户信息。
"""
db_user = session.get(User, user_id)
if not db_user:
raise HTTPException(
status_code=404,
- detail="The user with this id does not exist in the system",
+ detail="系统中不存在该ID的用户",
)
if user_in.email:
existing_user = crud.get_user_by_email(session=session, email=user_in.email)
if existing_user and existing_user.id != user_id:
raise HTTPException(
- status_code=409, detail="User with this email already exists"
+ status_code=409, detail="该邮箱已被其他用户使用"
)
db_user = crud.update_user(session=session, db_user=db_user, user_in=user_in)
@@ -210,17 +210,17 @@ def delete_user(
session: SessionDep, current_user: CurrentUser, user_id: uuid.UUID
) -> Message:
"""
- Delete a user.
+ 删除用户。
"""
user = session.get(User, user_id)
if not user:
- raise HTTPException(status_code=404, detail="User not found")
+ raise HTTPException(status_code=404, detail="用户未找到")
if user == current_user:
raise HTTPException(
- status_code=403, detail="Super users are not allowed to delete themselves"
+ status_code=403, detail="超级用户不允许删除自己"
)
statement = delete(Item).where(col(Item.owner_id) == user_id)
session.exec(statement) # type: ignore
session.delete(user)
session.commit()
- return Message(message="User deleted successfully")
+ return Message(message="用户删除成功")
diff --git a/backend/app/api/routes/utils.py b/backend/app/api/routes/utils.py
index fc09341..f7c1c44 100644
--- a/backend/app/api/routes/utils.py
+++ b/backend/app/api/routes/utils.py
@@ -15,7 +15,7 @@ router = APIRouter(prefix="/utils", tags=["utils"])
)
def test_email(email_to: EmailStr) -> Message:
"""
- Test emails.
+ 测试邮件发送。
"""
email_data = generate_test_email(email_to=email_to)
send_email(
@@ -23,7 +23,7 @@ def test_email(email_to: EmailStr) -> Message:
subject=email_data.subject,
html_content=email_data.html_content,
)
- return Message(message="Test email sent")
+ return Message(message="测试邮件已发送")
@router.get("/health-check/")
diff --git a/backend/app/backend_pre_start.py b/backend/app/backend_pre_start.py
index c2f8e29..7e5e5cb 100644
--- a/backend/app/backend_pre_start.py
+++ b/backend/app/backend_pre_start.py
@@ -22,7 +22,7 @@ wait_seconds = 1
def init(db_engine: Engine) -> None:
try:
with Session(db_engine) as session:
- # Try to create session to check if DB is awake
+ # 尝试创建会话以检查数据库是否已就绪
session.exec(select(1))
except Exception as e:
logger.error(e)
@@ -30,9 +30,9 @@ def init(db_engine: Engine) -> None:
def main() -> None:
- logger.info("Initializing service")
+ logger.info("正在初始化服务")
init(engine)
- logger.info("Service finished initializing")
+ logger.info("服务初始化完成")
if __name__ == "__main__":
diff --git a/backend/app/core/config.py b/backend/app/core/config.py
index 650b9f7..5f539e4 100644
--- a/backend/app/core/config.py
+++ b/backend/app/core/config.py
@@ -25,14 +25,14 @@ def parse_cors(v: Any) -> list[str] | str:
class Settings(BaseSettings):
model_config = SettingsConfigDict(
- # Use top level .env file (one level above ./backend/)
+ # 使用顶层的 .env 文件（在 ./backend/ 上一级目录）
env_file="../.env",
env_ignore_empty=True,
extra="ignore",
)
API_V1_STR: str = "/api/v1"
SECRET_KEY: str = secrets.token_urlsafe(32)
- # 60 minutes * 24 hours * 8 days = 8 days
+ # 60 分钟 * 24 小时 * 8 天 = 8 天
ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 8
FRONTEND_HOST: str = "http://localhost:5173"
ENVIRONMENT: Literal["local", "staging", "production"] = "local"
@@ -97,8 +97,8 @@ class Settings(BaseSettings):
def _check_default_secret(self, var_name: str, value: str | None) -> None:
if value == "changethis":
message = (
- f'The value of {var_name} is "changethis", '
- "for security, please change it, at least for deployments."
+ f'{var_name} 的值为 "changethis"，'
+ "出于安全考虑，请修改它，至少在部署时需要修改。"
)
if self.ENVIRONMENT == "local":
warnings.warn(message, stacklevel=1)
diff --git a/backend/app/core/db.py b/backend/app/core/db.py
index ba991fb..c263623 100644
--- a/backend/app/core/db.py
+++ b/backend/app/core/db.py
@@ -7,18 +7,17 @@ from app.models import User, UserCreate
engine = create_engine(str(settings.SQLALCHEMY_DATABASE_URI))
-# make sure all SQLModel models are imported (app.models) before initializing DB
-# otherwise, SQLModel might fail to initialize relationships properly
-# for more details: https://github.com/fastapi/full-stack-fastapi-template/issues/28
+# 确保在初始化数据库之前已导入所有 SQLModel 模型（app.models）
+# 否则，SQLModel 可能无法正确初始化关系
+# 更多详情请参考：https://github.com/fastapi/full-stack-fastapi-template/issues/28
def init_db(session: Session) -> None:
- # Tables should be created with Alembic migrations
- # But if you don't want to use migrations, create
- # the tables un-commenting the next lines
+ # 数据库表应该通过 Alembic 迁移创建
+ # 但如果你不想使用迁移，可以取消注释下面的代码来创建表
# from sqlmodel import SQLModel
- # This works because the models are already imported and registered from app.models
+ # 这样可以正常工作，因为模型已经从 app.models 导入并注册
# SQLModel.metadata.create_all(engine)
user = session.exec(
diff --git a/backend/app/initial_data.py b/backend/app/initial_data.py
index d806c3d..ca96f3a 100644
--- a/backend/app/initial_data.py
+++ b/backend/app/initial_data.py
@@ -14,9 +14,9 @@ def init() -> None:
def main() -> None:
- logger.info("Creating initial data")
+ logger.info("正在创建初始数据")
init()
- logger.info("Initial data created")
+ logger.info("初始数据创建完成")
if __name__ == "__main__":
diff --git a/backend/app/main.py b/backend/app/main.py
index 9a95801..69fee93 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -20,7 +20,7 @@ app = FastAPI(
generate_unique_id_function=custom_generate_unique_id,
)
-# Set all CORS enabled origins
+# 设置所有允许 CORS 的源
if settings.all_cors_origins:
app.add_middleware(
CORSMiddleware,
diff --git a/backend/app/models.py b/backend/app/models.py
index 2d060ba..48fe050 100644
--- a/backend/app/models.py
+++ b/backend/app/models.py
@@ -4,7 +4,7 @@ from pydantic import EmailStr
from sqlmodel import Field, Relationship, SQLModel
-# Shared properties
+# 共享属性
class UserBase(SQLModel):
email: EmailStr = Field(unique=True, index=True, max_length=255)
is_active: bool = True
@@ -12,7 +12,7 @@ class UserBase(SQLModel):
full_name: str | None = Field(default=None, max_length=255)
-# Properties to receive via API on creation
+# 创建用户时通过 API 接收的属性
class UserCreate(UserBase):
password: str = Field(min_length=8, max_length=128)
@@ -23,7 +23,7 @@ class UserRegister(SQLModel):
full_name: str | None = Field(default=None, max_length=255)
-# Properties to receive via API on update, all are optional
+# 更新用户时通过 API 接收的属性，所有字段均为可选
class UserUpdate(UserBase):
email: EmailStr | None = Field(default=None, max_length=255) # type: ignore
password: str | None = Field(default=None, min_length=8, max_length=128)
@@ -39,14 +39,14 @@ class UpdatePassword(SQLModel):
new_password: str = Field(min_length=8, max_length=128)
-# Database model, database table inferred from class name
+# 数据库模型，数据库表名从类名推断
class User(UserBase, table=True):
id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
hashed_password: str
items: list["Item"] = Relationship(back_populates="owner", cascade_delete=True)
-# Properties to return via API, id is always required
+# 通过 API 返回的属性，id 始终必填
class UserPublic(UserBase):
id: uuid.UUID
@@ -56,23 +56,23 @@ class UsersPublic(SQLModel):
count: int
-# Shared properties
+# 共享属性
class ItemBase(SQLModel):
title: str = Field(min_length=1, max_length=255)
description: str | None = Field(default=None, max_length=255)
-# Properties to receive on item creation
+# 创建 Item 时接收的属性
class ItemCreate(ItemBase):
pass
-# Properties to receive on item update
+# 更新 Item 时接收的属性
class ItemUpdate(ItemBase):
title: str | None = Field(default=None, min_length=1, max_length=255) # type: ignore
-# Database model, database table inferred from class name
+# 数据库模型，数据库表名从类名推断
class Item(ItemBase, table=True):
id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
owner_id: uuid.UUID = Field(
@@ -81,7 +81,7 @@ class Item(ItemBase, table=True):
owner: User | None = Relationship(back_populates="items")
-# Properties to return via API, id is always required
+# 通过 API 返回的属性，id 始终必填
class ItemPublic(ItemBase):
id: uuid.UUID
owner_id: uuid.UUID
@@ -92,18 +92,18 @@ class ItemsPublic(SQLModel):
count: int
-# Generic message
+# 通用消息
class Message(SQLModel):
message: str
-# JSON payload containing access token
+# 包含访问令牌的 JSON 载荷
class Token(SQLModel):
access_token: str
token_type: str = "bearer"
-# Contents of JWT token
+# JWT 令牌内容
class TokenPayload(SQLModel):
sub: str | None = None
diff --git a/backend/app/tests_pre_start.py b/backend/app/tests_pre_start.py
index 0ce6045..4387ee0 100644
--- a/backend/app/tests_pre_start.py
+++ b/backend/app/tests_pre_start.py
@@ -21,7 +21,7 @@ wait_seconds = 1
)
def init(db_engine: Engine) -> None:
try:
- # Try to create session to check if DB is awake
+ # 尝试创建会话以检查数据库是否已就绪
with Session(db_engine) as session:
session.exec(select(1))
except Exception as e:
@@ -30,9 +30,9 @@ def init(db_engine: Engine) -> None:
def main() -> None:
- logger.info("Initializing service")
+ logger.info("正在初始化服务")
init(engine)
- logger.info("Service finished initializing")
+ logger.info("服务初始化完成")
if __name__ == "__main__":
diff --git a/backend/app/utils.py b/backend/app/utils.py
index ac029f6..5a1d987 100644
--- a/backend/app/utils.py
+++ b/backend/app/utils.py
@@ -36,7 +36,7 @@ def send_email(
subject: str = "",
html_content: str = "",
) -> None:
- assert settings.emails_enabled, "no provided configuration for email variables"
+ assert settings.emails_enabled, "未提供邮件相关配置变量"
message = emails.Message(
subject=subject,
html=html_content,
diff --git a/backend/scripts/prestart.sh b/backend/scripts/prestart.sh
index 1b395d5..ab23636 100644
--- a/backend/scripts/prestart.sh
+++ b/backend/scripts/prestart.sh
@@ -3,11 +3,11 @@
set -e
set -x
-# Let the DB start
+# 等待数据库启动
python app/backend_pre_start.py
-# Run migrations
+# 运行数据库迁移
alembic upgrade head
-# Create initial data in DB
+# 在数据库中创建初始数据
python app/initial_data.py
diff --git a/copier.yml b/copier.yml
index f98e3fc..a278ede 100644
--- a/copier.yml
+++ b/copier.yml
@@ -1,66 +1,66 @@
project_name:
type: str
- help: The name of the project, shown to API users (in .env)
+ help: 项目名称，展示给 API 用户（保存在 .env）
default: FastAPI Project
stack_name:
type: str
- help: The name of the stack used for Docker Compose labels (no spaces) (in .env)
+ help: 用于 Docker Compose 标签的堆栈名称（不能有空格）（保存在 .env）
default: fastapi-project
secret_key:
type: str
help: |
- 'The secret key for the project, used for security,
- stored in .env, you can generate one with:
+ '项目的密钥，用于安全相关功能，
+ 保存在 .env，你可以用以下命令生成：
python -c "import secrets; print(secrets.token_urlsafe(32))"'
default: changethis
first_superuser:
type: str
- help: The email of the first superuser (in .env)
+ help: 第一个超级用户的邮箱（保存在 .env）
default: admin@example.com
first_superuser_password:
type: str
- help: The password of the first superuser (in .env)
+ help: 第一个超级用户的密码（保存在 .env）
default: changethis
smtp_host:
type: str
- help: The SMTP server host to send emails, you can set it later in .env
+ help: 用于发送邮件的 SMTP 服务器地址，你可以稍后在 .env 中设置
default: ""
smtp_user:
type: str
- help: The SMTP server user to send emails, you can set it later in .env
+ help: 用于发送邮件的 SMTP 服务器用户名，你可以稍后在 .env 中设置
default: ""
smtp_password:
type: str
- help: The SMTP server password to send emails, you can set it later in .env
+ help: 用于发送邮件的 SMTP 服务器密码，你可以稍后在 .env 中设置
default: ""
emails_from_email:
type: str
- help: The email account to send emails from, you can set it later in .env
+ help: 发送邮件的发件邮箱地址，你可以稍后在 .env 中设置
default: info@example.com
postgres_password:
type: str
help: |
- 'The password for the PostgreSQL database, stored in .env,
- you can generate one with:
+ 'PostgreSQL 数据库的密码，保存在 .env，
+ 你可以用以下命令生成：
python -c "import secrets; print(secrets.token_urlsafe(32))"'
default: changethis
sentry_dsn:
type: str
- help: The DSN for Sentry, if you are using it, you can set it later in .env
+ help: Sentry 的 DSN，如果你正在使用 Sentry，可以稍后在 .env 中设置
default: ""
_exclude:
- # Global
+ # 全局
- .vscode
- .mypy_cache
# Python
@@ -72,8 +72,8 @@ _exclude:
- htmlcov
- .cache
- .venv
- # Frontend
- # Logs
+ # 前端
+ # 日志
- logs
- "*.log"
- npm-debug.log*
@@ -85,7 +85,7 @@ _exclude:
- dist
- dist-ssr
- "*.local"
- # Editor directories and files
+ # 编辑器目录和文件
- .idea
- .DS_Store
- "*.suo"
diff --git a/deployment.md b/deployment.md
index 970032b..6b46223 100644
--- a/deployment.md
+++ b/deployment.md
@@ -1,263 +1,270 @@
-# FastAPI Project - Deployment
+# FastAPI 项目 - 部署（Deployment）
-You can deploy the project using Docker Compose to a remote server.
+你可以使用 Docker Compose 将本项目部署到远程服务器。
-This project expects you to have a Traefik proxy handling communication to the outside world and HTTPS certificates.
+本项目假定你已经有一个 Traefik 代理，用于处理对外的 HTTP/HTTPS 流量以及证书管理。
-You can use CI/CD (continuous integration and continuous deployment) systems to deploy automatically, there are already configurations to do it with GitHub Actions.
+你可以使用 CI/CD（持续集成与持续部署）系统自动部署，本项目已经提供了 GitHub Actions 的示例配置。
-But you have to configure a couple things first. 🤓
+在此之前，你需要完成一些基础配置。🤓
-## Preparation
+## 部署前准备
-* Have a remote server ready and available.
-* Configure the DNS records of your domain to point to the IP of the server you just created.
-* Configure a wildcard subdomain for your domain, so that you can have multiple subdomains for different services, e.g. `*.fastapi-project.example.com`. This will be useful for accessing different components, like `dashboard.fastapi-project.example.com`, `api.fastapi-project.example.com`, `traefik.fastapi-project.example.com`, `adminer.fastapi-project.example.com`, etc. And also for `staging`, like `dashboard.staging.fastapi-project.example.com`, `adminer.staging.fastapi-project.example.com`, etc.
-* Install and configure [Docker](https://docs.docker.com/engine/install/) on the remote server (Docker Engine, not Docker Desktop).
+* 准备一台可访问的远程服务器。
+* 将你的域名 DNS 记录解析到该服务器的 IP。
+* 为该域名配置通配符子域名（Wildcard），例如 `*.fastapi-project.example.com`，以便为不同服务使用不同子域名，如 `dashboard.fastapi-project.example.com`、`api.fastapi-project.example.com`、`traefik.fastapi-project.example.com`、`adminer.fastapi-project.example.com` 等；同时也便于配置 `staging` 环境，比如 `dashboard.staging.fastapi-project.example.com`、`adminer.staging.fastapi-project.example.com` 等。
+* 在远程服务器上安装并配置 [Docker](https://docs.docker.com/engine/install/)（Docker Engine，而非 Docker Desktop）。
-## Public Traefik
+## 公共 Traefik
-We need a Traefik proxy to handle incoming connections and HTTPS certificates.
+我们需要一个 Traefik 代理来处理外部请求以及 HTTPS 证书。
-You need to do these next steps only once.
+下面的步骤只需执行一次。
-### Traefik Docker Compose
+### Traefik 的 Docker Compose
-* Create a remote directory to store your Traefik Docker Compose file:
+* 在远程服务器上创建一个目录，用来存放 Traefik 的 Docker Compose 文件：
```bash
mkdir -p /root/code/traefik-public/
```
-Copy the Traefik Docker Compose file to your server. You could do it by running the command `rsync` in your local terminal:
+在本地终端中使用 `rsync` 将 Traefik 的 Docker Compose 文件拷贝到服务器：
```bash
rsync -a docker-compose.traefik.yml root@your-server.example.com:/root/code/traefik-public/
```
-### Traefik Public Network
+### Traefik 公共网络
-This Traefik will expect a Docker "public network" named `traefik-public` to communicate with your stack(s).
+Traefik 会期望有一个名为 `traefik-public` 的 Docker “公共网络”，用来与各个应用 stack 通信。
-This way, there will be a single public Traefik proxy that handles the communication (HTTP and HTTPS) with the outside world, and then behind that, you could have one or more stacks with different domains, even if they are on the same single server.
+通过这种方式，可以用一个公共 Traefik 代理对外处理 HTTP/HTTPS 流量，其后可以挂载一个或多个不同域名的应用 stack，即便它们都在同一台物理服务器上。
-To create a Docker "public network" named `traefik-public` run the following command in your remote server:
+在远程服务器中创建该网络：
```bash
docker network create traefik-public
```
-### Traefik Environment Variables
+### Traefik 环境变量
-The Traefik Docker Compose file expects some environment variables to be set in your terminal before starting it. You can do it by running the following commands in your remote server.
+Traefik 的 Docker Compose 文件在启动前需要若干环境变量，你可以在远程服务器终端中通过以下命令设置：
-* Create the username for HTTP Basic Auth, e.g.:
+* 为 HTTP Basic Auth 创建用户名，例如：
```bash
export USERNAME=admin
```
-* Create an environment variable with the password for HTTP Basic Auth, e.g.:
+* 创建 Basic Auth 密码对应的环境变量，例如：
```bash
export PASSWORD=changethis
```
-* Use openssl to generate the "hashed" version of the password for HTTP Basic Auth and store it in an environment variable:
+* 使用 openssl 生成该密码的哈希值并保存到环境变量中：
```bash
export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)
```
-To verify that the hashed password is correct, you can print it:
+可以通过打印检查哈希是否已生成：
```bash
echo $HASHED_PASSWORD
```
-* Create an environment variable with the domain name for your server, e.g.:
+* 创建保存服务器主域名的环境变量，例如：
```bash
export DOMAIN=fastapi-project.example.com
```
-* Create an environment variable with the email for Let's Encrypt, e.g.:
+* 创建保存 Let's Encrypt 邮箱的环境变量，例如：
```bash
export EMAIL=admin@example.com
```
-**Note**: you need to set a different email, an email `@example.com` won't work.
+**注意**：邮箱不能是 `@example.com` 这样的占位域名，需要使用真实邮箱。
-### Start the Traefik Docker Compose
+### 启动 Traefik Docker Compose
-Go to the directory where you copied the Traefik Docker Compose file in your remote server:
+在远程服务器上进入存放 Traefik Docker Compose 文件的目录：
```bash
cd /root/code/traefik-public/
```
-Now with the environment variables set and the `docker-compose.traefik.yml` in place, you can start the Traefik Docker Compose running the following command:
+在环境变量已经设置、`docker-compose.traefik.yml` 已就位的情况下，启动 Traefik：
```bash
docker compose -f docker-compose.traefik.yml up -d
```
-## Deploy the FastAPI Project
+## 部署 FastAPI 项目
-Now that you have Traefik in place you can deploy your FastAPI project with Docker Compose.
+在 Traefik 准备好之后，就可以使用 Docker Compose 部署 FastAPI 项目。
-**Note**: You might want to jump ahead to the section about Continuous Deployment with GitHub Actions.
+**提示**：你也可以直接跳到后面的「使用 GitHub Actions 持续部署」部分。
-## Environment Variables
+## 环境变量
-You need to set some environment variables first.
+在部署前，需要设置若干环境变量。
-Set the `ENVIRONMENT`, by default `local` (for development), but when deploying to a server you would put something like `staging` or `production`:
+设置 `ENVIRONMENT`，默认是 `local`（开发环境），部署到服务器时可以设置为 `staging` 或 `production`，例如：
```bash
export ENVIRONMENT=production
```
-Set the `DOMAIN`, by default `localhost` (for development), but when deploying you would use your own domain, for example:
+设置 `DOMAIN`，本地默认是 `localhost`，在部署时应改为你的实际域名，例如：
```bash
export DOMAIN=fastapi-project.example.com
```
-You can set several variables, like:
+你还可以设置以下变量：
-* `PROJECT_NAME`: The name of the project, used in the API for the docs and emails.
-* `STACK_NAME`: The name of the stack used for Docker Compose labels and project name, this should be different for `staging`, `production`, etc. You could use the same domain replacing dots with dashes, e.g. `fastapi-project-example-com` and `staging-fastapi-project-example-com`.
-* `BACKEND_CORS_ORIGINS`: A list of allowed CORS origins separated by commas.
-* `SECRET_KEY`: The secret key for the FastAPI project, used to sign tokens.
-* `FIRST_SUPERUSER`: The email of the first superuser, this superuser will be the one that can create new users.
-* `FIRST_SUPERUSER_PASSWORD`: The password of the first superuser.
-* `SMTP_HOST`: The SMTP server host to send emails, this would come from your email provider (E.g. Mailgun, Sparkpost, Sendgrid, etc).
-* `SMTP_USER`: The SMTP server user to send emails.
-* `SMTP_PASSWORD`: The SMTP server password to send emails.
-* `EMAILS_FROM_EMAIL`: The email account to send emails from.
-* `POSTGRES_SERVER`: The hostname of the PostgreSQL server. You can leave the default of `db`, provided by the same Docker Compose. You normally wouldn't need to change this unless you are using a third-party provider.
-* `POSTGRES_PORT`: The port of the PostgreSQL server. You can leave the default. You normally wouldn't need to change this unless you are using a third-party provider.
-* `POSTGRES_PASSWORD`: The Postgres password.
-* `POSTGRES_USER`: The Postgres user, you can leave the default.
-* `POSTGRES_DB`: The database name to use for this application. You can leave the default of `app`.
-* `SENTRY_DSN`: The DSN for Sentry, if you are using it.
+* `PROJECT_NAME`：项目名称，用于 API 文档及邮件内容中展示。
+* `STACK_NAME`：在 Docker Compose 中使用的 stack 名称，也用于标签与项目名。该值在 `staging`、`production` 等环境中应各不相同。一个常见做法是将域名中的点替换为短横线，例如 `fastapi-project-example-com` 与 `staging-fastapi-project-example-com`。
+* `BACKEND_CORS_ORIGINS`：允许的 CORS 源列表，使用逗号分隔。
+* `SECRET_KEY`：FastAPI 项目的密钥，用于签发 token 等安全相关操作。
+* `FIRST_SUPERUSER`：首个超级用户的邮箱地址，该用户可以创建其他用户。
+* `FIRST_SUPERUSER_PASSWORD`：首个超级用户的密码。
+* `SMTP_HOST`：SMTP 服务器地址，用于发邮件（如 Mailgun、Sparkpost、Sendgrid 等提供的地址）。
+* `SMTP_USER`：SMTP 用户名。
+* `SMTP_PASSWORD`：SMTP 密码。
+* `EMAILS_FROM_EMAIL`：发件邮箱地址。
+* `POSTGRES_SERVER`：PostgreSQL 服务器主机名。使用 Docker Compose 时可以保持默认值 `db`，除非你改为使用第三方数据库服务。
+* `POSTGRES_PORT`：PostgreSQL 端口，通常保持默认即可。
+* `POSTGRES_PASSWORD`：PostgreSQL 密码。
+* `POSTGRES_USER`：PostgreSQL 用户名，一般使用默认值即可。
+* `POSTGRES_DB`：本应用使用的数据库名称，默认 `app`。
+* `SENTRY_DSN`：如果接入了 Sentry，这里填入 DSN。
-## GitHub Actions Environment Variables
+## GitHub Actions 环境变量
-There are some environment variables only used by GitHub Actions that you can configure:
+有一些环境变量只在 GitHub Actions 中使用，可以按需配置：
-* `LATEST_CHANGES`: Used by the GitHub Action [latest-changes](https://github.com/tiangolo/latest-changes) to automatically add release notes based on the PRs merged. It's a personal access token, read the docs for details.
-* `SMOKESHOW_AUTH_KEY`: Used to handle and publish the code coverage using [Smokeshow](https://github.com/samuelcolvin/smokeshow), follow their instructions to create a (free) Smokeshow key.
+* `LATEST_CHANGES`：用于 [latest-changes](https://github.com/tiangolo/latest-changes) GitHub Action，根据合并的 PR 自动生成发布日志。它需要一个个人访问令牌（PAT），具体可见其文档。
+* `SMOKESHOW_AUTH_KEY`：用于 [Smokeshow](https://github.com/samuelcolvin/smokeshow) 发布测试覆盖率报告，同样需要按其说明生成一个（免费的）密钥。
-### 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.
+复制输出内容并用作密码 / 密钥；需要多个密钥时多执行几次即可。
-### Deploy with Docker Compose
+### 使用 Docker Compose 部署
-With the environment variables in place, you can deploy with Docker Compose:
+环境变量准备就绪后，可以使用 Docker Compose 部署：
```bash
docker compose -f docker-compose.yml up -d
```
-For production you wouldn't want to have the overrides in `docker-compose.override.yml`, that's why we explicitly specify `docker-compose.yml` as the file to use.
+在生产环境中，一般不希望加载 `docker-compose.override.yml` 中的开发用覆盖配置，因此这里显式指定只使用 `docker-compose.yml`。
-## Continuous Deployment (CD)
+## 持续部署（CD）
-You can use GitHub Actions to deploy your project automatically. 😎
+你可以使用 GitHub Actions 自动部署你的项目。😎
-You can have multiple environment deployments.
+可以为多个环境配置不同的部署流程。
-There are already two environments configured, `staging` and `production`. 🚀
+本项目中已经预置了 `staging` 与 `production` 两个环境。🚀
-### Install GitHub Actions Runner
+### 安装 GitHub Actions Runner
-* On your remote server, create a user for your GitHub Actions:
+* 在远程服务器上为 GitHub Actions 创建一个用户，例如：
```bash
sudo adduser github
```
-* Add Docker permissions to the `github` user:
+* 为 `github` 用户添加 Docker 权限：
```bash
sudo usermod -aG docker github
```
-* Temporarily switch to the `github` user:
+* 临时切换为 `github` 用户：
```bash
sudo su - github
```
-* Go to the `github` user's home directory:
+* 进入 `github` 用户的 home 目录：
```bash
cd
```
-* [Install a GitHub Action self-hosted runner following the official guide](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository).
+* 按照官方文档安装 GitHub Action 自托管 Runner：
+ - Something went wrong. Please try again. + 出现了错误。请重试。
- + ) diff --git a/frontend/src/components/UserSettings/UserInformation.tsx b/frontend/src/components/UserSettings/UserInformation.tsx index 4bfaf60..5e99cd5 100644 --- a/frontend/src/components/UserSettings/UserInformation.tsx +++ b/frontend/src/components/UserSettings/UserInformation.tsx @@ -64,7 +64,7 @@ const UserInformation = () => { const onSubmit = (data: FormData) => { const updateData: UserUpdateMe = {} - // only include fields that have changed + // 仅包含已更改的字段 if (data.full_name !== currentUser?.full_name) { updateData.full_name = data.full_name } diff --git a/frontend/src/components/ui/sidebar.tsx b/frontend/src/components/ui/sidebar.tsx index 60c0115..623535a 100644 --- a/frontend/src/components/ui/sidebar.tsx +++ b/frontend/src/components/ui/sidebar.tsx @@ -79,8 +79,8 @@ function SidebarProvider({ return cookie.split("=")[1] === "true" } - // This is the internal state of the sidebar. - // We use openProp and setOpenProp for control from outside the component. + // 这是侧边栏的内部状态。 + // 我们使用 openProp 和 setOpenProp 从组件外部进行控制。 const [_open, _setOpen] = React.useState(getInitialOpen) const open = openProp ?? _open const setOpen = React.useCallback( @@ -92,18 +92,18 @@ function SidebarProvider({ _setOpen(openState) } - // This sets the cookie to keep the sidebar state. + // 设置 cookie 以保持侧边栏状态。 document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}` }, [setOpenProp, open], ) - // Helper to toggle the sidebar. + // 切换侧边栏的辅助函数。 const toggleSidebar = React.useCallback(() => { return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open) }, [isMobile, setOpen]) - // Adds a keyboard shortcut to toggle the sidebar. + // 添加键盘快捷键来切换侧边栏。 React.useEffect(() => { const handleKeyDown = (event: KeyboardEvent) => { if ( @@ -119,8 +119,8 @@ function SidebarProvider({ return () => window.removeEventListener("keydown", handleKeyDown) }, [toggleSidebar]) - // We add a state so that we can do data-state="expanded" or "collapsed". - // This makes it easier to style the sidebar with Tailwind classes. + // 添加状态以便使用 data-state="expanded" 或 "collapsed"。 + // 这样可以更容易地使用 Tailwind 类来设置侧边栏样式。 const state = open ? "expanded" : "collapsed" const contextValue = React.useMemo