常见问题排查

我们收集了最常见的已知问题并列在此处。如果此处未描述您的问题，请查看以下 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 设置冲突，则可能发生这种情况。

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

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

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

在 Elastic Cloud 上设置 Fleet Server

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

要安装集成，Fleet 应用需要连接到名为 Elastic 包注册表的外部服务。

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

在隔离环境中，如果您使用 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 包注册表的 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

要解决此问题，请将 --insecure 标志与 enroll 或 install 命令一起传递。例如

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 服务器允许 Elastic Agent 连接到 Elasticsearch，这与先前版本中与 Kibana 的连接相同。但是，由于 Fleet 服务器位于边缘主机上，因此可能会导致额外的网络设置和故障排除。

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

elastic-agent status

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

如果 Elastic Agent 正在运行，但您没有看到预期的结果，以下是一些需要检查的项目：

Elastic Agent 诊断包收集以下信息：

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

使用 CLI 获取诊断包

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

elastic-agent diagnostics

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

通过 Fleet 获取诊断包

Fleet 提供远程生成和收集 Elastic Agent 诊断包的功能。如果 Agent 在线且状态为 Healthy 或 Unhealthy，则它可以收集并上传诊断信息。诊断信息将发送到 Fleet 服务器，然后 Fleet 服务器将其添加到 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>

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

有关查找 Agent 日志位置的信息，请参阅我们的 常见问题解答。

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

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

从非 Fleet 服务器主机运行以下命令：

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

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

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

为了保存 API 密钥并在 Elasticsearch 中加密它们，Fleet 需要一个加密密钥。

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

xpack.encryptedSavedObjects.encryptionKey: "something_at_least_32_characters"

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

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

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

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

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

在升级集成之后

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

您可以取消注册 Agent 以使与该 Agent 相关的所有 API 密钥失效并将状态更改为inactive，以便该 Agent 不再显示在 Fleet 中。

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

当您在 Elastic Agent 安装期间看到以下错误时，您就知道您的 Fleet 服务器已设置为使用其面向测试的自签名证书了

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 服务器 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 服务器部署，当需要托管的 Elastic Agent 或不再需要时，Elastic Cloud 会启动新的容器或关闭旧的容器。旧的 Elastic Agent 将在 Agent 列表中显示 24 小时，然后自动消失。

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

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

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

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

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

要解决此问题，您可以使用 API 调用重置 Elastic Cloud Agent 策略。请注意，这将删除您添加到策略中的任何自定义集成策略，例如 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 中删除包含此集成的策略，则所有其他 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

要解决此问题，请安装Elastic Agent时不要使用--unprivileged标志，使其具有管理员访问权限，或者在运行Elastic Agent命令时不要使用sudo前缀。

Kubernetes上Elastic Agent安装期间的潜在问题可以分为两大类：

在排查使用Kustomize执行的安装时，检查渲染后的清单输出是一个好习惯。为此，请使用Kibana Onboarding提供的安装命令，并将最后部分| kubectl apply -f-替换为重定向到本地文件的命令。这允许更容易地分析渲染后的输出。

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

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 独立实例步骤获得的内容，区别在于独立方法中不包含kube-state-metrics。

可能出现的问题

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

可能出现的问题

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