2. 搭建ZAP自动化工作环境

在开始编写任何自动化脚本之前，必须先让 ZAP 具备“可被程序调用”的能力。ZAP 提供了图形界面（GUI）、命令行（CLI）和 REST API 三种使用方式，自动化安全测试主要依赖后两者。本节围绕一条主线展开：先准备 Java 运行时，再安装 ZAP，然后分别验证命令行与 API 是否可用，最后用 Docker 部署一套可复现、可移植的 ZAP 环境。整个过程的目标不是“装上就行”，而是让 ZAP 成为一个能被 CI/CD 流水线稳定调用的服务组件。

一、Java 环境：ZAP 的运行前提

ZAP 是基于 Java 开发的，因此运行 ZAP 前必须安装合适的 JDK。ZAP 2.14 及以上版本要求 Java 11 或更高版本，推荐使用 Java 17（LTS）。安装完成后，需要确认 java 命令在终端中可用，并且版本符合要求。在 Linux/macOS 上可以执行：

java -version
# 期望输出示例：
# openjdk version "17.0.10" 2024-01-16
# OpenJDK Runtime Environment (build 17.0.10+7)
# OpenJDK 64-Bit Server VM (build 17.0.10+7, mixed mode)

如果系统同时存在多个 Java 版本，需要设置 JAVA_HOME 指向 ZAP 使用的 JDK，并将 $JAVA_HOME/bin 加入 PATH。在 Windows 上，可以通过“系统属性 → 环境变量”配置；在 Linux/macOS 上，可以在 ~/.bashrc 或 ~/.zshrc 中写入：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

配置完成后重新打开终端，再次执行 java -version 确认生效。这一步看似简单，但很多“ZAP 启动失败”的问题都源于 Java 版本不匹配或 JAVA_HOME 未正确设置。

二、安装 ZAP：三种方式的选择

ZAP 的安装方式主要有三种：安装包安装、解压包安装和 Docker 部署。安装包适合本地桌面使用，解压包适合需要自定义配置的服务器环境，Docker 则适合自动化流水线。对于自动化安全测试工程，推荐优先使用 Docker，因为它能保证环境一致性，避免“本地能跑、CI 上跑不起来”的问题。

如果选择解压包方式，下载 ZAP_2.14.0_Linux.tar.gz 后解压到 /opt/zap，目录结构大致如下：

/opt/zap/
├── zap.sh              # Linux 启动脚本
├── zap.bat             # Windows 启动脚本
├── zap.jar             # 核心程序
├── lib/                # 依赖库
├── plugin/             # 插件目录
└── xml/                # 配置文件

启动命令行模式时，使用 zap.sh -cmd 进入交互式命令行，或使用 zap.sh -daemon 以守护进程方式运行。守护进程模式是自动化测试的常用方式，它会在后台启动 ZAP，并开放 API 端口供外部调用。

三、Docker 部署：可复现的 ZAP 环境

ZAP 官方提供了 Docker 镜像 ghcr.io/zaproxy/zaproxy:stable。使用 Docker 部署时，需要把 ZAP 的 API 端口（默认 8080）映射到宿主机，并设置 API Key。一个典型的启动命令如下：

docker run -d --name zap \
  -p 8080:8080 \
  -p 8090:8090 \
  -e ZAP_API_KEY=mysecretkey \
  ghcr.io/zaproxy/zaproxy:stable \
  zap.sh -daemon -host 0.0.0.0 -port 8080 \
  -config api.key=mysecretkey \
  -config api.addrs.addr.name=.* \
  -config api.addrs.addr.regex=true

这里有几个关键参数需要解释：-daemon 表示以守护进程运行；-host 0.0.0.0 允许容器外部访问；-port 8080 指定 API 监听端口；api.key 设置 API 密钥，防止未授权调用；api.addrs.addr.name=.* 与 api.addrs.addr.regex=true 组合表示允许所有来源地址访问 API。在生产环境中，应把来源地址限制为具体的 CI 节点 IP，而不是使用 .*。

启动后，可以用 docker logs zap 查看日志，确认出现类似 ZAP is now listening on 0.0.0.0:8080 的输出。如果日志中出现 Failed to bind 或 API key not set，说明端口冲突或密钥配置有误，需要回到启动命令检查。

四、验证命令行与 API 可用性

环境搭好后，必须做两项验证：命令行能否正常执行，API 能否正常响应。命令行验证可以执行一次简单的扫描任务，例如：

zap.sh -cmd -quickurl http://example.com -quickout /tmp/report.html

如果命令正常结束并生成 report.html，说明命令行模式可用。API 验证则通过 HTTP 请求完成，ZAP 提供了一个基础接口 /JSON/core/view/version，用于返回当前版本号：

curl "http://localhost:8080/JSON/core/view/version/?apikey=mysecretkey"
# 期望返回示例：
# {"version":"2.14.0"}

如果返回中包含 version 字段，说明 API 已可用。若返回 {"code":"unauthorized"}，说明 API Key 不匹配；若连接被拒绝，说明端口未映射或 ZAP 未启动。建议把这两条验证命令写入一个 check_zap.sh 脚本，在每次环境初始化后自动执行，作为流水线的“健康检查”步骤。

五、环境搭建中的常见问题与排查

在实际操作中，最容易出现的问题集中在三类。第一类是 Java 版本问题：ZAP 启动时报 UnsupportedClassVersionError，说明当前 Java 版本低于 ZAP 要求，需要升级 JDK 或切换 JAVA_HOME。第二类是端口冲突：8080 被其他服务占用时，ZAP 无法绑定端口，可以通过 lsof -i :8080 或 netstat -ano | findstr 8080 查找占用进程，或改用其他端口。第三类是 API 访问被拒绝：如果返回 {"code":"unauthorized"}，需要检查 api.key 是否与请求中的 apikey 一致；如果返回 {"code":"forbidden"}，则需要检查 api.addrs.addr.name 是否允许了调用方 IP。

六、可复用的环境检查清单

为了确保每次搭建都完整、可验证，可以按照下面的清单逐项确认。这份清单可以直接作为自动化脚本的检查项：

检查项	验证命令 / 方法	通过标准
Java 版本	java -version	输出为 11 或 17
JAVA_HOME	echo $JAVA_HOME	指向有效 JDK 目录
ZAP 可执行	zap.sh -version	输出版本号
Docker 容器运行	docker ps | grep zap	状态为 Up
API 端口可达	curl http://localhost:8080	返回 JSON 响应
API Key 有效	curl .../version/?apikey=...	返回 version 字段
命令行扫描	zap.sh -cmd -quickurl ...	生成报告文件

完成以上步骤后，ZAP 就已经具备了被自动化脚本调用的基础条件。下一阶段的工作，是让 ZAP 能够按照预设策略执行扫描任务，并把结果输出为可解析的格式。环境搭建的质量直接决定了后续自动化流程的稳定性，因此建议在每次环境变更后都重新执行一遍验证命令，确保 ZAP 始终处于可用状态。