mirror of https://github.com/vapor/docs.git
182 lines
9.3 KiB
Markdown
182 lines
9.3 KiB
Markdown
# Fly
|
||
|
||
Fly 是一个托管平台，支持运行服务器应用程序和数据库，专注于边缘计算。更多信息请参阅[官网](https://fly.io/)。
|
||
|
||
!!! note "注意"
|
||
本文档指定的命令受 [Fly 价格](https://fly.io/docs/about/pricing/)约束，继续之前确保你已经了解它。
|
||
|
||
## 注册
|
||
如果你没有账号，你需要[注册](https://fly.io/app/sign-up)一个。
|
||
|
||
## 安装 flyctl
|
||
你与 Fly 的主要交互方式是使用专用的 CLI 工具 `flyctl`，你需要安装该工具。
|
||
|
||
### macOS
|
||
```bash
|
||
brew install flyctl
|
||
```
|
||
|
||
### Linux
|
||
```bash
|
||
curl -L https://fly.io/install.sh | sh
|
||
```
|
||
|
||
### 其它安装选项
|
||
有关更多选项和详细信息，请参阅 [flyctl 文档](https://fly.io/docs/flyctl/install/)。
|
||
|
||
## 登录
|
||
通过终端登录，运行如下命令：
|
||
```bash
|
||
fly auth login
|
||
```
|
||
|
||
## 配置你的 Vapor 项目
|
||
在部署到 Fly 之前，确保你的 Vapor 项目包含一个配置好的 Dockerfile 文件。因为 Fly 需要使用它来构建你的应用程序。在大多数情况下，这很容易，因为默认的 Vapor 模板已经包含了一个 Dockerfile 文件 。
|
||
|
||
### 创建新的 Vapor 项目
|
||
创建新项目的最简单方式是使用模板。你可以使用 GitHub 模板或 Vapor 工具箱创建模板。如果你需要一个数据库，推荐使用 Fluent 和 Postgres；Fly 可以轻松创建一个 Postgres 数据库，以便连接你的应用程序（请参阅下面的[具体章节](#postgres)）。
|
||
|
||
#### 使用 Vapor 工具箱
|
||
首先，确保你已安装了 Vapor 工具箱（请参见 [macOS](../install/macos.zh.md#install-toolbox) 或 [Linux](../install/linux.zh.md#install-toolbox) 的安装说明）。使用以下命令创建新应用程序，替换 `app-name` 为所需的应用程序名称：
|
||
```bash
|
||
vapor new app-name
|
||
```
|
||
|
||
该命令将显示一个交互式提示，让你配置 Vapor 项目，如果需要，你可以在此选择 Fluent 和 Postgres 。
|
||
|
||
#### 使用 GitHub 模板
|
||
在以下列表中选择最适合你需求的模板。你可以使用 Git 将其克隆到本地，也可以使用“使用此模板”按钮创建一个 GitHub 项目。
|
||
|
||
- [Barebones template](https://github.com/vapor/template-bare)
|
||
- [Fluent/Postgres template](https://github.com/vapor/template-fluent-postgres)
|
||
- [Fluent/Postgres + Leaf template](https://github.com/vapor/template-fluent-postgres-leaf)
|
||
|
||
### 已有的 Vapor 项目
|
||
如果你有一个现有的 Vapor 项目，请确保项目的根目录中有一个正确配置的 `Dockerfile` 文件；[Vapor 文档中关于使用 Docker](../deploy/docker.zh.md) 和 [Fly 文档中关于通过 Dockerfile 部署应用程序](https://fly.io/docs/languages-and-frameworks/dockerfile/)可能会对你有所帮助。
|
||
|
||
## 在 Fly 上启动应用
|
||
一旦你的 Vapor 项目准备就绪，就可以在 Fly 上启动它。
|
||
|
||
首先，确保你的当前目录设置为 Vapor 应用程序的根目录，并运行以下命令：
|
||
```bash
|
||
fly launch
|
||
```
|
||
|
||
这将启动一个交互式提示，以配置你的 Fly 应用程序设置：
|
||
|
||
- **Name:** 你可以输入一个名称，或保留空白以获取自动生成的名称。
|
||
- **Region:** 默认情况下，为用户当前所在区域。你可以选择使用它或列表中的任何其他区域。后期可以更改。
|
||
- **Database:** 你可以要求 Fly 创建一个数据库与应用程序一起使用。如果你愿意，你始终可以使用 `fly pg create` 和 `fly pg attach` 命令进行相同的操作（详细信息，请参阅[配置 Postgres 部分](#postgres)。
|
||
|
||
`fly launch` 命令会自动创建一个 `fly.toml` 文件。它包含私有/公共端口映射、健康检查参数等设置。如果你刚刚使用 `vapor new` 从头开始创建了一个新项目，则默认的 `fly.toml` 文件不需要更改。如果你有一个现有的项目，则 `fly.toml` 可能只需要进行轻微的更改。你可以在 [fly.toml 文档](https://fly.io/docs/reference/configuration/)中找到更多信息。
|
||
|
||
请注意，如果你请求 Fly 创建一个数据库，则必须等待一段时间才能创建并通过健康检查。
|
||
|
||
在退出之前，`fly launch` 命令将询问你是否要立即部署应用程序。你可以接受或稍后使用 `fly deploy` 进行部署。
|
||
|
||
!!! tip "建议"
|
||
当前目录在你的应用程序根目录中时，fly CLI 工具会自动检测到 `fly.toml` 文件的存在，从而让 Fly 知道命令作用于哪个应用程序。如果你想无论在哪个目录都能针对特定的应用程序，请在大多数 Fly 命令后面附加 `-a 你的应用程序名称`。
|
||
|
||
## 部署
|
||
每当你部署新更改到 Fly 时，运行 `fly deploy` 命令。
|
||
|
||
Fly 会读取你的目录中的 `Dockerfile` 和 `fly.toml` 文件来确定如何构建和运行你的 Vapor 项目。
|
||
|
||
一旦你的容器构建完成，Fly 会启动一个实例。它将运行各种健康检查，确保你的应用程序正常运行并且你的服务器响应请求。如果健康检查失败，`fly deploy` 命令将退出并显示错误消息。
|
||
|
||
默认情况下，如果新版本健康检查失败，Fly 会回滚到最新的可用版本。
|
||
|
||
## 配置 Postgres
|
||
|
||
### 在 Fly 上创建一个 Postgres 数据库
|
||
如果你在第一次启动应用时没有创建数据库应用，你可以使用以下命令创建：
|
||
```bash
|
||
fly pg create
|
||
```
|
||
|
||
这个命令创建了一个 Fly 应用程序，可以为其他 Fly 上的应用程序提供数据库服务，详情请参阅 [Fly 文档](https://fly.io/docs/postgres/)。
|
||
|
||
创建完数据库应用之后，进入你的 Vapor 应用程序的根目录，运行以下命令：
|
||
```bash
|
||
fly pg attach name-of-your-postgres-app
|
||
```
|
||
|
||
如果你不知道你的 Postgres 应用程序的名称，可以使用 `fly pg list` 命令查找。
|
||
|
||
`fly pg attach` 命令创建了一个数据库和一个专门针对你的应用程序的用户，然后通过 `DATABASE_URL` 环境变量将其暴露给你的应用程序。
|
||
|
||
!!! note "注意"
|
||
`fly pg create` 和 `fly pg attach` 的区别在于前者分配和配置了一个能够托管 Postgres 数据库的 Fly 应用程序，而后者则创建了一个实际的数据库和用户，以供你选择的应用程序使用。只要符合你的要求，单个 Postgres Fly 应用程序就可以托管多个由不同应用程序使用的数据库。当你在 `fly launch` 中请求 Fly 创建一个数据库应用程序时，Fly 会执行相当于调用 `fly pg create` 和 `fly pg attach` 两个命令的操作。
|
||
|
||
### 连接 Vapor 应用程序到数据库
|
||
一旦你的应用程序已连接到数据库，Fly 会将 `DATABASE_URL` 环境变量设置为包含你的凭据的连接 URL（它应该被视为敏感信息）。
|
||
|
||
对于大多数常见的 Vapor 项目设置，你可以在 `configure.swift` 文件中配置你的数据库。下面是你可能想要执行的操作：
|
||
|
||
```swift
|
||
if let databaseURL = Environment.get("DATABASE_URL") {
|
||
try app.databases.use(.postgres(url: databaseURL), as: .psql)
|
||
} else {
|
||
// 在这里处理缺少 DATABASE_URL 的情况...
|
||
//
|
||
// 或者，你也可以根据 app.environment 是否设置为 .development 或 .production 来设置不同的配置
|
||
}
|
||
```
|
||
|
||
此时，你的项目应该已准备好运行迁移并使用数据库了。
|
||
|
||
### 运行迁移
|
||
使用 `fly.toml` 的 `release_command`，可以要求 Fly 在运行主服务器进程之前运行某个命令。将其添加到 `fly.toml` 中：
|
||
```toml
|
||
[deploy]
|
||
release_command = "migrate -y"
|
||
```
|
||
|
||
!!! note "注意"
|
||
上面的代码片段假设你正在使用默认的 Vapor Dockerfile，该文件将你的应用程序 `ENTRYPOINT` 设置为 `./App`。具体来说，这意味着当你将 `release_command` 设置为 `migrate -y` 时，Fly 将调用 `./App migrate -y`。如果你的 `ENTRYPOINT` 设置为其他值，则需要调整 `release_command` 的值。
|
||
|
||
Fly 将在具有访问 Fly 内部网络、密钥和环境变量的临时实例中运行你的发布命令。
|
||
|
||
如果你的发布命令失败，部署将无法继续。
|
||
|
||
### 其他数据库
|
||
虽然 Fly 使创建 Postgres 数据库应用程序变得容易，但也可以托管其他类型的数据库（例如，请参阅 Fly 文档中的 [”使用 MySQL 数据库“](https://fly.io/docs/app-guides/mysql-on-fly/)）。
|
||
|
||
|
||
## 密钥和环境变量
|
||
### 密钥
|
||
使用密钥将任何敏感值设置为环境变量。
|
||
```bash
|
||
fly secrets set MYSECRET=A_SUPER_SECRET_VALUE
|
||
```
|
||
|
||
!!! warning "警告"
|
||
请注意，大多数 shell 都会保留你输入的命令历史记录。在使用此方式设置密钥时要注意。某些 shell 可以配置为不记录以空格为前缀的命令。请参阅 [`fly secrets import` 命令](https://fly.io/docs/flyctl/secrets-import/)的文档。
|
||
|
||
更多信息，请参阅 [`fly secrets` 文档](https://fly.io/docs/apps/secrets/) 。
|
||
|
||
### 环境变量
|
||
你可以在 [`fly.toml`](https://fly.io/docs/reference/configuration/#the-env-variables-section) 中设置其他非敏感的环境变量，例如：
|
||
|
||
```toml
|
||
[env]
|
||
MAX_API_RETRY_COUNT = "3"
|
||
SMS_LOG_LEVEL = "error"
|
||
```
|
||
|
||
## SSH连接
|
||
你可以使用以下方式连接到应用实例：
|
||
```bash
|
||
fly ssh console -s
|
||
```
|
||
|
||
## 查看日志
|
||
你可以使用以下命令查看应用程序的实时日志：
|
||
```bash
|
||
fly logs
|
||
```
|
||
|
||
## 下一步
|
||
现在，你的 Vapor 应用已经部署完成，你可以进行更多操作，例如在多个区域垂直和水平扩展你的应用程序、添加持久卷、设置持续部署，甚至创建分布式应用程序集群。学习如何执行这些操作的最好地方是查看 [Fly 文档](https://fly.io/docs/)。
|
||
|