┌─────────────────────────────────────────────────────────┐
│                      API Gateway                        │
│            (RESTful API + WebSocket)                    │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│                  Application Layer                      │
│  ┌──────────────┬──────────────┬─────────────────────┐ │
│  │ 相机接入服务  │ 录像编排服务  │ 算法任务编排服务     │ │
│  └──────────────┴──────────────┴─────────────────────┘ │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│              Infrastructure Layer                       │
│  ┌──────────────┬──────────────┬─────────────────────┐ │
│  │ ONVIF 适配层 │ MediaMTX网关  │ FFmpeg编码引擎      │ │
│  └──────────────┴──────────────┴─────────────────────┘ │
│  ┌──────────────┬──────────────┬─────────────────────┐ │
│  │   MySQL      │ 存储卷管理    │ 算法节点池           │ │
│  └──────────────┴──────────────┴─────────────────────┘ │
└─────────────────────────────────────────────────────────┘

paths:
  cam_10_0_1_20_ch1_main:
    source: rtsp://admin:pass@10.0.1.20:554/Streaming/Channels/101
    sourceOnDemand: yes
    sourceOnDemandStartTimeout: 10s
    sourceOnDemandCloseAfter: 10s

    # 录像配置
    record: yes
    recordPath: /recordings/%path/%Y-%m-%d/%H-%M-%S
    recordFormat: fmp4
    recordSegmentDuration: 10m
    recordDeleteAfter: 7d

{
  "streams": [{
    "codec_name": "h264",
    "width": 1920,
    "height": 1080,
    "avg_frame_rate": "25/1"
  }]
}

DROP TABLE IF EXISTS `camera_device`;
CREATE TABLE `camera_device` (
  `id`               BIGINT NOT NULL COMMENT '主键ID',
  `camera_name`      VARCHAR(100) DEFAULT NULL COMMENT '设备名称',
  `group_id`         BIGINT DEFAULT NULL COMMENT '分组ID',

  -- ONVIF 连接信息
  `ip`               VARCHAR(50) NOT NULL COMMENT '设备IP',
  `port`             INT NOT NULL DEFAULT 80 COMMENT 'ONVIF端口',
  `username`         VARCHAR(50) NOT NULL COMMENT 'ONVIF用户名',
  `password`         VARCHAR(255) NOT NULL COMMENT 'ONVIF密码(AES加密)',

  -- 设备元信息
  `serial_number`    VARCHAR(100) DEFAULT NULL COMMENT '序列号',
  `manufacturer`     VARCHAR(100) DEFAULT NULL COMMENT '厂商',
  `model`            VARCHAR(100) DEFAULT NULL COMMENT '型号',
  `firmware_version` VARCHAR(100) DEFAULT NULL COMMENT '固件版本',

  -- 状态字段
  `camera_status`    INT DEFAULT 0 COMMENT '1在线 0离线',
  `last_online_time` DATETIME DEFAULT NULL COMMENT '最后在线时间',

  -- 审计字段
  `create_user`      BIGINT DEFAULT NULL,
  `create_dept`      BIGINT DEFAULT NULL,
  `create_time`      DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_user`      BIGINT DEFAULT NULL,
  `update_time`      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `status`           INT DEFAULT 1 COMMENT '1启用 0停用',
  `is_deleted`       INT DEFAULT 0 COMMENT '1已删除 0正常',

  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_ip_is_deleted` (`ip`, `is_deleted`),
  KEY `idx_group_id` (`group_id`),
  KEY `idx_camera_status` (`camera_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='相机设备主档表';

DROP TABLE IF EXISTS `camera_group`;
CREATE TABLE `camera_group` (
  `id`          BIGINT NOT NULL AUTO_INCREMENT,
  `group_name`  VARCHAR(100) NOT NULL COMMENT '分组名称',
  `parent_id`   BIGINT DEFAULT NULL COMMENT '父分组ID',
  `group_type`  TINYINT DEFAULT 0 COMMENT '0普通分组 1地理分组 2功能分组',
  `sort_order`  INT DEFAULT 0 COMMENT '排序',
  `icon`        VARCHAR(50) DEFAULT NULL COMMENT '图标',
  `description` VARCHAR(500) DEFAULT NULL COMMENT '描述',

  `create_user` BIGINT DEFAULT NULL,
  `create_dept` BIGINT DEFAULT NULL,
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_user` BIGINT DEFAULT NULL,
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `status`      INT DEFAULT 1,
  `is_deleted`  TINYINT DEFAULT 0,

  PRIMARY KEY (`id`),
  KEY `idx_parent_id` (`parent_id`),
  KEY `idx_group_type` (`group_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='相机分组表';

DROP TABLE IF EXISTS `camera_stream_path`;
CREATE TABLE `camera_stream_path` (
  `id`             BIGINT NOT NULL COMMENT '主键ID',
  `camera_id`      BIGINT NOT NULL COMMENT '设备ID',
  `path_name`      VARCHAR(255) NOT NULL COMMENT '媒体路径主键',
  `source_url`     VARCHAR(1000) DEFAULT NULL COMMENT 'RTSP源地址',

  -- ONVIF Profile 信息
  `profile_token`  VARCHAR(64) DEFAULT NULL COMMENT 'ONVIF ProfileToken',
  `profile_name`   VARCHAR(100) DEFAULT NULL COMMENT 'Profile名称',
  `video_encoding` VARCHAR(20) DEFAULT NULL COMMENT '编码格式(原始)',
  `video_codec`    VARCHAR(16) DEFAULT NULL COMMENT '标准化编码(H264/H265/HEVC)',
  `resolution`     VARCHAR(20) DEFAULT NULL COMMENT '分辨率',
  `subtype`        INT NOT NULL DEFAULT 0 COMMENT '0主码流 1子码流',
  `channel`        INT DEFAULT NULL COMMENT '通道号',
  `need_transcode` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否转码',

  -- 状态字段
  `enabled`        TINYINT NOT NULL DEFAULT 1 COMMENT '1启用 0停用',
  `status`         INT NOT NULL DEFAULT 1 COMMENT '1可用 0失败',

  `create_time`    DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_time`    DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_path_name` (`path_name`),
  KEY `idx_camera_id` (`camera_id`),
  KEY `idx_codec_transcode` (`video_codec`, `need_transcode`),
  KEY `idx_channel_subtype` (`camera_id`, `channel`, `subtype`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='流路径表';

DROP TABLE IF EXISTS `camera_offline_event`;
CREATE TABLE `camera_offline_event` (
  `id`              BIGINT NOT NULL AUTO_INCREMENT,
  `device_id`       BIGINT NOT NULL COMMENT '设备ID',
  `device_ip`       VARCHAR(50) DEFAULT NULL COMMENT '设备IP(冗余)',
  `group_id`        BIGINT DEFAULT NULL COMMENT '分组ID(冗余)',

  -- 事件时间线
  `start_time`      DATETIME NOT NULL COMMENT '离线开始时间',
  `last_check_time` DATETIME NOT NULL COMMENT '最后检测时间',
  `end_time`        DATETIME DEFAULT NULL COMMENT '恢复在线时间',
  `duration`        BIGINT DEFAULT 0 COMMENT '离线时长(秒)',

  -- 事件状态
  `is_resolved`     TINYINT DEFAULT 0 COMMENT '1已恢复 0未恢复',
  `alarm_status`    TINYINT DEFAULT 0 COMMENT '1已告警 0未告警',
  `remark`          VARCHAR(255) DEFAULT NULL COMMENT '备注',

  `create_time`     DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_time`     DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

  PRIMARY KEY (`id`),
  KEY `idx_device_status` (`device_id`, `is_resolved`),
  KEY `idx_time` (`start_time`, `end_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='设备离线事件表';

建议创建专用 ONVIF 账号,而非复用管理员账号
最小权限集:
  - 读取设备信息
  - 读取媒体配置
  - 读取流 URI
不需要:
  - PTZ 控制权限
  - 参数修改权限

防火墙规则:
  允许入站: TCP 80 (ONVIF), TCP 554 (RTSP)
  允许出站: TCP 任意 (用于 RTSP 数据回传)

跨网段访问:
  确保路由可达
  确认 NAT 规则 (若设备在内网)

byte[] nonce = new byte[16];
SecureRandom.getInstanceStrong().nextBytes(nonce);
String nonceBase64 = Base64.getEncoder().encodeToString(nonce);

byte[] digest = MessageDigest.getInstance("SHA-1").digest(
    (nonce + created + password).getBytes(StandardCharsets.UTF_8)
);
String passwordDigest = Base64.getEncoder().encodeToString(digest);

public class OnvifSoapClient {

    public Document sendSoapRequest(String url, String username, String password, String body)
            throws Exception {
        String envelope = buildSoapEnvelope(username, password, body);

        HttpResponse response = HttpRequest.post(url)
            .header("Content-Type", "application/soap+xml; charset=utf-8")
            .timeout(5000)
            .body(envelope)
            .execute();

        if (!response.isOk()) {
            throw new OnvifException("HTTP " + response.getStatus());
        }

        Document doc = XmlUtil.readXML(response.body());
        validateSoapFault(doc);
        return doc;
    }

    private String buildSoapEnvelope(String username, String password, String body) {
        String created = utcNow();
        byte[] nonce = generateNonce();
        String nonceBase64 = Base64.getEncoder().encodeToString(nonce);
        String digest = calculateDigest(nonce, created, password);

        return "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
            "<s:Envelope xmlns:s=\"http://www.w3.org/2003/05/soap-envelope\">" +
            "<s:Header>" +
            "<Security s:mustUnderstand=\"1\" " +
            "xmlns=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\">" +
            "<UsernameToken>" +
            "<Username>" + username + "</Username>" +
            "<Password Type=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest\">" +
            digest + "</Password>" +
            "<Nonce EncodingType=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary\">" +
            nonceBase64 + "</Nonce>" +
            "<Created xmlns=\"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd\">" +
            created + "</Created>" +
            "</UsernameToken>" +
            "</Security>" +
            "</s:Header>" +
            "<s:Body>" + body + "</s:Body>" +
            "</s:Envelope>";
    }

    private void validateSoapFault(Document doc) throws OnvifFaultException {
        NodeList faults = doc.getElementsByTagNameNS("*", "Fault");
        if (faults.getLength() > 0) {
            Element fault = (Element) faults.item(0);
            String code = getTextContent(fault, "Code", "Value");
            String reason = getTextContent(fault, "Reason", "Text");
            throw new OnvifFaultException(code, reason);
        }
    }
}

<s:Envelope>
  <s:Body>
    <s:Fault>
      <s:Code>
        <s:Value>s:Sender</s:Value>
        <s:Subcode>
          <s:Value>ter:InvalidArgVal</s:Value>
        </s:Subcode>
      </s:Code>
      <s:Reason>
        <s:Text xml:lang="en">Invalid ProfileToken</s:Text>
      </s:Reason>
    </s:Fault>
  </s:Body>
</s:Envelope>

public class OnvifDeviceService {

    public DeviceInfo getDeviceInformation(String ip, int port, String user, String pass)
            throws OnvifException {
        String url = String.format("http://%s:%d/onvif/device_service", ip, port);
        String body = "<tds:GetDeviceInformation xmlns:tds=\"http://www.onvif.org/ver10/device/wsdl\" />";

        Document doc = soapClient.sendSoapRequest(url, user, pass, body);

        return DeviceInfo.builder()
            .manufacturer(getText(doc, "Manufacturer"))
            .model(getText(doc, "Model"))
            .firmwareVersion(getText(doc, "FirmwareVersion"))
            .serialNumber(getText(doc, "SerialNumber"))
            .hardwareId(getText(doc, "HardwareId"))
            .build();
    }
}

<GetDeviceInformationResponse>
  <Manufacturer>Hikvision</Manufacturer>
  <Model>DS-2CD2142FWD-I</Model>
  <FirmwareVersion>V5.5.0</FirmwareVersion>
  <SerialNumber>DS-2CD2142FWD-I20180101AAWRB12345678</SerialNumber>
  <HardwareId>88</HardwareId>
</GetDeviceInformationResponse>

public Capabilities getCapabilities(String ip, int port, String user, String pass)
        throws OnvifException {
    String url = String.format("http://%s:%d/onvif/device_service", ip, port);
    String body =
        "<tds:GetCapabilities xmlns:tds=\"http://www.onvif.org/ver10/device/wsdl\">" +
        "<tds:Category>Media</tds:Category>" +
        "</tds:GetCapabilities>";

    Document doc = soapClient.sendSoapRequest(url, user, pass, body);

    String mediaXAddr = getText(doc, "Media", "XAddr");
    if (mediaXAddr == null || mediaXAddr.isEmpty()) {
        // 降级处理:使用 Device Service 地址
        mediaXAddr = url;
    }

    return Capabilities.builder()
        .mediaXAddr(mediaXAddr)
        .build();
}

public List<OnvifProfile> getProfiles(String mediaXAddr, String user, String pass)
        throws OnvifException {
    String body = "<trt:GetProfiles xmlns:trt=\"http://www.onvif.org/ver10/media/wsdl\" />";

    Document doc = soapClient.sendSoapRequest(mediaXAddr, user, pass, body);

    List<OnvifProfile> profiles = new ArrayList<>();
    NodeList nodes = doc.getElementsByTagNameNS("*", "Profiles");

    for (int i = 0; i < nodes.getLength(); i++) {
        Element elem = (Element) nodes.item(i);

        OnvifProfile profile = OnvifProfile.builder()
            .token(elem.getAttribute("token"))
            .name(getText(elem, "Name"))
            .videoSourceToken(getText(elem, "VideoSourceConfiguration", "SourceToken"))
            .videoEncodingToken(getText(elem, "VideoEncoderConfiguration", "token"))
            .encoding(getText(elem, "VideoEncoderConfiguration", "Encoding"))
            .width(getInt(elem, "VideoEncoderConfiguration", "Resolution", "Width"))
            .height(getInt(elem, "VideoEncoderConfiguration", "Resolution", "Height"))
            .build();

        profiles.add(profile);
    }

    return profiles;
}

   // 从 SourceToken 提取通道号
   // 例如: VideoSource_1 -> 1
   private int extractChannel(String sourceToken) {
       if (sourceToken == null) return 1;
       Matcher m = Pattern.compile("\\d+").matcher(sourceToken);
       return m.find() ? Integer.parseInt(m.group()) : 1;
   }

   private int detectSubtype(int width, int height, String name) {
       if (width >= 1280 || height >= 720) return 0; // 主码流
       if (name != null && name.toLowerCase().contains("sub")) return 1;
       return 1; // 默认子码流
   }

public String getStreamUri(String mediaXAddr, String user, String pass, String profileToken)
        throws OnvifException {
    String body =
        "<trt:GetStreamUri xmlns:trt=\"http://www.onvif.org/ver10/media/wsdl\" " +
        "xmlns:tt=\"http://www.onvif.org/ver10/schema\">" +
        "<trt:StreamSetup>" +
        "<tt:Stream>RTP-Unicast</tt:Stream>" +
        "<tt:Transport><tt:Protocol>RTSP</tt:Protocol></tt:Transport>" +
        "</trt:StreamSetup>" +
        "<trt:ProfileToken>" + profileToken + "</trt:ProfileToken>" +
        "</trt:GetStreamUri>";

    Document doc = soapClient.sendSoapRequest(mediaXAddr, user, pass, body);

    String uri = getText(doc, "Uri");

    // 注入凭据
    return injectCredentials(uri, user, pass);
}

private String injectCredentials(String rtspUrl, String user, String pass) {
    try {
        URI uri = new URI(rtspUrl);
        String userInfo = user + ":" + pass;
        return new URI(
            uri.getScheme(),
            userInfo,
            uri.getHost(),
            uri.getPort(),
            uri.getPath(),
            uri.getQuery(),
            uri.getFragment()
        ).toString();
    } catch (URISyntaxException e) {
        throw new IllegalArgumentException("Invalid RTSP URL: " + rtspUrl, e);
    }
}

rtsp://10.0.1.20:554/Streaming/Channels/101

rtsp://admin:password@10.0.1.20:554/Streaming/Channels/101

public void checkOnline(String ip, int port, String user, String pass) throws OnvifException {
    String url = String.format("http://%s:%d/onvif/device_service", ip, port);
    String body = "<tds:GetSystemDateAndTime xmlns:tds=\"http://www.onvif.org/ver10/device/wsdl\" />";

    // 超时设置为 3 秒
    Document doc = soapClient.sendSoapRequest(url, user, pass, body, 3000);

    // 能成功调用即表示在线,无需解析返回值
}

String mediaXAddr = capabilities.getMediaXAddr();
if (StringUtils.isBlank(mediaXAddr)) {
    // 降级使用 Device Service 地址
    mediaXAddr = String.format("http://%s:%d/onvif/device_service", ip, port);
    log.warn("Media XAddr empty, fallback to device service for camera {}", cameraId);
}

// 不依赖 token 格式,按索引或分辨率选择
OnvifProfile mainStream = profiles.stream()
    .filter(p -> p.getWidth() >= 1280)
    .findFirst()
    .orElse(profiles.get(0));

SOAP Fault: The security token could not be authenticated or authorized

@Scheduled(cron = "0 */30 * * * ?") // 每 30 分钟执行
public void syncServerTime() {
    try {
        ProcessBuilder pb = new ProcessBuilder("ntpdate", "ntp.aliyun.com");
        Process process = pb.start();
        process.waitFor(10, TimeUnit.SECONDS);
    } catch (Exception e) {
        log.error("NTP sync failed", e);
    }
}

@Configuration
public class OnvifHttpConfig {

    @Bean
    public CloseableHttpClient httpClient() {
        PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
        cm.setMaxTotal(200);
        cm.setDefaultMaxPerRoute(50);

        return HttpClients.custom()
            .setConnectionManager(cm)
            .setDefaultRequestConfig(
                RequestConfig.custom()
                    .setConnectTimeout(3000)
                    .setSocketTimeout(5000)
                    .build()
            )
            .build();
    }
}

@Cacheable(value = "device-info", key = "#cameraId", unless = "#result == null")
public DeviceInfo getDeviceInfo(Long cameraId) {
    CameraDevice device = cameraRepository.findById(cameraId)
        .orElseThrow(() -> new NotFoundException("Camera not found"));

    return onvifClient.getDeviceInformation(
        device.getIp(),
        device.getPort(),
        device.getUsername(),
        device.getPassword()
    );
}

private final Semaphore onvifSemaphore = new Semaphore(50);

public <T> T callOnvif(Supplier<T> supplier) throws Exception {
    onvifSemaphore.acquire();
    try {
        return supplier.get();
    } finally {
        onvifSemaphore.release();
    }
}

paths:
  cam_*:
    source: rtsp://admin:pass@10.0.1.20:554/Streaming/Channels/101
    sourceOnDemand: yes
    sourceOnDemandStartTimeout: 10s
    sourceOnDemandCloseAfter: 10s

paths:
  cam_h265_*:
    source: publisher
    runOnDemand: ffmpeg -i $SOURCE_URL -c:v libx264 -f rtsp rtsp://127.0.0.1:$RTSP_PORT/$MTX_PATH
    runOnDemandRestart: yes

{
  "name": "cam_10_0_1_20_ch1_main",
  "source": "rtsp://admin:pass@10.0.1.20:554/Streaming/Channels/101",
  "sourceProtocol": "tcp",
  "sourceOnDemand": true,
  "sourceOnDemandStartTimeout": "10s",
  "sourceOnDemandCloseAfter": "10s",

  "record": false,
  "recordPath": "",
  "recordFormat": "fmp4",
  "recordSegmentDuration": "10m",
  "recordDeleteAfter": "7d"
}

cam_{ip}_{channel}_{subtype}

   paths:
     cam_*_main:
       # 所有主码流共享配置
     cam_*_sub:
       # 所有子码流共享配置

@Service
@Slf4j
public class MediaPathService {

    @Value("${media.mtx.apiBaseUrl}")
    private String apiBaseUrl;

    private final RestTemplate restTemplate;

    /**
     * 注册直连路径
     */
    public void registerDirectPath(StreamPath path) {
        Map<String, Object> config = new HashMap<>();
        config.put("name", path.getPathName());
        config.put("source", path.getSourceUrl());
        config.put("sourceProtocol", "tcp");
        config.put("sourceOnDemand", true);
        config.put("sourceOnDemandStartTimeout", "10s");
        config.put("sourceOnDemandCloseAfter", "10s");

        addPath(path.getPathName(), config);
    }

    /**
     * 注册转码路径
     */
    public void registerTranscodePath(StreamPath path) {
        String ffmpegCmd = buildFfmpegCommand(path.getSourceUrl());

        Map<String, Object> config = new HashMap<>();
        config.put("name", path.getPathName());
        config.put("source", "publisher");
        config.put("runOnDemand", ffmpegCmd);
        config.put("runOnDemandRestart", true);
        config.put("runOnDemandStartTimeout", "10s");
        config.put("runOnDemandCloseAfter", "10s");

        addPath(path.getPathName(), config);
    }

    /**
     * 删除并重建路径 (确保配置完全生效)
     */
    public void updatePath(StreamPath path) {
        deletePath(path.getPathName());

        if (path.getNeedTranscode() == 1) {
            registerTranscodePath(path);
        } else {
            registerDirectPath(path);
        }
    }

    private void addPath(String pathName, Map<String, Object> config) {
        String url = apiBaseUrl + "/v3/config/paths/add/" + pathName;

        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);

        HttpEntity<Map<String, Object>> request = new HttpEntity<>(config, headers);

        try {
            ResponseEntity<String> response = restTemplate.postForEntity(url, request, String.class);

            if (response.getStatusCode().is2xxSuccessful()) {
                log.info("Path registered: {}", pathName);
            } else {
                throw new MediaGatewayException("Failed to register path: " + response.getBody());
            }
        } catch (Exception e) {
            log.error("MediaMTX API error: {}", e.getMessage());
            throw new MediaGatewayException("Path registration failed", e);
        }
    }

    private void deletePath(String pathName) {
        String url = apiBaseUrl + "/v3/config/paths/delete/" + pathName;

        try {
            restTemplate.delete(url);
            log.info("Path deleted: {}", pathName);
        } catch (HttpClientErrorException.NotFound e) {
            // 路径不存在,忽略错误
        } catch (Exception e) {
            log.error("Failed to delete path {}: {}", pathName, e.getMessage());
        }
    }

    private String buildFfmpegCommand(String sourceUrl) {
        return String.format(
            "ffmpeg -hide_banner -loglevel warning " +
            "-rtsp_transport tcp " +
            "-i \"%s\" " +
            "-an " +
            "-c:v libx264 -preset veryfast -crf 23 " +
            "-tune zerolatency -pix_fmt yuv420p " +
            "-g 50 -keyint_min 50 -sc_threshold 0 " +
            "-x264-params repeat-headers=1 " +
            "-f rtsp -rtsp_transport tcp " +
            "\"rtsp://127.0.0.1:$RTSP_PORT/$MTX_PATH\"",
            sourceUrl
        );
    }
}

rtsp://{MediaMTX_IP}:{RTSP_Port}/{path_name}

rtsp://10.0.10.1:8554/cam_10_0_1_20_ch1_main

http://{MediaMTX_IP}:{HLS_Port}/{path_name}/index.m3u8

http://10.0.10.1:8888/cam_10_0_1_20_ch1_main/index.m3u8

http://{MediaMTX_IP}:{WebRTC_Port}/{path_name}

http://10.0.10.1:8889/cam_10_0_1_20_ch1_main

@Service
@Slf4j
public class CodecProbeService {

    @Value("${codec.probe.ffprobe-bin:ffprobe}")
    private String ffprobeBin;

    @Value("${codec.probe.timeout-ms:3000}")
    private int timeoutMs;

    private final Semaphore probeSemaphore = new Semaphore(8);

    public CodecInfo probe(String rtspUrl) {
        try {
            probeSemaphore.acquire();
            return doProbe(rtspUrl);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return CodecInfo.unknown();
        } finally {
            probeSemaphore.release();
        }
    }

    private CodecInfo doProbe(String rtspUrl) {
        List<String> command = Arrays.asList(
            ffprobeBin,
            "-v", "error",
            "-rtsp_transport", "tcp",
            "-analyzeduration", "1000000",
            "-probesize", "32768",
            "-select_streams", "v:0",
            "-show_entries", "stream=codec_name,width,height,avg_frame_rate",
            "-of", "json",
            rtspUrl
        );

        ProcessBuilder pb = new ProcessBuilder(command);
        pb.redirectErrorStream(true);

        try {
            Process process = pb.start();
            boolean finished = process.waitFor(timeoutMs, TimeUnit.MILLISECONDS);

            if (!finished) {
                process.destroyForcibly();
                log.warn("ffprobe timeout for {}", maskUrl(rtspUrl));
                return CodecInfo.unknown();
            }

            if (process.exitValue() != 0) {
                log.warn("ffprobe failed for {}", maskUrl(rtspUrl));
                return CodecInfo.unknown();
            }

            String output = IOUtils.toString(process.getInputStream(), StandardCharsets.UTF_8);
            return parseProbeOutput(output);

        } catch (Exception e) {
            log.error("ffprobe error for {}: {}", maskUrl(rtspUrl), e.getMessage());
            return CodecInfo.unknown();
        }
    }

    private CodecInfo parseProbeOutput(String json) {
        try {
            JSONObject obj = JSON.parseObject(json);
            JSONArray streams = obj.getJSONArray("streams");

            if (streams == null || streams.isEmpty()) {
                return CodecInfo.unknown();
            }

            JSONObject stream = streams.getJSONObject(0);

            String codecName = stream.getString("codec_name");
            int width = stream.getIntValue("width");
            int height = stream.getIntValue("height");
            String frameRate = stream.getString("avg_frame_rate");

            return CodecInfo.builder()
                .codec(normalizeCodec(codecName))
                .width(width)
                .height(height)
                .frameRate(parseFrameRate(frameRate))
                .build();

        } catch (Exception e) {
            log.error("Failed to parse ffprobe output", e);
            return CodecInfo.unknown();
        }
    }

    private String normalizeCodec(String codecName) {
        if (codecName == null) return "UNKNOWN";

        String lower = codecName.toLowerCase();
        if (lower.contains("h264") || lower.equals("avc")) return "H264";
        if (lower.contains("h265") || lower.equals("hevc")) return "H265";
        if (lower.contains("mjpeg")) return "MJPEG";

        return "UNKNOWN";
    }

    private double parseFrameRate(String frameRate) {
        if (frameRate == null || frameRate.isEmpty()) return 0.0;

        try {
            if (frameRate.contains("/")) {
                String[] parts = frameRate.split("/");
                double num = Double.parseDouble(parts[0]);
                double den = Double.parseDouble(parts[1]);
                return den == 0 ? 0 : num / den;
            }
            return Double.parseDouble(frameRate);
        } catch (Exception e) {
            return 0.0;
        }
    }

    private String maskUrl(String url) {
        return url.replaceAll("://[^@]+@", "://***:***@");
    }
}

@Service
public class CodecDecisionService {

    @Value("${codec.transcode.enabled:true}")
    private boolean transcodeEnabled;

    @Value("${codec.transcode.assume-h265-when-unknown:true}")
    private boolean assumeH265WhenUnknown;

    public boolean needTranscode(String codec) {
        if (!transcodeEnabled) {
            return false;
        }

        if (codec == null || "UNKNOWN".equals(codec)) {
            return assumeH265WhenUnknown;
        }

        return "H265".equals(codec) || "HEVC".equals(codec) || "MJPEG".equals(codec);
    }

    public TranscodeStrategy selectStrategy(CodecInfo info) {
        if (!needTranscode(info.getCodec())) {
            return TranscodeStrategy.DIRECT;
        }

        // 根据分辨率选择转码参数
        if (info.getWidth() >= 1920 || info.getHeight() >= 1080) {
            return TranscodeStrategy.HIGH_QUALITY;
        } else if (info.getWidth() >= 1280 || info.getHeight() >= 720) {
            return TranscodeStrategy.MEDIUM_QUALITY;
        } else {
            return TranscodeStrategy.LOW_QUALITY;
        }
    }
}

public enum TranscodeStrategy {
    DIRECT(null, null, null),
    HIGH_QUALITY("veryfast", "23", "50"),
    MEDIUM_QUALITY("faster", "25", "60"),
    LOW_QUALITY("fast", "28", "90");

    private final String preset;
    private final String crf;
    private final String gop;

    // constructor and getters
}

public class FfmpegCommandBuilder {

    public String buildTranscodeCommand(String sourceUrl, TranscodeStrategy strategy) {
        StringBuilder cmd = new StringBuilder();

        cmd.append("ffmpeg -hide_banner -loglevel warning ");
        cmd.append("-rtsp_transport tcp ");
        cmd.append("-stimeout 5000000 ");
        cmd.append("-probesize 5000000 ");
        cmd.append("-analyzeduration 5000000 ");
        cmd.append("-i \"").append(sourceUrl).append("\" ");

        // 禁用音频
        cmd.append("-an ");

        // 视频编码参数
        cmd.append("-c:v libx264 ");
        cmd.append("-preset ").append(strategy.getPreset()).append(" ");
        cmd.append("-crf ").append(strategy.getCrf()).append(" ");
        cmd.append("-tune zerolatency ");
        cmd.append("-pix_fmt yuv420p ");
        cmd.append("-g ").append(strategy.getGop()).append(" ");
        cmd.append("-keyint_min ").append(strategy.getGop()).append(" ");
        cmd.append("-sc_threshold 0 ");
        cmd.append("-x264-params repeat-headers=1 ");

        // 输出格式
        cmd.append("-f rtsp -rtsp_transport tcp ");
        cmd.append("\"rtsp://127.0.0.1:$RTSP_PORT/$MTX_PATH\"");

        return cmd.toString();
    }
}

public String buildNvencCommand(String sourceUrl) {
    StringBuilder cmd = new StringBuilder();

    cmd.append("ffmpeg -hide_banner -loglevel warning ");
    cmd.append("-hwaccel cuda -hwaccel_output_format cuda ");
    cmd.append("-rtsp_transport tcp ");
    cmd.append("-i \"").append(sourceUrl).append("\" ");
    cmd.append("-an ");
    cmd.append("-c:v h264_nvenc ");
    cmd.append("-preset p4 ");
    cmd.append("-b:v 3000k ");
    cmd.append("-g 50 ");
    cmd.append("-f rtsp -rtsp_transport tcp ");
    cmd.append("\"rtsp://127.0.0.1:$RTSP_PORT/$MTX_PATH\"");

    return cmd.toString();
}

public boolean isNvencAvailable() {
    try {
        ProcessBuilder pb = new ProcessBuilder("ffmpeg", "-encoders");
        Process process = pb.start();

        String output = IOUtils.toString(process.getInputStream(), StandardCharsets.UTF_8);
        return output.contains("h264_nvenc");

    } catch (Exception e) {
        return false;
    }
}

[前端] → [接口层] → [业务层] → [ONVIF层] → [设备]
   │         │          │           │
   │         │          │           └─→ GetDeviceInformation
   │         │          │           └─→ GetCapabilities
   │         │          │           └─→ GetProfiles
   │         │          │           └─→ GetStreamUri (per profile)
   │         │          │
   │         │          └─→ [数据层] 保存设备主档
   │         │          └─→ [异步任务] 流同步
   │         │                      │
   │         │                      └─→ FFprobe 探测编码
   │         │                      └─→ 保存流路径
   │         │                      └─→ MediaMTX 注册路径
   │         │
   │         └─→ 返回接入结果

@Data
public class CameraAddRequest {
    @NotBlank(message = "IP不能为空")
    private String ip;

    @Min(value = 1, message = "端口范围 1-65535")
    @Max(value = 65535, message = "端口范围 1-65535")
    private Integer port = 80;

    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;

    private String cameraName;
    private Long groupId;

    /**
     * 0: 标准 ONVIF 流程
     * 1: 厂商兜底模式 (跳过 ONVIF,使用固定规则)
     */
    private Integer skipOnvif = 0;

    /**
     * 厂商类型 (skipOnvif=1 时有效)
     * 支持: HIKVISION, DAHUA, UNIVIEW
     */
    private String vendorType;
}