本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在本機執行 X-Ray 協助程式
**注意**
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
您可以在 Linux、MacOS、Windows AWS X-Ray 或 Docker 容器中於本機執行協助程式。當您開發和測試檢測應用程式時，執行協助程式將追蹤資料轉送至 X-Ray。透過使用[此處](xray-daemon.md#xray-daemon-downloading)的說明，下載並解壓縮精靈。
在本機執行時，協助程式可以從 AWS SDK 登入資料檔案 (`.aws/credentials`在您的使用者目錄中） 或從環境變數讀取登入資料。如需詳細資訊，請參閱[授予協助程式將資料傳送至 X-Ray 的許可](xray-daemon.md#xray-daemon-permissions)。
精靈會在連接埠 2000 接聽 UDP 資料。您可以透過使用組態檔和命令列選項來變更連接埠及其他選項。如需詳細資訊，請參閱[設定 AWS X-Ray 協助程式](xray-daemon-configuration.md)。
## 在 Linux 上執行 X-Ray 協助程式
您可以從命令列執行精靈的可執行檔。使用 `-o` 選向來在本機模式中執行，以及 `-n` 來設定區域。
```
~/xray-daemon$ ./xray -o -n us-east-2
```
若要在背景執行精靈，請使用 `&`。
```
~/xray-daemon$ ./xray -o -n us-east-2 &
```
使用 `pkill` 終止在背景執行的精靈程序。
```
~$ pkill xray
```
## 在 Docker 容器中執行 X-Ray 協助程式
若要在 Docker 容器內於本機執行精靈，請將以下文字儲存到名為 `Dockerfile` 的檔案。在 Amazon ECR 上下載完整的[範例映像](https://gallery.ecr.aws/xray/aws-xray-daemon)。如需詳細資訊[，請參閱下載協助程式](xray-daemon.md#xray-daemon-downloading)。
**Example Dockerfile – Amazon Linux**
```
FROM amazonlinux
RUN yum install -y unzip
RUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip
RUN unzip daemon.zip && cp xray /usr/bin/xray
ENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]
EXPOSE 2000/udp
EXPOSE 2000/tcp
```
使用 `docker build` 建置容器映像。
```
~/xray-daemon$ docker build -t xray-daemon .
```
使用 `docker run` 在容器中執行映像。
```
~/xray-daemon$ docker run \
--attach STDOUT \
-v ~/.aws/:/root/.aws/:ro \
--net=host \
-e AWS_REGION=us-east-2 \
--name xray-daemon \
-p 2000:2000/udp \
xray-daemon -o
```
此命令使用下列選項：
+ `--attach STDOUT` – 檢視終端機中協助程式的輸出。
+ `-v ~/.aws/:/root/.aws/:ro` – 允許容器唯讀存取 `.aws`目錄，讓它讀取您的 AWS SDK 登入資料。
+ `AWS_REGION=us-east-2` – 設定`AWS_REGION`環境變數以告知協助程式要使用的區域。
+ `--net=host` – 將容器連接至`host`網路。主機網路上的容器可彼此互相通訊，而無須透過連接埠發佈。
+ `-p 2000:2000/udp` – 將機器上的 UDP 連接埠 2000 映射至容器上的相同連接埠。這並非位於相同網路上容器進行通訊的必要項目，但它可讓您[從命令列](xray-api-sendingdata.md#xray-api-daemon)將區段傳送至精靈，或是從沒有在 Docker 中執行的應用程式傳送。
+ `--name xray-daemon` – 命名容器，`xray-daemon`而不是產生隨機名稱。
+ `-o` （在映像名稱之後） – 將 `-o`選項附加至在容器內執行協助程式的進入點。此選項會告知協助程式在本機模式下執行，以防止其嘗試讀取 Amazon EC2 執行個體中繼資料。
若要停止精靈，請使用 `docker stop`。若您變更 `Dockerfile` 並建置新的映像，您需要刪除現有的容器，才能使用相同名稱建立另一個容器。使用 `docker rm` 來刪除容器。
```
$ docker stop xray-daemon
$ docker rm xray-daemon
```
## 在 Windows 上執行 X-Ray 協助程式
您可以從命令列執行精靈的可執行檔。使用 `-o` 選向來在本機模式中執行，以及 `-n` 來設定區域。
```
> .\xray_windows.exe -o -n us-east-2
```
使用 PowerShell 指令碼來建立和執行精靈的服務。
**Example PowerShell 指令碼 - Windows**
```
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ){
sc.exe stop AWSXRayDaemon
sc.exe delete AWSXRayDaemon
}
if ( Get-Item -path aws-xray-daemon -ErrorAction SilentlyContinue ) {
Remove-Item -Recurse -Force aws-xray-daemon
}
$currentLocation = Get-Location
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"
$zipPath = "$currentLocation\$zipFileName"
$destPath = "$currentLocation\aws-xray-daemon"
$daemonPath = "$destPath\xray.exe"
$daemonLogPath = "C:\inetpub\wwwroot\xray-daemon.log"
$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath
Add-Type -Assembly "System.IO.Compression.Filesystem"
[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
sc.exe create AWSXRayDaemon binPath= "$daemonPath -f $daemonLogPath"
sc.exe start AWSXRayDaemon
```
## 在 OS X 上執行 X-Ray 協助程式
您可以從命令列執行精靈的可執行檔。使用 `-o` 選向來在本機模式中執行，以及 `-n` 來設定區域。
```
~/xray-daemon$ ./xray_mac -o -n us-east-2
```
若要在背景執行精靈，請使用 `&`。
```
~/xray-daemon$ ./xray_mac -o -n us-east-2 &
```
使用 `nohup` 來防止精靈在終端機關閉時終止。
```
~/xray-daemon$ nohup ./xray_mac &
```