• 网络安全
• 应用安全
• 云原生
• 漏洞扫描

本篇技术指南聚焦 ThreatMapper（开源云原生应用保护平台 CNAPP）在Linux 裸机（bare-metal）与虚拟机（VM）工作负载上的传感器部署方式：以 Linux 二进制（而非容器镜像）形态安装 ThreatMapper Sensor Agent，并通过 systemd 将其注册为常驻守护服务。读完本文，你将掌握完整的安装脚本逐段解析、管理控制台 API Key 的获取、底层“认证换取下载地址”的调用链、日志查看与彻底卸载的实操方法，并能借助仓库源码理解每个环节的真实实现。

部署形态：为什么选择 Linux 二进制方式

从架构文档 sensors.md 可以看出，ThreatMapper 的传感器（Sensor Agent）按运行环境分为多种部署形态：

• Kubernetes：以 DaemonSet 形式随集群调度部署；
• Docker：在每个 Docker 主机上以容器形式运行；
• 裸机与虚拟机（Bare metal / VM）：在每个 Linux 操作系统实例上以守护服务方式运行——即本文介绍的Linux 二进制部署；
• AWS Fargate：以守护进程方式伴随每个 Serverless 实例运行。

官方支持 Linux 实例；Windows Server 不被支持（仅有实验性实现）。因此，对于不使用容器运行时托管传感器的裸金属或虚拟机，ThreatMapper 提供install_deepfence.sh一键安装脚本，将传感器二进制下载到/opt/deepfence并注册为deepfence-agent.service系统服务。

需要说明：原文档要求先在 Linux 主机上安装 Docker runtime（参考 传感器前置条件 中的支持平台说明）。这是因为传感器在保护容器工作负载时需要访问 Docker API——从容器形态的部署脚本 start-agent.sh 可以看到-v /var/run/docker.sock:/var/run/docker.sock挂载，且 start_deepfence_agent.sh 在DF_PROXY_MODE=1时会调用run_dind.sh启动容器内 Docker，依赖宿主机 Docker runtime。

前置准备：管理控制台地址与 API Key

安装前需要准备两个关键参数：

1. MGMT_CONSOLE_URL：Deepfence 管理控制台的地址，可以是域名（如threatmapper.customer.com）或 IP（如65.65.65.65）；
2. DEEPFENCE_KEY：Deepfence API Key。在管理控制台界面中通过Setting > User Management > API Key路径创建并获取。

从源码看，这个 API Key 并非直接用于下载，而是先通过管理控制台换取短期访问令牌（access token），详见下文“底层原理”一节。

安装脚本全解

将以下脚本完整复制并保存为install_deepfence.sh：

#!/bin/bash # MGMT_CONSOLE_URL: Example: threatmapper.customer.com or 65.65.65.65 export MGMT_CONSOLE_URL="${MGMT_CONSOLE_URL}" export DEEPFENCE_KEY="${DEEPFENCE_KEY}" if [[ -z "$MGMT_CONSOLE_URL" ]]; then echo "env MGMT_CONSOLE_URL is not set" exit 1 fi if [[ -z "$DEEPFENCE_KEY" ]]; then echo "env DEEPFENCE_KEY is not set" exit 1 fi export MGMT_CONSOLE_PORT="443" export MGMT_CONSOLE_URL_SCHEMA="https" export DF_HOSTNAME="$(hostname)" export DF_LOG_LEVEL="info" MANAGEMENT_CONSOLE_URL="$MGMT_CONSOLE_URL_SCHEMA://$MGMT_CONSOLE_URL:$MGMT_CONSOLE_PORT" OS_ID=$(grep -oP '(?<=^ID=).+' /etc/os-release | tr -d '"') if [[ "$OS_ID" == "amzn" || "$OS_ID" == "centos" ]]; then # Do necessary installs for Amazon Linux yum -y install logrotate jq curl if [[ "$?" != "0" ]]; then echo "Failed to install logrotate" exit 1 fi else # Do necessary installs for Ubuntu apt-get -y install logrotate jq curl if [[ "$?" != "0" ]]; then echo "Failed to install logrotate" exit 1 fi fi access_token_response=$(curl -m 5 -s -k "$MANAGEMENT_CONSOLE_URL/deepfence/auth/token" \ --header 'Content-Type: application/json' \ --data "{\"api_token\": \"$DEEPFENCE_KEY\"}") if [[ $access_token_response == "" ]]; then echo "Failed to connect to the management console" exit 1 fi access_token=$(jq -r '.access_token' <<< "$access_token_response") if [[ $access_token == "" || $access_token == "null" ]]; then echo "Failed to authenticate" echo "$access_token_response" exit 1 fi download_url_response=$(curl -m 5 -s -k "$MANAGEMENT_CONSOLE_URL/deepfence/agent-deployment/binary/download-url" \ --header "Authorization: Bearer $access_token") if [[ $download_url_response == "" ]]; then echo "Failed to get agent binary download url" exit 1 fi start_agent_script_download_url=$(jq -r '.start_agent_script_download_url' <<< "$download_url_response") if [[ $start_agent_script_download_url == "" ]]; then echo "Failed to get agent binary download url" echo "$download_url_response" exit 1 fi cat << EOF > uninstall_deepfence.sh #!/bin/bash systemctl stop deepfence-agent.service systemctl disable deepfence-agent.service rm -f /etc/systemd/system/deepfence-agent.service rm -rf /opt/deepfence EOF echo "Uninstalling existing Deepfence agent installation, if any" chmod +x uninstall_deepfence.sh bash uninstall_deepfence.sh if [[ ! -d "/opt/deepfence" ]]; then mkdir -p /opt/deepfence /opt/deepfence/var/log/ fi architecture="" case $(uname -m) in i386) architecture="386" ;; i686) architecture="386" ;; x86_64) architecture="amd64" ;; arm) dpkg --print-architecture | grep -q "arm64" && architecture="arm64" || architecture="arm" ;; aarch64) architecture="arm64" ;; esac echo "Detected architecture: $architecture" agent_binary_download_url=$(jq -r --arg architecture "agent_binary_${architecture}_download_url" '.[$architecture]' <<< "$download_url_response") agent_binary_filename=$(basename "$agent_binary_download_url") agent_binary_filename=$(cut -f1 -d"?" <<< "$agent_binary_filename") if [[ $agent_binary_download_url == "" || $agent_binary_filename == "" ]]; then echo "Failed to get agent binary download url" echo "$download_url_response" exit 1 fi echo "Downloading agent binary from $agent_binary_download_url to /opt/deepfence/$agent_binary_filename" curl -k -o "/opt/deepfence/$agent_binary_filename" "$agent_binary_download_url" curl -k -o /opt/deepfence/start_deepfence_agent.sh "$start_agent_script_download_url" chmod +x "/opt/deepfence/start_deepfence_agent.sh" tar -xzf "/opt/deepfence/$agent_binary_filename" -C /opt/deepfence/ echo "MGMT_CONSOLE_URL: $MGMT_CONSOLE_URL" echo "MGMT_CONSOLE_PORT: $MGMT_CONSOLE_PORT" echo "DF_HOSTNAME: $DF_HOSTNAME" echo "Installing Deepfence agent as daemon service" cat << EOF > /etc/systemd/system/deepfence-agent.service [Unit] Description=Deepfence Agent Service After=network.target [Service] Environment="MGMT_CONSOLE_URL=$MGMT_CONSOLE_URL" Environment="DEEPFENCE_KEY=$DEEPFENCE_KEY" Environment="MGMT_CONSOLE_PORT=$MGMT_CONSOLE_PORT" Environment="MGMT_CONSOLE_URL_SCHEMA=$MGMT_CONSOLE_URL_SCHEMA" Environment="DF_HOSTNAME=$(hostname)" Environment="DF_LOG_LEVEL=$DF_LOG_LEVEL" User=root Group=root Restart=on-failure Type=forking ExecStart=/opt/deepfence/start_deepfence_agent.sh WorkingDirectory=/opt/deepfence [Install] WantedBy=multi-user.target EOF systemctl daemon-reload systemctl enable deepfence-agent.service systemctl start deepfence-agent.service systemctl status deepfence-agent.service

设置管理控制台 URL 与 Deepfence Key 后，以 root 权限执行：

sudo bash install_deepfence.sh

脚本关键参数说明

脚本执行流程逐步拆解

1. 环境校验：检查MGMT_CONSOLE_URL与DEEPFENCE_KEY是否设置，未设置即报错退出；
2. 系统依赖安装：读取/etc/os-release的ID字段区分发行版——amzn/centos使用yum，其余（如 Ubuntu）使用apt-get，统一安装logrotate、jq、curl三个工具；
3. 换取访问令牌：调用管理控制台的/deepfence/auth/token接口，携带 API Key，用jq提取access_token；
4. 获取下载地址：携带 Bearer Token 调用/deepfence/agent-deployment/binary/download-url接口，得到传感器启动脚本与各架构二进制的下载 URL；
5. 清理旧安装：动态生成uninstall_deepfence.sh（停服务、删 systemd 单元、删/opt/deepfence），先执行一次以保证环境干净；
6. 架构检测与下载：通过uname -m识别386/amd64/arm/arm64，按agent_binary_<架构>_download_url字段下载对应二进制（tar.gz）并解压到/opt/deepfence，同时下载start_deepfence_agent.sh启动脚本；
7. 注册 systemd 服务：写入/etc/systemd/system/deepfence-agent.service，daemon-reload后enable、start，并以systemctl status展示服务状态。

底层原理：认证与下载链路源码印证

安装脚本中的两步 HTTP 调用在管理控制台（deepfence_server）侧均有对应实现：

1./deepfence/auth/token：API Key 换取访问令牌

路由定义于 router.go：r.Post("/auth/token", dfHandler.APIAuthHandler)，属于公开 API（无需登录即可调用，因为请求本身携带 API Key 凭据）。

处理函数 APIAuthHandler 的实现要点：

• 对请求体中的api_token做 Base64 原始解码；
• 将 Token 按:拆分，前半部分是命名空间（namespace），后半部分是 UUID，据此确定租户上下文并到 PostgreSQL 中查询对应的用户与 API Token 记录；
• 校验通过后调用user.GetAccessToken(...)签发 JWT 访问令牌并作为access_token字段返回——这正是脚本中jq -r '.access_token'取值的来源。

2./deepfence/agent-deployment/binary/download-url：下发下载地址

路由定义于 router.go：r.Route("/agent-deployment", ...)下的GET /binary/download-url，需携带 Bearer Token 访问。

处理函数 getAgentBinaryDownloadURL 的核心逻辑：

• 通过directory.FileServerClient获取文件服务器客户端，调用ExposeFile为每个文件生成带签名、24 小时有效期（getAgentBinaryDownloadURLExpiry = 24 * time.Hour，见 settings.go）的临时下载 URL；
• 下发 4 个下载地址，对应返回模型 GetAgentBinaryDownloadURLResponse 的 JSON 字段：

二进制文件存放于文件服务器的agent-binary路径（常量FileServerPathAgentBinary = "agent-binary"，见 constants.go）。脚本中使用jq -r --arg architecture "agent_binary_${architecture}_download_url" '.[$architecture]'动态按检测到的架构取值，即是对应上述字段的 amd64/arm64 分支。

3. 二进制包的内容

从构建侧脚本 copy-bin-from-agent.sh 可以看出，发布到文件服务器的 tar.gz 是一个自包含的传感器运行目录，包含：

• bin/下的deepfenced主守护进程，以及面向 arm64 用 busybox 软链出的cat、chmod、cp、gzip、tar等基础工具（保证最小化系统也能运行）；
• home/、opt/、usr/bin/、usr/local/bin/等目录下的辅助二进制与配置（如扫描插件、发现脚本）；
• etc/下的filebeat证书、logrotate.d轮转配置、supervisor配置。

启动脚本与 systemd 服务剖析

安装脚本生成的 deepfence-agent.service 单元使用Type=forking与ExecStart=/opt/deepfence/start_deepfence_agent.sh，以 root 身份运行，Restart=on-failure保证失败自动重启，并将管理控制台地址、Key、端口、主机名、日志级别等以Environment=注入。

启动脚本start_deepfence_agent.sh（仓库维护版位于 binary-install-scripts/start_deepfence_agent.sh）在启动时完成的关键工作：

1. 环境路径初始化：设置DF_BASE_DIR=/opt/deepfence，默认主机名SCOPE_HOSTNAME=$(hostname)；若启用INSTANCE_ID_SUFFIX=Y，还会调用getCloudInstanceId将云实例 ID 追加为后缀，用于区分同名主机；
2. 安装目录编排：将二进制包解压后的内容拷贝到$DF_INSTALL_DIR/df-agents/$SCOPE_HOSTNAME，并把bin、usr/local/bin等加入PATH；
3. cgroup 资源控制：调用create-cgroups.sh创建 cgroup 以便对传感器做资源限制；
4. 日志轮转配置：通过 cron 每 5 分钟执行一次logrotate（对应脚本中安装logrotate依赖的原因），轮转配置文件见 fenced_logrotate.conf；
5. Fluent Bit 配置注入：用envsubst将DEEPFENCE_KEY、MGMT_CONSOLE_URL、MGMT_CONSOLE_PORT、MGMT_CONSOLE_URL_SCHEMA、SCOPE_HOSTNAME、DF_INSTALL_DIR写入td-agent-bit配置文件，用于日志采集上报；
6. 拉起主进程：调用start_deepfenced.sh（见 start_deepfenced.sh）——该脚本是一个while true循环，以ulimit -l unlimited运行/opt/deepfence/bin/deepfenced，日志写入$DF_INSTALL_DIR/var/log/supervisor/deepfenced.log，进程异常退出 5 秒后自动重启，与 systemd 的Restart=on-failure形成双重保障。

查看日志

服务由 systemd 托管，可通过journalctl查看服务日志：

sudo journalctl -u deepfence-agent.service

若需跟踪传感器主进程运行日志，可查看启动脚本输出的deepfenced.log：

sudo tail -f /opt/deepfence/df-agents/$(hostname)/var/log/supervisor/deepfenced.log

各扫描子任务（恶意软件扫描、密钥扫描、合规扫描）的日志目录在启动脚本中预创建于$DF_INSTALL_DIR/var/log/fenced/下，分别对应malware-scan、malware-scan-log、secret-scan、secret-scan-log、compliance、compliance-scan-logs等子目录。

卸载传感器

如需彻底移除 ThreatMapper 传感器，依次执行：

sudo systemctl stop deepfence-agent.service sudo systemctl disable deepfence-agent.service sudo rm -f /etc/systemd/system/deepfence-agent.service sudo rm -rf /opt/deepfence

执行完毕后，管理控制台拓扑中该主机将随心跳超时不再显示。仓库还维护了一个更“激进”的卸载脚本 uninstall_deepfence_agent.sh，它会先按进程名df-agent强制结束残留进程再删除/opt/deepfence，适用于进程未被 systemd 正常回收的异常场景。

常见问题与排查建议

• env MGMT_CONSOLE_URL is not set：执行脚本前未导出环境变量，或未在脚本中填入实际值；可先执行export MGMT_CONSOLE_URL="..."与export DEEPFENCE_KEY="..."再运行。
• Failed to connect to the management console：/deepfence/auth/token无响应。检查管理控制台地址/端口是否可达、443 端口是否开放、网络与防火墙是否放行。
• Failed to authenticate：API Key 无效或已过期。重新在Setting>User Management>API Key生成 Key；注意脚本会对api_token做 Base64 原始解码（见 auth.go），请使用控制台导出的原始 Key 格式。
• Failed to get agent binary download url：携带令牌访问下载地址接口失败，令牌可能已过期，或文件服务器（deepfence_file_server）不可用。
• 服务启动失败：先执行sudo journalctl -u deepfence-agent.service与sudo tail -f /opt/deepfence/df-agents/$(hostname)/var/log/supervisor/deepfenced.log定位；若主机名包含特殊字符，可显式设置DF_HOSTNAME后再安装。
• 升级/重装：安装脚本会自动生成并执行uninstall_deepfence.sh清理旧实例，因此重复运行脚本即可完成覆盖安装，无需手动清理。

小结

Linux 主机（裸机/虚拟机）是 ThreatMapper 传感器矩阵中除 Kubernetes、Docker、Fargate 之外的重要落点。通过install_deepfence.sh脚本，传感器以原生二进制形态落地到/opt/deepfence，由 systemd 托管为deepfence-agent.service，并借助管理控制台/deepfence/auth/token与/deepfence/agent-deployment/binary/download-url两个 API 完成“API Key → 访问令牌 → 签名下载地址 → 二进制拉取”的自动化安装链路。理解这一链路与启动脚本的内部行为，能帮助你在排障、升级与大规模批量部署时快速定位问题。

• 网络安全
• 应用安全
• 云原生
• 漏洞扫描