本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 如何使用本機代理
您可以在來源裝置和目的地裝置上執行本機代理，以將資料傳輸至安全通道端點。若您的裝置位於使用 Web 代理的網路中，Web 代理可在將連線轉送至網際網路之前加以攔截。在這種情況下，您需要將本機代理設定為使用 Web 代理。如需詳細資訊，請參閱[為使用 Web 代理的裝置配置本機代理](configure-local-proxy-web-proxy.md)。
## 本機代理工作流程
下列步驟顯示了本機代理如何在來源和目的地裝置上執行。
1.
**將本機代理連線至安全通道**
本機代理必須先建立安全通道的連線。當您啟動本機代理時，請使用下列引數：
+ 指定通道開啟 AWS 區域 所在 的`-r`引數。
+ `-t` 引數傳遞從 `OpenTunnel` 傳回的來源或目標用戶端存取字符。
**注意**
使用相同用戶端存取字符值的兩個本機代理不能同時連線。
1.
**執行來源或目的地動作**
建立 WebSocket 連線之後，本機代理會執行來源模式或目標模式動作，取決於其組態。
根據預設，如果發生任何輸入/輸出 (I/O) 錯誤，或 WebSocket 連線意外關閉，本機代理會嘗試重新連線至安全通道。這會導致 TCP 連線關閉。如果發生任何 TCP 通訊端錯誤，本機代理會透過通道傳送訊息，通知對方關閉其 TCP 連線。根據預設，本機代理一律使用 SSL 通訊。
1.
**停用本機代理**
使用通道之後，可以安全地停止本機代理程序。建議您呼叫 `CloseTunnel` 來明確地關閉通道。呼叫 後，作用中通道用戶端可能不會立即關閉`CloseTunnel`。
如需如何使用 AWS 管理主控台 開啟通道並啟動 SSH 工作階段的詳細資訊，請參閱 [開啟通道並啟動遠端裝置的 SSH 工作階段](secure-tunneling-tutorial-open-tunnel.md)。
## 本機代理最佳實務
執行本機代理時，請遵循下列最佳實務：
+ 避免使用 `-t` 本機代理引數傳入存取字符。建議您使用 `AWSIOT_TUNNEL_ACCESS_TOKEN` 環境變數來設定本機代理的存取字符。
+ 在作業系統或環境中以最低權限執行本機代理可執行檔。
+ 避免在 Windows 上以系統管理員身分執行本機代理。
+ 避免在 Linux 和 macOS 上以 root 身分執行本機代理。
+ 考慮在個別的主機、容器、沙箱，chroot jail 或虛擬化環境上執行本機代理。
+ 使用相關的安全旗標建置本地代理，具體取決於您的工具鏈。
+ 在具有多個網路界面的裝置上，使用 `-b` 引數將 TCP 通訊端繫結至用來與目標應用程式通訊的網路界面。
## 命令和輸出範例
下列會顯示您執行的命令範例和對應的輸出。此範例顯示如何在 `source` 和 `destination` 模式下設定本機 Proxy。本機代理程式會將 HTTPS 通訊協定升級至 WebSockets，以建立長期連線，然後開始透過連線將資料傳輸至安全通道裝置端點。
**在您執行這些命令之前：**
您必須先開啟通道並取得來源和目的地的用戶端存取字符。您亦須依照先前所述建置本機代理。於 GitHub 儲存庫中開啟[本機 Proxy 來源程式碼](https://github.com/aws-samples/aws-iot-securetunneling-localproxy)，並遵循建置和安裝本機 Proxy 的指示。
**注意**
用於範例中的下列命令會使用 `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 版本
此參數可確保更新後的來源代理與較舊的目的地用戶端之間進行適當的通訊。如需本機代理版本的詳細資訊，請參閱 *GitHub* 上的[AWS IoT 安全通道](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)。
以下是在 `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 版本
此參數可確保更新的目的地代理與較舊的來源用戶端之間進行適當的通訊。如需本機代理版本的詳細資訊，請參閱 *GitHub* 上的[AWS IoT 安全通道](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)。
以下是在 `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...
```