本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 本地代理
本地代理通过安全连接使用安全隧道传输源设备上运行的应用程序发送的数据。 WebSocket 您可以从中下载本地代理源[GitHub](https://github.com/aws-samples/aws-iot-securetunneling-localproxy)。
本地代理可以在两种模式下运行：`source` 或 `destination`。在源模式下，本地代理与启动 TCP 连接的客户端应用程序在同一设备或网络上运行。在目标模式下，本地代理与目标应用程序一起在远程设备上运行。通过使用隧道多路复用功能，一条隧道一次最多可以支持三个数据流。对于每个数据流，安全隧道使用多个 TCP 连接，这将减小发生超时的几率。有关更多信息，请参阅 [多路复用数据流并在安全隧道中使用同步 TCP 连接](multiplexing.md)。
# 如何使用本地代理
您可以在源设备和目标设备上运行本地代理，将数据传输到安全隧道端点。如果您的设备位于使用 Web 代理的网络中，Web 代理可以在将连接转发到互联网之前拦截它们。在这种情况下，您需要配置本地代理，才能使用 Web 代理。有关更多信息，请参阅 [为使用 Web 代理的设备配置本地代理](configure-local-proxy-web-proxy.md)。
## 本地代理工作流
以下步骤展示如何在源设备和目标设备上运行本地代理。
1.
**将本地代理连接到安全隧道**
首先，本地代理必须与安全隧道建立连接。启动本地代理时，请使用以下参数：
+ 用于指定 AWS 区域 在其中打开隧道的`-r`参数。
+ `-t` 参数，用于传递从 `OpenTunnel` 返回的源或目标客户端访问令牌。
**注意**
不能同时连接两个使用相同客户端访问令牌值的本地代理。
1.
**执行源操作或目标操作**
建立 WebSocket 连接后，本地代理将根据其配置执行源模式或目标模式操作。
默认情况下，如果出现任何 input/output （I/O）错误或连接意外关闭，本地代理会尝试重新连接到安全隧道。 WebSocket 这会导致 TCP 连接关闭。如果出现任何 TCP 套接字错误，本地代理将通过隧道发送一条消息，通知对方关闭其 TCP 连接。预设情况下，本地代理始终使用 SSL 通信。
1.
**终止本地代理**
当您使用隧道后，可以安全地终止本地代理进程。我们建议您通过调用 `CloseTunnel` 显式关闭隧道。调用 `CloseTunnel` 后可能不会立即关闭活动隧道客户端。
有关如何使用打开隧道和启动 SSH 会话的更多信息，请参阅[打开隧道并启动与远程设备的 SSH 会话](secure-tunneling-tutorial-open-tunnel.md)。 AWS 管理控制台
## 本地代理最佳实践
运行本地代理时，请遵循以下最佳实践：
+ 避免使用本地代理参数 `-t` 传入访问令牌。我们建议您使用 `AWSIOT_TUNNEL_ACCESS_TOKEN` 环境变量设置本地代理的访问令牌。
+ 在操作系统或环境中以最少权限运行本地代理可执行文件。
+ 避免以管理员身份在 Windows 上运行本地代理。
+ 避免以 root 身份在 Linux 和 macOS 上运行本地代理。
+ 考虑在单独的主机、容器、沙盒、chroot jail 或虚拟化环境上运行本地代理。
+ 使用相关安全标志构建本地代理，具体取决于您的工具链。
+ 在具有多个网络接口的设备上，使用 `-b` 参数将 TCP 套接字绑定到用于与目标应用程序通信的网络接口。
## 命令和输出示例
下面显示了您运行的命令示例以及相应的输出。该示例说明如何在 `source` 和 `destination` 模式下配置本地代理。本地代理将 HTTPS 协议升级 WebSockets 为以建立长寿命连接，然后开始通过连接将数据传输到安全隧道设备端点。
**在运行这些命令之前：**
您必须已打开隧道并获得源和目标的客户端访问令牌。您还必须已按照前面所述构建本地代理。要构建本地代理，请在 GitHub 存储库中打开[本地代理源代码](https://github.com/aws-samples/aws-iot-securetunneling-localproxy)，然后按照说明构建和安装本地代理。
**注意**
示例中使用的以下命令使用 `verbosity` 标志来说明运行本地代理后先前描述的不同步骤概览。建议您仅将此标记用于测试。
**在源模式下运行本地代理**
以下命令展示如何在源模式下运行本地代理。
------
#### [ Linux/macOS ]
在 Linux 或 macOS 的终端中运行以下命令来配置和启动源上的本地代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
./localproxy -s 5555 -v 5 -r us-west-2
```
其中：
+ `-s` 是源侦听端口，用于在源模式下启动本地代理。
+ `-v` 表示输出的详细程度，可以是 0 到 6 之间的值。
+ `-r` 是打开隧道的终端节点区域。
有关这些参数的更多信息，请参阅[使用命令行参数设置的选项](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#options-set-via-command-line-arguments)。
------
#### [ Windows ]
在 Windows 中，您可以配置本地代理，操作类似于 Linux 或 macOS 的配置，但是如何定义环境变量则与其它平台不同。在 `cmd` 窗口中运行以下命令来配置和启动源上的本地代理。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
.\localproxy -s 5555 -v 5 -r us-west-2
```
其中：
+ `-s` 是源侦听端口，用于在源模式下启动本地代理。
+ `-v` 表示输出的详细程度，可以是 0 到 6 之间的值。
+ `-r` 是打开隧道的终端节点区域。
有关这些参数的更多信息，请参阅[使用命令行参数设置的选项](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#options-set-via-command-line-arguments)。
------
**注意**
在源模式下使用最新版本的本地代理时，为了向后兼容，必须在源设备`--destination-client-type V1`上包含该 AWS CLI 参数。这在连接到以下任何目标模式时适用：
AWS IoT 设备客户端
AWS IoT 安全隧道组件或 AWS IoT Greengrass Version 2 安全隧道组件
2022 年之前编写的任何 AWS IoT 安全隧道演示代码
1.X 版本的本地代理
此参数可确保更新的源代理与旧版目标客户端之间的正常通信。有关本地代理版本的更多信息，请参阅上的 [AWS IoT Secure Tunneling](https://github.com/aws-samples/aws-iot-securetunneling-localproxy/blob/main/README.md#as-of-312-may-2024-update---destination-client-type-v1-will-be-a-required-parameter-when-connecting-with-the-following)。*GitHub*
以下内容是在 `source` 模式下运行本地代理的示例输出。
```
...
...
Starting proxy in source mode
Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Resolved proxy server IP: 10.10.0.11
Connected successfully with proxy server
Performing SSL handshake with proxy server
Successfully completed SSL handshake with proxy server
HTTP/1.1 101 Switching Protocols
...
Connection: upgrade
channel-id: 01234567890abc23-00001234-0005678a-b1234c5de677a001-2bc3d456
upgrade: websocket
...
Web socket session ID: 01234567890abc23-00001234-0005678a-b1234c5de677a001-2bc3d456
Web socket subprotocol selected: aws.iot.securetunneling-2.0
Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Setting up web socket pings for every 5000 milliseconds
Scheduled next read:
...
Starting web socket read loop continue reading...
Resolved bind IP: 127.0.0.1
Listening for new connection on port 5555
```
**在目标模式下运行本地代理**
以下命令展示如何在目标模式下运行本地代理。
------
#### [ Linux/macOS ]
在 Linux 或 macOS 的终端中运行以下命令来配置和启动目标上的本地代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
./localproxy -d 22 -v 5 -r us-west-2
```
其中：
+ `-d` 是在目标模式下启动本地代理的目标应用程序。
+ `-v` 表示输出的详细程度，可以是 0 到 6 之间的值。
+ `-r` 是打开隧道的终端节点区域。
有关这些参数的更多信息，请参阅[使用命令行参数设置的选项](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#options-set-via-command-line-arguments)。
------
#### [ Windows ]
在 Windows 中，您可以配置本地代理，操作类似于 Linux 或 macOS 的配置，但是如何定义环境变量则与其它平台不同。在 `cmd` 窗口中运行以下命令来配置和启动目标上的本地代理。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
.\localproxy -d 22 -v 5 -r us-west-2
```
其中：
+ `-d` 是在目标模式下启动本地代理的目标应用程序。
+ `-v` 表示输出的详细程度，可以是 0 到 6 之间的值。
+ `-r` 是打开隧道的终端节点区域。
有关这些参数的更多信息，请参阅[使用命令行参数设置的选项](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#options-set-via-command-line-arguments)。
------
**注意**
在目标模式下使用最新版本的本地代理时，为了向后兼容，必须在目标设备`--destination-client-type V1`上包含该 AWS CLI 参数。这在连接到以下任一源模式时适用：
通过控制台进行基于浏览器的安全隧道传输。 AWS
1.X 版本的本地代理
此参数可确保更新的目标代理与旧版源客户端之间的正常通信。有关本地代理版本的更多信息，请参阅上的 [AWS IoT Secure Tunneling](https://github.com/aws-samples/aws-iot-securetunneling-localproxy/blob/main/README.md#as-of-312-may-2024-update---destination-client-type-v1-will-be-a-required-parameter-when-connecting-with-the-following)。*GitHub*
以下内容是在 `destination` 模式下运行本地代理的示例输出。
```
...
...
Starting proxy in destination mode
Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Resolved proxy server IP: 10.10.0.11
Connected successfully with proxy server
Performing SSL handshake with proxy server
Successfully completed SSL handshake with proxy server
HTTP/1.1 101 Switching Protocols
...
Connection: upgrade
channel-id: 01234567890abc23-00001234-0005678a-b1234c5de677a001-2bc3d456
upgrade: websocket
...
Web socket session ID: 01234567890abc23-00001234-0005678a-b1234c5de677a001-2bc3d456
Web socket subprotocol selected: aws.iot.securetunneling-2.0
Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Setting up web socket pings for every 5000 milliseconds
Scheduled next read:
...
Starting web socket read loop continue reading...
```
# 为使用 Web 代理的设备配置本地代理
您可以在 AWS IoT 设备上使用本地代理与 AWS IoT 安全隧道 APIs进行通信。本地代理通过安全连接使用安全隧道传输设备应用程序发送的数据。 WebSocket 本地代理可以以 `source` 或者 `destination` 模式工作。在 `source` 模式中，它在启动 TCP 连接的同一设备或网络上运行。在 `destination` 模式下，本地代理与目标应用程序一起在远程设备上运行。有关更多信息，请参阅 [本地代理](local-proxy.md)。
本地代理需要直接连接到互联网才能使用 AWS IoT 安全隧道。对于使用安全隧道的长期 TCP 连接，本地代理会升级 HTTPS 请求以建立与[安全隧道](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html)设备 WebSockets 连接端点之一的连接。
如果您的设备位于使用 Web 代理的网络中，Web 代理可以在将连接转发到互联网之前将其拦截。要建立与安全隧道设备连接端点的长期连接，请将本地代理配置为使用 Web 代理，如 [Websocket 规范](https://tools.ietf.org/html/rfc6455#section-4.1)中所述。
**注意**
[AWS IoT 设备客户端](iot-sdks.md#iot-sdk-device-client) 不支持使用 Web 代理的设备。要使用 Web 代理，您需要使用本地代理并将其配置为使用 Web 代理，如下所述。
以下步骤显示了本地代理如何与 Web 代理协同工作。
1. 本地代理发送一个 HTTP `CONNECT` 请求发送到包含安全隧道服务远程地址的 Web 代理服务，同时发布的还有 Web 代理身份验证信息。
1. 然后，Web 代理将创建到远程安全隧道端点的长期连接。
1. TCP 连接已建立，并且本地代理现在将在源模式和目标模式下工作以进行数据传输。
**Topics**
+ [构建本地代理](#build-local-proxy)
+ [配置 Web 代理](#configure-web-proxy)
+ [配置和启动本地代理](#configure-start-local-proxy)
## 构建本地代理
打开 GitHub 存储库中的[本地代理源代码](https://github.com/aws-samples/aws-iot-securetunneling-localproxy)，然后按照说明构建和安装本地代理。
## 配置 Web 代理
本地代理依赖于 HTTP 隧道机制，如 [HTTP/1.1 规范](https://tools.ietf.org/html/rfc7231#section-4.3.6)中所述。为了符合规范，您的 Web 代理必须允许设备使用 `CONNECT` 方法。
如何配置 Web 代理取决于您使用的 Web 代理和 Web 代理版本。要确保正确配置 Web 代理，请检查 Web 代理的文档。
要配置 Web 代理，请首先确定 Web 代理 URL 并确认 Web 代理是否支持 HTTP 隧道。稍后在配置和启动本地代理时，将使用 Web 代理 URL。
1.
**识别您的 Web 代理 URL**
您的 Web 代理 URL 采用以下格式。
```
protocol://web_proxy_host_domain:web_proxy_port
```
AWS IoT 安全隧道仅支持 Web 代理的基本身份验证。要使用基本身份验证，您必须指定 **username** 和 **password** 作为 Web 代理 URL 的一部分。Web 代理 URL 采用以下格式。
```
protocol://username:password@web_proxy_host_domain:web_proxy_port
```
+ *protocol*可以是`http`或`https`。建议使用 `https`。
+ *web\$1proxy\$1host\$1domain*是您的网络代理的 IP 地址或解析为 Web 代理的 IP 地址的 DNS 名称。
+ *web\$1proxy\$1port*是 Web 代理正在监听的端口。
+ Web 代理使用此 **username** 和 **password** 来验证请求。
1.
**测试您的 Web 代理 URL**
要确认您的 Web 代理是否支持 TCP 隧道，请使用 `curl` 命令，并确保您获得 `2xx` 或 `3xx` 响应。
例如，如果您的 Web 代理 URL 是 `https://server.com:1235`，请使用 `proxy-insecure` 标记与 `curl` 命令，因为 Web 代理可能依赖于自签名证书。
```
export HTTPS_PROXY=https://server.com:1235
curl -I https://aws.amazon.com --proxy-insecure
```
如果您的 Web 代理 URL 具有 `http` 端口（例如，`http://server.com:1234`），您不一定要使用 `proxy-insecure` 标记。
```
export HTTPS_PROXY=http://server.com:1234
curl -I https://aws.amazon.com
```
## 配置和启动本地代理
要配置本地代理以使用 Web 代理，您必须以 DNS 域名或 Web 代理所用的 IP 地址和端口号码来配置 `HTTPS_PROXY` 环境变量。
配置了本地代理后，您可以使用本地代理，如本[自述文件](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#readme)文档所述。
**注意**
环境变量声明区分大小写。我们建议您使用全部大写或全部小写字母定义每个变量一次。以下示例显示了全部使用大写字母的环境变量名称。如果同时使用大写字母和小写字母指定相同的变量，则使用小写字母指定的变量优先。
以下命令说明如何将目标上运行的本地代理配置为使用 Web 代理并启动本地代理。
+ `AWSIOT_TUNNEL_ACCESS_TOKEN`：此变量保存目标的客户端访问令牌（CAT）。
+ `HTTPS_PROXY`：此变量保存用于配置本地代理的 Web 代理 URL 或 IP 地址。
以下示例中显示的命令取决于您使用的操作系统以及 Web 代理侦听的是 HTTP 端口还是 HTTPS 端口。
### Web 代理侦听 HTTP 端口
如果您的 Web 代理正在侦听 HTTP 端口，您可以为 `HTTPS_PROXY` 变量提供 Web 代理 URL 或 IP 地址。
------
#### [ Linux/macOS ]
在 Linux 或 macOS 中，在终端中运行以下命令，以配置和启动目标上的本地代理，使用侦听 HTTP 端口的 Web 代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http:proxy.example.com:1234
./localproxy -r us-east-1 -d 22
```
如果您必须使用代理进行身份验证，则必须指定 **username** 和 **password** 作为 `HTTPS_PROXY` 变量的一部分。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http://username:password@proxy.example.com:1234
./localproxy -r us-east-1 -d 22
```
------
#### [ Windows ]
在 Windows 中，您可以配置本地代理，操作类似于 Linux 或 macOS 的配置，但是如何定义环境变量则与其它平台不同。在 `cmd` 窗口中运行以下命令以配置和启动目标上的本地代理，以使用侦听 HTTP 端口的 Web 代理。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
set HTTPS_PROXY=http://proxy.example.com:1234
.\localproxy -r us-east-1 -d 22
```
如果您必须使用代理进行身份验证，则必须指定 **username** 和 **password** 作为 `HTTPS_PROXY` 变量的一部分。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
set HTTPS_PROXY=http://username:password@10.15.20.25:1234
.\localproxy -r us-east-1 -d 22
```
------
### 侦听 HTTPS 端口的 Web 代理
如果您的 Web 代理正在侦听 HTTPS 端口，请运行以下命令。
**注意**
如果您为 Web 代理使用自签名证书，或者在不支持本机 OpenSSL 和默认配置的操作系统上运行本地代理，则必须按照存储库中 “证书设置” 部分所述设置 Web 代理[证书](https://github.com/aws-samples/aws-iot-securetunneling-localproxy#certificate-setup)。 GitHub
以下命令看起来与您为 HTTP 代理配置 Web 代理的方式相似，但您还需要指定您安装的证书文件的路径，如前所述。
------
#### [ Linux/macOS ]
在 Linux 或 macOS 中，在终端中运行以下命令，以配置目标上运行的本地代理，使其使用侦听 HTTPS 端口的 Web 代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http:proxy.example.com:1234
./localproxy -r us-east-1 -d 22 -c /path/to/certs
```
如果您必须使用代理进行身份验证，则必须指定 **username** 和 **password** 作为 `HTTPS_PROXY` 变量的一部分。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http://username:password@proxy.example.com:1234
./localproxy -r us-east-1 -d 22 -c /path/to/certs
```
------
#### [ Windows ]
在 Windows 中，在 `cmd` 窗口中运行以下命令以配置和启动目标上运行的本地代理，以使用侦听 HTTP 端口的 Web 代理。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
set HTTPS_PROXY=http://proxy.example.com:1234
.\localproxy -r us-east-1 -d 22 -c \path\to\certs
```
如果您必须使用代理进行身份验证，则必须指定 **username** 和 **password** 作为 `HTTPS_PROXY` 变量的一部分。
```
set AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
set HTTPS_PROXY=http://username:password@10.15.20.25:1234
.\localproxy -r us-east-1 -d 22 -c \path\to\certs
```
------
### 命令和输出示例
下面显示了在 Linux 操作系统上运行的命令示例以及相应的输出。该示例显示了正在侦听 HTTP 端口的 Web 代理，以及如何在 `source` 和 `destination` 模式下使用 Web 代理配置本地代理。在运行这些命令之前，您必须已打开隧道并获得源和目标的客户端访问令牌。您还必须已构建本地代理并按照前面所述配置 Web 代理。
以下是启动本地代理后的步骤概览。本地代理：
+ 标识 Web 代理 URL，以便它可以使用 URL 连接到代理服务器。
+ 建立与 Web 代理的 TCP 连接。
+ 发送 HTTP `CONNECT` 请求到 Web 代理，并等待 `HTTP/1.1 200` 响应，这表示连接已建立。
+ 将 HTTPS 协议升级 WebSockets 为以建立长期连接。
+ 开始通过与安全隧道设备端点的连接进行数据传输。
**注意**
示例中使用的以下命令使用 `verbosity` 标志来说明运行本地代理后先前描述的不同步骤概览。建议您仅将此标记用于测试。
**在源模式下运行本地代理**
以下命令显示如何在源模式下运行本地代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http:username:password@10.15.10.25:1234
./localproxy -s 5555 -v 5 -r us-west-2
```
以下显示了在 `source` 模式下运行本地代理的示例输出。
```
...
Parsed basic auth credentials for the URL
Found Web proxy information in the environment variables, will use it to connect via the proxy.
...
Starting proxy in source mode
Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Resolved Web proxy IP: 10.10.0.11
Connected successfully with Web Proxy
Successfully sent HTTP CONNECT to the Web proxy
Full response from the Web proxy:
HTTP/1.1 200 Connection established
TCP tunnel established successfully
Connected successfully with proxy server
Successfully completed SSL handshake with proxy server
Web socket session ID: 0a109afffee745f5-00001341-000b8138-cc6c878d80e8adb0-f186064b
Web socket subprotocol selected: aws.iot.securetunneling-2.0
Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Seting up web socket pings for every 5000 milliseconds
Scheduled next read:
...
Starting web socket read loop continue reading...
Resolved bind IP: 127.0.0.1
Listening for new connection on port 5555
```
**在目标模式下运行本地代理**
以下命令显示如何在目标模式下运行本地代理。
```
export AWSIOT_TUNNEL_ACCESS_TOKEN=${access_token}
export HTTPS_PROXY=http:username:password@10.15.10.25:1234
./localproxy -d 22 -v 5 -r us-west-2
```
以下显示了在 `destination` 模式下运行本地代理的示例输出。
```
...
Parsed basic auth credentials for the URL
Found Web proxy information in the environment variables, will use it to connect via the proxy.
...
Starting proxy in destination mode
Attempting to establish web socket connection with endpoint wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Resolved Web proxy IP: 10.10.0.1
Connected successfully with Web Proxy
Successfully sent HTTP CONNECT to the Web proxy
Full response from the Web proxy:
HTTP/1.1 200 Connection established
TCP tunnel established successfully
Connected successfully with proxy server
Successfully completed SSL handshake with proxy server
Web socket session ID: 06717bfffed3fd05-00001355-000b8315-da3109a85da804dd-24c3d10d
Web socket subprotocol selected: aws.iot.securetunneling-2.0
Successfully established websocket connection with proxy server: wss://data.tunneling.iot.us-west-2.amazonaws.com:443
Seting up web socket pings for every 5000 milliseconds
Scheduled next read:
...
Starting web socket read loop continue reading...
```