本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 Amazon ECS 上執行 X-Ray 協助程式
<a name="xray-daemon-ecs"></a>

**注意**  
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)。

在 Amazon ECS 中，建立執行 X-Ray 協助程式的 Docker 映像，將其上傳至 Docker 映像儲存庫，然後將其部署到您的 Amazon ECS 叢集。您可以使用您任務定義檔案中的連接埠映射和網路模式設定，來允許應用程式與精靈容器通訊。

## 使用官方 Docker 映像檔
<a name="xray-daemon-ecs-image"></a>

X-Ray 在 Amazon ECR 上提供 Docker [容器映像](https://gallery.ecr.aws/xray/aws-xray-daemon)，您可以隨應用程式一起部署。如需詳細資訊[，請參閱下載協助程式](xray-daemon.md#xray-daemon-downloading)。

**Example 任務定義**  

```
    {
      "name": "xray-daemon",
      "image": "amazon/aws-xray-daemon",
      "cpu": 32,
      "memoryReservation": 256,
      "portMappings" : [
          {
              "hostPort": 0,
              "containerPort": 2000,
              "protocol": "udp"
          }
       ]
    }
```

## 建立和建置 Docker 影像
<a name="xray-daemon-ecs-build"></a>

用於自訂組態時，您可能需要定義自己的 Docker 影像。

將受管政策新增至您的任務角色，以授予協助程式將追蹤資料上傳至 X-Ray 的許可。如需詳細資訊，請參閱[授予協助程式將資料傳送至 X-Ray 的許可](xray-daemon.md#xray-daemon-permissions)。

使用以下其中一個 Dockerfiles 建立執行精靈的映像。

**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
```

**注意**  
指定要接聽多重容器環境迴路的繫結地址時，必須提供標記 `-t` 和 `-b`。

**Example Dockerfile – Ubuntu**  
若是 Debian 的衍生產品，您還需要安裝憑證授權機構 (CA) 憑證，以避免下載安裝程式時發生問題。  

```
FROM ubuntu:16.04
RUN apt-get update && apt-get install -y --force-yes --no-install-recommends apt-transport-https curl ca-certificates wget && apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*
RUN wget https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.deb
RUN dpkg -i aws-xray-daemon-3.x.deb
ENTRYPOINT ["/usr/bin/xray", "--bind=0.0.0.0:2000", "--bind-tcp=0.0.0.0:2000"]
EXPOSE 2000/udp
EXPOSE 2000/tcp
```

在您的任務定義中，組態取決於您使用的聯網模式。預設值是橋接聯網，可在您的預設 VPC 中使用。在橋接網路中，設定`AWS_XRAY_DAEMON_ADDRESS`環境變數以告知 X-Ray SDK 要參考和設定主機連接埠的容器連接埠。舉例來說，您可以發佈 UDP 連接埠 2000，然後建立您應用程式容器與精靈容器的連結。

**Example 任務定義**  

```
    {
      "name": "xray-daemon",
      "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon",
      "cpu": 32,
      "memoryReservation": 256,
      "portMappings" : [
          {
              "hostPort": 0,
              "containerPort": 2000,
              "protocol": "udp"
          }
       ]
    },
    {
      "name": "scorekeep-api",
      "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api",
      "cpu": 192,
      "memoryReservation": 512,
      "environment": [
          { "name" : "AWS_REGION", "value" : "us-east-2" },
          { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" },
          { "name" : "AWS_XRAY_DAEMON_ADDRESS", "value" : "xray-daemon:2000" }
      ],
      "portMappings" : [
          {
              "hostPort": 5000,
              "containerPort": 5000
          }
      ],
      "links": [
        "xray-daemon"
      ]
    }
```

若您在 VPC 私有子網路中執行您的叢集，您可以使用 [`awsvpc` 網路模式](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html)來將彈性網路界面 (ENI) 連接到您的容器。這可讓您避免使用連結。忽略連接埠映射、連結，以及 `AWS_XRAY_DAEMON_ADDRESS` 環境變數中的主機連接埠。

**Example VPC 任務定義**  

```
{
    "family": "scorekeep",
    "networkMode":"awsvpc",
    "containerDefinitions": [
        {
          "name": "xray-daemon",
          "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon",
          "cpu": 32,
          "memoryReservation": 256,
          "portMappings" : [
              {
                  "containerPort": 2000,
                  "protocol": "udp"
              }
          ]
        },
        {
            "name": "scorekeep-api",
            "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api",
            "cpu": 192,
            "memoryReservation": 512,
            "environment": [
                { "name" : "AWS_REGION", "value" : "us-east-2" },
                { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" }
            ],
            "portMappings" : [
                {
                    "containerPort": 5000
                }
            ]
        }
    ]
}
```

## 在 Amazon ECS 主控台中設定命令列選項
<a name="xray-daemon-ecs-cmdline"></a>

命令列選項會覆寫影像組態檔中的任何衝突值。命令列選項通常用於本機測試，但也可以在設定環境變數或控制啟動程序時使用。

透過新增命令列選項，您將更新傳遞給容器的 Docker `CMD`。如需詳細資訊，請參閱 [Docker 執行參考](https://docs.docker.com/engine/reference/run/#overriding-dockerfile-image-defaults)。

**若要設定命令列選項**

1. 開啟 Amazon ECS 傳統主控台，網址為 [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/)。

1. 從導覽列中選擇包含您任務定義的區域。

1. 在導覽窗格中，選擇 **Task Definitions** (任務定義)。

1. 在 **Task Definitions** (任務定義) 頁面中，選取要修訂之任務定義左側的方塊，並選擇 **Create new revision** (建立新修訂版)。

1. 在 **Create new revision of Task Definition** (建立任務定義的新修訂版) 頁面上，選取容器。

1. 在 **ENVIRONMENT** (環境) 區段中，將逗號分隔的命令列選項清單新增至 **Command** (命令) 欄位。

1. 選擇**更新**。

1. 驗證資訊，然後選擇 **Create** (建立)。

下列範例顯示如何為 `RoleARN` 選項撰寫逗號分隔的命令列。`RoleARN` 選項會擔任指定的 IAM 角色，將區段上傳至不同的帳戶。

**Example**  

```
--role-arn, arn:aws:iam::{{123456789012}}:role/{{xray-cross-account}}
```

若要進一步了解 X-Ray 中可用的命令列選項，請參閱[設定 AWS X-Ray 協助程式](xray-daemon-configuration.md)。