{"id":15014221,"url":"https://github.com/kuangcp/netty-ws-starter","last_synced_at":"2026-02-25T06:05:34.414Z","repository":{"id":248053789,"uuid":"827226675","full_name":"Kuangcp/netty-ws-starter","owner":"Kuangcp","description":"SpringBoot starter for websocket cluster by netty ","archived":false,"fork":false,"pushed_at":"2024-08-30T11:04:02.000Z","size":99,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T02:51:13.640Z","etag":null,"topics":["netty","springboot-stater","websocket"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kuangcp.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-07-11T08:34:13.000Z","updated_at":"2024-12-13T06:31:38.000Z","dependencies_parsed_at":"2024-09-20T10:00:34.648Z","dependency_job_id":"16658228-f482-4861-9c1d-f84433e74d63","html_url":"https://github.com/Kuangcp/netty-ws-starter","commit_stats":{"total_commits":37,"total_committers":1,"mean_commits":37.0,"dds":0.0,"last_synced_commit":"e9f7495fcfb55febdfff96f555f30551441a8121"},"previous_names":["kuangcp/netty-ws-starter"],"tags_count":2,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kuangcp%2Fnetty-ws-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kuangcp%2Fnetty-ws-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kuangcp%2Fnetty-ws-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kuangcp%2Fnetty-ws-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kuangcp","download_url":"https://codeload.github.com/Kuangcp/netty-ws-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248536981,"owners_count":21120683,"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","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":["netty","springboot-stater","websocket"],"created_at":"2024-09-24T19:45:20.604Z","updated_at":"2025-10-26T20:11:28.413Z","avatar_url":"https://github.com/Kuangcp.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# netty websocket starter\n\n![](/arch.drawio.svg)\n\n- 支持功能：\n  - SDK随应用集成，不单独部署，并且无需考虑类似于Cookie/Session场景下的 session 共享问题\n  - 广播消息\n  - 心跳检测\n  - HTTP握手请求时支持自定义认证\n  - 自定义编解码方式，JSON Protobuf等\n\n- 不支持功能：\n  - 消息持久化，历史消息搜索 \n  - 消息的已读\u0026未读 回执\n  - 发送和接收消息的 Once 语义\n  - 发送离线消息\n  - 断线重连时的节点亲和\n  - 节点故障转移时，保证消息不丢失\n\n\n## Quick Start\n\n[Demo 项目](/netty-ws-server-demo)\n\n\u003e 添加依赖\n\n```xml\n\u003c!--添加源--\u003e\n\u003crepository\u003e\n    \u003cid\u003egithub\u003c/id\u003e\n    \u003curl\u003ehttps://maven.pkg.github.com\u003c/url\u003e\n    \u003csnapshots\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n    \u003c/snapshots\u003e\n\u003c/repository\u003e\n```\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.kuangcp\u003c/groupId\u003e\n    \u003cartifactId\u003enetty-ws-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.5-RELEASE\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003e 基础配置\n\n```yaml\nnetty-ws:\n  # websocket 服务 端口 \n  port: 5455\n  # ws url 根路径 默认为 ws://host:port/ws\n  prefix: /ws\n  # HTTP握手请求时最大请求体字符串长度\n  max-content-length: 4096\n  # 单条消息最大字符串长度，需要按业务设置合理值，防范DOS攻击\n  max-frame-size: 65536\n  # 60s 未读取到客户端发来的消息 认为是触发一次idle事件\n  reader-idle-sec: 60\n  # 当idle事件累计到2次后，关闭当前用户连接\n  reader-idle-threshold: 2\n  # 是否开启 token 认证机制\n  connect-auth: true\n```\n\n\u003e 自定义连接处理类\n\n```java\n\n@Component\n@ChannelHandler.Sharable\npublic class DemoHandler extends AbstractBizHandler {\n\n    public DemoHandler(CacheDao cacheDao, UserDao userDao, WsServerConfig config) {\n        super(cacheDao, userDao, config);\n        this.schedulerPollQueueMsg(Executors.newScheduledThreadPool(1));\n    }\n\n    @Override\n    public void connectSuccess(Long userId) {\n        log.info(\"connected {}\", userId);\n    }\n\n    @Override\n    public void channelInactive(ChannelHandlerContext ctx) throws Exception {\n        String id = WsSocketUtil.id(ctx);\n        Long userId = channelUserMap.get(id);\n        log.info(\"disconnect {}\", userId);\n        super.channelInactive(ctx);\n    }\n\n    @Override\n    protected void handSharkHttpRequest(ChannelHandlerContext ctx, FullHttpRequest request) {\n        super.handSharkHttpRequest(ctx, request);\n    }\n}\n```\n\n\u003e 实现存储扩展 com.github.kuangcp.websocket.store.CacheDao  \n\u003e 实现认证扩展 com.github.kuangcp.websocket.store.UserDao  \n\n- 然后启动项目, 验证websocket通信。 可使用 [Js 测试客户端](/netty-ws-server-demo/src/main/resources/client.html) 测试，连接地址 `ws://127.0.0.1:5455/ws?uid={uid}\u0026token={token}`\n    - 注意认证的实现方式为HTTP握手时，解析 url参数或者Header中的token值。\n    - 如果未开启认证（connect-auth） token可不传\n\n## 设计思路\n\n1. Netty作为通信基础，每个用户连接时通过前置的Nginx等LB层负载均衡到WS集群中的任意节点。\n1. 用户和主机ip关系绑定到Redis map结构中 (userid -\u003e host) \n1. 每个主机ip绑定一个Redis的list队列，存放了需要推送的消息（由其他节点写入），解决应用层向用户推送消息时，用户连接随机分散的问题。\n\n注意：Redis可替换成任意中心存储, 已由 CacheDao 抽象, 例如关系型数据库 MySQL，PG；非关系型数据库：MongoDB 等等。\n\n## Dev\n\nmvn clean source:jar deploy -U -DskipTests=true\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuangcp%2Fnetty-ws-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuangcp%2Fnetty-ws-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuangcp%2Fnetty-ws-starter/lists"}