{"id":14563807,"url":"https://github.com/gowsp/wsp","last_synced_at":"2026-01-27T00:22:55.438Z","repository":{"id":46682907,"uuid":"407539587","full_name":"gowsp/wsp","owner":"gowsp","description":"socks5 and reverse proxy based on websocket","archived":false,"fork":false,"pushed_at":"2025-08-14T07:18:07.000Z","size":125,"stargazers_count":61,"open_issues_count":4,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-14T09:24:05.105Z","etag":null,"topics":["http-proxy","http-server","proxy","proxy-server","reverse-proxy","socks5-proxy","tunnel","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","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/gowsp.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}},"created_at":"2021-09-17T12:53:10.000Z","updated_at":"2025-08-14T07:18:12.000Z","dependencies_parsed_at":"2023-10-22T11:45:18.717Z","dependency_job_id":"644e33c2-3e40-4c3c-ba41-8865fc21ae87","html_url":"https://github.com/gowsp/wsp","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/gowsp/wsp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gowsp%2Fwsp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gowsp%2Fwsp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gowsp%2Fwsp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gowsp%2Fwsp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gowsp","download_url":"https://codeload.github.com/gowsp/wsp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gowsp%2Fwsp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28792890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["http-proxy","http-server","proxy","proxy-server","reverse-proxy","socks5-proxy","tunnel","websocket"],"created_at":"2024-09-07T02:04:43.035Z","updated_at":"2026-01-27T00:22:55.391Z","avatar_url":"https://github.com/gowsp.png","language":"Go","funding_links":[],"categories":["websocket"],"sub_categories":[],"readme":"# wsp\n\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/gowsp/wsp/release)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/gowsp/wsp)\n[![Go Report Card](https://goreportcard.com/badge/github.com/gowsp/wsp)](https://goreportcard.com/report/github.com/gowsp/wsp)\n\nwsp 全称**W**eb**S**ocket **P**roxy 是一种基于 WebSocket 的全方位代理, 仅需要web端口即可提供以下功能：\n\n- 正向代理：支持 socks5 http代理，实现突破防火墙的访问\n- 反向代理：支持将NAT或防火墙后面的本地服务暴露在Internet\n- 网络穿透：将处在NAT设备之后的机器建立连接通讯隧道，进行数据的相互访问\n\nwsp为C/S架构，其中 wsps 位于公网提供 WebSocket 服务，wspc 连接 wsps 进行数据转发，以下为简单的结构示意图\n\n```mermaid\nflowchart TD\n    wspc1 --\u003e wsps\n    wspc2 --\u003e wsps\n    wspc3 --\u003e wsps\n    wsps --\u003e wspc1\n    wsps --\u003e wspc2\n    wsps --\u003e wspc3\n```\n\n## 配置说明\n\n## Wsps\n\n服务端安装，根据操作系统从[Release](https://github.com/gowsp/wsp/releases/latest)下载相应的程序包，解压后将wsps放置在公网机器上，配置用于提供服务的web端口，最小化\n\n最小化配置如下：\n\n```json\n{\n    \"port\": 8010\n}\n```\n\n启动服务端， `./wsps -c wsps.json`，其他配置可参考 `configs/wsps_template.json`\n\n完整配置示例：\n\n```json\n{\n    \"log\": {\n        \"level\": \"info\",\n        \"output\": \"/var/log/wsps.log\"\n    },\n    \"ssl\": {\n        \"enable\": false,\n        \"key\": \"/var/cert/key.file\",\n        \"cert\": \"/var/cert/cert.file\"\n    },\n    \"host\": \"mywsps.com\",\n    \"auth\": \"auth\",\n    \"path\": \"/proxy\",\n    \"port\": 8010\n}\n```\n\n完整配置项说明：\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| port | 整数 | 是 | 服务监听端口 |\n| auth | 字符串 | 否 | 认证 Token，客户端需要提供相同的 Token 才能连接 |\n| path | 字符串 | 否 | WebSocket 服务路径，默认为 \"/\" |\n| host | 字符串 | 否 | 主机名，用于域名模式的反向代理 |\n| log  | 对象 | 否 | 日志配置 |\n| ssl  | 对象 | 否 | SSL 配置 |\n\n#### 日志配置 (log)\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| level | 字符串 | 否 | 日志级别，支持 error、info、debug、trace |\n| output | 字符串 | 否 | 日志输出文件路径，默认输出到标准输出 |\n\n#### SSL 配置 (ssl)\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| enable | 布尔值 | 否 | 是否启用 SSL，默认为 false |\n| key | 字符串 | 否 | SSL 私钥文件路径 |\n| cert | 字符串 | 否 | SSL 证书文件路径 |\n\n## Wspc\n\n客户端wspc功能设计参考了ssh，配置项存在三种转发模式：\n\n- DynamicForward，动态转发，提供正向代理如：socks5，http代理\n- RemoteForward，远程转发，将本地端口服务暴露在wsps上，支持 TCP  HTTP HTTPS 协议\n- LocalForward，本地转发，用于本地访问已注册的`远程转发`服务\n\n支持连接多个 wsps 服务端，配置格式类似如下：\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://wsp1.com:8010\",\n      \"local\": []\n    },\n    {\n      \"server\": \"ws://wsp1.com:8010\",\n      \"remote\": []\n    }\n  ]\n}\n```\n\n`wspc`的其他配置可参考 `configs/wspc_template.json`\n\n完整配置示例：\n\n```json\n{\n    \"log\": {\n        \"level\": \"info\",\n        \"output\": \"/var/log/wspc.log\"\n    },\n    \"client\": [\n        {\n            \"auth\": \"auth\",\n            \"server\": \"ws://mywsps.com:8010/proxy\",\n            \"dynamic\": [\n                \"socks5://:1080\"\n            ],\n            \"remote\": [\n                \"tcp://ssh:passwod@192.168.1.100:22\",\n                \"http://127.0.0.1:8080?mode=path\u0026value=api\",\n                \"http://127.0.0.1:8080?mode=domain\u0026value=custom.com\"\n            ],\n            \"local\": [\n                \"tcp://ssh:passwod@127.0.0.1:2200\"\n            ]\n        }\n    ]\n}\n```\n\n完整配置项说明：\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| auth | 字符串 | 否 | 认证 Token，需要与服务端配置一致 |\n| server | 字符串 | 是 | 服务端地址 |\n| dynamic | 数组 | 否 | 动态转发配置（正向代理） |\n| remote | 数组 | 否 | 远程转发配置（反向代理/网络穿透服务端） |\n| local | 数组 | 否 | 本地转发配置（网络穿透客户端） |\n| log  | 对象 | 否 | 日志配置 |\n\n## 正向代理\n\n### client模式\n\n此模式下需要在本机中安装wspc配合wsps使用正向代理，wspc动态转发代理请求，连接的打开和流量传输通过wsps，示意图如下\n\n```mermaid\nsequenceDiagram\n    actor  client\n    participant wspc\n    participant wsps\n    actor server\n    par connect\n        wspc --\u003e wsps : keep websocket connect\n    and proxy\n        client -\u003e\u003e wspc: socks5 or http proxy reqeust\n        wspc -\u003e\u003e wsps: request open connect\n        wsps -\u003e\u003e server: open connect\n        server -\u003e\u003e wsps: connect response\n        wsps -\u003e\u003e wspc: connect response\n        wspc -\u003e\u003e client: proxy response\n    and tranfer data\n        client --\u003e\u003e server: tranfer data, via wspc\n        server --\u003e\u003e client: tranfer data, via wsps\n    end\n```\n\n配置格式：`protocols://[bind_address]:port`\n\n- `protocols`支持 socks5 代理协议，HTTP 代理\n- `bind_address`可选，空地址表示监听所有网卡IP\n- `port`本地监听端口\n\n示例如下：\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"dynamic\": [\n        \"http://:80\",\n        \"socks5://:1080\"\n      ]\n    }\n  ]\n}\n```\n\n启动wspc， `./wsps -c wsps.json`, 此时本地`1080`提供socks5代理，`80`提供http代理, 流量则通过`wsps`进行访问\n\n## 反向代理\n\n将本地服务暴露在wsps上，供浏览器直接访问\n\n### 暴露本地HTTP HTTPS服务\n\n示意图如下：\n\n```mermaid\nsequenceDiagram\n    actor  browser\n    participant wsps\n    participant wspc\n    actor http as web server\n    par register \n        wspc --\u003e wsps: websocket connect\n    and connect\n        browser -\u003e\u003e wsps : http request\n        wsps -\u003e\u003e wspc : select wspc to serve\n        wspc -\u003e\u003e http: open connect\n        http -\u003e\u003e wspc: connect response\n        wspc -\u003e\u003e wsps: connect response\n    and reqeust\n        wsps -\u003e\u003e wspc: http reqeust data\n        wspc -\u003e\u003e http: http reqeust data\n        http -\u003e\u003e wspc: http response data\n        wspc -\u003e\u003e wsps: http response data\n        wsps -\u003e\u003e browser: http response data\n    end\n\n```\n\n配置格式：`protocols://bind_address:port/[path]?mode=[mode]\u0026value=[value]`\n\n- `protocols` 支持 http, https（支持websocket）\n- `bind_address`http服务地址\n- `port`http服务端口\n- `path`可选http服务路径\n- `mode`访问模式，为以下两种\n  - `path` 路径模式\n  - `domain` 域名模式\n\n例：\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"remote\": [\n        \"http://127.0.0.1:8080?mode=path\u0026value=api\",\n        \"http://127.0.0.1:8080/api/?mode=path\u0026value=api\",\n        \"http://127.0.0.1:8080?mode=domain\u0026value=customwsp.com\",\n        \"http://127.0.0.1:8080/api/?mode=domain\u0026value=customapi.com\"\n      ]\n    }\n  ]\n}\n```\n\n启动wspc， `./wsps -c wsps.json`，此时在wsps注册的访问映射关系由上至下为\n\n- 访问 http://mywsps.com:8010/api/greet -\u003e http://127.0.0.1:8080/greet\n- 访问 http://mywsps.com:8010/api/greet -\u003e http://127.0.0.1:8080/api/greet\n- 访问 http://customwsp.com:8010/api/greet -\u003e http://127.0.0.1:8080/api/greet\n- 访问 http://customwsp.com:8010/greet -\u003e http://127.0.0.1:8080/api/greet\n\n### 包装本地TCP服务为websocket\n\n某些场景下希望将TCP流量通过websocket进行转发，配置格式：`protocols://bind_address:port?mode=[mode]\u0026value=[value]`\n\n- `protocols` 支持 tcp\n- `bind_address`服务IP地址\n- `port`服务端口\n- `mode`访问模式，为以下两种\n  - `path` 路径模式\n  - `domain` 域名模式\n\n例暴露vnc服务在websocket，我们配置如下：\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"remote\": [\n        \"tcp://127.0.0.1:5900?mode=path\u0026value=vnc\"\n      ]\n    }\n  ]\n}\n```\n\n这时我们可以打开[novnc](https://novnc.com/noVNC/vnc.html), 修改配置，修改为暴露的vnc服务参数，即可实现vnc的远程访问\n\n## 网络穿透\n\n### 普通模式\n\n此模式下需要两台wspc配合wsps使用，三者功能角色如下：\n\n- wspc client 接入侧\n- wsps 中转侧，负责将wspc clinet的代理请求和数据中转给目标的wspc server\n- wspc server 服务侧，注册在wsps，负责打开来至wspc client的连接或转发数据\n\n示意图如下\n\n```mermaid\nsequenceDiagram\n    actor  client\n    participant wspc1\n    participant wsps\n    participant wspc2\n    actor target\n    par target register \n        wspc2 -\u003e\u003e wsps: websocket connect\n    and local register\n        wspc1 -\u003e\u003e wsps: websocket connect\n    end\n    par request connect \n        client -\u003e\u003e+ wspc1: request\n        wspc1 -\u003e\u003e+ wsps : request\n        wsps -\u003e\u003e+ wspc2 : request\n        wspc2 -\u003e\u003e+ target : request\n        target -\u003e\u003e- wspc2 : reponse\n        wspc2 -\u003e\u003e- wsps : reponse\n        wsps -\u003e\u003e- wspc1 : reponse\n        wspc1 -\u003e\u003e- client: reponse\n    and tranfer data\n        client --\u003e\u003e target: virtual connection, via wspc1 websocket\n        target --\u003e\u003e client: virtual connection, via wspc2 websocket\n    end\n```\n\n`wspc server`将本地服务注册至wsps等待`wspc client`连接，配置格式：`protocols://channel[:password]@[bind_address]:port`\n\n- `protocols` 支持 tcp\n- `channel`信道标识，注册在wsps上等待其他wspc接入的标识信息\n- `password`连接密码，接入的wspc连接密码需要一致才能通讯\n- `bind_address`监听地址\n- `port`服务端口\n\n如注册本地网络中ssh服务配置如下\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"remote\": [\n        \"tcp://ssh:ssh@192.168.1.200:22\"\n      ]\n    }\n  ]\n}\n```\n\n`wspc client`本地转发，开启本地端口来访问远程已注册的`wspc server`，配置格式：`protocols://remote_channel[:password]@[bind_address]:port`\n\n- `protocols` 支持 tcp\n- `channel`信道标识，wsps上已注册的的channel才能访问\n- `password`连接密码，与`RemoteForward`端密码一致才能通讯\n- `bind_address`监听地址\n- `port`本地端口\n\n如访问已注册的`wspc server`ssh服务，本地`wspc client`进行如下配置\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"local\": [\n        \"tcp://ssh:ssh@127.0.0.1:2200\"\n      ]\n    }\n  ]\n}\n```\n\n此时访问本地的`127.0.0.1:2200`即为访问`wspc server`端中`192.168.1.200:22`的ssh服务\n\n### vpn模式\n\n此模式下需要两台wspc配合wsps使用，三者功能角色如下：\n\n- wspc client 代理侧\n- wsps 中转侧，负责将wspc clinet的代理请求和数据中转给目标的wspc server\n- wspc server 服务侧，注册在wsps，负责打开来至wspc client的代理连接转发代理数据\n\n`wspc server`端配置`tunnel://channel[:password]@`\n\n- `channel`信道标识，注册在wsps上等待其他wspc接入的标识信息\n- `password`连接密码，接入的wspc连接密码需要一致才能通讯\n\n例：\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"remote\": [\n        \"tunnel://work_tunnel:password@\"\n      ]\n    }\n  ]\n}\n```\n\n`wspc client`端配置`protocols://remote_channel[:password]@[bind_address]:port`\n\n- `protocols`代理协议，支持 socks5 代理，HTTP 代理\n- `remote_channel`信道标识，`RemoteForward`端注册的`channel`\n- `password`密码，对应`RemoteForward`端密码\n- `bind_address`可选，空地址表示监听所有网卡IP\n- `port`本地监听端口\n\n```json\n{\n  \"client\": [\n    {\n      \"server\": \"ws://mywsps.com:8010\",\n      \"dynamic\": [\n        \"socks5://work_tunnel:password@127.0.0.1:1080\"\n      ]\n    }\n  ]\n}\n```\n\n在`wspc client`端用socket5代理的连接和流量都会转发到`wspc server`端，如socket5代理下，访问`192.168.1.200:22`即访问`wspc server`端的`192.168.1.200:22`\n\n## 日志记录\n\nwsp 支持日志分级记录，可在 wsps 或 wspc 中加入如下配置：\n\n```json\n{\n  \"log\": {\n    \"level\": \"info\",\n    \"output\": \"/var/log/wsp.log\"\n  }\n}\n```\n\n其中 `level` 支持以下级别：\n\n- error：只记录错误\n- info：记录信息，包含错误\n- debug：记录收发的信令，包含以上信息\n- trace：记录全过程信息\n\n## 作为模块引入\n\nwsp在开发时考虑了与现有web服务的协作，支持作为一个功能模块引入\n\n```\ngo get -u github.com/gowsp/wsp\n```\n\n与官方http集成\n\n```go\nimport \"github.com/gowsp/wsp/pkg/server\"\n\nconfig := \u0026server.Config{Auth: \"auth\"}\n\nserver.NewWithHandler(config, http.NewServeMux())\nserver.NewWithHandler(config, http.DefaultServeMux)\n```\n\n与gin集成\n\n```go\nimport \"github.com/gowsp/wsp/pkg/server\"\n\nconfig := \u0026server.Config{Auth: \"auth\"}\nr := gin.Default()\nserver.NewWithHandler(config, r)\n```\n\n## TODO\n\n- [ ] 支持命令行模式使用\n\n## 反馈建议\n\n目前此项目为个人独立开发，难免会有BUG和功能设计上的缺陷，如有问题请提issues反馈，也欢迎参与代码或文档的贡献，祝使用愉快\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgowsp%2Fwsp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgowsp%2Fwsp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgowsp%2Fwsp/lists"}