中文汉化

2025-12-18 09:40:41 +08:00
parent 6a91475bf6
commit db867dcbe5
41 changed files with 671 additions and 666 deletions
@@ -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：  
+  <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>

-* When asked about labels, add a label for the environment, e.g. `production`. You can also add labels later.
+* 在安装过程中，当被询问标签（labels）时，为 Runner 添加对应环境的标签，例如 `production`；也可以在后续再补充标签。

-After installing, the guide would tell you to run a command to start the runner. Nevertheless, it would stop once you terminate that process or if your local connection to your server is lost.
+安装完成后，官方文档会让你手动运行一个命令以启动 Runner。但一旦你断开终端连接或进程退出，Runner 就会停止。

-To make sure it runs on startup and continues running, you can install it as a service. To do that, exit the `github` user and go back to the `root` user:
+为了确保服务器重启后 Runner 仍能自动运行，建议将其安装为服务。具体步骤如下：
+
+* 从 `github` 用户退出，回到之前的用户：

 ```bash
 exit
 ```

-After you do it, you will be on the previous user again. And you will be on the previous directory, belonging to that user.
+此时你会回到之前的用户及其当前目录。

-Before being able to go the `github` user directory, you need to become the `root` user (you might already be):
+* 在能访问 `github` 用户 home 目录之前，你需要切换成 `root` 用户（如果已经是则可略过）：

 ```bash
 sudo su
 ```

-* As the `root` user, go to the `actions-runner` directory inside of the `github` user's home directory:
+* 在 `root` 用户下，进入 `github` 用户 home 下的 `actions-runner` 目录：

 ```bash
 cd /home/github/actions-runner
 ```

-* Install the self-hosted runner as a service with the user `github`:
+* 安装 Runner 为服务，并指定服务用户为 `github`：

 ```bash
 ./svc.sh install github
 ```

-* Start the service:
+* 启动该服务：

 ```bash
 ./svc.sh start
 ```

-* Check the status of the service:
+* 查看服务状态：

 ```bash
 ./svc.sh status
 ```

-You can read more about it in the official guide: [Configuring the self-hosted runner application as a service](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service).
+更多细节可参考官方文档：  
+「Configuring the self-hosted runner application as a service」  
+<https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service>

-### Set Secrets
+### 配置 Secrets

-On your repository, configure secrets for the environment variables you need, the same ones described above, including `SECRET_KEY`, etc. Follow the [official GitHub guide for setting repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
+在 GitHub 仓库中，为部署需要的环境变量配置 Secrets，包括前面提到的 `SECRET_KEY` 等。可参考官方文档：  
+「Using secrets in GitHub Actions」  
+<https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository>

-The current Github Actions workflows expect these secrets:
+当前的 GitHub Actions 工作流期望存在以下 Secrets：

 * `DOMAIN_PRODUCTION`
 * `DOMAIN_STAGING`
@@ -271,39 +278,39 @@ The current Github Actions workflows expect these secrets:
 * `LATEST_CHANGES`
 * `SMOKESHOW_AUTH_KEY`

-## GitHub Action Deployment Workflows
+## GitHub Actions 部署工作流

-There are GitHub Action workflows in the `.github/workflows` directory already configured for deploying to the environments (GitHub Actions runners with the labels):
+在 `.github/workflows` 目录中已经包含了一些用于部署到不同环境（基于 Runner 标签）的 GitHub Actions 工作流：

-* `staging`: after pushing (or merging) to the branch `master`.
-* `production`: after publishing a release.
+* `staging`：在推送（或合并）到 `master` 分支后触发。
+* `production`：在发布 Release 后触发。

-If you need to add extra environments you could use those as a starting point.
+如果你需要更多环境，可以以上述工作流为模板进行扩展。

 ## URLs

-Replace `fastapi-project.example.com` with your domain.
+下面示例中出现的 `fastapi-project.example.com` 请替换为你自己的域名。

-### Main Traefik Dashboard
+### 主 Traefik 控制台

-Traefik UI: `https://traefik.fastapi-project.example.com`
+Traefik UI：`https://traefik.fastapi-project.example.com`

-### Production
+### 生产环境（Production）

-Frontend: `https://dashboard.fastapi-project.example.com`
+前端：`https://dashboard.fastapi-project.example.com`

-Backend API docs: `https://api.fastapi-project.example.com/docs`
+后端 API 文档：`https://api.fastapi-project.example.com/docs`

-Backend API base URL: `https://api.fastapi-project.example.com`
+后端 API 基础地址：`https://api.fastapi-project.example.com`

-Adminer: `https://adminer.fastapi-project.example.com`
+Adminer：`https://adminer.fastapi-project.example.com`

-### Staging
+### 预发布环境（Staging）

-Frontend: `https://dashboard.staging.fastapi-project.example.com`
+前端：`https://dashboard.staging.fastapi-project.example.com`

-Backend API docs: `https://api.staging.fastapi-project.example.com/docs`
+后端 API 文档：`https://api.staging.fastapi-project.example.com/docs`

-Backend API base URL: `https://api.staging.fastapi-project.example.com`
+后端 API 基础地址：`https://api.staging.fastapi-project.example.com`

-Adminer: `https://adminer.staging.fastapi-project.example.com`
+Adminer：`https://adminer.staging.fastapi-project.example.com`