Observability：如何在隔离环境中部署 Elastic Agents

作者：来自 Elastic Pete Ward

从手动下载到自动化 artifact 管理。

问题：当 "只需下载" 不是选项时

想象这种场景：你需要在敏感/机密网络、关键基础设施或具有严格网络隔离策略的金融系统中部署 Elastic Agents。网络被严格锁定 ------ 没有互联网访问，没有外部下载，更不能访问 artifacts.elastic.co ------ 但 Elastic Agent 需要更新，或者 Endpoint 安全需要最新的威胁检测 artifacts。

这就是许多组织的现实：它们需要 Elastic 强大的基于 agent 的可观测性和安全功能，但运行在隔离或受限环境中。本该是一个简单的 agent 部署，却变成了手动 artifact 下载、U 盘传输和在每个 Elastic 发布中重复的繁琐流程的后勤噩梦。

在支持企业 Elastic Agent 部署时，我作为一名高级 Elastic 工程师多次遇到这种挑战。我不得不反复手动查找 URL 并下载 agent 二进制文件、Endpoint artifacts 和安全签名，为不同的客户站点重复这一过程。每次新的 Elastic 发布都意味着数小时的手工劳动，而且这个过程容易出错。

解决方案：自动化 artifact 管理

与其接受这种现状，我构建了一个解决方案，把数小时的手工操作转变为一个命令。artifacts-bundler 工具自动化整个下载、打包和为离线环境提供 Elastic Stack 组件的过程。

它的实际作用

该工具解决了我在现场遇到的三大核心挑战：

批量下载 ：自动从 artifacts.elastic.co 和 artifacts.security.elastic.co 获取 Elastic Agent 二进制文件、Beats、APM server、Fleet Server 和关键的 Endpoint 安全 artifacts。
智能打包：创建带有时间戳和版本的 bundle，并包含清单文件以便可追溯和验证。
本地分发：可选构建一个自包含的 NGINX 容器，作为内部 artifact 镜像源。

技术架构

智能下载

我构建它来智能使用 Elastic 的官方 API：

从 artifacts.elastic.co 和 artifacts.security.elastic.co 查询当前 artifact 清单
在可用时验证校验和和签名
创建详细的清单文件，记录下载了什么以及何时下载
支持使用 --update 标志进行增量更新，避免重复下载已有文件

灵活的部署选项

我设计的 NGINX 容器方式带来以下优势：

自成一体：无需外部依赖或复杂的服务器设置
可移植：可在 Docker、Podman、containerd 等不同容器平台上一致运行
可扩展：可以在 Kubernetes 中通过水平扩展进行部署
安全：支持使用自定义证书的 SSL/TLS 终止

版本管理

该工具能同时处理多个 Elastic 版本，这对需要以下场景的环境来说至关重要：

支持跨不同系统的渐进式发布
为测试和生产维护多个版本
在需要时快速回滚到先前版本

真实场景演练：从零到运行

让我带你完整走一遍使用 artifacts-bundler 搭建离线 Elastic Agent artifact 服务器的过程 ------ 这就是我在客户部署中使用的相同工作流。

步骤 1：初始设置

从一个可以访问互联网的系统开始（你的构建/预发布环境）：

克隆仓库

bash 复制代码

`

1.  git clone https://github.com/pkward/artifacts-bundler.git
2.  cd artifacts-bundler

`AI写代码

安装前置条件（RHEL/CentOS 示例）

go 复制代码

 `sudo dnf install -y curl tar jq gzip docker|podman`AI写代码

步骤 2：选择你的部署策略

artifacts-bundler 支持我为不同环境设计的两种不同部署方式：

选项 A：适用于裸机/传统服务器的打包方式

typescript 复制代码

 ``1.   ./scripts/download-artifacts.sh \
2.       --versions 8.18.5,9.1.2 \
3.       --bundle

5.  This creates a timestamped tarball (`elastic-artifacts-bundle-20250813-154323.tar.gz`) that you can extract and serve with any web server.``AI写代码

选项 B：自包含容器镜像

markdown 复制代码

``

1.  ./scripts/download-artifacts.sh \
2.       --versions 8.18.5,9.1.2 \
3.       --build-nginx-image

5.  This builds a ready-to-deploy NGINX Docker image (`elastic-artifacts-nginx:latest`) with artifacts preloaded.

``AI写代码

这两个命令都会触发我自动化的相同全面下载流程：

Linux、Windows 和 macOS 的 Elastic Agent 二进制文件
安全 endpoint artifacts，包括检测签名和行为模型
指定版本的 APM server 和 Fleet Server
记录下载内容和时间的清单文件

步骤 3：传输到隔离环境

方法取决于你选择的部署策略：

对于裸机部署（打包选项）
将 bundle 传输到目标服务器

bash 复制代码

 `scp elastic-artifacts-bundle-20250813-154323.tar.gz target-server:/tmp/`AI写代码

替代方案：复制到已挂载的 USB 驱动器进行物理传输
首先挂载 USB 驱动器：sudo mount /dev/sdb1 /mnt/usb

bash 复制代码

 `cp elastic-artifacts-bundle-20250813-154323.tar.gz /mnt/usb/`AI写代码

对于容器部署
保存容器镜像（在传输前在构建环境中执行）：

go 复制代码

 `docker|podman save elastic-artifacts-nginx:latest | gzip > elastic-artifacts-nginx.tar.gz`AI写代码

传输到目标服务器

bash 复制代码

 `scp elastic-artifacts-ningx.tar.gz target-server:/tmp/`AI写代码

替代方案：复制到已挂载的 USB 驱动器进行物理传输
首先挂载 USB 驱动器：sudo mount /dev/sdb1 /mnt/usb

bash 复制代码

 `cp elastic-artifacts-nginx.tar.gz /mnt/usb/`AI写代码

这种方法的优势在传输阶段尤为明显。你不再需要管理几十个单独文件（我以前都是手动操作），而是拥有一个单一的自包含包，无论是通过网络还是通过 USB 等物理介质，都可以在环境间移动。

步骤 4：部署你的 artifact 服务器

部署选项 A：裸机 NGINX 服务器

对于传统服务器环境，解压并使用 NGINX 提供 bundle 服务：

bash 复制代码

`

1.  # In the air-gapped environment, extract to web directory
2.  sudo mkdir -p /var/www/elastic-artifacts
3.  cd /var/www/elastic-artifacts
4.  sudo tar -xzf /tmp/elastic-artifacts-bundle-20250813-154323.tar.gz

6.  # Set proper ownership and permissions (check NGINX user first)
7.  # Check which user NGINX runs as: ps aux | grep nginx
8.  sudo chown -R nginx:nginx /var/www/elastic-artifacts  
9.  # Use www-data:www-data on Ubuntu/Debian
10.  sudo chmod -R 755 /var/www/elastic-artifacts

12.  # Configure SELinux context for NGINX to serve static files
13.  sudo semanage fcontext -a -t httpd_sys_content_t "/var/www/elastic-artifacts(/.*)?"
14.  sudo restorecon -Rv /var/www/elastic-artifacts

16.  # Verify SELinux labels are correct
17.  sudo ls -laZ /var/www/elastic-artifacts/
18.  # Expected output should show: unconfined_u:object_r:httpd_sys_content_t:s0

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

安装并配置 NGINX：

ini 复制代码

`

1.  # Install NGINX (RHEL/CentOS example)
2.  sudo dnf install -y nginx

4.  # Create NGINX configuration
5.  sudo tee /etc/nginx/conf.d/elastic-artifacts.conf << 'EOF'
6.  server {
7.      listen 80;
8.      server_name elastic-artifacts.local;

10.      root /var/www/elastic-artifacts;
11.      index index.html;

13.      # Enable ETags globally - REQUIRED for Elastic Endpoint artifact updates
14.      etag on;

16.      location /downloads/ {
17.          alias /var/www/elastic-artifacts/;
18.          autoindex on;
19.          autoindex_exact_size off;
20.          autoindex_localtime on;

22.          # Enable CORS for cross-origin requests
23.          add_header Access-Control-Allow-Origin *;
24.          add_header Access-Control-Allow-Methods "GET, OPTIONS";
25.          add_header Access-Control-Allow-Headers "Origin, Content-Type, Accept";

27.          # Ensure ETags are sent for all files (critical for Endpoint)
28.          add_header Cache-Control "public, must-revalidate";

30.          # Set appropriate MIME types
31.          location ~* \.(tar\.gz|tgz)$ {
32.              add_header Content-Type application/gzip;
33.          }

35.          location ~* \.zip$ {
36.              add_header Content-Type application/zip;
37.          }
38.      }

40.      # Optional: Create a simple index page
41.      location = / {
42.          return 301 /downloads/;
43.      }
44.  }
45.  EOF

47.  # Enable and start NGINX
48.  sudo systemctl enable nginx
49.  sudo systemctl start nginx

51.  # Configure firewall (if needed)
52.  sudo firewall-cmd --permanent --add-service=http
53.  sudo firewall-cmd --reload

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

你的 artifact 服务器现在可通过 http://your-server/downloads/ 访问，支持可浏览的目录列表和适用于 Elastic Endpoint artifact 更新检测的 ETag。

重要注意事项：ETag 头配置对 Elastic Endpoint 功能是必需的。没有 ETag，Elastic Endpoint 无法判断全局 artifacts 是否已更新，也不会在新版本可用时下载。

验证 ETag 配置 ：

测试 ETag 是否正常工作：

arduino 复制代码

`curl -I http://your-server/downloads/endpoint/manifest/artifacts-8.18.5.zip`AI写代码

应显示：ETag: "十六进制值"

部署选项 B：容器部署

对于容器化环境，使用预构建镜像：

arduino 复制代码

`

1.  # In the air-gapped environment, load and run the pre-built image

3.   docker|podman load < /tmp/elastic-artifacts-nginx.tar.gz
4.   docker|podman run -d -p 80:80 elastic-artifacts-nginx:latest

`AI写代码

部署选项 C：Kubernetes 部署

bash 复制代码

`

1.  # Deploy using the included manifests
2.   kubectl apply -f k8s/nginx-deploy.yaml
3.   kubectl apply -f k8s/nginx-nodeport.yaml

`AI写代码

步骤 5：配置 Elastic Stack 使用本地镜像

这就是该解决方案的价值所在。每个组件不再尝试访问外部服务器，而是全部指向你的本地镜像。

Fleet 配置

在 Kibana 中，导航到 Fleet > Settings 并配置 Agent Binary Download URL：

Fleet 设置显示"Edit agent binary source"对话框，在此配置内部 artifact 服务器的 URL

关键是将 Host 字段设置为指向你的本地 artifact 服务器（例如：http://10.0.0.33/downloads/）。这告诉 Fleet 在所有 agent 安装和更新时从哪里下载 Elastic Agent 二进制文件。

Agent 安装命令会自动使用你配置的 artifact 服务器，在 curl 命令中显示自定义下载 URL

从此时起，所有 Elastic Agent 部署、更新和策略更改都会从你的本地服务器获取二进制文件，而不是从互联网获取。

Endpoint 安全配置

对于 Elastic Defend（Endpoint 安全），在 Endpoint 策略中配置全局 artifact 下载源，路径为 Security > Endpoint > Policies > [Your Defend Policy ] > Edit > Advanced Settings。

为每个平台配置全局 artifact 下载源：

Windows 高级 artifacts 全局基础 URL 配置