{"id":30827738,"url":"https://github.com/lunasaw/gb28181-proxy","last_synced_at":"2025-09-06T13:36:38.381Z","repository":{"id":200073940,"uuid":"703394622","full_name":"lunasaw/gb28181-proxy","owner":"lunasaw","description":"gb28181-proxy 基于sip实现GB28181的通信框架，区分client和server。以便于快速构建发起SIP请求和处理响应。支持NAT穿透，支持海康、大华、宇视等品牌的IPC、NVR、DVR接入及联平台。项目不仅限于gb28181协议。也可以利用封装的SIP方法处理其他协议。","archived":false,"fork":false,"pushed_at":"2025-08-14T12:19:01.000Z","size":21925,"stargazers_count":119,"open_issues_count":10,"forks_count":30,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-08-14T12:28:15.735Z","etag":null,"topics":["28181","client","gb28181","ipc","onvif","sdp","server","sip"],"latest_commit_sha":null,"homepage":"https://lunasaw.github.io/gb28181-proxy/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lunasaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-11T06:56:28.000Z","updated_at":"2025-08-14T12:19:06.000Z","dependencies_parsed_at":"2024-01-08T15:14:57.678Z","dependency_job_id":"0d13499b-08d1-4d81-8630-e2b9082a541a","html_url":"https://github.com/lunasaw/gb28181-proxy","commit_stats":null,"previous_names":["lunasaw/gb28181-proxy"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lunasaw/gb28181-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunasaw%2Fgb28181-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunasaw%2Fgb28181-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunasaw%2Fgb28181-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunasaw%2Fgb28181-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lunasaw","download_url":"https://codeload.github.com/lunasaw/gb28181-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lunasaw%2Fgb28181-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273912842,"owners_count":25189970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["28181","client","gb28181","ipc","onvif","sdp","server","sip"],"created_at":"2025-09-06T13:36:31.759Z","updated_at":"2025-09-06T13:36:38.361Z","avatar_url":"https://github.com/lunasaw.png","language":"Java","funding_links":[],"categories":["网络编程"],"sub_categories":["Spring Cloud框架"],"readme":"# SIP Proxy\n\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.lunasaw/sip-proxy)](https://mvnrepository.com/artifact/io.github.lunasaw/sip-common)\n[![GitHub license](https://img.shields.io/badge/MIT_License-blue.svg)](https://raw.githubusercontent.com/lunasaw/gb28181-proxy/master/LICENSE)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.3.1-brightgreen.svg)](https://spring.io/projects/spring-boot)\n[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)\n\n[项目文档](https://lunasaw.github.io/gb28181-proxy/) | [在线演示](http://www.isluna.ml) | [问题反馈](https://github.com/lunasaw/gb28181-proxy/issues)\n\n## 📖 项目介绍\n\n基于Java 17 + Spring Boot 3.3.1 +\nSIP协议栈实现的GB28181通信框架，采用多模块架构设计，提供完整的SIP协议通信能力。项目支持客户端和服务端双向通信，专为构建视频监控、安防系统等GB28181协议应用而设计。\n\n### 🎯 设计目标\n\n- **高性能**：异步消息处理、连接池管理、缓存优化\n- **易扩展**：模块化架构、插件化设计、统一接口\n- **标准化**：严格遵循GB28181-2016协议规范\n- **生产级**：完整的监控、日志、异常处理机制\n\n## 🏗️ 项目架构\n\n### 模块架构图\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      SIP Proxy 项目架构                      │\n├─────────────────────┬───────────────────────────────────────┤\n│   gb28181-test      │            测试和示例模块              │\n│   ├─ 集成测试       │            性能测试                   │\n│   └─ 示例代码       │            配置示例                   │\n├─────────────────────┼───────────────────────────────────────┤\n│  gb28181-client     │         gb28181-server              │\n│  ├─ 设备注册        │         ├─ 设备管理                  │\n│  ├─ 心跳检测        │         ├─ 设备控制                  │\n│  ├─ 告警上报        │         ├─ 云台控制                  │\n│  ├─ 实时点播响应    │         ├─ 实时点播                  │\n│  └─ 回放控制响应    │         └─ 视频回放                  │\n├─────────────────────┼───────────────────────────────────────┤\n│           gb28181-common (GB28181协议模型)                 │\n│           ├─ 设备模型    ├─ 控制命令    ├─ 告警模型         │\n│           └─ 查询模型    └─ 响应模型    └─ 通知模型         │\n├─────────────────────────────────────────────────────────────┤\n│                    sip-common (SIP基础包)                  │\n│    ├─ SIP协议栈封装        ├─ 异步消息处理                 │\n│    ├─ 连接池管理           ├─ 缓存服务                     │\n│    ├─ 配置管理             ├─ 性能监控                     │\n│    └─ 设备管理             └─ 事件总线                     │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 技术栈\n\n| 技术          | 版本         | 说明     |\n|-------------|------------|--------|\n| Java        | 17         | 编程语言   |\n| Spring Boot | 3.3.1      | 应用框架   |\n| JAIN-SIP    | 1.3.0-91   | SIP协议栈 |\n| Caffeine    | 3.1.8      | 高性能缓存  |\n| Micrometer  | 1.12.0     | 性能监控   |\n| Guava       | 32.1.3-jre | 工具库    |\n| Dom4j       | 2.1.4      | XML处理  |\n| Maven       | 3.8+       | 构建工具   |\n\n## ✨ 功能特性\n\n### 🔧 SIP通用能力\n\n- [x] **SIP协议栈封装**：基于JAIN-SIP的高性能封装\n- [x] **异步消息处理**：高并发异步处理机制\n- [x] **连接池管理**：SIP连接池管理和监控\n- [x] **缓存服务**：基于Caffeine的多级缓存\n- [x] **配置管理**：外部化配置和动态配置\n- [x] **性能监控**：基于Micrometer的指标收集\n- [x] **Spring Boot Starter**：开箱即用的自动配置\n\n### 📱 GB28181客户端\n\n- [x] **设备注册**：完整的设备注册认证流程\n- [x] **心跳检测**：设备保活和状态监控\n- [x] **告警上报**：设备告警信息推送\n- [x] **事件推送**：设备状态变更通知\n- [x] **实时点播响应**：实时视频流媒体响应\n- [x] **回放控制响应**：历史视频回放控制\n- [x] **设备控制响应**：云台控制、录像控制等\n- [x] **设备信息查询响应**：设备状态、目录信息查询\n- [x] **语音广播处理**：语音广播消息处理\n\n### 🖥️ GB28181服务端\n\n- [x] **设备管理**：设备注册、认证、会话管理\n- [x] **设备控制**：云台控制、录像控制、复位等\n- [x] **实时点播**：实时视频流请求和控制\n- [x] **视频回放**：历史视频回放和控制\n- [x] **告警处理**：告警接收、处理、转发\n- [x] **设备查询**：设备信息、状态、目录查询\n- [x] **订阅管理**：设备状态、告警、目录订阅\n- [x] **级联支持**：上下级平台级联通信\n\n### 🧪 测试和示例\n\n- [x] **集成测试**：完整的客户端服务端测试\n- [x] **性能测试**：压力测试和性能基准\n- [x] **示例代码**：详细的使用示例和配置\n- [x] **测试工具**：SIP消息构建和验证工具\n\n## 🚀 快速开始\n\n### 环境要求\n\n- Java 17+\n- Maven 3.8+\n- Spring Boot 3.3.1+\n\n### 安装依赖\n\n#### 全量包引入\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.lunasaw\u003c/groupId\u003e\n    \u003cartifactId\u003egb28181-proxy\u003c/artifactId\u003e\n    \u003cversion\u003e${last.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### 按需引入\n\n```xml\n\u003c!-- SIP基础包 --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.lunasaw\u003c/groupId\u003e\n    \u003cartifactId\u003esip-common\u003c/artifactId\u003e\n    \u003cversion\u003e${last.version}\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- GB28181协议模型 --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.lunasaw\u003c/groupId\u003e\n    \u003cartifactId\u003egb28181-common\u003c/artifactId\u003e\n    \u003cversion\u003e${last.version}\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- GB28181客户端 --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.lunasaw\u003c/groupId\u003e\n    \u003cartifactId\u003egb28181-client\u003c/artifactId\u003e\n    \u003cversion\u003e${last.version}\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- GB28181服务端 --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.lunasaw\u003c/groupId\u003e\n    \u003cartifactId\u003egb28181-server\u003c/artifactId\u003e\n    \u003cversion\u003e${last.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 基础配置\n\n创建 `application.yml` 配置文件：\n\n```yaml\n# SIP基础配置\nsip:\n  # 本地配置\n  local:\n    ip: 127.0.0.1\n    port: 5060\n    transport: UDP\n    charset: UTF-8\n\n  # 性能配置\n  performance:\n    enable-async: true\n    thread-pool-size: 200\n    cache-enable: true\n    cache-size: 10000\n\n  # 监控配置\n  monitor:\n    enable: true\n    metrics-enable: true\n\n# GB28181协议配置\ngb28181:\n  # 设备配置\n  device:\n    domain: 4405010000\n    device-id: 44050100001327000001\n    device-name: \"测试设备\"\n    manufacturer: \"测试厂商\"\n    model: \"测试型号\"\n    firmware: \"V1.0.0\"\n\n  # 认证配置\n  auth:\n    enable: true\n    realm: \"4405010000\"\n    username: \"admin\"\n    password: \"12345678\"\n\n  # 超时配置\n  timeout:\n    register: 60\n    heartbeat: 30\n    invite: 30\n```\n\n### 快速示例\n\n#### 启动GB28181服务端\n\n```java\n@SpringBootApplication\n@EnableSipProxy\npublic class Gb28181ServerApplication {\n\n    public static void main(String[] args) {\n        SpringApplication.run(Gb28181ServerApplication.class, args);\n    }\n\n    @Autowired\n    private ServerSendCmd serverSendCmd;\n\n    @PostConstruct\n    public void init() {\n        // 服务端启动后自动监听设备注册\n        log.info(\"GB28181服务端启动成功\");\n    }\n}\n```\n\n#### 启动GB28181客户端\n\n```java\n@SpringBootApplication\n@EnableSipProxy\npublic class Gb28181ClientApplication {\n\n    public static void main(String[] args) {\n        SpringApplication.run(Gb28181ClientApplication.class, args);\n    }\n\n    @Autowired\n    private ClientSendCmd clientSendCmd;\n\n    @PostConstruct\n    public void registerDevice() {\n        // 客户端启动后自动注册设备\n        clientSendCmd.register();\n        log.info(\"设备注册请求已发送\");\n    }\n}\n```\n\n## 📚 模块说明\n\n### sip-common（SIP基础包）\n\nSIP协议的基础封装和通用功能模块，提供SIP通信的核心能力。\n\n**核心组件：**\n\n- `SipLayer`：SIP协议层封装\n- `AsyncSipMessageProcessor`：异步消息处理器\n- `CacheService`：缓存服务\n- `SipConnectionPool`：连接池管理\n- `SipSender`：SIP消息发送器\n- `SipConfigurationManager`：配置管理器\n\n**主要功能：**\n\n- SIP协议栈封装和配置管理\n- 异步消息处理和线程池管理\n- 高性能缓存系统\n- 连接池管理和监控\n- 性能指标收集\n\n### gb28181-common（GB28181协议模型）\n\nGB28181协议的数据模型和实体定义模块。\n\n**主要包含：**\n\n- 设备控制命令：云台控制、录像控制等\n- 设备信息模型：设备目录、状态信息等\n- 告警模型：设备告警、告警通知等\n- 查询模型：各种查询和响应类\n\n### gb28181-client（GB28181客户端）\n\nGB28181协议的客户端实现，模拟设备端行为。\n\n**核心服务：**\n\n- `ClientSendCmd`：主动服务接口，提供各种SIP命令发送\n- 被动消息处理器：各种RequestProcessor和ResponseProcessor\n- 设备配置和用户管理\n\n**使用场景：**\n\n- 模拟GB28181设备进行测试\n- 构建设备端应用\n- 协议兼容性验证\n\n### gb28181-server（GB28181服务端）\n\nGB28181协议的服务端实现，提供平台级服务。\n\n**核心服务：**\n\n- `ServerSendCmd`：主动服务接口，提供各种SIP命令发送\n- 被动消息处理器：各种RequestProcessor和ResponseProcessor\n- 设备会话管理\n\n**使用场景：**\n\n- 构建GB28181平台服务\n- 设备管理和控制\n- 视频监控系统集成\n\n### gb28181-test（测试和示例）\n\n集成测试和示例代码模块。\n\n**主要内容：**\n\n- 客户端和服务端集成测试\n- 协议功能验证\n- 性能测试和压力测试\n- 示例代码和配置\n\n## ⚙️ 配置指南\n\n### 基础配置\n\n#### SIP协议配置\n\n```yaml\nsip:\n  local:\n    ip: 127.0.0.1              # 本地IP地址\n    port: 5060                 # 本地端口\n    transport: UDP             # 传输协议 UDP/TCP\n    charset: UTF-8             # 字符编码\n\n  performance:\n    enable-async: true         # 启用异步处理\n    thread-pool-size: 200      # 线程池大小\n    cache-enable: true         # 启用缓存\n    cache-size: 10000          # 缓存大小\n\n  monitor:\n    enable: true               # 启用监控\n    metrics-enable: true       # 启用指标收集\n```\n\n#### GB28181协议配置\n\n```yaml\ngb28181:\n  device:\n    domain: 4405010000                    # SIP域\n    device-id: 44050100001327000001       # 设备ID\n    device-name: \"测试设备\"                # 设备名称\n    manufacturer: \"测试厂商\"               # 厂商\n    model: \"测试型号\"                     # 型号\n    firmware: \"V1.0.0\"                   # 固件版本\n\n  auth:\n    enable: true                         # 启用认证\n    realm: \"4405010000\"                  # 认证域\n    username: \"admin\"                    # 用户名\n    password: \"12345678\"                 # 密码\n\n  timeout:\n    register: 60                         # 注册超时(秒)\n    heartbeat: 30                        # 心跳超时(秒)\n    invite: 30                           # 邀请超时(秒)\n```\n\n### 高级配置\n\n#### 性能优化配置\n\n```yaml\nsip:\n  performance:\n    # 异步处理配置\n    async:\n      core-pool-size: 50               # 核心线程数\n      max-pool-size: 200               # 最大线程数\n      queue-capacity: 1000             # 队列容量\n      keep-alive: 60                   # 线程保活时间\n\n    # 缓存配置\n    cache:\n      initial-capacity: 100            # 初始容量\n      maximum-size: 10000              # 最大容量\n      expire-after-write: 3600         # 写入后过期时间(秒)\n      expire-after-access: 1800        # 访问后过期时间(秒)\n\n    # 连接池配置\n    pool:\n      max-connections: 100             # 最大连接数\n      min-connections: 10              # 最小连接数\n      connection-timeout: 30           # 连接超时(秒)\n      idle-timeout: 300                # 空闲超时(秒)\n```\n\n#### 监控配置\n\n```yaml\nsip:\n  monitor:\n    metrics:\n      enable: true                     # 启用指标收集\n      step: 60                         # 收集间隔(秒)\n\n    logging:\n      level: INFO                      # 日志级别\n      pattern: \"[%d{HH:mm:ss}] [%thread] %-5level %logger{36} - %msg%n\"\n\n    health:\n      enable: true                     # 启用健康检查\n      interval: 30                     # 检查间隔(秒)\n```\n\n## 💻 使用示例\n\n### 设备注册示例\n\n```java\n@Component\npublic class DeviceRegistrationExample {\n\n    @Autowired\n    private ClientSendCmd clientSendCmd;\n\n    /**\n     * 设备注册\n     */\n    public void registerDevice() {\n        try {\n            // 发送注册请求\n            ResultDTO result = clientSendCmd.register();\n\n            if (result.isSuccess()) {\n                log.info(\"设备注册成功\");\n            } else {\n                log.error(\"设备注册失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"设备注册异常\", e);\n        }\n    }\n\n    /**\n     * 设备心跳\n     */\n    @Scheduled(fixedDelay = 30000)\n    public void sendHeartbeat() {\n        try {\n            clientSendCmd.keepalive();\n            log.debug(\"发送心跳成功\");\n        } catch (Exception e) {\n            log.error(\"发送心跳失败\", e);\n        }\n    }\n}\n```\n\n### 设备控制示例\n\n```java\n@Component\npublic class DeviceControlExample {\n\n    @Autowired\n    private ServerSendCmd serverSendCmd;\n\n    /**\n     * 云台控制\n     */\n    public void ptzControl(String deviceId, int command) {\n        try {\n            DeviceControlPtz ptzCmd = new DeviceControlPtz();\n            ptzCmd.setDeviceId(deviceId);\n            ptzCmd.setPtzCmd(command);\n\n            ResultDTO result = serverSendCmd.deviceControl(ptzCmd);\n\n            if (result.isSuccess()) {\n                log.info(\"云台控制成功\");\n            } else {\n                log.error(\"云台控制失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"云台控制异常\", e);\n        }\n    }\n\n    /**\n     * 设备查询\n     */\n    public void queryDevice(String deviceId) {\n        try {\n            DeviceInfoQuery query = new DeviceInfoQuery();\n            query.setDeviceId(deviceId);\n\n            ResultDTO result = serverSendCmd.deviceInfoQuery(query);\n\n            if (result.isSuccess()) {\n                log.info(\"设备查询成功\");\n            } else {\n                log.error(\"设备查询失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"设备查询异常\", e);\n        }\n    }\n}\n```\n\n### 实时点播示例\n\n```java\n@Component\npublic class VideoPlayExample {\n\n    @Autowired\n    private ServerSendCmd serverSendCmd;\n\n    /**\n     * 实时点播\n     */\n    public void invitePlay(String deviceId, String channelId) {\n        try {\n            InviteRequest inviteRequest = new InviteRequest();\n            inviteRequest.setDeviceId(deviceId);\n            inviteRequest.setChannelId(channelId);\n            inviteRequest.setMediaServerId(\"zlm001\");\n\n            ResultDTO\u003cInviteEntity\u003e result = serverSendCmd.invitePlay(inviteRequest);\n\n            if (result.isSuccess()) {\n                InviteEntity invite = result.getData();\n                log.info(\"点播成功, 流地址: {}\", invite.getStreamUrl());\n            } else {\n                log.error(\"点播失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"点播异常\", e);\n        }\n    }\n\n    /**\n     * 停止点播\n     */\n    public void stopPlay(String deviceId, String channelId) {\n        try {\n            ResultDTO result = serverSendCmd.byePlay(deviceId, channelId);\n\n            if (result.isSuccess()) {\n                log.info(\"停止点播成功\");\n            } else {\n                log.error(\"停止点播失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"停止点播异常\", e);\n        }\n    }\n}\n```\n\n### 告警处理示例\n\n```java\n@Component\npublic class AlarmHandlingExample {\n\n    @Autowired\n    private ClientSendCmd clientSendCmd;\n\n    /**\n     * 发送告警\n     */\n    public void sendAlarm(String deviceId, String alarmType) {\n        try {\n            DeviceAlarm alarm = new DeviceAlarm();\n            alarm.setDeviceId(deviceId);\n            alarm.setAlarmType(alarmType);\n            alarm.setAlarmTime(System.currentTimeMillis());\n            alarm.setAlarmDescription(\"设备告警\");\n\n            ResultDTO result = clientSendCmd.alarm(alarm);\n\n            if (result.isSuccess()) {\n                log.info(\"告警发送成功\");\n            } else {\n                log.error(\"告警发送失败: {}\", result.getMsg());\n            }\n        } catch (Exception e) {\n            log.error(\"告警发送异常\", e);\n        }\n    }\n}\n```\n\n## 🔧 开发指南\n\n### 代码规范\n\n#### Java代码规范\n\n1. **命名约定**\n    - 类名使用 PascalCase\n    - 方法名和变量名使用 camelCase\n    - 常量使用 UPPER_SNAKE_CASE\n    - 包名使用小写，以 `io.github.lunasaw` 为根包\n\n2. **Lombok使用**\n    - 统一使用 `@Slf4j` 处理日志\n    - 统一使用 `@Getter` 和 `@Setter` 处理访问器\n    - 统一使用 `@AllArgsConstructor` 和 `@NoArgsConstructor` 处理构造方法\n    - 统一使用 `@ToString` 处理字符串转换\n\n3. **依赖注入**\n    - 强制使用 `jakarta` 包而不是 `javax` 包\n    - 使用 `@Autowired` 进行依赖注入\n    - 使用 `@Component`、`@Service`、`@Repository` 等注解\n\n4. **异常处理**\n    - 使用 `ServiceException` 进行业务异常处理\n    - 使用 `GlobalExceptionHandler` 进行全局异常处理\n    - 自定义异常枚举 `ServiceExceptionEnum`\n\n#### 时间处理规范\n\n1. **DO/DTO层**：统一使用 `LocalDateTime` 类型\n2. **VO层**：统一返回unix时间戳（毫秒级）\n3. **转换方法**：提供 `fieldNameToEpochMilli()` 方法\n\n#### JSON序列化规范\n\n- 项目内统一使用 `fastjson2` 进行JSON序列化\n- 禁止使用 `Jackson`、`Gson` 等其他JSON库\n\n#### 外部接口规范\n\n- 所有外部接口调用必须通过 `Wrapper` 类封装\n- 统一返回 `ResultDTO` 格式\n- 包含完整的异常处理和日志记录\n\n### 扩展开发\n\n#### 自定义消息处理器\n\n```java\n@Component\npublic class CustomMessageProcessor extends AbstractSipRequestProcessor {\n\n    @Override\n    public String getMethod() {\n        return Request.MESSAGE;\n    }\n\n    @Override\n    protected void processInternal(RequestEvent requestEvent) {\n        // 自定义消息处理逻辑\n        SIPRequest request = (SIPRequest) requestEvent.getRequest();\n\n        // 解析消息体\n        String body = new String(request.getRawContent());\n\n        // 业务处理\n        handleCustomMessage(body);\n\n        // 发送响应\n        sendResponse(requestEvent, Response.OK);\n    }\n\n    private void handleCustomMessage(String body) {\n        // 实现自定义业务逻辑\n        log.info(\"处理自定义消息: {}\", body);\n    }\n}\n```\n\n#### 自定义设备提供器\n\n```java\n@Component\npublic class CustomDeviceSupplier implements DeviceSupplier {\n\n    @Override\n    public Device queryDevice(String deviceId) {\n        // 从数据库或外部接口查询设备信息\n        return deviceRepository.findByDeviceId(deviceId);\n    }\n\n    @Override\n    public List\u003cDevice\u003e queryDeviceList(String parentId) {\n        // 查询设备列表\n        return deviceRepository.findByParentId(parentId);\n    }\n\n    @Override\n    public void updateDevice(Device device) {\n        // 更新设备信息\n        deviceRepository.save(device);\n    }\n}\n```\n\n#### 自定义缓存策略\n\n```java\n@Configuration\npublic class CustomCacheConfig {\n\n    @Bean\n    public CacheManager customCacheManager() {\n        CaffeineCacheManager cacheManager = new CaffeineCacheManager();\n        cacheManager.setCaffeine(Caffeine.newBuilder()\n            .maximumSize(10000)\n            .expireAfterWrite(1, TimeUnit.HOURS)\n            .recordStats());\n        return cacheManager;\n    }\n}\n```\n\n### 测试开发\n\n#### 单元测试规范\n\n```java\n@SpringBootTest\n@TestPropertySource(locations = \"classpath:application-test.yml\")\nclass DeviceControllerTest {\n\n    @MockitoBean\n    private DeviceService deviceService;\n\n    @Autowired\n    private DeviceController deviceController;\n\n    @Test\n    void testRegisterDevice() {\n        // 准备测试数据\n        Device device = new Device();\n        device.setDeviceId(\"44050100001327000001\");\n\n        // Mock服务行为\n        when(deviceService.register(any(Device.class)))\n            .thenReturn(ResultDTOUtils.success());\n\n        // 执行测试\n        ResultDTO result = deviceController.register(device);\n\n        // 验证结果\n        assertTrue(result.isSuccess());\n        verify(deviceService).register(device);\n    }\n}\n```\n\n#### 集成测试示例\n\n```java\n@SpringBootTest\n@Testcontainers\nclass Gb28181IntegrationTest {\n\n    @Container\n    static PostgreSQLContainer\u003c?\u003e postgres = new PostgreSQLContainer\u003c\u003e(\"postgres:13\")\n        .withDatabaseName(\"testdb\")\n        .withUsername(\"test\")\n        .withPassword(\"test\");\n\n    @Autowired\n    private Gb28181Client client;\n\n    @Autowired\n    private Gb28181Server server;\n\n    @Test\n    void testDeviceRegistration() {\n        // 启动服务端\n        server.start();\n\n        // 客户端注册\n        ResultDTO result = client.register();\n\n        // 验证注册成功\n        assertTrue(result.isSuccess());\n\n        // 验证设备状态\n        assertTrue(client.isOnline());\n    }\n}\n```\n\n## 📊 性能优化\n\n### 异步处理优化\n\n```yaml\nsip:\n  performance:\n    async:\n      core-pool-size: 50\n      max-pool-size: 200\n      queue-capacity: 1000\n      keep-alive: 60\n```\n\n### 缓存优化\n\n```yaml\nsip:\n  performance:\n    cache:\n      initial-capacity: 100\n      maximum-size: 10000\n      expire-after-write: 3600\n      expire-after-access: 1800\n```\n\n### 连接池优化\n\n```yaml\nsip:\n  performance:\n    pool:\n      max-connections: 100\n      min-connections: 10\n      connection-timeout: 30\n      idle-timeout: 300\n```\n\n## 🔍 监控和诊断\n\n### 性能指标\n\n项目集成了Micrometer，提供以下监控指标：\n\n- **SIP消息处理指标**：请求数量、处理时间、成功率\n- **设备状态指标**：在线设备数、注册成功率、心跳成功率\n- **系统资源指标**：CPU使用率、内存使用率、线程池状态\n- **缓存指标**：命中率、缓存大小、过期统计\n\n### 健康检查\n\n```java\n@Component\npublic class SipHealthIndicator implements HealthIndicator {\n\n    @Autowired\n    private SipLayer sipLayer;\n\n    @Override\n    public Health health() {\n        if (sipLayer.isRunning()) {\n            return Health.up()\n                .withDetail(\"sip-stack\", \"running\")\n                .withDetail(\"listening-points\", sipLayer.getListeningPoints().size())\n                .build();\n        } else {\n            return Health.down()\n                .withDetail(\"sip-stack\", \"stopped\")\n                .build();\n        }\n    }\n}\n```\n\n### 日志配置\n\n```xml\n\u003c!-- logback-spring.xml --\u003e\n\u003cconfiguration\u003e\n    \u003cappender name=\"CONSOLE\" class=\"ch.qos.logback.core.ConsoleAppender\"\u003e\n        \u003cencoder\u003e\n            \u003cpattern\u003e[%d{HH:mm:ss}] [%thread] %-5level %logger{36} - %msg%n\u003c/pattern\u003e\n        \u003c/encoder\u003e\n    \u003c/appender\u003e\n\n    \u003cappender name=\"FILE\" class=\"ch.qos.logback.core.rolling.RollingFileAppender\"\u003e\n        \u003cfile\u003elogs/sip-proxy.log\u003c/file\u003e\n        \u003crollingPolicy class=\"ch.qos.logback.core.rolling.TimeBasedRollingPolicy\"\u003e\n            \u003cfileNamePattern\u003elogs/sip-proxy.%d{yyyy-MM-dd}.log\u003c/fileNamePattern\u003e\n            \u003cmaxHistory\u003e30\u003c/maxHistory\u003e\n        \u003c/rollingPolicy\u003e\n        \u003cencoder\u003e\n            \u003cpattern\u003e[%d{yyyy-MM-dd HH:mm:ss}] [%thread] %-5level %logger{36} - %msg%n\u003c/pattern\u003e\n        \u003c/encoder\u003e\n    \u003c/appender\u003e\n\n    \u003clogger name=\"io.github.lunasaw\" level=\"INFO\"/\u003e\n    \u003clogger name=\"gov.nist.javax.sip\" level=\"WARN\"/\u003e\n\n    \u003croot level=\"INFO\"\u003e\n        \u003cappender-ref ref=\"CONSOLE\"/\u003e\n        \u003cappender-ref ref=\"FILE\"/\u003e\n    \u003c/root\u003e\n\u003c/configuration\u003e\n```\n\n## 🤝 贡献指南\n\n### 贡献流程\n\n1. **Fork项目**：Fork本项目到您的GitHub账号\n2. **创建分支**：创建功能分支 `feature/your-feature`\n3. **提交更改**：提交您的更改到分支\n4. **创建PR**：创建Pull Request到主分支\n5. **代码审查**：等待代码审查和合并\n\n### 代码提交规范\n\n提交信息格式：`\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e`\n\n**类型说明：**\n\n- `feat`: 新功能\n- `fix`: 修复bug\n- `docs`: 文档更新\n- `style`: 代码格式调整\n- `refactor`: 代码重构\n- `test`: 测试相关\n- `chore`: 构建/工具相关\n\n**示例：**\n\n```\nfeat(client): 添加设备注册功能\nfix(server): 修复心跳检测bug\ndocs(readme): 更新使用说明\n```\n\n### 代码质量要求\n\n- 遵循项目代码规范\n- 添加必要的单元测试\n- 通过所有测试用例\n- 添加适当的文档说明\n- 使用统一的代码格式化工具\n\n## 📋 更新日志\n\n### v1.2.0 (2024-01-15)\n\n**新增功能：**\n\n- 支持Spring Boot 3.3.1\n- 添加异步消息处理机制\n- 集成Micrometer监控\n- 添加缓存服务支持\n\n**功能改进：**\n\n- 优化SIP连接池管理\n- 提升消息处理性能\n- 完善错误处理机制\n- 增强配置管理能力\n\n**Bug修复：**\n\n- 修复设备注册超时问题\n- 解决心跳检测异常\n- 修复内存泄漏问题\n\n### v1.1.0 (2023-12-01)\n\n**新增功能：**\n\n- 支持GB28181-2016协议\n- 添加设备控制功能\n- 实现云台控制\n- 支持视频回放\n\n**功能改进：**\n\n- 优化消息处理性能\n- 完善异常处理机制\n- 增强日志记录能力\n\n## 📞 技术支持\n\n### 问题反馈\n\n- **GitHub Issues**: [提交问题](https://github.com/lunasaw/gb28181-proxy/issues)\n- **讨论区**: [GitHub Discussions](https://github.com/lunasaw/gb28181-proxy/discussions)\n- **邮件支持**: lunasaw@qq.com\n\n### 技术交流\n\n- **技术博客**: [www.isluna.ml](http://www.isluna.ml)\n- **项目文档**: [在线文档](https://lunasaw.github.io/gb28181-proxy/)\n- **API文档**: [API Reference](https://lunasaw.github.io/gb28181-proxy/api/)\n\n## 🏆 致谢\n\n感谢所有为本项目做出贡献的开发者！\n\n### 核心贡献者\n\n- [@lunasaw](https://github.com/lunasaw) - 项目创建者和维护者\n\n### 特别感谢\n\n- [JAIN-SIP](https://github.com/usnistgov/jsip) - 优秀的SIP协议栈实现\n- [Spring Boot](https://spring.io/projects/spring-boot) - 强大的应用框架\n- [Caffeine](https://github.com/ben-manes/caffeine) - 高性能缓存库\n\n## 📄 许可证\n\n本项目采用 [MIT License](LICENSE) 许可证。\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e如果这个项目对您有帮助，请给我们一个 ⭐️ Star！\u003c/p\u003e\n  \u003cp\u003eMade with ❤️ by \u003ca href=\"https://github.com/lunasaw\"\u003e@lunasaw\u003c/a\u003e\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunasaw%2Fgb28181-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flunasaw%2Fgb28181-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunasaw%2Fgb28181-proxy/lists"}