半年多以前扫过一遍依赖，报告归档在某个共享盘里，今天某个公共组件爆出高危漏洞，团队第一反应是翻报告——可那份报告只能说明"当时没问题"。这就是绝大多数依赖扫描的真实处境：扫描动作完成了，风险监控却没建立起来。Dependency-Track 解决的正是这件事，它不是又一个扫描器，而是一个持续运转的软件成分账本，把每个项目用到的组件版本登记在案，然后反复拿这些版本去比对最新公开的漏洞情报，一旦某个老项目里躺着的依赖被披露有问题，你能立刻定位到底是哪几个项目、哪个版本、被谁引用。本文按从部署到跑通再到日常使用的完整路径展开，适合已经接触过 SBOM 概念、想把依赖治理从"季度巡检"变成"实时盯防"的开发、测试和安全的同学，也适合完全没部署过这类平台、想先跑一套环境看看效果的新手。
1. 从"扫一次就归档"到"天天盯着看"：它到底补的是哪块短板
1.1 一次性扫描方案留下的三个断点
绝大多数团队最早接触的依赖检查，都是集成在构建流程里的那一类：构建时跑一遍，发现问题就阻断，不阻断就出份报告。这个模式听着很严，实际跑下来有三个明显的断点。
第一个断点是信息只在构建那一刻有效。今天的构建用的是 Spring 的某个版本，构建通过、报告清零、大家心情舒畅；三个月后这个版本被披露存在反序列化风险，但没有任何机制会主动回来告诉你"你线上跑的那个服务还挂在这个版本上"。漏洞披露是持续发生的，扫描却是一次性的，两边的时间轴对不上。
第二个断点是扫描结果散落在各个流水线的构建产物里。十个项目十条流水线，每份报告格式不一样、存放位置不一样、保留策略也不一样。真要回答"这个漏洞影响我们哪些服务"，得挨个翻，翻完还得自己人工比对版本号，效率极低而且极容易漏。
第三个断点是版本号的口径不统一。构建工具里写的是1.2.3，传递依赖实际引进来的是1.2.4，有的包管理器还会把版本写成范围表达式。人工看依赖树时很容易把"声明版本"当成"实际版本"，最后得出的结论是错位的。
Dependency-Track 的定位就是把这些断点一次性补上。它自己不做代码扫描，不分析你的源码，只做一件事：接收一份标准化的组件清单，长期保存，持续比对漏洞情报，并在状态变化时通知你。
1.2 SBOM 是账本，漏洞库是流水，平台负责对账
理解这个工具，抓住两个概念就够了。
SBOM，软件物料清单，本质就是你项目的一份"配料表"。它按标准格式描述了这个应用里包含哪些组件、每个组件什么版本、由谁发布、通过什么方式引入。目前流通最广的两种格式是 CycloneDX 和 SPDX，前者在安全场景下用得更多，生态也更全，主流构建工具基本都有对应的插件能直接吐出来。
漏洞情报源，就是持续更新的"问题公告"。平台内置了几个分析器，会定期把公开漏洞库里的条目拉下来，建立本地索引，然后用 SBOM 里的每个组件去索引里查。
平台的价值就体现在"对账"这个动作可以无限次重复。你把 SBOM 传上去之后，它不会像扫描器那样"跑完就出结论"，而是会拿着这份清单里的每个组件，反复去查最新情报。今天没问题的组件，下个月可能就有问题了，平台会自动把状态从"无风险"改成"有风险"，并按照你配的规则推送出来。这个机制听起来简单，却是整个依赖治理链条里最难靠人工维持的一环——因为它要求的是"每天都做一遍"，而人做不到，机器可以。
需要注意的一点：平台的风险判断完全依赖公开情报的时效性和准确性。它告诉你"这个版本被披露有某某问题"，不代表你的代码真的调用了那段有问题的逻辑，实际可利用性还得结合调用路径自己判断。
2. 部署前先想清楚：组件构成、资源盘子与数据库选型
2.1 三个进程各管什么，端口怎么分
Dependency-Track 的服务端不是单体，标准部署下要跑两个 Java 进程加一个数据库。
API 服务端是核心，负责接收 SBOM、跑分析器、管理项目与策略、对外提供 REST 接口，默认监听 8080。前端服务端是一个独立部署的静态资源加反向代理容器，默认也监听 8080，它只负责渲染界面，所有数据交互都是浏览器直接打到 API 服务端。数据库存项目、组件、漏洞关联、策略这些结构化数据。
这里有个新手特别容易栽的坑：两个容器默认端口都是 8080，如果直接映射到宿主机又不改端口，必然冲突。我一般会这样规划：API 服务端映射到宿主机 8081，前端映射到 8080，浏览器访问 8080 上的界面。同时前端的API_BASE_URL环境变量必须指向浏览器能访问到的 API 地址，而不是容器内部的localhost。写成http://localhost:8081只在你本机浏览器直接访问时有效；如果部署在服务器上，就得写成服务器 IP 或域名，否则界面能打开但所有请求都 404，让人一脸懵。
2.2 数据库选型：演示用内嵌，长期用外部
API 服务端支持两种数据库模式。一种是内嵌的嵌入式数据库，零配置，容器一启动就能用，适合本地评估、写 Demo、临时验证。另一种是外部的 PostgreSQL，适合任何要长期跑的场景。
我强烈建议只要不是纯本地试验，一律上 PostgreSQL。原因很实际：内嵌模式的数据文件挂载在容器卷里，一旦容器重建、卷没挂对、或者升级时镜像行为变化，数据说没就没了；而且内嵌模式在并发写入和大量组件索引时的表现明显吃力，项目数量上去之后查询会变得很慢。PostgreSQL 则是成熟方案，备份、迁移、扩容都有现成手段。
资源方面，给一个参考盘子：项目数在 50 个以内、每个 SBOM 几百个组件，API 服务端 2 核 4G、PostgreSQL 2 核 2G 基本够用；如果要长期保留完整的漏洞库索引，API 服务端内存建议给到 4G 以上，因为漏洞库全量索引加载起来体积不小，内存不足会导致频繁 GC，表现为界面越用越卡。磁盘上留出至少 20G 给数据库，漏洞库索引和组件记录都会持续增长。
部署时区也要留意。容器默认时区往往是 UTC，导致界面上的时间戳和你本地差 8 小时，排查"到底什么时候同步的"时很容易误判。建议给容器统一挂上时区环境变量。
3. 把服务拉起来：一份能直接复用的编排配置
3.1 编排文件逐段拆解
下面这份配置是我在测试环境反复用过的基础版本，三个服务、数据卷持久化、端口错开，拿来改改就能用。
version: "3.8" services: dtrack-apiserver: image: dependencytrack/apiserver:4.11.3 container_name: dtrack-apiserver environment: - ALPINE_DATABASE_MODE=external - ALPINE_DATABASE_URL=jdbc:postgresql://dtrack-postgres:5432/dtrack - ALPINE_DATABASE_DRIVER=org.postgresql.Driver - ALPINE_DATABASE_USERNAME=dtrack - ALPINE_DATABASE_PASSWORD=change_me_strong - ALPINE_CORS_ENABLED=true - ALPINE_CORS_ALLOW_ORIGIN=http://192.168.10.20:8080 - TZ=Asia/Shanghai volumes: - ./dtrack-data:/data ports: - "8081:8080" depends_on: - dtrack-postgres restart: unless-stopped dtrack-frontend: image: dependencytrack/frontend:4.11.3 container_name: dtrack-frontend environment: - API_BASE_URL=http://192.168.10.20:8081 - TZ=Asia/Shanghai ports: - "8080:8080" depends_on: - dtrack-apiserver restart: unless-stopped dtrack-postgres: image: postgres:15-alpine container_name: dtrack-postgres environment: - POSTGRES_USER=dtrack - POSTGRES_PASSWORD=change_me_strong - POSTGRES_DB=dtrack - TZ=Asia/Shanghai volumes: - ./pgdata:/var/lib/postgresql/data restart: unless-stopped几处值得单独说明的地方。
ALPINE_CORS_ALLOW_ORIGIN必须填前端的完整访问地址，包括协议、IP、端口，一个字符都不能差。这是浏览器同源策略的要求，填错的表现是登录页面能刷出来，但点登录按钮一直转圈，浏览器控制台里全是跨域报错。我第一次部署时就因为这个卡了半小时，一直以为是后端没启动。
./dtrack-data:/data这个挂载是 API 服务端的持久化目录，里面会存配置文件和临时数据。注意宿主机目录的属主权限，容器内进程以非 root 用户运行，如果目录属主是 root 且权限是 755，写不进去，日志里会报权限拒绝。稳妥做法是提前创建目录并放开写权限。
镜像版本号建议锁定具体小版本，别用latest。这个项目的版本迭代节奏不慢，跨大版本升级时数据库表结构可能有变化，用latest意味着某次重启就悄悄换了版本，出问题时排查方向会被带偏。
3.2 首次启动与初始账号处理
编排文件就位后，docker compose up -d拉起，然后用docker compose logs -f dtrack-apiserver盯日志。启动时间取决于机器性能，通常一两分钟能起来，看到类似"server started"的字样就说明 API 服务端就绪了。
数据表结构会在首次启动时自动初始化，这个过程也需要时间，期间前端访问会报各种奇怪的 500，属正常现象，耐心等。
初始账号是内置的 admin，密码同样有默认值。各版本的具体默认口令请在启动完成后查阅对应版本的官方部署说明，不要凭记忆输。登录后第一件事就是改密码，第二件事是创建一个专用的 API 账号。这个平台的角色权限设计得比较细，日常给流水线用的是只有上传 SBOM 权限的账号，不要图省事直接拿 admin 的密钥往 CI 里塞。
创建 API 密钥的路径在 管理 → 访问管理 → 团队，新建团队、分配权限、生成密钥，密钥只在生成时显示一次，记得当场记下来。
如果你是升级而不是新建，务必先备份数据库，再确认目标版本的升级说明里有没要求先跑某次中间版本。跨大版本直接跳，很容易卡在表结构迁移上。
4. 接上情报源：漏洞分析器怎么配才不白跑
4.1 漏洞库同步：配额、节奏与首次全量的代价
平台跑起来不等于能查漏洞，还要把情报源接上。
主力的公开漏洞库需要申请一个访问密钥，免费申请，但有速率限制。这个限制是双刃剑：不填密钥也能用，只是拉取速度极慢，全量同步可能要跑很久；填了密钥，速度明显提升，但短时间内频繁请求会被限流，返回 403 甚至临时封禁。
配置入口在 管理 → 分析器 → 对应的漏洞库分析器，填密钥、勾选启用。保存之后平台不会立刻开始拉，需要手动触发一次全量同步，或者等定时任务。
首次全量同步是最考验耐心的一步，我见过跑了三四个小时还没结束的。原因有两个：一是数据量本身就大，二十多万条漏洞记录加上关联的组件标识；二是每拉一批要落库建立索引。这个过程中可以随时在界面上看同步状态，别重启容器，重启会中断并可能导致部分数据重复处理。
同步完成后还有个容易忽略的点：增量更新的频率。默认配置下是每天跑一次增量，这个频率对绝大多数团队够用。如果你们对新生漏洞的响应要求很高，可以调高频率，但要权衡水源的限流风险，别把自己搞得被拒绝访问。
4.2 分析器各管一摊，别指望一个包打天下
平台内置的分析器不止一个，分工不同。
漏洞库分析器负责比对 CVE 类公开漏洞，是主力。另一个常见的分析器基于第三方组件情报服务，除了漏洞还会给出组件的维护状态、是否有新版本等信息，需要单独注册账号，同样有免费额度限制。此外还有一些针对特定生态的分析器，比如检查组件是否已被官方废弃、检查许可证合规等。
我踩过的一个坑是：只开了漏洞库分析器，就一直以为"组件生命周期"这类信息也会自动出现，结果界面上那几列一直是空的。后来才明白不同的分析器要在 分析器 页面逐个启用，而且有一些需要额外凭据。
另一个细节是分析器启用后对已有数据的影响。新启用一个分析器，它不会自动回扫所有历史项目，需要手动触发重新分析。项目数量多的话，这一步耗时也不短。建议在部署初期就把要用的分析器一次性配齐，避免后面反复补扫。
5. 把依赖送进去：SBOM 从哪来、怎么传
5.1 生成清单：先用构建工具自带的插件
最省事的方式是用各语言生态现成的插件在打包阶段顺手生成。
Java 项目加一个 Maven 插件，绑定到package阶段，构建完target目录下就多出一份 CycloneDX 格式的 JSON；Node 项目有对应的命令行工具，npx直接跑；容器镜像可以用镜像扫描工具以 CycloneDX 格式输出。Go 和 Python 也都有成熟插件。
有个细节值得强调：清单要包含传递依赖，否则等于白做。很多团队的依赖问题不在自己直接声明的那几个包上，而在第三层、第四层被间接引进来的包。生成时确认工具的参数里包含了完整依赖树的解析，而不是只读一下清单文件。
生成出来的文件我习惯先人眼看一眼，重点看三个地方：metadata.component里的项目名和版本对不对、components数组的长度是不是符合预期、每个组件有没有purl字段。purl是包的唯一标识，形如pkg:maven/group/artifact@1.2.3，平台靠它来精确匹配漏洞记录。缺了purl的组件，匹配率会直线下降，等于摆在那里但查不出问题。
5.2 走 API 上传：一条 curl 打通全流程
界面上的"上传 BOM"按钮适合手工验证，真正要用起来必须走接口。核心接口是PUT /api/v1/bom，用 multipart 表单提交。
export DT_URL="http://192.168.10.20:8081" export DT_API_KEY="你的密钥" export PROJECT_UUID="项目的唯一标识" curl -sS -X PUT "${DT_URL}/api/v1/bom" \ -H "X-Api-Key: ${DT_API_KEY}" \ -H "Accept: application/json" \ -F "project=${PROJECT_UUID}" \ -F "autoCreate=true" \ -F "bom=@target/bom.json"几个参数的实际含义得说清楚。project传的是项目 UUID，不是项目名，这个值在项目详情页的地址栏里能看到。autoCreate=true表示如果这个 UUID 对应的项目不存在就自动创建，配合项目名和版本可以在某些接口变体里一并指定。bom是文件字段。
上传接口是异步的，返回 200 不代表处理完了，只代表收到并入了队列。真正的处理结果要看响应里的 token，再拿 token 去查处理状态，或者在界面上看项目的"BOM 处理"页面。我第一次接入时看到 200 就以为成功了，结果刷新项目一看组件数是 0，回头查才发现处理失败了——原因是文件格式不合法。
autoCreate这个开关是把双刃剑。开着的确省事，但一旦项目名或版本算错，会在平台里悄悄造出一堆名字相近的重复项目，清理起来很烦。我的做法是：流水线里首次上传前先用接口查一下项目是否存在，不存在就显式创建并把 UUID 落下来写进流水线变量，之后固定用这个 UUID 上传，autoCreate只在本地试验时开。
5.3 接进流水线：位置比工具更重要
SBOM 上传放在流水线的哪一步，直接影响数据的可用性。
放在构建成功之后、部署之前是最合理的。此时依赖已经解析完成，清单是准确的；如果上传失败，可以让流水线继续，因为上传失败不该阻断业务发布，但要在日志里明确告警出来。
有一个取舍要提前想：是按每次构建都上传，还是只在主干分支上传？我的经验是主干分支每次构建都传，特性分支只在需要评审时手动传。原因是平台里每个项目对应一个 UUID，如果每个特性分支都建一个项目，项目列表会爆炸，而且这些短期分支的漏洞状态没人看。主干持续覆盖上传的好处是，同一个项目的组件清单始终反映最新状态，漏洞关联会自动跟着更新。
还有一个容易忽略的配置：项目的版本维度。同一个服务有 1.0、2.1 多个在跑，是建一个项目还是按版本建多个？平台的模型是项目 + 版本，一个项目下可以有多个版本。实践中我把"服务"作为项目，把"发布版本"作为版本，这样既能看某个版本的具体情况，也能在项目层面看到整体风险分布。
6. 从"发现"到"有人管"：策略规则和通知怎么配
6.1 策略粒度：别一上来就全量告警
平台默认有一套策略，比如发现某个严重级别以上的漏洞就标记违规。这套默认规则在项目少的时候还行，项目一多就是灾难——几千个组件里总有那么几十个带着各种历史遗留的中低危问题，通知渠道天天响，响到最后所有人都麻木了，真出高危反而没人看。
我的建议是按"影响面 + 可利用性"分层建策略，而不是按严重级别一刀切。
| 策略维度 | 规则示例 | 违规动作 | 适用场景 |
|---|---|---|---|
| 严重级别硬门槛 | 严重级别为最高档且组件为直接依赖 | 标记为拒绝 | 对外服务项目 |
| 版本状态 | 存在已修复的新版本且当前版本落后两个大版本 | 标记为需关注 | 全部项目 |
| 许可证约束 | 命中特定许可证清单 | 标记为需关注 | 对外分发的产品 |
| 组件活跃度 | 组件所属项目已停止维护超过一定时间 | 标记为需关注 | 核心系统 |
| 排除规则 | 明确判定为误报的组件版本对 | 忽略 | 全部项目 |
"忽略"这个能力一定要善用。有些漏洞在特定使用方式下根本不可利用，比如某个库的问题出在一个你完全没调用的功能模块里。这种反复被报出来、团队已经确认无风险的条目，就应该进白名单，否则会持续污染告警信噪比。白名单要写明原因和确认人，别让它变成"一键消音"。
6.2 通知渠道：分层推送，控制噪音
通知配置的模型是"规则 + 发布器 + 模板"。规则定义什么条件下触发，发布器定义往哪发，模板定义消息长什么样。
渠道选择上，我最推荐接团队日常用的即时通讯工具的 Webhook，因为消息进了大群，相关的人都能看到，不容易被邮件规则过滤掉。邮件适合作为周报汇总，不适合实时告警。
推送分级很有必要。最高级别的违规直接推到主频道并 @ 相关值班人，中等级别推到单独的告警频道每天汇总一次，全部违规的完整清单做成定时报表，一周发一次。这样既保证高危能被立刻看到，又不会让日常讨论被大量噪音淹没。
模板内容要定制，默认模板信息太少。我一般会往里面加三样东西：项目名和版本、组件的完整坐标和当前版本、以及平台里该项目的直达链接。加了链接之后，收到告警的人点一下就能看到上下文，响应速度会明显快很多。
通知触发是有节流的，同一组件的同一状态不会反复推。但如果你频繁重新上传 SBOM，可能会看到状态在"违规"和"正常"之间来回跳，导致通知重复。根源往往是不同流水线传了不同版本的清单互相覆盖，排查时先看最近几次上传的时间戳。
7. 跑起来之后才会遇到的问题：几个真实的排查记录
7.1 组件明明在清单里，为什么漏洞查不出来
这是被问得最多的一类问题，表现是 SBOM 上传成功、组件数量也对，但某个已知有漏洞的组件就是没有关联出漏洞。排查下来原因基本集中在三种。
第一种，purl缺失或格式不规范。平台匹配漏洞靠的是包的生态、命名空间、名称、版本这四个要素，任何一个不对就匹配不上。有些生成工具默认不输出purl，或者把 Maven 的 group 和 artifact 拼错了位置，看起来很相似但匹配失败。验证方法很简单：进组件详情，看标识符字段是不是空的。
第二种，版本号被规范化了。有类包的版本里带前导 v、带额外的元数据后缀、或者是范围表达式，生成工具解析后写进清单的可能是规范化之后的形态，而漏洞库里的版本区间是按原始形态描述的。这类问题比较隐蔽，需要在组件详情里对照实际声明版本看一眼。
第三种，漏洞库还没同步到这条记录。公开漏洞从披露到进入各个漏洞库有延迟，短的几小时，长的几天。如果漏洞是昨天刚公布的，查不出来很正常。这时候可以看漏洞库里该条目的最后修改时间来判断。
排查顺序我一般这么走：先看组件标识符有没有、对不对；再看这个组件在平台里的"分析"面板，看分析器有没有跑过、有没有报错；最后才是怀疑漏洞库数据的时效。
7.2 内存与同步那点事：几个能省下大量时间的配置
跑一段时间后最常见的抱怨是"卡"。界面加载慢、项目列表转圈、分析任务排队。
第一个抓手是API 服务端的内存。这个服务的默认堆内存偏保守，项目多、组件多的时候会频繁 GC。给容器配置合理的内存上限，并通过环境变量设置 JVM 堆大小，通常调到 4G 以上会有明显改善。但别把容器内存限制和堆大小设成一样大，留出四分之一的余量给堆外内存和系统，否则容器会被 OOM 直接杀掉，比卡更麻烦。
第二个抓手是数据库连接池。默认连接数在小规模下够用，并发上传多个 SBOM 时会看到连接等待超时。适当调大，同时确认 PostgreSQL 的最大连接数配置跟得上，两头不匹配一样会报错。
第三个抓手是分析任务的并发度。组件数量多的项目，重新分析是个重活。并发开太高会把 CPU 和数据库打满，开太低一次分析跑半小时。我的经验值是并发度设在 CPU 核数左右比较平衡，超过这个数收益不明显。
第四个是老项目的清理。跑了一年之后，平台里往往积累了大量已经下线的服务和临时项目，这些项目的组件记录还在被持续分析、持续产生告警。定期把确认下线的项目设为"未激活"，能显著减少后台负担和告警噪音。
7.3 备份与升级：别把账本弄丢了
平台里存的东西有个特点：重建成本极高。项目、历史 SBOM、白名单里的判定结论、策略配置，这些都是人工积累出来的，容器可以重建，这些丢了就没了。
备份策略分两层。数据库按天全量转储，这层是根本；配置文件目录（那个挂载到/data的卷）定期打包，里面有些运行期生成的密钥材料，恢复时如果没有，已签发的令牌会全部失效。
升级时的动作顺序固定下来：先停前端和 API 服务端，转储数据库，拉取目标版本镜像，启动，观察日志直到初始化完成，最后验证一遍登录、项目列表、上传。跨大版本时同时要看升级说明里关于数据库迁移的注意事项，有些版本要求先升到某个中间版本再继续，硬跳会卡住。
Dependency-Track 这套东西刚上手时容易觉得步骤多，但真正的门槛不在部署，而在于把它嵌进团队的日常——SBOM 要稳定地产生并上传，策略要贴着实际情况调，告警要有人接。我在实际推进时最有效的一个做法是先从两三个核心服务开始，把从构建到告警的完整链路跑顺，让团队先看到"上周披露的那个漏洞，我们在两小时内定位到了受影响的三个服务"这样的实际效果，再往其它项目铺开。反过来，一上来就全量接入、全量告警，大概率两周之后所有人都会把它当噪音源屏蔽掉。
