1. 为什么一个依赖清单工具值得单独写安装篇软件供应链安全这几年被反复提及但真正落到日常开发里很多团队连我到底用了哪些第三方组件、它们各自是什么版本、有没有已知问题都说不清楚。Dependency-Track 就是冲着这个痛点来的它是一款开源的软件成分分析平台核心能力是接收 SBOM软件物料清单然后持续比对组件版本与公开的漏洞库把风险以仪表盘的形式呈现出来。我第一次接触它是在一个多模块的项目里当时安全同事丢过来一份组件清单问某个间接依赖的版本有没有问题我们几个人翻了半天构建文件也没理清楚传递依赖的完整链路。那次之后我就意识到靠人工维护依赖清单迟早要出事必须有一个能自动接收 SBOM、自动比对的平台。Dependency-Track 正好满足这个需求而且它是自托管的数据留在自己手里对内部项目比较友好。不过它的安装并不像pip install那样一行搞定。它依赖数据库、需要 API Key、还要考虑前端和后端的配合第一次装很容易在某个环节卡住。所以这篇我打算把安装这件事讲透从架构理解到落地验证把每一步的意图和坑都说清楚。适合谁看适合第一次部署 Dependency-Track 的后端或运维同学也适合想了解 SBOM 平台怎么落地的人。哪怕你之前没接触过软件成分分析跟着走也能跑起来。需要先说明一点Dependency-Track 的版本迭代比较快不同大版本之间配置项会有差异。我下面讲的是基于常见的 4.x 系列部署方式如果你用的是更新的版本个别参数名可能要对一下官方文档。但整体思路和排查方法是通用的。2. 先把架构想明白再动手装2.1 它到底由哪几块组成很多人装到一半卡住根本原因是一开始没搞清楚 Dependency-Track 不是一个单体应用。它至少包含三个部分API Server后端基于 Java 开发负责接收 SBOM、执行漏洞分析、对外提供 REST 接口。它是整个系统的核心。Frontend前端一个独立的 Web 界面通过调用后端 API 来展示数据。注意前端和后端是分开部署的不是打包在一起的。Database数据库存储项目、组件、漏洞、策略等所有数据。官方支持 PostgreSQL早期版本也支持过其他数据库但生产环境基本都推荐 PostgreSQL。理解这个拆分非常关键。因为这意味着你不能只启动一个容器就完事前端要能访问到后端后端要能连上数据库三者缺一不可。我见过有人只跑了后端容器然后打开浏览器发现是空白页折腾半天才发现前端根本没部署。2.2 为什么官方推荐容器化部署Dependency-Track 官方主推 Docker 和 Docker Compose 部署这不是为了赶时髦而是有实际原因的。它的后端是 Java 应用对 JDK 版本、内存参数、启动脚本都有要求数据库需要初始化 schema前后端之间还有网络配置。如果手动装光是环境依赖就能耗掉大半天而且换一台机器又要重来一遍。用容器编排的好处是所有依赖被封装进镜像配置通过环境变量注入数据库用官方镜像一键拉起。整个栈可以用一个 compose 文件描述清楚迁移和重建都很方便。对于自托管场景这是性价比最高的方式。提示如果你的环境完全不允许使用容器也可以手动部署 Java 应用加外部数据库但配置复杂度会明显上升本文以容器化为主线手动方式只做思路说明。2.3 安装前需要确认的资源动手之前先确认几件事能省掉后面很多返工项目建议配置说明CPU2 核以上漏洞分析是计算密集型核数太少会明显变慢内存4GB 以上后端 JVM 本身就要吃内存数据库也要磁盘20GB 以上漏洞库和 SBOM 数据会持续增长数据库PostgreSQL 13生产环境强烈建议独立部署或持久化卷网络能访问漏洞数据源后端需要定期同步漏洞情报内存这一项我要特别强调。Dependency-Track 后端默认的 JVM 堆可能不够用如果机器内存小启动后跑一会儿就 OOM。后面我会讲怎么调这个参数。3. 用 Compose 把整套栈拉起来3.1 准备目录和 compose 文件我习惯先建一个独立目录把所有配置和数据都放进去方便备份和迁移mkdir -p /opt/dtrack cd /opt/dtrack然后创建docker-compose.yml。下面这份是我实际用过的精简版本去掉了不必要的注释保留了关键配置version: 3.8 services: dtrack-apiserver: image: dependencytrack/apiserver:latest depends_on: - dtrack-postgres environment: - ALPINE_DATABASE_MODEexternal - ALPINE_DATABASE_URLjdbc:postgresql://dtrack-postgres:5432/dtrack - ALPINE_DATABASE_DRIVERorg.postgresql.Driver - ALPINE_DATABASE_USERNAMEdtrack - ALPINE_DATABASE_PASSWORDchangeme_strong_password - ALPINE_DATABASE_POOL_ENABLEDtrue ports: - 8081:8080 volumes: - ./data:/data restart: unless-stopped dtrack-frontend: image: dependencytrack/frontend:latest depends_on: - dtrack-apiserver environment: - API_BASE_URLhttp://localhost:8081 ports: - 8080:8080 restart: unless-stopped dtrack-postgres: image: postgres:15-alpine environment: - POSTGRES_USERdtrack - POSTGRES_PASSWORDchangeme_strong_password - POSTGRES_DBdtrack volumes: - ./pgdata:/var/lib/postgresql/data restart: unless-stopped这里有几个点值得展开说。第一ALPINE_DATABASE_MODEexternal表示使用外部数据库。Dependency-Track 后端镜像其实内置了一个嵌入式数据库模式但那个模式只适合演示数据量一大就不行生产必须用 external。第二数据库连接串里的主机名是dtrack-postgres这是 compose 里的服务名。容器之间通过服务名互相解析不需要写 IP。这一点如果搞错后端会一直报连接失败。第三前端的环境变量API_BASE_URL指向的是浏览器能访问到的后端地址不是容器内部的地址。这是个高频坑如果你写http://dtrack-apiserver:8080容器内部能通但浏览器解析不了这个主机名页面就会一直转圈或者报错。所以这里要填宿主机对外暴露的地址比如http://localhost:8081或者你的服务器域名。3.2 密码和端口的安全处理上面示例里的密码是占位符实际部署一定要换成强密码。数据库密码会同时出现在后端和数据库两个服务里必须保持一致改的时候两处都要改。端口方面我把后端映射到宿主机的 8081前端映射到 8080。这样浏览器访问http://服务器IP:8080就是前端界面后端 API 在 8081。如果你前面还有反向代理可以把这两个端口都收进去只对外暴露一个域名。注意后端 API 默认没有强认证保护任何能访问到 8081 的人都能调用接口。生产环境务必通过网络策略或反向代理限制访问来源不要直接暴露在公网。3.3 启动顺序与首次初始化配置写好后直接拉起docker compose up -d第一次启动会比较慢因为后端要初始化数据库 schema、下载漏洞数据源的元信息。你可以用下面的命令观察日志docker compose logs -f dtrack-apiserver看到类似Started ApiServerApplication或者监听 8080 端口的日志说明后端起来了。数据库初始化可能需要一两分钟耐心等一下。如果日志里反复出现数据库连接异常先检查数据库容器是否健康docker compose ps确认dtrack-postgres的状态是Up而不是Restarting。如果数据库一直重启多半是密码或者数据目录权限的问题。4. 装完之后必须做的几项验证4.1 确认前端能正常连上后端浏览器打开http://服务器IP:8080正常情况下会看到登录页。如果页面能加载但登录时报错或者界面元素加载不全八成是前端连不上后端。这时候按 F12 打开开发者工具看 Network 面板里对 API 的请求是不是失败了。排查思路是这样的先在宿主机上直接访问后端接口比如curl http://localhost:8081/api/version如果能返回版本信息说明后端本身没问题那问题就出在前端的API_BASE_URL配置上检查它是不是填了浏览器访问不到的地址。4.2 默认账号与首次登录Dependency-Track 首次启动会创建一个默认管理员账号用户名是admin初始密码也是admin。登录后第一件事就是改密码这个不用我多说。改完密码后建议顺手创建一个专门用于 CI 的 API Key后面集成流水线时会用到。API Key 在用户管理里生成注意它只在生成时显示一次要立刻保存下来。4.3 检查漏洞数据源是否同步成功Dependency-Track 的价值在于漏洞比对如果数据源没同步平台就是个空壳。登录后进入后台的漏洞数据源管理页面看看各个数据源的状态。首次同步可能需要一段时间因为要拉取全量数据。如果某个数据源一直显示同步失败先确认后端容器能不能访问外网。有些内网环境需要配置代理才能出去这时候要在后端服务里加代理相关的环境变量。这一点在纯内网部署时特别容易忽略。5. 那些让我折腾半天的坑5.1 内存不足导致后端反复重启这是我最开始踩的坑。机器给了 2GB 内存后端启动后跑几分钟就挂日志里是OutOfMemoryError。原因是 JVM 默认堆大小按物理内存比例算容器里识别到的内存和实际可用内存不一致导致堆开得过大。解决办法是显式限制 JVM 堆。可以在 compose 里加环境变量environment: - JAVA_OPTS-Xmx2g -Xms512m具体数值按你的机器来一般留一半内存给数据库和系统剩下的给 JVM。我现在的习惯是 4GB 内存的机器给后端 2GB 堆跑起来比较稳。5.2 数据库连接池耗尽并发上传 SBOM 的时候如果连接池配置太小会出现请求排队甚至超时。后端默认的连接池大小对一般场景够用但如果你的团队同时跑很多流水线建议调大。相关参数通过环境变量控制具体名称不同版本略有差异建议对照官方文档确认。我的经验是先按默认跑观察日志里有没有连接等待的告警有的话再逐步调大不要一上来就设很大否则数据库压力也会跟着上去。5.3 前端页面白屏但后端正常这个坑前面提过根源就是API_BASE_URL配错。还有一种情况是跨域问题如果前端和后端不在同一个域名下浏览器会因为 CORS 策略拦截请求。解决办法是在后端配置允许的来源或者干脆用反向代理把前后端放在同一个域名下用路径区分。后者更省事也更安全。5.4 数据卷权限问题PostgreSQL 容器对数据目录的权限有要求如果宿主机上的pgdata目录属主不对数据库会启动失败。日志里通常能看到permission denied之类的提示。处理方式是确认目录属主和容器内运行数据库的用户匹配或者干脆让 Docker 自己管理卷不手动挂载宿主机目录。6. 手动部署的替代思路如果你的环境确实不能用容器手动部署也不是不行但要有心理准备。大致步骤是先装好 PostgreSQL 并创建数据库和用户然后下载后端发行包配置数据库连接参数用 Java 命令启动最后单独部署前端静态资源用 Nginx 之类的服务器托管并把 API 请求代理到后端。手动部署最容易出问题的地方是版本匹配。后端、前端、数据库驱动之间都有版本对应关系装错一个就可能起不来。所以除非有硬性限制我还是建议用容器方式省心太多。7. 装好只是起点接下来怎么用安装完成、能登录、数据源同步正常这只是把平台搭起来了。真正发挥价值是要把它接进你的构建流程在 CI 里生成 SBOM通过 API Key 上传到 Dependency-Track然后让平台自动分析并触发策略告警。这一步打通之后每次构建都会自动更新组件清单新出现的漏洞会被及时标记出来而不是等到安全审计才手忙脚乱。我在实际使用中的一个体会是安装阶段多花点时间把网络、内存、数据持久化这几件事做扎实后面会省掉大量运维麻烦。尤其是数据卷一定要做好备份漏洞库和项目数据重新同步的成本很高。另外API Key 要按用途分开管理CI 用的和人工查询用的不要混在一起方便出问题时快速定位和吊销。最后分享一个小技巧部署完成后先用一个简单的测试项目上传一份 SBOM走一遍完整流程确认从上传到漏洞展示都正常再去接真实的流水线。这样能把配置问题在影响面最小的时候暴露出来。