From 598a10751e0623078ef7c313ac974c34adaed384 Mon Sep 17 00:00:00 2001 From: JIN Date: Sun, 19 Feb 2023 21:41:10 +0800 Subject: [PATCH] update cn doc (#769) Co-authored-by: Tim Condon <0xTim@users.noreply.github.com> --- docs/advanced/sessions.zh.md | 2 +- docs/deploy/digital-ocean.zh.md | 88 +++++++++++++++++++----------- docs/security/authentication.zh.md | 4 ++ 3 files changed, 60 insertions(+), 34 deletions(-) diff --git a/docs/advanced/sessions.zh.md b/docs/advanced/sessions.zh.md index 630df1f5..052f0278 100644 --- a/docs/advanced/sessions.zh.md +++ b/docs/advanced/sessions.zh.md @@ -4,7 +4,7 @@ 会话非常适合内置在 Vapor 中的前端应用程序，这些应用程序直接向浏览器提供 HTML。对于 API，在请求之间保留用户数据，我们建议使用无状态、[基于令牌的身份验证](../security/authentication.md)方式。 -## 配置 +## 配置(Configuration) 要在路由中使用会话，请求必须通过 `SessionsMiddleware` 中间件。 最简单的实现方式是全局添加此中间件。建议你在声明 Cookie 后添加此代码。这是因为 Sessions 是一个结构体，它是一个值类型，而不是引用类型。因为它是值类型，所以必须先设置该值才能使用 `SessionsMiddleware`。 diff --git a/docs/deploy/digital-ocean.zh.md b/docs/deploy/digital-ocean.zh.md index b4255cd2..f6dd4526 100644 --- a/docs/deploy/digital-ocean.zh.md +++ b/docs/deploy/digital-ocean.zh.md @@ -8,12 +8,12 @@ ![Create Droplet](../images/digital-ocean-create-droplet.png) -在发行版下，选择 Ubuntu 18.04 LTS。以下指南将以此版本为例。 +在发行版下，选择 Ubuntu 22.04 LTS。以下指南将以此版本为例。 ![Ubuntu Distro](../images/digital-ocean-distributions-ubuntu.png) !!! note "注意" - 你也可以选择 Swift 支持的其它 Linux 发行版。在撰写本文时， Swift 5.2.4 支持 Ubuntu 16.04、18.04、20.04、CentOS 8, 和 Amazon Linux 2。你可以在 [Swift Releases](https://swift.org/download/#releases) 页面上查看官方支持哪些操作系统。 + 你也可以选择 Swift 支持的其它 Linux 发行版。在撰写本文时， Swift 5.7.3 支持 Ubuntu 18.04、20.04、22.04、CentOS 7, 和 Amazon Linux 2。你可以在 [Swift Releases](https://swift.org/download/#releases) 页面上查看官方支持哪些操作系统。 选择完发行版后，选择你喜欢的套餐和数据中心所在区域。然后设置一个 SSH 密钥以在创建服务器后访问它。最后， 点击创建 Droplet 并等待新服务器启动。 @@ -29,7 +29,7 @@ ssh root@your_server_ip ``` -在 [Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-18-04) 上初始化服务器设置，DigitalOcean 提供了深入指南。 本指南将快速介绍一些基础知识。 +在 [Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-22-04) 上初始化服务器设置，DigitalOcean 提供了深入指南。 本指南将快速介绍一些基础知识。 ### 配置防火墙 @@ -77,38 +77,40 @@ ssh vapor@your_server_ip ```sh sudo apt-get update -sudo apt-get install clang libicu-dev libatomic1 build-essential pkg-config +sudo apt-get install binutils git gnupg2 libc6-dev libcurl4-openssl-dev + \ libedit2 libgcc-9-dev libpython3.8 libsqlite3-0 libstdc++-9-dev + \ libxml2-dev libz3-dev pkg-config tzdata unzip zlib1g-dev ``` -### 下载 Toolchain +### 下载 Swift Toolchain -本指南将安装 Swift 5.2.4。访问 [Swift Releases](https://swift.org/download/#releases) 页面获取最新版本的链接。复制 Ubuntu 18.04 的下载链接。 +本指南将安装 Swift 5.7.3。访问 [Swift Releases](https://swift.org/download/#releases) 页面获取最新版本的链接。复制 Ubuntu 22.04 的下载链接。 ![Download Swift](../images/swift-download-ubuntu-copy-link.png) 下载并解压 Swift toolchain。 ```sh -wget https://swift.org/builds/swift-5.2.4-release/ubuntu1804/swift-5.2.4-RELEASE/swift-5.2.4-RELEASE-ubuntu18.04.tar.gz -tar xzf swift-5.2.4-RELEASE-ubuntu18.04.tar.gz +wget https://download.swift.org/swift-5.7.3-release/ubuntu2204/swift-5.7.3-RELEASE/swift-5.7.3-RELEASE-ubuntu22.04.tar.gz +tar xzf swift-5.7.3-RELEASE-ubuntu22.04.tar.gz ``` !!! note "注意" Swift 的[使用下载指南](https://swift.org/download/#using-downloads)包含有关如何使用 PGP 签名验证下载的信息。 -### 安装 Toolchain +### 安装 Swift Toolchain 将 Swift 移到易于访问的地方。本指南将 `/swift` 与子文件夹中的每个编译器版本一起使用。 ```sh sudo mkdir /swift -sudo mv swift-5.2.4-RELEASE-ubuntu18.04 /swift/5.2.4 +sudo mv swift-5.7.3-RELEASE-ubuntu22.04 /swift/5.7.3 ``` 将 Swift 添加到 `/usr/bin` 以便 `vapor` 和 `root` 用户可以执行。 ```sh -sudo ln -s /swift/5.2.4/usr/bin/swift /usr/bin/swift +sudo ln -s /swift/5.7.3/usr/bin/swift /usr/bin/swift ``` 验证 Swift 是否正确安装。 @@ -117,52 +119,72 @@ sudo ln -s /swift/5.2.4/usr/bin/swift /usr/bin/swift swift --version ``` -## 设置项目 +## 使用 Vapor 工具箱安装 Vapor -现在已经安装了 Swift，让我们克隆并编译项目。本示例，我们使用 Vapor 的 [API 模板](https://github.com/vapor/api-template/)。 +现在已经安装了 Swift，让我们 Vapor工具箱来安装 Vapor。你需要通过源码在构建工具箱。在 GitHub 上查看工具箱的[发布](https://github.com/vapor/toolbox/releases)版本，以查找最新版本。在本例中，我们使用 18.6.0 版本。 -首先安装 Vapor 的系统依赖项。 +### 克隆并构建 Vapor + +克隆 Vapor 工具箱仓库。 ```sh -sudo apt-get install openssl libssl-dev zlib1g-dev libsqlite3-dev +git clone https://github.com/vapor/toolbox.git ``` -允许 HTTP 通过防火墙。 +切换到最近的发布版本。 ```sh -sudo ufw allow http +cd toolbox +git checkout 18.6.0 ``` -### 克隆和构建 - -现在克隆项目并构建它。 +构建 Vapor 并将二进制文件移动到你的 path 中。 ```sh -git clone https://github.com/vapor/api-template.git -cd api-template -swift build +swift build -c release --disable-sandbox --enable-test-discovery +sudo mv .build/release/vapor /usr/local/bin +``` + +### 创建 Vapor 项目 + +使用工具箱的 new 命令初始化项目。 + +```sh +vapor new HelloWorld -n ``` !!! tip "建议" - 如果生产环境进行构建， 请使用 `swift build -c release` + `-n` 标志表示自动回答所有问题为 no，并提供一个基础的模板。 + + +![Vapor Splash](../images/vapor-splash.png) + +命令执行完成后，切换到新创建的文件夹: + +```sh +cd HelloWorld +``` + +### 打开 HTTP 端口 + +为了访问服务器上的 Vapor 程序，需要开启相应 HTTP 端口。 + +```sh +sudo ufw allow 8080 +``` ### 运行 -项目编译完成后，在服务器的 IP 端口80上运行它。本示例的 IP 地址为 `157.245.244.228`。 +现在 Vapor 已经设置好了，并且有了公开的端口，让我们启动它吧。 ```sh -sudo .build/debug/Run serve -b 157.245.244.228:80 +vapor run serve --hostname 0.0.0.0 --port 8080 ``` -如果你使用 `swift build -c release` 进行构建, 然后你需要运行： -```sh -sudo .build/release/Run serve -b 157.245.244.228:80 -``` - -通过浏览器或者本地终端访问服务器的 IP， 你应该会看到 “It works!”。 +通过浏览器或者本地终端访问服务器的 IP， 你应该会看到 “It works!”。本例中的 IP 地址为 `134.122.126.139`。 ``` -$ curl http://157.245.244.228 +$ curl http://134.122.126.139:8080 It works! ``` diff --git a/docs/security/authentication.zh.md b/docs/security/authentication.zh.md index 78ffe9cf..19ffbaf9 100644 --- a/docs/security/authentication.zh.md +++ b/docs/security/authentication.zh.md @@ -744,6 +744,10 @@ app.middleware.use(User.sessionAuthenticator()) * 会话中间件获取请求中提供的会话 cookie 并将其转换为会话 * 会话身份认证器获取会话，并查看该会话是否有经过身份验证的用户。如果是，中间件对请求进行身份验证。在响应中，会话身份认证器查看请求是否具有经过身份验证的用户，并将其保存在会话中，以便在下一个请求中对其进行身份验证。 +!!! note "注意" + 默认情况下会话 cookie 不会设置为 `secure` 和 `httpOnly`。查看 [Session API](../advanced/sessions.zh.md#configuration) 获取更多关于配置 cookie 的信息。 + + ### 保护路由 当保护 API 的路由时，如果请求没有经过身份验证，通常会返回一个包含状态码（比如 **401 未经授权**）的 HTTP 响应。然而，对于使用浏览器的用户来说，这并不是一个很好的用户体验。Vapor 提供了一个 `RedirectMiddleware` 中间件，用于该场景中的任何 `Authenticatable` 类型：