本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在本地运行 X-Ray 进程守护程序
在本地运行进程守护程序

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

你可以在 Linux、macOS、Windows 或 Docker 容器中本地运行 Amazon X-Ray 守护程序。当您在开发和测试经过检测的应用程序时，运行进程守护程序可将跟踪数据中继到 X-Ray。使用[此处](xray-daemon.md#xray-daemon-downloading)的说明下载并解压缩进程守护程序。

在本地运行时，守护程序可以从 Amazon SDK 凭据文件（`.aws/credentials`在您的用户目录中）或环境变量中读取凭据。有关更多信息，请参阅 [授予进程守护程序向 X-Ray 发送数据的权限](xray-daemon.md#xray-daemon-permissions)。

进程守护程序在端口 2000 上侦听 UDP 数据。您可以使用配置文件和命令行选项更改端口和其他选项。有关更多信息，请参阅 [配置 Amazon 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`目录的只读访问权限，使其能够读取您的 Amazon 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 &
```