对常见问题进行故障排除

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

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

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

故障排除内容编辑

在以下文档中查找舰队、Fleet Server 和 Elastic Agent 的故障排除信息

Elastic Agent 取消注册失败编辑

在舰队中，如果您删除了与一个或多个非活动已注册 Agent 关联的 Elastic Agent 策略，则当 Agent 返回到 健康 或 离线 状态时，将无法取消注册。尝试取消注册 Agent 会导致 取消注册 Agent 时出错 消息，并且取消注册失败。

要解决此问题，您可以使用 Kibana 舰队 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
}

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

启用 TSDB 时出现 illegal_argument_exception编辑

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

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

有关错误以及如何解决该错误的详细信息，请参阅 Innovation Hub 文章 针对 Elastic Agent 启用了 TSDB 的集成 中的 无法在 TSDB 索引中使用运行时字段 部分。

托管在 Elastic Cloud 上的 Elastic Agent 卡在 正在更新 或 离线 状态编辑

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

使用 Elastic Cloud 时，Fleet Server 未在 Kibana 中列出编辑

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

要在 Elastic Cloud 上设置 Fleet Server

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

/api/fleet/setup 端点无法访问软件包注册表编辑

要安装集成，舰队应用程序需要连接到名为 Elastic 软件包注册表的外部服务。

为此，Kibana 服务器必须在端口 443 上连接到 https://epr.elastic.co。

在气隙环境中，Kibana 无法连接到 Elastic 软件包注册表编辑

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

{"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 配置 部分。

Kibana 中的舰队崩溃编辑

Elastic Agent 在主机上注册失败，并显示 x509：证书由未知颁发机构签名 消息编辑

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

如果您尝试将 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

要解决此问题，请在 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。

Elastic Agent 注册在主机上失败，并显示 x509: cannot validate certificate for x.x.x.x because it doesn't contain any IP SANs 消息编辑

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

当您将自签名证书与使用 IP 作为通用名称 (CN) 的 Elasticsearch 一起使用时，会出现此错误。如果使用 IP 作为 CN，Fleet Server 会查找主题备用名称 (SAN)，而该名称为空。要解决此问题，请使用 --fleet-server-es-insecure 标志禁用证书验证。

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

Elastic Agent 注册在主机上失败，并显示 Client.Timeout exceeded 消息编辑

要注册到 Fleet，Elastic Agent 必须连接到 Fleet Server 实例。如果代理无法连接，您会看到以下错误：

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 问题可以使用以下技巧进行分类和修复编辑

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

检索 Elastic Agent 版本编辑

检查 Elastic Agent 状态编辑

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

elastic-agent status

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

如果 Elastic Agent 正在运行，但您没有看到预期结果，请查看以下项目：

收集 Elastic Agent 诊断包编辑

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

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

使用 CLI 获取诊断包

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

elastic-agent diagnostics

通过 Fleet 获取诊断包

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

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

请注意，这些包存储在 Elasticsearch 中，将在 30 天后删除。

有些问题出现得太早，以至于没有足够的日志可用编辑

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

./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 或完全不同的端口上运行。

有关代理日志存储位置的信息，请参阅我们的常见问题解答。

Elastic Agent 的状态为 健康，但在将数据发送到 Elasticsearch 时仍然存在设置问题编辑

Elastic Agent 停留在 正在更新 状态编辑

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

Fleet Server 正在运行且状态良好，但其他代理无法使用它连接到 Elasticsearch编辑

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

在非 Fleet Server 主机上，运行以下命令：

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

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

一个常见问题是，Fleet Server 主机上用于通信的默认 Fleet Server 端口 8220 未打开。您可以使用与您的任何网络和安全问题相一致的常用工具来查看和更正此问题。

Elasticsearch 身份验证服务失败，并显示 Authentication using apikey failed 消息编辑

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

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

xpack.encryptedSavedObjects.encryptionKey: "something_at_least_32_characters"

Elastic Agent 失败，并显示 Agent process is not root/admin or validation failed 消息编辑

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

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

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

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

集成策略升级存在太多冲突编辑

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

在 升级集成 后

Elastic Agent 在取消注册时挂起编辑

取消注册 Elastic Agent 时，Fleet 会等待代理的确认，然后才会完成取消注册过程。如果 Fleet 未收到确认，则状态将挂起在 正在取消注册。

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

Fleet Server 启动时，出现错误，并显示 State changed to CRASHED: exited with code: 1编辑

您可能会由于多种不同原因而看到此错误消息。一个常见原因是，在尝试进行类似生产的使用时，找不到传入的 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 Endpoint 失败编辑

卸载 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

API 密钥无权将遥测数据发送到 .logs-endpoint.diagnostic.collection-* 索引编辑

默认情况下，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 集成的遥测功能，直到下一个补丁版本可用。

托管 Elastic Agent 处于离线状态编辑

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

Elastic Agent 无法注册到在 localhost 上运行的 Fleet Server。编辑

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

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

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

APM 和 Fleet 无法在 Elastic Cloud 上升级到 8.x编辑

在某些情况下，如果手动修改了 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'

由于无法访问 PGP 密钥，离线 Elastic Agent 升级可能会失败编辑

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

删除 Fleet Server 集成后，Elastic Agent 无法连接编辑

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

解决此问题有两种方法，具体取决于运行 Fleet Server 集成的 Elastic Agent 是否仍然安装且运行正常（但现在运行的是其他策略）。

恢复 Elastic Agent

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

Kubernetes 上的 Elastic Agent 内存不足错误编辑

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

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

       Last State:   Terminated
       Reason:       OOMKilled
       Exit Code:    137

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