海康威视 ISAPI 协议录像管理与下载工具，提供 Web 管理界面，支持录像搜索、多模式下载、实时预览、云台控制等功能。
- 设备管理 — 连接海康威视 NVR/DVR，查看设备信息、通道列表、存储状态
- 录像搜索 — 按通道和时间段搜索设备上的录像记录
- 多模式下载
- ISAPI HTTP 时间段截取（推荐） — 通过 HTTP 接口直接下载指定时间段录像，速度远快于 RTSP，生成单个连续文件。失败时自动回退到 RTSP 方式
- RTSP 时间段截取 — 使用 FFmpeg 按指定时间段截取 RTSP 回放流，生成单个连续文件（速度接近实时）
- 文件下载（downloadPath）— 直接下载设备已存储的录像文件，速度快
- 流式下载（playbackURI）— 通过流式接口分段下载，自动尝试多种下载方式
- 实时预览 — 生成 RTSP / HTTP-FLV 预览地址，可用 VLC 等播放器观看
- 云台控制（PTZ） — 支持上下左右、变焦、预置点调用
- 存储管理 — 查看硬盘状态、容量、剩余空间
- Web 界面 — 现代化深色主题 UI，无需安装额外前端依赖
| 模式 | 速度 | 输出 | 需要 FFmpeg | 说明 |
|---|---|---|---|---|
| ISAPI HTTP 截取 | 快（HTTP 文件传输速度） | 单文件 | 可选（非 MP4 时需转封装） | 推荐，失败自动回退 RTSP |
| RTSP 截取 | 慢（接近实时） | 单文件 | 必需 | 兼容性最好 |
| 文件下载 | 快 | 多文件（按录像片段） | 不需要 | 需先搜索 |
| 流式下载 | 中 | 多文件（按录像片段） | 不需要 | 需先搜索 |
- 构建
playbackURI（含精确时间段），POST 到/ISAPI/ContentMgmt/download - 自动尝试 4 种 URI 变体（tracks/channels/ISAPI 路径 + 尾斜杠变体），兼容不同固件
- 下载到临时文件，检查是否为标准 MP4（ftyp 检测）
- 非 MP4 时使用 FFmpeg 本地转封装（三级降级策略：纯 copy → 音频 AAC → 无音频）
- 失败时自动回退到 FFmpeg RTSP 方式
| 依赖 | 版本 | 说明 |
|---|---|---|
| Java (JDK) | >= 8 | 必需，推荐 Adoptium |
| Maven | >= 3.x | 可选，无 Maven 时自动下载依赖并编译 |
| FFmpeg | 任意版本 | 可选，RTSP 截取必需；ISAPI HTTP 截取时非 MP4 转封装需要 |
| Python 3 | >= 3.6 | 可选，仅运行模拟服务器时需要 |
macOS / Linux：
chmod +x start.sh
./start.shWindows：
start.bat启动脚本会自动完成以下操作：
- 检查 Java 环境
- 检查 FFmpeg（未安装时可选择自动下载到项目目录）
- 使用 Maven 构建项目（无 Maven 时自动下载依赖并手动编译）
- 启动 Web 服务器
启动成功后，在浏览器访问：
http://localhost:8080
在 Web 界面中填写设备 IP、端口、用户名和密码，点击"连接设备"即可。
testISAPI/
├── src/main/java/com/comp/testISAPI/
│ ├── ISAPIWebServer.java # Web 服务器主程序（入口）
│ ├── ISAPIClient.java # ISAPI 协议客户端封装
│ ├── ISAPIQueryRecMain.java # 命令行录像查询/下载工具
│ ├── DigestAuthenticator.java # HTTP Digest 认证实现
│ └── Logger.java # 日志工具（控制台 + 文件）
├── index.html # Web 管理界面
├── pom.xml # Maven 项目配置
├── mock_server.py # ISAPI 模拟服务器（Python）
├── start.sh # macOS/Linux 一键启动脚本
├── start.bat # Windows 一键启动脚本
├── setup-ffmpeg.sh # FFmpeg 安装脚本（macOS/Linux）
├── setup-ffmpeg.bat # FFmpeg 安装脚本（Windows）
├── start_mock.sh # 模拟服务器启动脚本（macOS/Linux）
└── start_mock.bat # 模拟服务器启动脚本（Windows）
# 编译打包（生成 fat jar）
mvn clean package -DskipTests
# 运行
cd target
java -Dfile.encoding=UTF-8 -jar testISAPI-1.0.0.jarRTSP 时间段截取功能必需 FFmpeg；ISAPI HTTP 截取在非 MP4 转封装时也会用到 FFmpeg（无 FFmpeg 则跳过转封装直接输出原始文件）。
方式一：运行安装脚本（推荐）
# macOS / Linux
chmod +x setup-ffmpeg.sh
./setup-ffmpeg.sh
# Windows
setup-ffmpeg.bat脚本会自动下载对应平台的 FFmpeg 到项目 ffmpeg/ 目录。
方式二：使用系统包管理器
# macOS
brew install ffmpeg
# Ubuntu / Debian
sudo apt install ffmpeg
# Windows (Scoop)
scoop install ffmpeg程序会按以下优先级查找 FFmpeg：系统 PATH → 常见系统路径 → 用户目录 → 项目内置 → 旧目录结构。
Web 服务器提供以下 REST 接口：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / |
Web 管理界面 |
| POST | /api/device-info |
获取设备信息 |
| POST | /api/channels |
获取通道列表 |
| POST | /api/search |
搜索录像 |
| POST | /api/download |
下载录像（文件/流式模式） |
| POST | /api/rtsp-download |
时间段截取下载（ISAPI HTTP / RTSP） |
| GET | /api/download-status?taskId=xxx |
查询下载进度 |
| DELETE | /api/download-status?taskId=xxx |
取消运行中任务或删除已完成任务记录 |
| POST | /api/rtsp-url |
获取 RTSP 预览地址 |
| POST | /api/storage |
获取存储状态 |
| POST | /api/ptz |
云台控制 |
| GET | /downloads/{filename} |
下载已保存的录像文件 |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
deviceIp |
string | 是 | 设备 IP |
port |
int | 否 | HTTP 端口，默认 80 |
username |
string | 是 | 用户名 |
password |
string | 是 | 密码 |
channelId |
string | 是 | 通道 ID |
startTime |
string | 是 | 开始时间（yyyy-MM-dd'T'HH:mm） |
endTime |
string | 是 | 结束时间 |
rtspPort |
int | 否 | RTSP 端口，默认 554 |
downloadMethod |
string | 否 | isapi-http（推荐）或 rtsp，默认 rtsp |
clientTimezoneOffsetMinutes |
int | 否 | 浏览器时区偏移（分钟） |
除常规进度字段外，包含以下诊断字段：
| 字段 | 说明 |
|---|---|
requestedMethod |
用户请求的下载方式（isapi-http / rtsp） |
effectiveMethod |
实际使用的下载方式（可能因回退而与请求不同） |
fallbackUsed |
是否发生了自动回退（true / false） |
timeMode |
时间模式 |
timeBasis |
时间基准来源（device / browser / server） |
deviceTimeZone |
设备时区 |
normalizedStart / normalizedEnd |
归一化后的搜索时间 |
attemptedUrls |
已尝试的 URL 列表 |
cancelRequested |
是否收到取消请求 |
| 变量名 | 默认值 | 说明 |
|---|---|---|
ISAPI_TIME_MODE |
DEVICE_LOCAL_LITERAL_Z |
时间模式，可选 DEVICE_LOCAL_LITERAL_Z / UTC_Z |
MAX_DOWNLOAD_RANGE_MINUTES |
1440 |
最大下载时间范围（分钟） |
STREAM_READ_TIMEOUT_SECONDS |
600 |
流式下载 / ISAPI HTTP 下载读取超时（秒） |
FFMPEG_TIMEOUT_SECONDS |
1800 |
RTSP 截取 FFmpeg 总超时（秒） |
FFMPEG_STALL_TIMEOUT_SECONDS |
30 |
RTSP 截取时 FFmpeg 无输出判定卡死超时（秒） |
FFMPEG_GRACEFUL_QUIT_SECONDS |
10 |
RTSP 截取结束时等待 FFmpeg 优雅退出的时间（秒） |
TASK_TTL_MINUTES |
30 |
已完成/失败/取消任务保留时长（分钟） |
MAX_TASK_LOG_LINES |
500 |
单任务日志最大保留行数 |
RTSP_PORT_DEFAULT |
554 |
RTSP 默认端口 |
METHOD5_ENABLED |
true |
是否启用 StreamingProxy 回退下载方法 |
项目内置 Python 模拟服务器，可在无真实设备的情况下进行开发调试：
# macOS / Linux
./start_mock.sh
# Windows
start_mock.bat
# 或直接运行
python3 mock_server.py模拟服务器默认监听 localhost:8000，支持设备信息查询和录像搜索接口。在 Web 界面中将设备 IP 设为 localhost，端口设为 8000 即可连接。
- 后端：Java 8 +
com.sun.net.httpserver（内置 HTTP 服务器） - HTTP 客户端：OkHttp 4.12.0（含 Digest Authentication）
- 认证方式：HTTP Digest Authentication（Apache Commons Codec）
- 前端：原生 HTML/CSS/JavaScript（单文件，无框架依赖）
- 录像下载：ISAPI ContentMgmt/download（HTTP 快速下载）+ FFmpeg（RTSP 流录制 / 本地转封装）
- 构建工具：Maven 3.x（maven-shade-plugin 打 fat jar）
日志同时输出到控制台和文件，日志文件按日期存放在 ./log/ 目录，文件名格式为 isapi_yyyy-MM-dd.log：
log/isapi_2026-02-09.log
- 支持 DEBUG、INFO、WARN、ERROR 四个级别，默认 DEBUG。
- 控制台与文件均使用 UTF-8 编码，跨平台一致。
- RTSP 截取任务会记录目标时长、尝试的 URL、进度等详细日志，便于排查问题。
- 录像下载保存在
./recordings/目录 - 建议单次搜索时间段不超过 1 小时，避免返回过多录像片段
- ISAPI HTTP 截取模式在设备不支持时会自动回退到 RTSP 方式
- RTSP 截取模式需要设备支持 RTSP 回放功能，且必须安装 FFmpeg
- 流式下载会自动尝试多种方式（POST+XML、GET+Token、StreamingProxy 等），兼容不同固件版本
- 搜索录像时会尝试 3 种 XML 命名空间格式，兼容不同设备型号
- ISAPI HTTP 下载使用 CDATA 包裹 playbackURI，避免 URL 中的
&破坏 XML - 流式下载方法2 使用 GET + query 参数传递 playbackURI（避免 GET 带 body 的兼容问题），方法3 使用 PUT + XML Body
- RTSP 截取：增加目标时长计算与日志输出，便于确认请求时间范围；支持 FFmpeg 卡死超时与优雅退出时间配置（
FFMPEG_STALL_TIMEOUT_SECONDS、FFMPEG_GRACEFUL_QUIT_SECONDS）。 - 流式下载：方法2 改为 GET +
playbackURIquery 参数；方法3 改为 PUT + XML Body；新增 playbackURI 请求窗口派生，兼容按时间段缩窄下载的机型。 - 环境变量：README 与环境变量表已同步上述 FFmpeg 相关配置及日志说明。