中文汉化

2025-12-18 09:40:41 +08:00
parent 6a91475bf6
commit db867dcbe5
41 changed files with 671 additions and 666 deletions
@@ -1,34 +1,34 @@
-# FastAPI Project - Development
+# FastAPI 项目 - 开发（Development）

 ## Docker Compose

-* Start the local stack with Docker Compose:
+* 使用 Docker Compose 启动本地 stack：

 ```bash
 docker compose watch
 ```

-* Now you can open your browser and interact with these URLs:
+* 启动后，你可以在浏览器中访问以下地址：

-Frontend, built with Docker, with routes handled based on the path: <http://localhost:5173>
+前端（通过 Docker 构建，基于路径路由）：<http://localhost:5173>

-Backend, JSON based web API based on OpenAPI: <http://localhost:8000>
+后端（基于 OpenAPI 的 JSON Web API）：<http://localhost:8000>

-Automatic interactive documentation with Swagger UI (from the OpenAPI backend): <http://localhost:8000/docs>
+自动生成的 Swagger UI 交互文档：<http://localhost:8000/docs>

-Adminer, database web administration: <http://localhost:8080>
+Adminer 数据库管理界面：<http://localhost:8080>

-Traefik UI, to see how the routes are being handled by the proxy: <http://localhost:8090>
+Traefik UI（查看代理如何路由请求）：<http://localhost:8090>

-**Note**: The first time you start your stack, it might take a minute for it to be ready. While the backend waits for the database to be ready and configures everything. You can check the logs to monitor it.
+**注意**：第一次启动整个 stack 时，后端会等待数据库就绪并完成配置，这可能需要一点时间。你可以通过查看日志来确认进度。

-To check the logs, run (in another terminal):
+在另一个终端中查看日志：

 ```bash
 docker compose logs
 ```

-To check the logs of a specific service, add the name of the service, e.g.:
+查看某个特定服务的日志时，可以加上服务名，例如：

 ```bash
 docker compose logs backend
@@ -36,136 +36,136 @@ docker compose logs backend

 ## Mailcatcher

-Mailcatcher is a simple SMTP server that catches all emails sent by the backend during local development. Instead of sending real emails, they are captured and displayed in a web interface.
+Mailcatcher 是一个简单的 SMTP 服务器，在本地开发过程中会拦截后端发出的所有邮件。邮件不会真正发送出去，而是通过 Web 界面展示。

-This is useful for:
+它适用于：

-* Testing email functionality during development
-* Verifying email content and formatting
-* Debugging email-related functionality without sending real emails
+* 在开发阶段测试邮件功能；
+* 检查邮件内容与排版；
+* 调试邮件相关逻辑，而无需发送真实邮件。

-The backend is automatically configured to use Mailcatcher when running with Docker Compose locally (SMTP on port 1025). All captured emails can be viewed at <http://localhost:1080>.
+在本地使用 Docker Compose 运行时，后端会自动配置为使用 Mailcatcher（SMTP 端口为 1025）。所有被捕获的邮件可以在 <http://localhost:1080> 查看。

-## Local Development
+## 本地开发

-The Docker Compose files are configured so that each of the services is available in a different port in `localhost`.
+Docker Compose 文件已经配置好，让每个服务在 `localhost` 上使用不同端口。

-For the backend and frontend, they use the same port that would be used by their local development server, so, the backend is at `http://localhost:8000` and the frontend at `http://localhost:5173`.
+后端与前端使用的端口与其本地开发服务器一致：后端为 `http://localhost:8000`，前端为 `http://localhost:5173`。

-This way, you could turn off a Docker Compose service and start its local development service, and everything would keep working, because it all uses the same ports.
+这样你可以随时关闭某个 Docker 服务并启动本地开发服务器，其余服务仍能通过相同端口正常访问。

-For example, you can stop that `frontend` service in the Docker Compose, in another terminal, run:
+例如，想用本地 Vite 开发服务器，可以在另一个终端中停止 Docker 中的 `frontend` 服务：

 ```bash
 docker compose stop frontend
 ```

-And then start the local frontend development server:
+然后启动本地前端开发服务器：

 ```bash
 cd frontend
 npm run dev
 ```

-Or you could stop the `backend` Docker Compose service:
+同样地，可以停止 Docker 中的 `backend` 服务：

 ```bash
 docker compose stop backend
 ```

-And then you can run the local development server for the backend:
+接着运行本地后端开发服务器：

 ```bash
 cd backend
 fastapi dev app/main.py
 ```

-## Docker Compose in `localhost.tiangolo.com`
+## 在 `localhost.tiangolo.com` 下使用 Docker Compose

-When you start the Docker Compose stack, it uses `localhost` by default, with different ports for each service (backend, frontend, adminer, etc).
+启动 Docker Compose stack 时，默认使用 `localhost`，不同服务（后端、前端、Adminer 等）分别占用不同端口。

-When you deploy it to production (or staging), it will deploy each service in a different subdomain, like `api.example.com` for the backend and `dashboard.example.com` for the frontend.
+在生产（或预发布）环境中，每个服务通常使用不同子域名，例如后端使用 `api.example.com`，前端使用 `dashboard.example.com`。

-In the guide about [deployment](deployment.md) you can read about Traefik, the configured proxy. That's the component in charge of transmitting traffic to each service based on the subdomain.
+在 [deployment.md](deployment.md) 中提到的 Traefik 就是用于根据子域名将请求转发到对应服务的反向代理。

-If you want to test that it's all working locally, you can edit the local `.env` file, and change:
+如果你想在本地完整测试这套子域名路由方案，可以修改本地 `.env` 文件中的配置：

 ```dotenv
 DOMAIN=localhost.tiangolo.com
 ```

-That will be used by the Docker Compose files to configure the base domain for the services.
+该值会被 Docker Compose 用于配置各服务的基础域名。

-Traefik will use this to transmit traffic at `api.localhost.tiangolo.com` to the backend, and traffic at `dashboard.localhost.tiangolo.com` to the frontend.
+Traefik 会将 `api.localhost.tiangolo.com` 的请求转发到后端，将 `dashboard.localhost.tiangolo.com` 的请求转发到前端。

-The domain `localhost.tiangolo.com` is a special domain that is configured (with all its subdomains) to point to `127.0.0.1`. This way you can use that for your local development.
+`localhost.tiangolo.com` 是一个特殊域名，它及其所有子域名都指向 `127.0.0.1`，非常适合作为本地多子域名开发环境。

-After you update it, run again:
+修改 `.env` 后，重新运行：

 ```bash
 docker compose watch
 ```

-When deploying, for example in production, the main Traefik is configured outside of the Docker Compose files. For local development, there's an included Traefik in `docker-compose.override.yml`, just to let you test that the domains work as expected, for example with `api.localhost.tiangolo.com` and `dashboard.localhost.tiangolo.com`.
+在生产环境部署时，主 Traefik 一般在 Docker Compose 之外单独配置。本地开发时，`docker-compose.override.yml` 中包含了一个 Traefik 配置，仅用于测试如 `api.localhost.tiangolo.com` 与 `dashboard.localhost.tiangolo.com` 这样的本地域名是否按预期工作。

-## Docker Compose files and env vars
+## Docker Compose 文件与环境变量

-There is a main `docker-compose.yml` file with all the configurations that apply to the whole stack, it is used automatically by `docker compose`.
+主配置文件 `docker-compose.yml` 包含整个 stack 的全部配置，`docker compose` 会自动读取它。

-And there's also a `docker-compose.override.yml` with overrides for development, for example to mount the source code as a volume. It is used automatically by `docker compose` to apply overrides on top of `docker-compose.yml`.
+另外还有一个 `docker-compose.override.yml` 文件，专门用于开发环境的覆盖配置，例如将源代码目录挂载为 volume。`docker compose` 会自动将其作为 `docker-compose.yml` 的覆盖层进行合并。

-These Docker Compose files use the `.env` file containing configurations to be injected as environment variables in the containers.
+这些 Docker Compose 文件会读取 `.env` 文件中的配置，并将其作为环境变量注入到容器中。

-They also use some additional configurations taken from environment variables set in the scripts before calling the `docker compose` command.
+此外，在运行 `docker compose` 命令前，某些脚本可能会设置额外的环境变量供配置使用。

-After changing variables, make sure you restart the stack:
+修改环境变量后，请记得重启 stack：

 ```bash
 docker compose watch
 ```

-## The .env file
+## .env 文件

-The `.env` file is the one that contains all your configurations, generated keys and passwords, etc.
+`.env` 文件包含所有配置、生成的密钥和密码等。

-Depending on your workflow, you could want to exclude it from Git, for example if your project is public. In that case, you would have to make sure to set up a way for your CI tools to obtain it while building or deploying your project.
+根据你的工作流程，你可能希望将其从 Git 中排除（尤其当项目是公开的）。在这种情况下，需要确保 CI 工具在构建或部署时能够获取到这些配置。

-One way to do it could be to add each environment variable to your CI/CD system, and updating the `docker-compose.yml` file to read that specific env var instead of reading the `.env` file.
+一种做法是：将每个环境变量添加到 CI/CD 系统中，并修改 `docker-compose.yml`，让它读取对应的环境变量，而不是从 `.env` 文件中读取。

-## Pre-commits and code linting
+## Pre-commit 与代码检查

-we are using a tool called [pre-commit](https://pre-commit.com/) for code linting and formatting.
+本项目使用 [pre-commit](https://pre-commit.com/) 进行代码检查与格式化。

-When you install it, it runs right before making a commit in git. This way it ensures that the code is consistent and formatted even before it is committed.
+安装后，它会在每次 git commit 之前自动运行，确保代码在提交前就保持一致的风格和格式。

-You can find a file `.pre-commit-config.yaml` with configurations at the root of the project.
+项目根目录下有一个 `.pre-commit-config.yaml` 配置文件，定义了所有检查规则。

-#### Install pre-commit to run automatically
+#### 安装 pre-commit 以自动运行

-`pre-commit` is already part of the dependencies of the project, but you could also install it globally if you prefer to, following [the official pre-commit docs](https://pre-commit.com/).
+`pre-commit` 已经作为项目依赖的一部分，你也可以按照 [官方文档](https://pre-commit.com/) 全局安装它。

-After having the `pre-commit` tool installed and available, you need to "install" it in the local repository, so that it runs automatically before each commit.
+安装好 `pre-commit` 工具后，需要在本地仓库"安装"它，使其在每次提交前自动执行。

-Using `uv`, you could do it with:
+使用 `uv` 的方式：

 ```bash
 ❯ uv run pre-commit install
 pre-commit installed at .git/hooks/pre-commit
 ```

-Now whenever you try to commit, e.g. with:
+现在每次执行 commit 时，例如：

 ```bash
 git commit
 ```

-...pre-commit will run and check and format the code you are about to commit, and will ask you to add that code (stage it) with git again before committing.
+...pre-commit 都会运行，检查并格式化即将提交的代码，如果有修改会要求你重新 `git add` 这些文件后再提交。

-Then you can `git add` the modified/fixed files again and now you can commit.
+然后你可以 `git add` 修改 / 修复的文件，再执行 commit。

-#### Running pre-commit hooks manually
+#### 手动运行 pre-commit 钩子

-you can also run `pre-commit` manually on all the files, you can do it using `uv` with:
+你也可以手动对所有文件运行 `pre-commit`，使用 `uv` 的方式：

 ```bash
 ❯ uv run pre-commit run --all-files
@@ -178,42 +178,42 @@ eslint...................................................................Passed
 prettier.................................................................Passed
 ```

-## URLs
+## 访问地址

-The production or staging URLs would use these same paths, but with your own domain.
+生产或预发布环境使用相同的路径结构，只是替换为你自己的域名。

-### Development URLs
+### 开发环境地址

-Development URLs, for local development.
+以下是本地开发环境的地址。

-Frontend: <http://localhost:5173>
+前端：<http://localhost:5173>

-Backend: <http://localhost:8000>
+后端：<http://localhost:8000>

-Automatic Interactive Docs (Swagger UI): <http://localhost:8000/docs>
+自动生成的交互式文档（Swagger UI）：<http://localhost:8000/docs>

-Automatic Alternative Docs (ReDoc): <http://localhost:8000/redoc>
+自动生成的备选文档（ReDoc）：<http://localhost:8000/redoc>

-Adminer: <http://localhost:8080>
+Adminer：<http://localhost:8080>

-Traefik UI: <http://localhost:8090>
+Traefik UI：<http://localhost:8090>

-MailCatcher: <http://localhost:1080>
+MailCatcher：<http://localhost:1080>

-### Development URLs with `localhost.tiangolo.com` Configured
+### 配置 `localhost.tiangolo.com` 后的开发地址

-Development URLs, for local development.
+以下是本地开发环境的地址。

-Frontend: <http://dashboard.localhost.tiangolo.com>
+前端：<http://dashboard.localhost.tiangolo.com>

-Backend: <http://api.localhost.tiangolo.com>
+后端：<http://api.localhost.tiangolo.com>

-Automatic Interactive Docs (Swagger UI): <http://api.localhost.tiangolo.com/docs>
+自动生成的交互式文档（Swagger UI）：<http://api.localhost.tiangolo.com/docs>

-Automatic Alternative Docs (ReDoc): <http://api.localhost.tiangolo.com/redoc>
+自动生成的备选文档（ReDoc）：<http://api.localhost.tiangolo.com/redoc>

-Adminer: <http://localhost.tiangolo.com:8080>
+Adminer：<http://localhost.tiangolo.com:8080>

-Traefik UI: <http://localhost.tiangolo.com:8090>
+Traefik UI：<http://localhost.tiangolo.com:8090>

-MailCatcher: <http://localhost.tiangolo.com:1080>
+MailCatcher：<http://localhost.tiangolo.com:1080>