企业官网建设流程全解析

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

本文是 ThreatMapper 官方文档《Build from Source》的深度实战解读。ThreatMapper 是一款开源云原生应用保护平台（CNAPP），用于运行时威胁发现、攻击路径枚举与漏洞优先级排序。读完本文，你将掌握：如何在一台满足最低配置的构建机上从源码一键产出全套容器镜像、如何用 docker-compose 在本地拉起 Deepfence Management Console 并注册首个用户，以及如何把构建产物推送到自己的远程镜像仓库（如 DockerHub）完成多主机分发。

一、构建前的准备：硬件、软件与 Docker 权限

官方文档首先明确了构建主机（Build host）的最低要求，这是能否顺利跑完整套构建流程的关键前提：

仓库中与这一要求相互印证的是 install.sh 里的预检逻辑：Docker 部署模式会调用check_docker_requirements，强制校验nproc≥ 4 且可用内存 ≥ 16 GB，不满足直接退出；Kubernetes 部署模式则要求至少 3 个节点、每个节点 4 核 8 GB（见check_kubernetes_node_requirements，install.sh）。可见 16 GB / 4 核并非官方文档的随意估算，而是安装脚本中硬编码的硬性门槛。

如果当前用户不在docker组中，需要先授权并让组变更生效：

sudo usermod -aG docker $USER # 重新开一个 shell，或执行 'su $USER' 让组变更生效

提示：构建过程会大量调用docker run、docker build、docker push，确保当前用户具备 Docker 守护进程的操作权限是第一步。

二、一键构建：make到底帮你做了什么

官方文档给出的核心构建命令只有三条：

git clone https://github.com/deepfence/ThreatMapper.git cd ThreatMapper make

但背后是一条相当复杂的构建流水线。仓库根目录的 Makefile 定义了完整的依赖链，其中最关键的一段是：

default: bootstrap console_plugins agent console fargate-local # Makefile#L28 console: redis postgres kafka-broker router server worker ui file-server graphdb jaeger # Makefile#L31 console_plugins: secretscanner malwarescanner packagescanner compliancescanner # Makefile#L34

也就是说，一条make命令实际展开为 5 大阶段：

1. bootstrap：执行 bootstrap.sh，其内容为git submodule update --init --recursive --remote，递归拉取并更新仓库的全部 Git 子模块（agent 依赖的第三方组件即通过子模块方式引入）；
2. console_plugins：构建 4 个扫描插件镜像 —— SecretScanner（密钥扫描）、YaraHunter（恶意软件扫描）、package-scanner（软件包/漏洞扫描）、compliance（合规扫描）；
3. agent：构建传感器代理相关镜像，依赖debian_builder、deepfenced与console_plugins；
4. console：构建管理控制台的 9 个组件镜像；
5. fargate-local：从 agent 镜像中导出可执行二进制并打包成 tar.gz，供 AWS Fargate 等场景使用。

2.1 可调构建参数

Makefile 顶部集中定义了构建参数，全部支持命令行覆盖（make IMAGE_REPOSITORY=xxx DF_IMG_TAG=yyy）：

注意：官方文档推送示例中使用的是deepfenceio/$IMG前缀（对应 DockerHub），而当前仓库 Makefile 的默认IMAGE_REPOSITORY为quay.io/deepfenceio，deployment-scripts/docker-compose.yml 中的镜像默认值同样是quay.io/deepfenceio（标签默认2.5.8）。实际构建时以你传入的IMAGE_REPOSITORY为准。

2.2 两个“构建器”镜像：alpine 与 debian

构建流程会先制作两个编译环境镜像（builder image），所有 Go 代码编译都在其中进行，因此宿主机只要装了 Docker，对本地 Go 工具链版本并不敏感：

• alpine_builder（deepfence_builder_ce）：基于golang:1.25-alpine3.23，通过 docker_builders/Dockerfile-alpine 构建。镜像内预装 git、make、libpcap、YARA 4.5.5（VirusTotal 规则引擎，--enable-magic --enable-cuckoo配置）、Hyperscan（vectorscan）以及 asynq 工具，用于编译 agent 侧代码；
• debian_builder（deepfence_glibc_builder_ce）：基于golang:1.25-trixie，通过 docker_builders/Dockerfile-debian 构建，预装 build-essential、libjansson、libmagic、protoc 及 protoc-gen-go 等，用于编译需要 glibc 动态链接的 server / worker 二进制。

2.3 Console 组件镜像清单

console目标共产出 9 个镜像，每个镜像都对应仓库中的独立模块与独立构建 target（详见 Makefile）：

其中jaeger目标额外产出deepfence_telemetry_ce（基于 deepfence_telemetry，用于链路追踪）。

2.4 源码级细节：版本号如何注入二进制

以 server 为例，deepfence_server/Makefile 的image目标先在 glibc builder 容器内编译二进制，再打包镜像：

image: docker run --rm -i -e VERSION=${VERSION} -e GIT_COMMIT=${GIT_COMMIT} -e BUILD_TIME=${BUILD_TIME} \ -v $(ROOT_MAKEFILE_DIR):/src:rw -v /tmp/go:/go:rw \ $(IMAGE_REPOSITORY)/deepfence_glibc_builder_ce:$(DF_IMG_TAG) \ bash -c 'cd /src/deepfence_server && make deepfence_server' docker build -f ./Dockerfile -t $(IMAGE_REPOSITORY)/deepfence_server_ce:$(DF_IMG_TAG) ..

编译时通过-ldflags把Version、Commit、BuildTime注入到github.com/deepfence/ThreatMapper/deepfence_server/pkg/constants包（deepfence_server/Makefile），这正是管理控制台"关于/版本"页面数据来源。worker 采用同样的机制，注入到 deepfence_worker/utils 包；而 deepfence_bootstrapper/Makefile 则用CGO_ENABLED=0静态编译 agent 引导程序，并可选upx压缩体积。

2.5 Agent 与插件镜像的构建链

Agent 侧构建集中在 deepfence_agent/build.sh，依次完成：编译getCloudInstanceId→ 编译deepfence_shipper（数据上报器）→ 编译discovery（基于 weaveworks scope 的拓扑发现）→ 构建deepfence_cluster_agent_ce→ 构建deepfence_agent_ce。其中 agent 主镜像（deepfence_agent/Dockerfile）会通过COPY --from=secret_build / ...等阶段引用 secretscanner、packagescanner、malwarescanner、compliancescanner 四个插件镜像，把 SecretScanner、YaraHunter、syft、package-scanner、compliance 等扫描组件集成进 Agent，同时从 downloads 阶段拷贝 docker / vessel / nerdctl / crictl 运行时工具。

构建完成后，所有镜像都会存入本地 Docker 仓库（docker images即可查看），make不会自动推送，推送动作见第四节。

三、在本地运行 Deepfence Management Console

镜像构建完成后，即可在本地拉起整套管理控制台：

cd ThreatMapper/deployment-scripts docker-compose -f docker-compose.yml up --detach

该 Compose 文件（deployment-scripts/docker-compose.yml）定义的完整服务栈包括：deepfence-postgres、deepfence-redis、deepfence-neo4j、deepfence-kafka-broker、deepfence-server、deepfence-worker、deepfence-ingester、deepfence-scheduler、deepfence-ui、deepfence-router、deepfence-file-server、deepfence-telemetry以及自监控的deepfence-console-agent（Agent 以network_mode: host、privileged: true方式运行，见 docker-compose.yml）。

文件中还预置了大量可通过环境变量覆盖的配置（见 docker-compose.yml 的x-service-variables锚点），例如：

• DEEPFENCE_NEO4J_HOST/DEEPFENCE_NEO4J_BOLT_PORT：Neo4j 连接地址与 Bolt 端口（默认7687）；
• DEEPFENCE_POSTGRES_USER_DB_HOST/..._PORT/..._NAME：PostgreSQL 连接参数（默认5432/ 库名users）；
• DEEPFENCE_KAFKA_BROKERS：Kafka 地址（默认deepfence-kafka-broker:9092）；
• DEEPFENCE_FILE_SERVER_DB_BUCKET/DEEPFENCE_FILE_SERVER_BUCKET：文件服务桶配置，database桶公开只读托管漏洞数据库，default桶存放报告与 SBOM；
• DEEPFENCE_REDIS_HOST/DEEPFENCE_REDIS_PORT：Redis 地址（默认6379，TLS 由DEEPFENCE_REDIS_TLS控制）；
• DEEPFENCE_TASKS_CONCURRENCY（默认 50）、DEEPFENCE_TASKS_MAX_RETRIES（默认 3）、DEEPFENCE_MAX_SCAN_WORKLOAD（默认 5）：任务并发与扫描负载上限。

启动成功后，用浏览器访问https://--IP-ADDRESS---/即可进入首次配置页面，注册第一个用户（后续用户需由管理员邀请）。控制台默认使用内部自签 TLS 证书，浏览器会提示证书告警，可先绕过；完整流程见《Initial Configuration》，其中还包含注册 License（用于下载 ThreatIntel 威胁情报库）与获取传感器 Agent API Key 的步骤。

停止管理控制台：

docker-compose -f docker-compose.yml down

如需彻底清理不再需要的镜像与数据卷，可再执行：

docker image prune docker volume prune

提示：官方文档中的镜像标签与 Compose 默认标签均为2.5.8。若你构建时使用了自定义DF_IMG_TAG，本地 Compose 启动前需通过环境变量DF_IMG_TAG（及需要时的IMAGE_REPOSITORY）指向你构建出的标签，否则 Compose 会按默认值去拉取远端镜像。

四、把镜像推送到远程仓库：跨主机分发

构建产物只存在于本地 Docker 仓库。如果计划把 Management Console 或传感器（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

对这段脚本，结合当前仓库可以给出三条实战补充：

1. 源镜像前缀要与你构建时一致：脚本假设源镜像为deepfenceio/$IMG。若你按 Makefile 默认值quay.io/deepfenceio构建，应把docker tag的源改为quay.io/deepfenceio/$IMG（或直接用IMAGE_REPOSITORY变量统一管理）；
2. 产物不止这 14 个：完整构建还会产出deepfence_telemetry_ce（jaeger 链路追踪）与deepfence_compliance_scanner_ce（合规扫描插件），如部署环境需要可一并推送；
3. 仓库内置 publish 目标：Makefile 提供了make publish一键发布能力，它会按IMAGE_REPOSITORY/DF_IMG_TAG依次docker pushredis、postgres、kafka、router、file-server、server、worker、ui、agent、cluster-agent、各扫描插件、graphdb 与 jaeger 镜像，比手写循环更贴合当前仓库的产物集合。

推送完成后，目标主机即可通过docker pull $ACC/deepfence_server_ce:latest等方式拉取镜像部署；传感器的安装方式可参考 deployment-scripts/start-agent.sh 或仓库 README.md 中给出的docker run示例（需传入MGMT_CONSOLE_URL、MGMT_CONSOLE_PORT、DEEPFENCE_KEY三个关键环境变量）。

五、常见问题与排查建议

以下排查点均基于仓库源码与配置可验证的事实，供构建/启动失败时对照：

• 内存或 CPU 不足：构建与运行整套控制台需要 16 GB 内存、4 核（install.sh 的预检会硬性校验）。内存不足时优先关闭无关容器，或考虑仅构建部分镜像（如make console或单独make server）。
• Docker 权限报错：确认当前用户在docker组并已重新登录（sudo usermod -aG docker $USER），否则所有docker run/build都会失败。
• 子模块拉取失败：bootstrap阶段执行git submodule update --init --recursive --remote（bootstrap.sh），网络受限时可能失败，需确保可访问 Git 远端并重试make bootstrap。
• 镜像标签不匹配：本地 Compose 启动前检查DF_IMG_TAG与IMAGE_REPOSITORY环境变量是否指向本地构建产物，避免意外从远端拉取。
• 控制台证书告警：默认使用自签证书属正常现象，可在《Initial Configuration》中配置自定义 TLS 证书（Docker 方式将.key/.crt放入/etc/deepfence/certs后重启控制台即可）。

六、开发者进阶：从源码到 API 的下一步

完成"源码构建 → 本地运行 → 镜像发布"的闭环后，开发者可以继续深入 ThreatMapper 的开发者资源（见 docs/docs/developers/index.md）：

• REST API Reference：管理控制台暴露的 REST API 说明；
• Python SDK 使用指南：基于官方 SDK 编写自动化脚本。

如需在 Kubernetes 集群中部署而非单机 Docker，可参考仓库中的 Helm Charts（deployment-scripts/helm-charts/deepfence-console 与 deployment-scripts/helm-charts/deepfence-agent），或直接使用 install.sh 提供的-d kubernetes一键安装模式（会自动校验节点规格、生成 Neo4j 密码并执行 helm upgrade）。

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