问题排查

我们收集了最常见的已知问题，并在此处列出。如果此处没有描述您的问题，请查看以下 GitHub 存储库中的未解决问题

有问题吗？请阅读我们的常见问题解答，或在讨论论坛中与我们联系。您的反馈对我们非常重要。

是否正在独立运行 Elastic Agent？另请参阅调试独立的 Elastic Agent。

在以下文档中查找有关 Fleet、Fleet Server 和 Elastic Agent 的问题排查信息

在 Fleet 中，如果您删除与一个或多个处于非活动状态的已注册 Agent 关联的 Elastic Agent 策略，当 Agent 返回到 Healthy 或 Offline 状态时，将无法取消注册。尝试取消注册 Agent 会导致 Error unenrolling agent 消息，并且取消注册失败。

要解决此问题，您可以使用Kibana Fleet API强制取消注册 Agent。

要卸载单个 Elastic Agent

POST kbn:/api/fleet/agents/<agent_id>/unenroll
{
  "force": true,
  "revoke": true
}

要批量卸载一组 Elastic Agent

POST kbn:/api/fleet/agents/bulk_unenroll
{ "agents": ["<agent_id1>", "<agent-id2>"],
  "force": true,
  "revoke": true
}

我们还在更新 Fleet UI，以防止删除当前与任何非活动 Agent 关联的 Elastic Agent 策略。

当您使用启用了 TSDB（时间序列数据库）的 Elastic Agent 集成时，您可能会在 Fleet UI 中遇到 illegal_argument_exception 错误。

如果您的组件模板定义包含 _source 属性，而该属性与启用 TSDB 时使用的 _source: synthetic 设置冲突，则可能会发生这种情况。

有关该错误以及如何解决该错误的详细信息，请参阅创新中心文章为 Elastic Agent 启用 TSDB 集成中“运行时字段不能用于 TSDB 索引”部分。

在 Elastic Cloud 中，在升级 Fleet Server 及其集成策略后，在 Elastic Cloud Agent 策略中注册的 Agent 可能会在更新时遇到问题。要解决此问题

如果您无法在 Kibana 中看到 Fleet Server，请确保已设置它。

要在 Elastic Cloud 上设置 Fleet Server

要在自托管集群上启用 Fleet 并设置 Fleet Server

要安装集成，Fleet 应用程序需要连接到名为 Elastic Package Registry 的外部服务。

要使其正常工作，Kibana 服务器必须连接到端口 443 上的 https://epr.elastic.co。

在气隙环境中，如果您使用的是 Kibana 不可用的自定义证书颁发机构 (CA)，则可能会遇到以下错误

{"type":"log","@timestamp":"2022-03-02T09:58:36-05:00","tags":["error","plugins","fleet"],"pid":58716,"message":"Error connecting to package registry: request to https://customer.server.name:8443/categories?experimental=true&include_policy_templates=true&kibana.version=7.17.0 failed, reason: self signed certificate in certificate chain"}

要解决此问题，请通过定义 NODE_EXTRA_CA_CERTS 环境变量，将 CA 证书文件路径添加到 Kibana 启动文件。有关此方面的更多信息，请参见Elastic Package Registry 的 TLS 配置部分。

为确保与 Fleet Server 的通信已加密，Fleet Server 要求 Elastic Agent 提供签名证书。在自托管集群中，如果您在设置 Fleet Server 时未指定证书，则会自动生成自签名证书。

如果您尝试在带有自签名证书的 Fleet Server 中注册 Elastic Agent，则会遇到以下错误

Error: fail to enroll: fail to execute request to fleet-server: x509: certificate signed by unknown authority
Error: enroll command failed with exit code: 1

要解决此问题，请在 enroll 或 install 命令中传递 --insecure 标志。例如

sudo ./elastic-agent install --url=https://<fleet-server-ip>:8220 --enrollment-token=<token> --insecure

Elastic Agent 和 Fleet Server 之间通过 HTTPS 传输的流量将被加密；您只是在承认您了解无法验证证书链。

允许 Fleet Server 生成自签名证书对于启动开发工作很有用，但不建议在生产环境中使用。

有关更多信息，请参阅为自托管的 Fleet Server 配置 SSL/TLS。

为确保与 Elasticsearch 的通信已加密，Fleet Server 要求 Elasticsearch 提供签名证书。

当您使用以 IP 作为通用名称 (CN) 的 Elasticsearch 自签名证书时，会发生此错误。当 IP 作为 CN 时，Fleet Server 会查看主体备用名称 (SAN)，该名称为空。要解决此问题，请使用 --fleet-server-es-insecure 标志禁用证书验证。

您还需要在 Fleet 和集成 UI 的输出设置中设置 ssl.verification_mode: none。

要在 Fleet 中注册，Elastic Agent 必须连接到 Fleet Server 实例。如果 Agent 无法连接，您将看到以下故障

fail to enroll: fail to execute request to {fleet-server}:Post http://fleet-server:8220/api/fleet/agents/enroll?: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

以下是帮助您排查问题的几个步骤。

Fleet Server 允许 Elastic Agent 连接到 Elasticsearch，这与之前版本中连接到 Kibana 的方式相同。但是，由于 Fleet Server 位于边缘主机上，因此可能会导致额外的网络设置和故障排除。

运行以下命令以查看 Elastic Agent 的当前状态。

elastic-agent status

根据返回的信息，您可以采取进一步的操作。

如果 Elastic Agent 正在运行，但您没有看到期望的结果，请查看以下事项

Elastic Agent 诊断包收集以下信息

请注意，诊断包仅用于调试目的，其结构可能在不同版本之间发生变化。

使用 CLI 获取诊断包

运行以下命令生成包含诊断信息的 zip 存档，Elastic 团队可以使用这些信息来调试案例。

elastic-agent diagnostics

如果要从诊断中省略原始事件，请添加标志 --exclude-events。

通过 Fleet 获取诊断包

Fleet 提供了远程生成和收集 Elastic Agent 诊断包的功能。如果代理在线且处于 健康 或 不健康 状态，则可以收集并上传诊断信息。诊断信息将发送到 Fleet Server，然后将其添加到 Elasticsearch 中。因此，即使对于未使用 Elasticsearch 输出的 Elastic Agent，此功能也有效。要下载诊断包以供本地查看

此页面上将列出 Elastic Agent 的任何正在进行或以前收集的捆绑包。

请注意，捆绑包存储在 Elasticsearch 中，并在 7 天后自动删除。您还可以通过单击 垃圾桶 图标来删除任何先前创建的捆绑包。

如果某些问题发生得很早，并且没有足够的日志可用，请运行以下命令

./elastic-agent install -f

独立的安装命令会安装 Elastic Agent，并且会设置所有服务配置。现在您可以运行 _注册_ 命令。例如

elastic-agent enroll --fleet-server-es=https://<es-url>:443 --fleet-server-service-token=<token> --fleet-server-policy=<policy-id>

注意：端口 443 通常在 Elastic Cloud 中使用。但是，对于自管理部署，您的 Elasticsearch 可能在端口 9200 或完全不同的端口上运行。

有关在何处查找代理日志的信息，请参阅我们的 FAQ。

从 Elastic Stack 8.11 版本开始，应该会自动检测到卡住的 Elastic Agent 升级，您可以从 Fleet 重新启动升级。

某些设置仅在您有多个 Elastic Agent 时使用。如果是这种情况，检查主机是否可以与 Fleet Server 通信可能会有所帮助。

从非 Fleet Server 主机运行以下命令

curl -f http://<fleet-server-ip>:8220/api/status

响应可能会产生您可以进一步调试的错误，或者它可能有效并表明通信端口和网络不是问题。

一个常见的问题是，Fleet Server 的默认端口 8220 未在 Fleet Server 主机上打开以进行通信。您可以使用常用工具根据您可能存在的任何网络和安全问题来查看和纠正此问题。

为了保存 API 密钥并在 Elasticsearch 中对其进行加密，Fleet 需要一个加密密钥。

要提供 API 密钥，请在 kibana.yml 配置文件中，设置 xpack.encryptedSavedObjects.encryptionKey 属性。

xpack.encryptedSavedObjects.encryptionKey: "something_at_least_32_characters"

确保运行 Elastic Agent 的用户具有 root 权限，因为某些集成需要 root 权限才能收集敏感数据。

如果您在 Linux 或 macOS 上在前台（而不是作为服务）运行 Elastic Agent，请在 root 用户下运行代理：sudo 或 su。

如果您正在使用 Elastic Defend 集成，请确保在 SYSTEM 帐户下运行 Elastic Agent。

要在 SYSTEM 帐户下运行 Elastic Agent，您可以执行以下操作

如果您尝试升级一个版本过旧的集成策略，则可能会出现大量的冲突或配置问题。与其尝试解决这些问题，不如创建一个新的策略，对其进行测试，并将集成升级推广到其他主机可能会更快。

在升级集成之后

取消注册 Elastic Agent 时，Fleet 会等待代理的确认，然后才会完成取消注册过程。如果 Fleet 没有收到确认，则状态会停留在 unenrolling。

您可以取消注册代理，以使所有与该代理相关的 API 密钥失效，并将状态更改为 inactive，这样该代理将不再出现在 Fleet 中。

您可能会由于多种不同的原因看到此错误消息。一个常见原因是，在尝试类似生产环境的使用时，找不到传入的 ca.crt 文件。要验证是否是此问题，请在不传入 ca.crt 文件的情况下引导 Fleet Server。这意味着您将临时使用 {fleet-sever} 自己的自签名证书来测试任何后续的 Elastic Agent 安装。

当您在 Elastic Agent 安装过程中看到以下错误时，您就知道您的 Fleet Server 已设置为使用其面向测试的自签名证书：

Error: fail to enroll: fail to execute request to fleet-server: x509: certificate signed by unknown authority
Error: enroll command failed with exit code: 1

要针对自签名证书 Fleet Server Elastic Agent 进行安装或注册，请将 --insecure 选项添加到命令中。

sudo ./elastic-agent install --url=https://<fleet-server-ip>:8220 --enrollment-token=<token> --insecure

有关更多信息，请参阅主机上 Elastic Agent 注册失败，并显示 x509: certificate signed by unknown authority 消息。

当您卸载 Elastic Agent 时，由 Elastic Agent 管理的所有程序（如 Elastic Endpoint）也会被删除。如果卸载失败，Elastic Endpoint 可能会保留在您的系统中。

要删除 Elastic Endpoint，请运行以下命令

cd /tmp
cp /Library/Elastic/Endpoint/elastic-endpoint elastic-endpoint
sudo ./elastic-endpoint uninstall
rm elastic-endpoint

cd /tmp
cp /opt/Elastic/Endpoint/elastic-endpoint elastic-endpoint
sudo ./elastic-endpoint uninstall
rm elastic-endpoint

cd %TEMP%
copy "c:\Program Files\Elastic\Endpoint\elastic-endpoint.exe" elastic-endpoint.exe
.\elastic-endpoint.exe uninstall
del .\elastic-endpoint.exe

默认情况下，Elastic Stack 中启用了遥测功能，以帮助我们了解用户最感兴趣的功能。这有助于我们将精力集中在改进功能上。

如果您最近从 7.10 版本升级到 7.11 版本，则在查看 Elastic Defend 日志时可能会看到以下消息：

action [indices:admin/auto_create] is unauthorized for API key id [KbvCi3YB96EBa6C9k2Cm]
of user [fleet_enroll] on indices [.logs-endpoint.diagnostic.collection-default]

以上消息表明 Elastic Endpoint 没有发送遥测数据的正确权限。这是 7.11 中的已知问题，将在即将发布的补丁版本中修复。

要从日志中删除此消息，您可以关闭 Elastic Defend 集成的遥测功能，直到下一个补丁版本可用。

为了扩展 Fleet Server 部署，当需要或不再需要托管的 Elastic Agent 时，Elastic Cloud 会启动新容器或关闭旧容器。旧的 Elastic Agent 将在 Agent 列表中显示 24 小时，然后自动消失。

如果您在 macOS 系统上使用 localhost (https://127.0.0.1:8220) 作为主机 URL 在本地测试 Fleet Server，则可能会遇到此错误：

Error: fail to enroll: fail to execute request to fleet-server:
lookup My-MacBook-Pro.local: no such host

这可能发生在较新的 macOS 软件上。要解决此问题，请确保在本地系统上启用了文件共享。

在某些情况下，如果手动修改了 Elastic Cloud 代理策略，则将 APM 和 Fleet 升级到 8.x 可能会失败。Kibana 中的 Fleet 应用程序可能会显示如下消息：

Unable to create package policy. Package 'apm' already exists on this agent policy

要解决此问题，您可以使用 API 调用重置 Elastic Cloud 代理策略。请注意，这将删除您添加到策略中的任何自定义集成策略，例如 Synthetics 监视器。

curl -u elastic:<password> --request POST \
  --url <kibana_url>/internal/fleet/reset_preconfigured_agent_policies/policy-elastic-agent-on-cloud \
  --header 'Content-Type: application/json' \
  --header 'kbn-xsrf: xyz'

在 8.9 及更高版本中，当升级程序无法访问验证二进制签名所需的 PGP 密钥时，Elastic Agent 升级可能会失败。有关详细信息和解决方法，请参阅 8.9.0 版本发行说明中的空载环境中 PGP 密钥下载失败已知问题，或参阅 elastic-agent GitHub 存储库中的解决方法文档。

当您使用 Fleet 管理的 Elastic Agent 时，至少需要一个 Elastic Agent 运行Fleet Server 集成。如果包含此集成的策略意外地从 Elastic Agent 中删除，则将无法管理所有其他代理。但是，Elastic Agent 将继续向其配置的输出发送数据。

有两种方法可以解决此问题，具体取决于运行 Fleet Server 集成的 Elastic Agent 是否仍已安装并运行正常（但现在正在运行另一个策略）。

要恢复 Elastic Agent：

运行这些步骤后，您的 Elastic Agent 应能够再次连接到 Fleet。

在 Kubernetes 环境中，由于可用内存不足，Elastic Agent 可能会因 OOMKilled 原因被终止。

要检测问题，请运行 kubectl describe pod 命令，并检查结果中是否包含以下内容：

       Last State:   Terminated
       Reason:       OOMKilled
       Exit Code:    137

要解决此问题，请为代理分配更多内存，然后重新启动它。

在 Linux 系统上，当您在没有管理权限的情况下安装 Elastic Agent 时（即使用 --unprivileged 标志），不应使用 sudo 运行 Elastic Agent 命令。这样做可能会导致错误，因为代理没有所需的权限。

例如，当您使用 --unprivileged 标志运行 Elastic Agent 时，运行 elastic-agent inspect 命令将导致如下错误：

Error: error loading agent config: error loading raw config: fail to read configuration /Library/Elastic/Agent/fleet.enc for the elastic-agent: fail to decode bytes: cipher: message authentication failed

要解决此问题，请在不使用 --unprivileged 标志的情况下安装 Elastic Agent，以便它具有管理访问权限，或者在不使用 sudo 前缀的情况下运行 Elastic Agent 命令。

Kubernetes 上 Elastic Agent 安装期间的潜在问题可以分为两个主要领域：

在使用 Kustomize 进行故障排除安装时，最好检查渲染清单的输出。为此，请使用 Kibana Onboarding 提供的安装命令，并将最后一部分 | kubectl apply -f- 替换为重定向到本地文件。这有助于更轻松地分析渲染的输出。

例如，以下命令最初由 Kibana 为 Elastic Agent Standalone 安装提供，并已修改为将输出重定向以进行故障排除：

kubectl kustomize https://github.com/elastic/elastic-agent/deploy/kubernetes/elastic-agent-kustomize/default/elastic-agent-standalone\?ref\=v8.15.3 | sed -e 's/JUFQSV9LRVkl/ZDAyNnZaSUJ3eWIwSUlCT0duRGs6Q1JfYmJoVFRUQktoN2dXTkd0FNMtdw==/g' -e "s/%ES_HOST%/https:\/\/7a912e8674a34086eacd0e3d615e6048.us-west2.gcp.elastic-cloud.com:443/g" -e "s/%ONBOARDING_ID%/db687358-2c1f-4ec9-86e0-8f1baa4912ed/g" -e "s/\(docker.elastic.co\/beats\/elastic-agent:\).*$/\18.15.3/g" -e "/{CA_TRUSTED}/c\ " > elastic_agent_installation_complete_manifest.yaml

前面的命令生成一个名为 elastic_agent_installation_complete_manifest.yaml 的本地文件，您可以将其用于进一步分析。它包含 Elastic Agent 安装所需的全套资源，包括：

此文件的内容等效于您按照在 Kubernetes 上运行 Elastic Agent Standalone 步骤获得的内容，但 kube-state-metrics 不包含在独立方法中。

可能的问题：

如果安装正确且所有资源都已部署，但数据未按预期流动（例如，您在 [指标 Kubernetes] 集群概览 仪表板上看不到任何数据），请检查以下项目

可能的问题：

有关 Kubernetes 上 Elastic Agent 故障排除和信息的其他资源