wezterm TLS 域TLS Domains配置指南tls_servers 服务端完整解析【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermTLS 域是 wezterm 多路复用multiplexing体系中使用 TLS 加密 TCP 连接的一种域类型适合跨公网、跨主机安全地连接远程 wezterm 多路复用服务器。本文以tls_servers配置项为核心完整讲解其字段含义、TlsDomainServer结构体细节、客户端配套配置、连接启动流程并结合仓库源码揭示其底层实现原理帮助你独立搭建一套基于证书认证的 wezterm TLS 多路复用服务。说明本文涉及的功能属于 wezterm 的 multiplexing多路复用子系统相关背景可先阅读仓库中的 docs/multiplexing.md其 TLS Domains 章节与本主题直接对应tls_servers配置项的原始文档位于 docs/config/lua/config/tls_servers.md。tls_servers是什么tls_servers是 wezterm 配置~/.wezterm.lua中的一个顶层配置项用于定义多路复用服务器端的 TLS 监听端点。与之相对的还有tls_clients客户端域定义和unix_domains、ssh_domains其他域类型。在 wezterm 的配置结构中tls_servers被定义为TlsDomainServer对象的列表。仓库源码 config/src/config.rs 中可以看到它的官方注释与相邻字段/// When running in server mode, defines configuration for /// each of the endpoints that well listen for connections #[dynamic(default)] pub tls_servers: VecTlsDomainServer, /// The set of tls domains that we can connect to as a client #[dynamic(default)] pub tls_clients: VecTlsDomainClient,从源码结构看tls_servers的职责是在服务器模式下定义每个将要监听连接的端点它只关心监听与证书不包含域名称等身份信息而域名称用于wezterm connect name定义在客户端的tls_clients中。与 Unix 域、SSH 域的定位差异wezterm 的多路复用域一共有几种形态本地域local domainwezterm 启动时默认创建管理 UI 中的窗口和标签页Unix 域unix domain通过 Unix socket 连接多路复用服务器适合本机或 WSL 等场景配置对应config.unix_domainsSSH 域ssh domain通过 SSH 通道启动并连接远端 wezterm 多路复用服务器配置对应config.ssh_domainsTLS 域TLS domain通过TLS 加密的 TCP 连接访问多路复用服务器配置对应config.tls_servers服务端与config.tls_clients客户端。TLS 域的核心价值在于当多路复用服务器运行在公网可达的机器上时可以用 TLS 保证信道的机密性与完整性并用 x509 证书完成双向认证而不是依赖 SSH 密钥或本机 socket 权限。TlsDomainServer的字段详解TlsDomainServer是tls_servers列表的元素类型。其完整的 Lua 配置骨架如下摘自仓库 docs/config/lua/TlsDomainServer.md结合源码字段补充注释config.tls_servers { { -- 服务器监听客户端连接所用的 address:port 组合 bind_address server.hostname:8080, -- x509 PEM 编码的私钥文件路径。 -- 如果你的 tls_client 使用了 bootstrap_via_ssh可以省略此项。 -- pem_private_key /path/to/key.pem, -- x509 PEM 编码的证书文件路径。 -- 如果你的 tls_client 使用了 bootstrap_via_ssh可以省略此项。 -- pem_cert /path/to/cert.pem, -- x509 PEM 编码的 CA 链文件路径。 -- 如果你的 tls_client 使用了 bootstrap_via_ssh可以省略此项。 -- pem_ca /path/to/chain.pem, -- 一组要额外加载的 CA 证书路径。 -- 每个条目可以是目录路径也可以是 PEM 编码的 CA 文件 -- 如果是目录目录下的内容会作为 CA 证书被加载进信任库。 -- 如果你的 tls_client 使用了 bootstrap_via_ssh可以省略此项。 -- pem_root_certs { /some/path/ca1.pem, /some/path/ca2.pem }, }, }字段逐一说明字段类型是否必填作用bind_addressstring必填host:port形式的监听地址服务器在此地址上等待客户端连接pem_private_keystring可选x509 PEM 私钥文件路径使用bootstrap_via_ssh引导时可省略pem_certstring可选x509 PEM 证书文件路径使用bootstrap_via_ssh引导时可省略pem_castring可选x509 PEM CA 链文件路径使用bootstrap_via_ssh引导时可省略pem_root_certsstring 数组可选额外信任的 CA 证书路径集合条目可以是目录或单个 PEM 文件对应的 Rust 定义位于仓库 config/src/tls.rs。值得注意的实现细节bind_address是必填的String其余证书字段都是OptionPathBuf即未配置时为Nonepem_root_certs标注了#[dynamic(default)]未配置时默认得到空列表注释中反复强调只要客户端使用bootstrap_via_ssh引导服务端这几个证书字段就可以全部省略因为在 SSH 引导阶段服务器会自动生成并分发一套自签证书。证书字段缺省时的行为从服务器监听实现看即使不配置任何证书文件TLS 监听也能启动。原因在于spawn_tls_listener中使用了缺省回退逻辑见 wezterm-mux-server/src/ossl.rslet cert_file tls_server .pem_cert .clone() .unwrap_or_else(|| PKI.server_pem()); ... let key_file tls_server .pem_private_key .clone() .unwrap_or_else(|| PKI.server_pem());也就是说当pem_cert/pem_private_key未配置时服务器会回退使用内置 PKI 自动生成的服务器证书PKI.server_pem()。这意味着最简服务器配置只需要bind_address一个字段即可启动。服务端监听spawn_listener 与 ossl 实现TLS 服务器监听并不是 GUI 进程的职责而是由wezterm-mux-server即wezterm-mux-server二进制在服务器模式下启动。仓库 wezterm-mux-server/src/main.rs 中的spawn_listener函数遍历config.tls_servers为每个端点启动一个 TLS 监听线程pub fn spawn_listener() - anyhow::Result() { let config configuration(); for unix_dom in config.unix_domains { ... } for tls_server in config.tls_servers { ossl::spawn_tls_listener(tls_server)?; } Ok(()) }每个tls_server对应的spawn_tls_listener见 wezterm-mux-server/src/ossl.rs完整流程如下初始化 OpenSSL使用SslAcceptor::mozilla_modern(SslMethod::tls())构建 Mozilla Modern 级别的 TLS 配置现代浏览器同款安全基线加载服务端证书优先使用pem_cert缺省回退到内置 PKI 证书若配置了pem_ca通过set_certificate_chain_file设置证书链加载私钥优先使用pem_private_key缺省回退到内置 PKI遍历pem_root_certs目录条目递归读取其中的 PEM 文件文件条目直接读取逐个加入证书信任存储cert store将内置 CA 证书也加入信任存储并调用set_verify(SslVerifyMode::PEER | SslVerifyMode::FAIL_IF_NO_PEER_CERT)—— 强制双向验证客户端必须持有受信任 CA 签发的证书才能建立连接TcpListener::bind(tls_server.bind_address)绑定监听地址随后在线程中运行net_listener.run()。这里的第 7 步是安全模型的关键TLS 域并不只是加密传输还通过FAIL_IF_NO_PEER_CERT强制客户端出示证书实现双向认证防止未授权客户端接入多路复用服务器。配置服务端与启动服务器1. 编写服务端配置在服务器的~/.wezterm.lua中配置tls_servers。最简配置只需监听地址config.tls_servers { { bind_address server.hostname:8080, }, }由于缺省会回退到内置自动生成的证书这个配置即可直接启动。若希望使用自有 CA 体系例如客户端不通过 SSH 引导、直接使用预共享证书则补全证书字段config.tls_servers { { bind_address 0.0.0.0:8080, pem_private_key /etc/wezterm/server-key.pem, pem_cert /etc/wezterm/server-cert.pem, pem_ca /etc/wezterm/ca-chain.pem, pem_root_certs { /etc/wezterm/extra-ca }, }, }2. 启动 wezterm-mux-serverTLS 监听由 wezterm 的服务器端二进制承载。在服务器上运行$ wezterm-mux-server --daemonize--daemonize使服务器进入守护进程模式相关实现可参考 wezterm-mux-server/src/daemonize.rs。服务器启动后即会读取配置并调用spawn_listener日志中会打印listening with TLS on bind_address见 wezterm-mux-server/src/ossl.rs说明 TLS 监听器已就绪。配置客户端tls_clients 与 bootstrap_via_ssh服务端就绪后需要在客户端本地机器的~/.wezterm.lua中配置tls_clients才能连接。相关章节详见仓库 docs/multiplexing.md 中的 TLS Domains 部分。方式一通过 SSH 引导推荐自版本20200202-180558-2489abf9起wezterm 支持先 SSH、后 TLS的引导机制客户端先通过 SSH 连接远端主机、启动远端多路复用服务器并安全地获取服务器自动生成的证书引导完成后后续通信全部切换到 TLS 加密的 TCP 连接。配置如下config.tls_clients { { -- 该会话的别名之后用 wezterm connect server.name 连接它 name server.name, -- 远端主机的 host:port remote_address server.hostname:8080, -- 值为 userhost:port接受与 wezterm ssh 子命令相同的语法 bootstrap_via_ssh server.hostname, }, }bootstrap_via_ssh在源码 config/src/tls.rs 中注释为使用 ssh 连接、启动服务器并获取证书其值会通过ssh_parameters()解析为SshParameters同 config/src/tls.rs与wezterm ssh的语法保持一致。此时服务端可以完全省略证书字段因为引导阶段会自动生成并分发证书。这也是上文反复强调使用 bootstrap_via_ssh 时服务端证书字段可省略的原因。方式二不使用 SSH 引导直接预共享证书若不想走 SSH 引导客户端需要与服务端共享同一套 CA并显式配置自己的证书与信任链config.tls_clients { { name server.name, remote_address server.hostname:8080, -- 客户端自身的 x509 PEM 私钥 / 证书 pem_private_key /path/to/client-key.pem, pem_cert /path/to/client-cert.pem, -- 用于验证服务器证书的 CA 链 pem_ca /path/to/ca-chain.pem, }, }这是因为服务器端强制了SslVerifyMode::PEER | SslVerifyMode::FAIL_IF_NO_PEER_CERT双向认证客户端必须持有被服务端信任的证书。客户端其他可选字段TlsDomainClient还提供若干可选配置见 config/src/tls.rs可用于调优连接行为expected_cn期望匹配服务器证书 CN 的 hostname默认取remote_address的 hostname 部分一般无需覆盖accept_invalid_hostnames是否跳过证书 hostname 校验默认为false。源码注释明确指出该选项仅供排障使用不应在受控环境之外使用因为它会削弱 TLS 信道的安全性connect_automatically是否在启动时自动连接该域read_timeout/write_timeout读写超时local_echo_threshold_ms预测性本地回显的往返延迟阈值仅在multiplexing WezTerm时生效remote_wezterm_path远端 wezterm 二进制路径overlay_lag_indicator等待响应时是否显示滞后指示。连接与断线重连客户端配置完成后在本地执行$ wezterm connect server.name连接过程如下参见 docs/multiplexing.md客户端解析name对应的tls_clients条目若配置了bootstrap_via_ssh先建立 SSH 连接在远端启动 wezterm 多路复用服务器并通过 SSH 通道安全地获取 TLS 证书连接窗口中会显示进度并可能提示你进行 SSH 认证引导完成后客户端自动切换到 TLS 加密的 TCP 连接remote_address指向的地址后续多路复用流量全部在 TLS 信道中传输连接建立后客户端与服务器之间保持多路复用会话你可以把远端窗口、标签页附着到本地原生 UI 上正常使用鼠标、剪贴板与滚动缓冲区等终端特性断线自动恢复一旦连接因网络中断而断开wezterm 会自动使用引导阶段获取的证书重新发起 TLS 连接并恢复你中断前的远端终端会话无需手动重连。若未配置connect_automatically每次手动wezterm connect server.name即可随时接入或恢复会话。安全模型小结综合文档与源码TLS 域的安全模型可以归纳为三点传输加密使用 OpenSSLMozilla Modern 配置建立 TLS 1.2/1.3 级别的加密 TCP 信道双向证书认证服务器通过FAIL_IF_NO_PEER_CERT强制要求客户端出示由受信任 CA 签发的证书未授权客户端无法接入引导即信任通过bootstrap_via_ssh引导时证书的分发发生在已认证的 SSH 信道内规避了第一次连接时的信任问题这也是推荐在公网场景使用 TLS 域而不是直接暴露 Unix 域的核心原因。相关配置的完整字段定义可继续查阅 docs/config/lua/TlsDomainServer.md 与 docs/config/lua/TlsDomainClient.mdTLS 域在整套多路复用体系中的位置可参见 docs/multiplexing.md。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考