websockify: 为任何应用程序/服务器提供WebSocket支持

websockify曾名为wsproxy，是noVNC项目的一部分。

在最基本的层面上，websockify只是将WebSocket流量转换为普通套接字流量。websockify接受WebSocket握手，解析它，然后开始双向转发客户端和目标之间的流量。

新闻/帮助/联系

显著的提交、公告和新闻发布到 @noVNC

如果您是websockify的开发者/集成者/用户（或希望成为）请加入noVNC/websockify讨论组

可以通过github issues提交错误和功能请求。

如果您想对websockify表示感谢，可以向以下优秀的非营利组织捐款：国际怜悯、SIL、人济会、电子前沿基金会、对抗疟疾基金会、无网仅网等。如果您这样做，请通过@noVNC发推。

WebSockets二进制数据

从websockify 0.5.0版本开始，仅支持HyBi / IETF 6455 WebSocket协议。不再支持旧版的Base64编码数据格式。

加密的WebSocket连接（wss://）

要使用WebSocket 'wss://' URI方案加密流量，您需要为Websockify生成一个证书和密钥。默认情况下，Websockify加载名为self.pem的证书文件，但--cert=CERT和--key=KEY选项可以覆盖文件名。您可以使用openssl生成自签名证书。当被要求输入公用名称时，请使用代理将运行的服务器的主机名

openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem

为了使自签名证书能够工作，您需要让您的客户端/浏览器理解它。您可以通过将其作为接受的证书安装，或者使用相同的证书进行HTTPS连接（您首先导航并批准的连接）来实现。浏览器通常不会通过打开具有无效证书的WSS套接字来给您“信任证书？”提示，因此您需要通过这两种方法中的任何一种让它接受。

端口可能会被视为浏览器区分连接的方式，例如，如果您的网站URL是https://my.local:8443，而您的WebSocket URL是wss://my.local:8001，首先浏览到https://my.local:8001，添加异常，然后浏览到https://my.local:8443并添加另一个异常。然后通过:8443提供的html页面将能够打开到:8001的WSS

如果您有一个带有一个或多个中间证书的商业/有效SSL证书，请将它们合并到一个文件中，首先是服务器证书，然后是来自CA的中间（s），等等。使用--cert选项指向此文件，然后也使用--key指向密钥。最后，根据需要使用--ssl-only。

Websockify的其他功能

这些对于基本操作不是必需的。

• 守护进程化：当指定-D选项时，websockify作为守护进程在后台运行。

• SSL（wss:// WebSocket URI）：websockify通过嗅探客户端发送的第一个字节来自动检测，如果数据以'\x16'或'\x80'（表示SSL）开始，则包装套接字。

• 会话录制：此功能允许使用--record选项将发送和接收的客户端流量记录到文件中。

• 迷你Web服务器：websockify可以检测和响应与WebSocket代理相同端口的正常Web请求。此功能通过--web DIR选项激活，其中DIR是要提供服务的web目录的根目录。

• 包装程序：请参阅下方的“包装程序”部分。

• 日志文件：websockify可以将所有日志信息保存到文件中。此功能通过--log-file FILE选项激活，其中FILE是日志应该保存到的文件。

• 身份验证插件：websockify可以为WebSocket连接请求身份验证，如果您使用--web-auth，还可以为正常Web请求请求身份验证。此功能通过--auth-plugin CLASS和--auth-source ARG选项激活，其中CLASS通常是来自auth_plugins.py的一个，而ARG是插件的配置。

• 令牌插件：单个websockify实例可以连接到多个不同的预配置目标，具体取决于客户端通过token URL参数发送的令牌，或者用于到达websockify的主机名，如果您使用了--host-token。此功能通过--token-plugin CLASS和--token-source ARG选项激活，其中CLASS通常是来自token_plugins.py的一个，ARG是插件的配置。

websockify的其他实现

websockify的主要实现是在Python中。在我们的姊妹仓库中有几个其他语言的替代实现可供使用：websockify-js（JavaScript/Node.js）和websockify-other（C, Clojure, Ruby）。

此外，还有一些其他外部项目实现了websockify "协议"。有关更多信息，请参阅替代实现功能矩阵。

包装程序

除了从源地址到目标地址的代理（这些地址可能位于不同的系统上）之外，websockify还具有在本地系统上启动程序并将其WebSockets流量代理到程序拥有的/绑定到正常TCP端口的特性。

这是通过LD_PRELOAD库（rebind.so）实现的，该库拦截程序对bind()系统调用的调用。指定的端口被移动到一个新的本地主机/环回免费的较高端口。然后，websockify将指向原始端口的WebSockets流量代理到程序的新（移动后）端口。

通过将目标替换为--后跟包装程序的命令行来调用程序包装模式。

`./run 2023 -- PROGRAM ARGS`

可以使用--wrap-mode选项来指示包装程序退出或守护进程化时要采取的操作。

以下是一个使用websockify包装vncserver命令（该命令在后台运行）的示例，以便与noVNC一起使用。

`./run 5901 --wrap-mode=ignore -- vncserver -geometry 1024x768 :1`

以下是一个包装telnetd（从krb5-telnetd）的示例。telnetd在连接关闭后退出，因此包装模式设置为重新启动命令。

`sudo ./run 2023 --wrap-mode=respawn -- telnetd -debug 2023`

websockify-js项目中的wstelnet.html页面演示了一个简单的基于WebSockets的telnet客户端（分别使用'localhost'和'2023'作为主机和端口）。

安装websockify

下载一个版本或最新的开发版本，解压它，并以root用户身份在解压文件所在的目录中运行python3 setup.py install。通常，这也会安装numpy以获得更好的性能，如果您尚未安装它。但是，numpy是可选的。如果您不想安装numpy或无法编译它，您可以在运行python3 setup.py install之前编辑setup.py并删除install_requires=['numpy'],行。

之后，websockify应该在您的路径中可用。运行websockify --help以确认已正确安装。

使用Docker/Podman运行

您还可以使用Docker、Podman、Singularity、udocker或您喜欢的支持OCI容器镜像的容器运行时运行websockify。

镜像的入口点是run命令。

要构建镜像

./docker/build.sh

构建完成后，您可以仅用与run命令相同的参数启动它，并注意分配端口映射。

docker run -it --rm -p <port>:<container_port> novnc/websockify <container_port> <run_arguments>

例如，要转发本地端口7000到10.1.1.1:5902，可以使用

docker run -it --rm -p 7000:80 novnc/websockify 80 10.1.1.1:5902

如果您需要包含文件，例如对于--web或--cert选项，只需将所需的文件挂载到/data卷中，然后您可以按通常的方式引用它们。

docker run -it --rm -p 443:443 -v websockify-data:/data novnc/websockify --cert /data/self.pem --web /data/noVNC :443 --token-plugin TokenRedis --token-source myredis.local:6379 --ssl-only --ssl-version tlsv1_2

更改

0.12.0

• simplejson模块不再需要用于redis令牌支持
• redis令牌现在可以是JSON或纯文本
• websockify现在可以监听Unix套接字以接收传入的连接

0.11.0

• 命令行现在支持禁用目录列表
• 包括基本Dockerfile

0.10.0

• 现在需要 Python 3.4 或更高版本
• 现在支持空消息帧
• 令牌现在可以指定连接的 Unix 域套接字文件
• 现在尊重 JWT 令牌的时间限制
• 在令牌文件中对空白符的容忍度更高
• 许多小的修复...

0.9.0

• 移除了 Base64 支持，现在需要二进制模式
• 低级别 WebSocket 协议处理现在有自己的类
• 现在可以为网络服务器选择性地要求身份验证
• 可以将服务器主机名用作令牌
• 可以使用 JWT/JWS/JWE 作为令牌
• 可以使用 redis 作为令牌
• 现在可以记录到系统日志
• 通过禁用代理连接的 Nagle 来提高延迟
• 添加了客户端证书身份验证
• 支持受密码保护的证书密钥文件
• 现在可以配置 TLS 密码和选项
• 可以通过 inetd 调用
• 许多小的修复...

0.8.0

• 使 websockify 在 SIGTERM 信号时正确终止子进程 (#226)
• 从信号处理器中删除记录 (这可能在某些条件下导致 Python 挂起) (#219)
• 使记录到文件更容易 (#205)
• 在 TokenFile 令牌插件中添加对 IPv6 地址的支持 (#197)
• 改进认证插件框架，以支持更好的 HTTP 认证 (#194, #201)
• 修复 JSONTokenAPI 令牌插件中的错误 (#192)
• 修复异常处理器中缺失的变量 (#178)

0.7.0

• 修复 Python 3 支持问题 (#140, #155, #159)
• 支持通用的令牌解析插件 (#162)
• 支持通用的认证插件 (#172)
• 修复了在大端系统上的帧损坏问题 (#161)
• 支持心跳（通过 PING）和自动响应 PONG (#169)
• 默认情况下自动拒绝未屏蔽的客户端帧（严格模式）(#174)
• 自动重新启动中断的 select 调用 (#175)
• 使 'run' 尊重环境设置（包括 virtualenv）(#176)

0.6.1 - 2015 年 5 月 11 日

• PATCH RELEASE：修复了导致 file_only 未正确传递的 bug

0.6.0 - 2014 年 2 月 18 日

• 注意：0.6.0 将破坏现有的 WebsocketProxy 子类代码
• 重构以使用标准 SocketServer RequestHandler 设计
• 修复了在使用多进程时某些系统上的僵尸进程 bug
• 添加了更好的单元测试
• 通过 python logging 模块记录信息

0.5.1 - 2013 年 6 月 27 日

• 使用与 websockify.js 兼容的上游 einaros/ws (>=0.4.27)
• 为 WSRequestHandler 添加 file_only 和 no_parent 安全选项
• 更新 web-socket-js 的构建 (c0855c6cae)
• 将 include/web-socket-js-project 子模块添加到 gimite/web-socket-js 以符合 DSFG 标准。
• 删除 Hixie 协议支持

0.4.1 - 2013 年 3 月 12 日

• 注意：0.5.0 将删除 Hixie 协议支持
• 添加 include/ 目录并从源分布中删除一些开发文件。

0.4.0 - 2013 年 3 月 12 日

• 注意：0.5.0 将删除 Hixie 协议支持
• 在 Node.js 实现中使用 Buffer base64 支持

0.3.0 - 2013 年 1 月 15 日

• 重构为模块：websocket、websocketproxy
• 切换到使用 IETF 6455 的 web-socket-js
• 将 include/*.js 的许可证更改为 MPL 2.0
• 修复会话记录

0.2.1 - 2012 年 10 月 15 日

• 重新发布，版本号已更新

0.2.0 - 2012 年 9 月 17 日

• 在 websock.js 中支持二进制数据
• 支持目标配置文件/目录和具有令牌选择器的多个目标
• IPv6 修复
• 支持 SSL 目标
• 支持从/到 Unix 套接字代理

0.1.0 - 2012 年 5 月 11 日

• 初始版本发布。