企业官网建设流程全解析

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

本指南面向需要基于自研或私有化镜像部署 ThreatMapper 传感器（Sensor Agent）的开发者与运维人员，讲解如何先构建并推送自定义 Agent 镜像，再分别通过docker run与 Helm Chart 两种方式将 Agent 部署到 Docker 主机和 Kubernetes 集群，并深入解析镜像仓库替换、MGMT_CONSOLE_URL、DEEPFENCE_KEY等关键参数的作用原理。读完本文，你将能够完全脱离 Deepfence 官方镜像仓库，在自己的环境中完成传感器全生命周期管理（部署、验证、升级、卸载）。

前置条件：先构建镜像并推送至自有仓库

部署自定义传感器之前，必须先在构建机上完成 ThreatMapper 的源码构建，并将生成的镜像推送到一个可访问的镜像仓库。官方推荐的构建流程记录在 构建指南 中，核心步骤为：

git clone <ThreatMapper 仓库地址> cd ThreatMapper make

构建过程会产出管理控制台与传感器相关的多个容器镜像并保存在本地 Docker 仓库中。若要在其他主机上部署传感器，需要将deepfence_agent_ce（普通传感器）与deepfence_cluster_agent_ce（集群传感器）推送到你的镜像仓库，例如 DockerHub：

ACC=myorg # 你的 dockerhub 账户名 docker login -u $ACC # 登录账户 for IMG in \ deepfence_redis_ce \ deepfence_postgres_ce \ deepfence_kafka_broker_ce \ deepfence_router_ce \ deepfence_file_server_ce \ deepfence_server_ce \ deepfence_worker_ce \ deepfence_ui_ce \ deepfence_agent_ce \ deepfence_cluster_agent_ce \ deepfence_package_scanner_ce \ deepfence_malware_scanner_ce \ deepfence_secret_scanner_ce \ deepfence_neo4j_ce do docker tag deepfenceio/$IMG $ACC/$IMG:latest docker push $ACC/$IMG:latest done

完成镜像推送后，就可以把标准安装文档（Docker 安装指南、Kubernetes 安装指南）中的镜像引用从 Deepfence 官方地址替换为你自己的镜像地址，其余安装逻辑完全一致。

从源码结构看，Agent 镜像并非单一二进制：在 deepfence_agent/Dockerfile 中，secret_build、package_build、malware_build、compliance_build四个构建阶段分别把 SecretScanner、Syft/package-scanner、YaraHunter、compliance 扫描器集成进最终镜像，同时内置docker、vessel、nerdctl、crictl等工具用于与宿主机容器运行时交互。因此推送镜像时，上述扫描器基础镜像同样需要一并推送。

在 Docker 主机上安装并运行自定义 Sensor Agent

Linux Docker 主机上的 ThreatMapper 传感器以一个轻量容器形式运行。参照 Docker 安装指南 的部署形态，把镜像地址替换为你的仓库即可：

ACC=myorg # 你的 dockerhub 账户名 docker login -u $ACC # 登录账户 docker run -dit \ --cpus=".2" \ --name=deepfence-agent \ --restart on-failure \ --pid=host \ --net=host \ --log-driver json-file \ --log-opt max-size=50m \ --privileged=true \ -v /sys/kernel/debug:/sys/kernel/debug:rw \ -v /var/log/fenced \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /:/fenced/mnt/host/:ro \ -e DF_LOG_LEVEL="info" \ -e CUSTOM_TAGS="" \ -e MGMT_CONSOLE_URL="---CONSOLE-IP---" \ -e MGMT_CONSOLE_PORT="443" \ -e DEEPFENCE_KEY="---DEEPFENCE-API-KEY---" \ -e http_proxy="" \ -e https_proxy="" \ -e no_proxy="" \ $ACC/deepfence_agent_ce:THREATMAPPER_VERSION

其中THREATMAPPER_VERSION是你构建/推送时使用的版本标签（官方仓库同时提供quay.io/deepfenceio/deepfence_agent_ce:THREATMAPPER_VERSION-multiarch多架构镜像，支持 amd64 与 arm64/v8 架构）。若使用 Podman，将命令中的docker换成podman，并将-v /var/run/docker.sock:/var/run/docker.sock替换为-v /run/podman/podman.sock:/run/podman/podman.sock，同时挂载-v /run/systemd/:/run/systemd/；部署前需确保 Podman system service（API service）已启动。

关键启动参数说明

环境变量在 Agent 内部的真实作用链路

这些环境变量并非表面参数，而是直接驱动 Agent 的启动逻辑：

• 在 deepfence_agent/run_discovery.sh 中，MGMT_CONSOLE_URL与MGMT_CONSOLE_PORT会拼接成https://$MGMT_CONSOLE_URL:$MGMT_CONSOLE_PORT，DEEPFENCE_KEY作为--probe.token传入deepfence-discovery探测进程；DF_LOG_LEVEL映射为--probe.log.level（默认info）。脚本还会调用vessel自动探测宿主机容器运行时（docker/containerd/crio/podman），再按探测结果选择对应的--probe.docker/--probe.cri/--probe.podman参数启动探测。
• 在 deepfence_agent/tools/apache/deepfence/df-utils/utils.go#L26-L36 中，GetCustomTags()读取CUSTOM_TAGS环境变量，按逗号切分并TrimSpace去除首尾空白后作为节点标签上报。
• 在 deepfence_agent/start_agent.sh 中，启动阶段会创建/var/log/fenced下的扫描日志目录、配置 logrotate 定时任务，并通过 supervisord 拉起全部 Agent 子进程；DEEPFENCE_KEY、MGMT_CONSOLE_URL等环境变量还会被注入到 fluentbit（shipper）配置中，用于日志回传。

通过代理服务器访问控制台

如果管理控制台需要通过代理访问，有两种方式：

• 在docker run时直接设置http_proxy、https_proxy环境变量，Agent 会使用该代理与控制台通信（即上文命令中预留的空变量）；
• 或者配置 Docker 客户端全局代理，编辑~/.docker/config.json：

{ "auths": { "https://index.docker.io/v1/": { "auth": "" } }, "HttpHeaders": { "User-Agent": "Docker-Client/19.03.1 (linux)" }, "proxies": { "default": { "httpProxy": "http://111.111.111.111:8006", "httpsProxy": "http://111.111.111.111:8006", "noProxy": "localhost,127.0.0.1" } } }

随后重启 Docker 守护进程：sudo systemctl restart docker。

升级传感器

升级 Docker 传感器时，先停止旧容器，再以新版本镜像标签启动新容器即可：

docker stop deepfence-agent docker rm deepfence-agent # 使用新版本标签重新执行 docker run

在 Kubernetes 集群中部署自定义 Sensor Agent

在 Kubernetes 中，传感器以 DaemonSet 形态运行（集群传感器则以单 Pod 形式运行），统一通过 Helm Chart 管理，适用于独立集群与托管集群（EKS、AKS、GKE 等）。注意：deepfence-consoleChart 默认会在其部署的集群中同时运行 agent 与 cluster-agent Pod，因此无需再额外安装deepfence-agentChart。

快速安装（--set 方式）

helm repo add deepfence https://artifacts.threatmapper.org/helm-charts/threatmapper helm repo update helm install deepfence-agent deepfence/deepfence-agent \ --set managementConsoleUrl=x.x.x.x \ --set deepfenceKey=73f6f3d0-9931-4b31-8967-fd6adf475f80 \ --set global.imageTag=THREATMAPPER_VERSION \ --set clusterName="prod-cluster" \ --set mountContainerRuntimeSocket.containerdSock=true \ --set mountContainerRuntimeSocket.dockerSock=false \ --set mountContainerRuntimeSocket.crioSock=false \ --set mountContainerRuntimeSocket.podmanSock=false \ --set mountContainerRuntimeSocket.containerdSockPath="/run/containerd/containerd.sock" \ --set logLevel="info" \ --namespace deepfence \ --create-namespace \ --version TM_AGENT_HELM_CHART_VERSION

要点说明：

• clusterName是集群名称/标识，不同集群必须使用不同值（如prod-cluster-1、test-cluster），它会作为主机名前缀出现在 Deepfence UI 中；
• 容器运行时 Socket 的挂载需与实际运行时匹配：默认 Chart 中 containerd 开启、docker 关闭；在 Minikube 等特殊平台上若 Agent 无法启动，可尝试将containerdSock设为false；
• 官方镜像标签quay.io/deepfenceio/deepfence_agent_ce:THREATMAPPER_VERSION-multiarch支持 amd64 与 arm64/v8。

细调部署（values 文件方式）

需要替换为自定义镜像或深度调优时，推荐导出 values 文件后修改：

helm repo add deepfence https://artifacts.threatmapper.org/helm-charts/threatmapper helm repo update helm show values deepfence/deepfence-agent --version TM_AGENT_HELM_CHART_VERSION > deepfence_agent_values.yaml # 必须更新以下值： # managementConsoleUrl 和 deepfenceKey - 指定你的控制台 IP/URL 与 API Key # image:name 和 image:clusterAgentImageName - 改为指向你的自定义镜像 # 可按需调整其他值，例如： # containerdSock - 在 Minikube 等平台上 Agent 启动失败时可设为 false vim deepfence_agent_values.yaml helm install -f deepfence_agent_values.yaml deepfence-agent deepfence/deepfence-agent \ --namespace deepfence \ --create-namespace \ --version TM_AGENT_HELM_CHART_VERSION

允许容器在 Kubernetes 环境中拉取并部署，等待数秒即可完成。

替换自定义镜像的完整参数对照

deepfence-agent values.yaml 定义了全部可调参数，部署自定义传感器时重点修改以下内容：

私有仓库与 Key 的底层实现

从 Chart 模板可以确认自定义镜像与认证机制的实际落地方式：

• 镜像替换：在 templates/daemonset.yaml 中，容器镜像由{{ .Values.agent.image.name }}:{{ default .Values.global.imageTag .Values.agent.image.tag }}渲染，即“镜像名 + 标签”完全由 values 驱动；该模板同时把MGMT_CONSOLE_URL、MGMT_CONSOLE_PORT、DF_KUBERNETES_ON=Y、DF_CLUSTER_NAME、CUSTOM_TAGS、DF_LOG_LEVEL、代理变量以及DOCKER_SOCKET_PATH/CONTAINERD_SOCKET_PATH等运行时 Socket 路径注入容器环境，并将/sys/kernel/debug、宿主机根目录（只读）、/var/log/fenced等挂载进 Pod，与 Docker 部署的参数一一对应。
• Key 下发：在 templates/secret.yaml 中，deepfenceKey被 base64 编码写入名为<release>-key的 Opaque Secret，DaemonSet 通过secretKeyRef引用该 Secret 填充DEEPFENCE_KEY环境变量。若你的环境中已存在外部定义的 Secret，可将createDeepfenceKeySecret设为false。
• 私有仓库拉取：设置imagePullSecret.create: true并填写registry、username、password后，Chart 会生成kubernetes.io/dockerconfigjson类型的 Secret 用于拉取自定义镜像。

完整可参考 deepfence-agent Chart 文档。

部署验证、卸载与容器运行时识别

验证部署状态

kubectl get daemonset -n deepfence kubectl get pods -n deepfence

随后即可在管理控制台的拓扑与主机列表中看到以clusterName-hostname命名的传感器节点。

删除传感器

helm delete deepfence-agent -n deepfence # 或：helm uninstall deepfence-agent -n deepfence

识别集群容器运行时

如果不知道集群使用哪种容器运行时，可先执行：

kubectl get nodes -o=custom-columns=NAME:.metadata.name,Runtime:.status.nodeInfo.containerRuntimeVersion

之后在安装时按结果设置对应的mountContainerRuntimeSocket.*Sock开关与 Socket 路径。即便配置有出入，Agent 容器内的vessel工具也会在启动时自动探测实际运行时（见 deepfence_agent/run_discovery.sh），并据此选择 docker/containerd/crio/podman 对应的探测参数，这也是 DaemonSet 模板中挂载多种 Socket 的原因所在。

小结

部署自定义 ThreatMapper 传感器可以概括为三步：其一，通过make构建并推送deepfence_agent_ce、deepfence_cluster_agent_ce等镜像到自有仓库；其二，在 Docker 主机上用docker run以--privileged+ 宿主机命名空间 + 多卷挂载的方式拉起 Agent，并通过MGMT_CONSOLE_URL、DEEPFENCE_KEY、DF_LOG_LEVEL、CUSTOM_TAGS等环境变量完成与控制台的对接与行为定制；其三，在 Kubernetes 集群中通过deepfence-agentHelm Chart 以 DaemonSet 方式批量部署，替换agent.image.name、cluster_agent.image.name并填写控制台地址与 Key。理解环境变量与 Chart values 到底如何驱动run_discovery.sh、start_agent.sh与 DaemonSet 模板（参见 run_discovery.sh、start_agent.sh、daemonset.yaml），就能在离线、私有化或定制镜像场景下稳定复现官方部署行为。

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