Websockify 技术文档

1. 安装指南

1.1 安装方式

1.1.1 通过源码安装

1. 下载最新版本的 websockify 源码包或开发版本。

2. 解压下载的文件。

3. 进入解压后的目录，运行以下命令进行安装：

   sudo python3 setup.py install
   

   默认情况下，安装过程中会自动安装 numpy 以提高性能。如果不需要 numpy 或无法编译 numpy，可以在 setup.py 文件中删除 install_requires=['numpy'], 这一行，然后再运行安装命令。

4. 安装完成后，可以通过运行 websockify --help 来确认安装是否成功。

1.1.2 通过 Docker/Podman 安装

1. 构建 Docker 镜像：

   ./docker/build.sh
   

2. 构建完成后，可以使用以下命令启动 websockify：

   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
   

3. 如果需要包含文件（如 --web 或 --cert 选项），可以通过挂载卷的方式将文件挂载到容器中：

   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
   

2. 项目使用说明

2.1 基本功能

websockify 的主要功能是将 WebSocket 流量转换为普通 socket 流量。它接受 WebSocket 握手请求，解析后开始在客户端和目标服务器之间双向转发数据。

2.2 加密 WebSocket 连接

要使用加密的 WebSocket 连接（wss://），需要生成一个证书和密钥供 websockify 加载。默认情况下，websockify 会加载名为 self.pem 的证书文件，但可以通过 --cert=CERT 和 --key=KEY 选项指定其他文件。

生成自签名证书的命令如下：

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

为了让客户端/浏览器信任自签名证书，可以通过以下两种方式：

1. 将证书安装为受信任的证书。
2. 先通过 HTTPS 连接到服务器并批准证书。

2.3 其他功能

• 守护进程模式：通过 -D 选项，websockify 可以在后台以守护进程模式运行。
• SSL 支持：websockify 会自动检测客户端发送的第一个字节，如果数据以 \x16 或 \x80 开头，则表示 SSL 连接。
• 会话记录：使用 --record 选项可以将客户端发送和接收的流量记录到文件中。
• 迷你 Web 服务器：通过 --web DIR 选项，websockify 可以在同一端口上处理普通 Web 请求。
• 日志记录：使用 --log-file FILE 选项可以将所有日志信息保存到指定文件中。
• 认证插件：通过 --auth-plugin CLASS 和 --auth-source ARG 选项，websockify 可以要求对 WebSocket 连接进行认证。
• 令牌插件：通过 --token-plugin CLASS 和 --token-source ARG 选项，websockify 可以根据客户端发送的令牌或主机名将客户端连接到不同的目标。

3. 项目 API 使用文档

3.1 命令行参数

• --cert=CERT：指定 SSL 证书文件。
• --key=KEY：指定 SSL 密钥文件。
• --ssl-only：仅允许 SSL 连接。
• --web DIR：启用迷你 Web 服务器，并指定 Web 根目录。
• --log-file FILE：将日志信息保存到指定文件中。
• --auth-plugin CLASS：启用认证插件。
• --token-plugin CLASS：启用令牌插件。

3.2 示例

1. 启动 websockify 并转发 WebSocket 流量到目标服务器：

   websockify 8080 192.168.1.100:5900
   

2. 使用自签名证书启动加密的 WebSocket 连接：

   websockify --cert=self.pem --key=self.pem 8443 192.168.1.100:5900
   

3. 启用迷你 Web 服务器并记录会话：

   websockify --web /var/www --record session.log 8080 192.168.1.100:5900
   

4. 项目安装方式

4.1 源码安装

通过源码安装 websockify 是最常见的方式。用户需要下载源码包，解压后运行 python3 setup.py install 进行安装。

4.2 Docker/Podman 安装

对于容器化环境，用户可以通过 Docker 或 Podman 运行 websockify。首先构建镜像，然后通过 docker run 或 podman run 命令启动容器。

通过以上步骤，用户可以顺利安装并使用 websockify 项目，实现 WebSocket 流量的代理和转发。