本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 測試和疑難排解與 Proton for Amazon GameLift Streams 的相容性 如果您的 Amazon GameLift Streams 應用程式在 Proton 執行時間環境中執行，本節可協助您疑難排解應用程式與 Proton layer 之間的相容性問題。這些指示包括一組指令碼，可將 Proton 安裝到您自己的機器，模擬 Amazon GameLift Streams 將使用的環境。透過不使用 Amazon GameLift Streams 服務進行故障診斷，您可以專注於針對應用程式和執行時間環境的特定問題進行故障診斷。 ## 測試和疑難排解的高階步驟 1. 取得 Ubuntu 22.04 LTS 機器。您可以使用本機電腦或 Amazon EC2 雲端桌面。從下列主題中選擇以取得指示： + [設定本機機器](troubleshoot-compatibility-setup-local.md) + [設定遠端機器](troubleshoot-compatibility-setup-remote.md) 1. 安裝 Proton 執行時間環境來測試和偵錯您的應用程式。如需指引[Proton 上的故障診斷](troubleshoot-compatibility-wp-proton.md)，請參閱 。 ## Proton 的已知問題 如需最新的相容性和故障診斷資源，請參閱 [Proton GitHub wiki](https://github.com/ValveSoftware/Proton/wiki)。您也可以在 Proton GitHub 問題[追蹤器中搜尋問題](https://github.com/ValveSoftware/Proton/issues)。以下是客戶在 Proton 上執行 Windows 應用程式時遇到的一些特定問題： **Proton 上的 Godot 應用程式** + 如果啟用 Amazon Vulkan 擷取層，在 Proton 上執行的 Godot 型應用程式可能會遇到黑色畫面。若要緩解此問題，請設定環境變數 ，在串流時停用共用紋理`VK_LAYER_AMZN_BLITSURFACE_SHARED_TEXTURES=0`。 **Proton 上的 Unreal Engine 應用程式** + 如果您使用 Electra Media Player (Unreal Engine 外掛程式） 在 Proton 8.x 上遇到問題，我們建議您使用 [https://github.com/ValveSoftware/wine/pull/257](https://github.com/ValveSoftware/wine/pull/257)：// 中找到的修正。 # 設定本機機器對 Proton 進行故障診斷 Proton 是一種相容性層，可讓 Windows 應用程式在 Linux 上執行。因此，您必須擁有 Ubuntu 機器來進行測試和故障診斷。如果您沒有本機 Ubuntu 機器，您可以使用 Amazon EC2 設定遠端機器。若要這樣做，[設定遠端機器](troubleshoot-compatibility-setup-remote.md)請改為遵循 中的步驟。 ## 先決條件 + [Ubuntu 22.04 LTS](https://releases.ubuntu.com/jammy/)。如需安裝說明，您可以使用 Ubuntu 的[安裝 Ubuntu 桌面](https://ubuntu.com/tutorials/install-ubuntu-desktop)教學課程。 + NVIDIA GPU ## 安裝 GPU 驅動程式 安裝最新的 GPU 驅動程式可防止應用程式效能不佳和當機。 **若要檢查您的系統使用哪些 GPU 驅動程式** 1. 在終端機執行下列命令︰ ``` lshw -C display | grep driver ``` 1. 如果安裝正確的驅動程式，您應該會看到以下輸出或類似的輸出，其中 ** `nvidia`適用於 NVIDIA： `configuration: driver= latency=0` **安裝最新的 NVIDIA GPU 驅動程式** 遵循 [NVIDIA 驅動程式安裝](https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/)中的指示。 ## 驗證 GPU 驅動程式 確認 GPU 驅動程式已安裝並正常運作。其中一種驗證方式是在終端機中執行 [vkcube](https://github.com/krh/vkcube) 應用程式。 1. 使用下列命令安裝 `vulkan-tools` apt 套件。 ``` sudo apt install -y vulkan-tools ``` 1. 執行 `vkcube`。 1. 檢閱輸出。 + 如果您的系統正確使用正確的 GPU，您會看到類似以下的輸出，並顯示 GPU 的名稱： `Selected GPU 0: AMD Radeon Pro V520 (RADV NAVI12), type: 2` + 如果您的應用程式無法正確使用 GPU，您可能會看到類似下列的不同輸出： `Selected GPU 0: llvmpipe (LLVM 15.0.7, 256 bits), type: 4` 在此情況下，請檢查 GPU 驅動程式並視需要重新安裝。 ## 下一步驟 本機 Ubuntu 機器準備就緒後，下一步是設定 Proton。如需說明，請參閱 [Proton 上的故障診斷](troubleshoot-compatibility-wp-proton.md)。 # 設定遠端 Amazon EC2 機器來疑難排解 Proton 如果您沒有本機 Ubuntu 機器，請依照這些指示改為設定遠端機器。 在此步驟中，您將使用 Amazon Elastic Compute Cloud (Amazon EC2) 設定遠端 Ubuntu 機器，以針對應用程式與 Amazon GameLift Streams 的 Proton 相容性進行疑難排解。本主題說明如何使用 Ubuntu 22.04 LTS、必要的 GPU 驅動程式和視覺化遠端桌面的 Amazon DCV Server 設定 Amazon EC2 執行個體。 ## 使用 Ubuntu 22.04 LTS AMI 啟動 Amazon EC2 執行個體 1. 在 AWS 管理主控台中導覽至 Amazon EC2。 1. 選取**啟動執行個體**。 1. 輸入**名稱**的「Amazon GameLift Streams Testing」。 1. 針對應用程式和作業系統映像 **(Amazon Machine Image) 選取 Ubuntu Server 22.04 LTS (HVM**)。 **** 1. 選取**執行個體類型的** **g4dn.2xlarge**。 1. 對於**金鑰對 （登入）**，如果您想要使用 SSH 存取執行個體，請選擇金鑰對。我們建議您將執行個體描述檔與 `AmazonSSMManagedInstanceCore`政策搭配使用，以使用 連線至您的執行個體 AWS Systems Manager Session Manager。如需詳細資訊，請遵循[將工作階段管理員許可新增至現有 IAM 角色](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-add-permissions-to-existing-profile.html)。 1. 針對**網路設定**，建立新的安全群組： 1. 針對**安全群組名稱**，輸入 **DCV。** 1. 新增**類型**為 `Custom TCP`、**連接埠範圍** `8443`和**來源類型的****傳入安全群組規則**`Anywhere`，以允許使用 Amazon DCV 進行存取。 1. 將儲存體增加到至少 **256 GiB**，然後選擇 **gp3** 作為儲存體類型。 1. 選擇**啟動執行個體**。 您的執行個體現在應該已啟動。 請遵循[連線至 Linux 執行個體](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html)中的指示，使用 SSH 或 連線至執行個體 AWS Systems Manager Session Manager。 ## 安裝 GPU 驅動程式 ### G4dn - NVIDIA GPU 執行下列命令來安裝其他模組和 Linux 韌體： ``` sudo apt install linux-modules-extra-aws linux-firmware # Install the AWS CLI required for NVIDIA driver installation curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" sudo apt install unzip unzip awscliv2.zip sudo ./aws/install ``` 在 [Linux 上安裝 NVIDIA 驅動程式時，請遵循適用於 Ubuntu 和 Debian 的 NVIDIA GRID 驅動程式](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/install-nvidia-driver.html)上的指示。 ## 設定使用者環境 設定您的使用者環境，使其可以執行下列命令來使用 GPU。這會執行下列動作： + 將您新增至`video`群組，以讓您存取視訊裝置，而 `render`群組可讓您存取轉譯裝置。 + 安裝 NVIDIA 驅動程式和從 Amazon S3 下載應用程式或遊戲 AWS CLI所需的 。 ``` sudo adduser user # Add the current user to the video and render group sudo usermod -a -G video user sudo usermod -a -G render user sudo adduser user sudo # Install the AWS CLI curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" sudo apt install unzip unzip awscliv2.zip sudo ./aws/install sudo reboot ``` ## Amazon DCV 的安裝和組態 使用 SSH 或 重新連線至執行個體， AWS Systems Manager Session Manager 並遵循[在適用於 Ubuntu 的 Linux 上安裝 Amazon DCV 伺服器](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux.html)的指示。 + 確認已如 文件所述正確設定伺服器。 + 請遵循[安裝和設定 NVIDIA GPU 的 NVIDIA 驅動程式](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gpu)中的步驟。 + 將 Amazon DCV 使用者新增至視訊群組，如[安裝伺服器指南的步驟 7](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-server.html) 所述 （導覽至 Ubuntu 索引標籤）。 您不需要安裝 Amazon DCV Server 的任何選用部分。 完成後，請執行下列命令來啟動 Amazon DCV 伺服器： ``` sudo systemctl start dcvserver sudo systemctl enable dcvserver ``` ## 使用 Amazon DCV 用戶端連線至 Ubuntu 伺服器 重新連線至 Ubuntu 執行個體，並執行下列動作為使用者建立工作階段： ``` sudo dcv create-session --owner user --user user my-session --type console ``` 您現在可以使用 Amazon DCV 用戶端，使用其公有 IP 地址存取 Ubuntu 執行個體。當您啟動 Amazon DCV 用戶端時，會出現視窗，讓您透過視覺化顯示來存取 Ubuntu 執行個體。 ![\[當您啟動 Amazon DCV 用戶端時，會出現視窗，讓您透過視覺化顯示來存取 Ubuntu 執行個體。\]](http://docs.aws.amazon.com/zh_tw/gameliftstreams/latest/developerguide/images/troubleshoot-compatibility-setup-remote-dcv.png) ## 驗證 GPU 驅動程式 確認 GPU 驅動程式已安裝並正常運作。其中一種驗證方式是在終端機中執行 [vkcube](https://github.com/krh/vkcube) 應用程式。 1. 使用下列命令安裝 `vulkan-tools` apt 套件。 ``` sudo apt install -y vulkan-tools ``` 1. 執行 `vkcube`。 1. 檢閱輸出。 + 如果您的系統正確使用正確的 GPU，您會看到類似以下的輸出，並顯示 GPU 的名稱： `Selected GPU 0: AMD Radeon Pro V520 (RADV NAVI12), type: 2` + 如果您的應用程式無法正確使用 GPU，您可能會看到類似下列的不同輸出： `Selected GPU 0: llvmpipe (LLVM 15.0.7, 256 bits), type: 4` 在此情況下，請檢查 GPU 驅動程式並視需要重新安裝。 ## 設定 Podman （僅限質子） 如果您使用的是 Proton 執行期，則必須安裝 [Podman](https://wiki.debian.org/Podman)，這是 Proton 建置程序所使用的容器。在終端機中完成下列步驟。 1. 安裝 Podman，這是 Proton 建置程序使用的容器。 ``` sudo apt install podman ``` 1. 在 檔案`/etc/subgid`和 中 `/etc/subgid` 1. 確認檔案列出您的 Linux 機器使用者名稱和密碼。您可以開啟檔案或使用 `cat`命令來查看檔案中的內容。格式範例：`test:165536:65536`，其中 `test`對應於您的使用者名稱。 1. 如果未列出，請將它們新增至其中。格式範例：`test:165536:65536`，其中 `test`對應於您的使用者名稱。 ``` $ cat /etc/subuid ceadmin:100000:65536 test:165536:65536 $ cat /etc/subgid ceadmin:100000:65536 test:165536:65536 ``` 如需詳細資訊，請參閱 [Podman 文件中無根環境中 Podman 的基本設定和使用](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md#basic-setup-and-use-of-podman-in-a-rootless-environment)。 ## 下一步驟 您現在已設定 Amazon EC2 執行個體和環境，以疑難排解 Amazon GameLift Streams 的相容性問題。下一步是設定 Proton。如需說明，請參閱 [Proton 上的故障診斷](troubleshoot-compatibility-wp-proton.md)。 # 針對 Proton 上的相容性進行故障診斷 在此步驟中，您將在自己的機器上設定 Proton，以便疑難排解 Amazon GameLift Streams 應用程式與 Proton 之間的相容性問題。在沒有 Amazon GameLift Streams 伺服器的模擬環境中執行應用程式，可協助您識別應用程式和執行時間環境的特定問題。 ## 先決條件 + Ubuntu 22.04 LTS 已安裝 GPU 驅動程式。如需說明，請參閱 [設定本機機器](troubleshoot-compatibility-setup-local.md)或 [設定遠端機器](troubleshoot-compatibility-setup-remote.md)。 ## 安裝 Proton 若要在 Ubuntu 22.04 LTS 機器上安裝 Proton，請使用下列指令碼複製、建置和設定您要從 Proton [ GitHub 儲存庫測試的 Proton](https://github.com/ValveSoftware/Proton/) 版本。 1. 將下列程式碼複製並貼到您的 Ubuntu 22.04 LTS 機器`proton-setup.sh`上名為 的檔案。 ``` #!/bin/bash # This is a script to build Proton. The default build is a tag from the # experimental_9.0 branch of Proton, but can be changed as a parameter to this script. # # Usage: ./proton-setup.sh [optional proton_branch_name {default: experimental-9.0-20241121b}] set -e sudo apt install -y podman make git # clone proton from github, recurse submodules # if no proton git link is supplied, use a default tag from the experimental_8.0 branch PROTON_BRANCH=${1:-"experimental-9.0-20241121b"} PROTON_BUILD_DIR=protonBuild PROTON_DIR=$(pwd)/proton if git clone https://github.com/ValveSoftware/Proton.git --recurse-submodules --branch $PROTON_BRANCH proton; then echo "Successfully cloned Proton and its submodules." else echo "Warning: a proton directory/repository already exists. It is recommended to delete this folder and re-run this script unless it is a valid repository with initialized submodules." fi if [ -d $PROTON_BUILD_DIR ]; then echo "Error: protonBuild directory already exists. Delete this folder first to create a fresh build of Proton before re-running this script." exit 1 fi mkdir $PROTON_BUILD_DIR cd $PROTON_BUILD_DIR $PROTON_DIR/configure.sh --enable-ccache --container-engine=podman # build proton echo "Building Proton" make echo "Done building Proton!" # prepare proton for execution cd dist mkdir compatdata if [ -e ./dist ]; then PROTON_FILES=dist elif [ -e ./files ]; then PROTON_FILES=files fi cp version $PROTON_FILES/ echo "Finished installing proton. Proton binary location: $(pwd)/proton" echo "STEAM_COMPAT_DATA_PATH: $(pwd)/compatdata" echo "STEAM_COMPAT_CLIENT_INSTALL_PATH: anything" ``` 1. 在此步驟中，您將執行 Proton 設定指令碼來複製和安裝 Proton 和其他相依性。指令碼接受您要安裝之 Proton 版本的標籤或分支名稱做為引數。若要模擬 Amazon GameLift Streams 提供的其中一個 Proton 自訂組建，請使用以下該版本的說明。 **注意** 預期從 GitHub 複製需要一些時間。有許多子模組可供下載，總計數 GB。 在您的終端機中，執行`proton-setup.sh`指令碼並指定 Proton 版本分支： + **內建 Proton 版本** + 針對 Proton 9.0-2 (`PROTON-20250516`)，請使用 [experimental-9.0-20241121b。](https://github.com/ValveSoftware/Proton/tree/experimental-9.0-20241121b) ``` proton-setup.sh experimental-9.0-20241121b ``` + 針對 Proton 8.0-5 (`PROTON-20241007`)，請使用 [experimental-8.0-20240205。](https://github.com/ValveSoftware/Proton/tree/experimental-8.0-20240205) ``` proton-setup.sh experimental-8.0-20240205 ``` 一般而言，不需要額外的原始程式碼。不過，如果您遇到 Electra Media Player (Unreal Engine 外掛程式） 的問題，建議您使用 https：//[https://github.com/ValveSoftware/wine/pull/257](https://github.com/ValveSoftware/wine/pull/257) 中找到的修正。 **注意** 對於 Proton 8.0-2c (`PROTON-20230704`)，Amazon GameLift Streams 使用專屬建置，此建置無法在本機進行膨脹。 + **建議的自訂 Proton 版本** 對於自訂 Proton 版本，建議使用 Proton experimental\$18.0 分支。 ``` proton-setup.sh experimental_8.0 ``` + **其他自訂 Proton 版本** 對於其他 Proton 版本，請使用 [Proton 版本](https://github.com/ValveSoftware/Proton/releases)中列出的確切分支或標籤名稱。 ``` proton-setup.sh branch-or-tag-name ``` 如果您的安裝成功，終端機中的輸出應該類似下列內容： ``` ... Done building Proton! Finished preparing proton. Proton binary location: /home/test/protonBuild/dist/proton STEAM_COMPAT_DATA_PATH: /home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH: anything ``` 請記下輸出中的下列變數，因為在下一個步驟中，您將需要這些變數來執行 Proton： + Proton 二進位位置 + `STEAM_COMPAT_DATA_PATH` + `STEAM_COMPAT_CLIENT_INSTALL_PATH` ## 在 Proton 上執行您的應用程式 下列步驟假設應用程式可執行檔位於 中`path/myapplication/bin/application.exe`。將其取代為應用程式的路徑和檔案名稱。 + 在終端機中，導覽至應用程式可執行檔所在的資料夾。 ``` cd path/myapplication/bin/application.exe ``` + 在 Proton 上執行您的應用程式。使用您在上一個步驟中取得的 Proton 二進位位置和環境變數。 ``` STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe ``` 應用程式現在應嘗試啟動。如果應用程式在本機啟動，但未在 Amazon GameLift Streams 上啟動，則可能是由於呼叫 Amazon GameLift Streams APIs 時發生組態問題所致。驗證 API 呼叫參數是否正確。否則，請繼續下一個除錯步驟。 ## 透過日誌檔案對應用程式進行偵錯 如果您的應用程式在本機 Proton 環境上執行時發生問題，請檢查輸出日誌。日誌包含來自您應用程式和執行期環境的輸出。追蹤應用程式無法發現應用程式端問題的位置。 若要將日誌輸出傾印到文字檔案中，例如 `proton.log`，請使用下列命令： ``` STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe &>proton.log ``` Proton 也會指出問題是否是由於Wine 外掛程式、未實作的函數、缺少 dll 等。如需詳細資訊，請參閱「[Wine HQ 的 DebuggingWine ](https://wiki.winehq.org/Wine_Developers_Guide/Debugging_Wine)指南」。如果您在應用程式端無法修正的日誌中發現 Proton 或 Honey 錯誤，請聯絡您的 AWS 客戶經理或在 [AWS re：Post](https://repost.aws/tags/TAOU7EpUOuTQSSWmIHCfb2fQ/amazon-gamelift-streams) 中張貼問題，以協助進一步偵錯。