teleterm

分享您的终端！

概述

当我刚开始学习编程时，我在业余时间做的一件事就是玩 NetHack。特别是，我在 nethack.alt.org 公共服务器上玩游戏，并在 IRC 的 #nethack 上闲逛。这个环境之所以成为一个很好的学习环境，是因为在这个服务器上玩的所有游戏都会自动记录和直播。这使得你既能观看其他人的游戏来获取技巧，也能请其他人查看你的游戏并给出建议。

一段时间后，我们中的一群人意识到这种模式可以用于不仅仅是玩游戏，于是我们建立了一个类似的用于一般用途的终端重播器。这使得我们能够实时看到其他人的开发环境和工作流程，使项目协作变得更加流畅。 teleterm 是尝试重现我在自己的学习过程中非常有帮助的环境，同时解决了一些原始版本存在的问题。

特别是，teleterm 旨在能够完全透明地运行（你在流式传输时甚至不应知道它在运行），你应该能够打开一个窗口在屏幕角落观看其他人的终端，而不会造成干扰。 teleterm 不包括任何用于远程控制本地终端的功能，也不包括任何通信功能（除了终端本身） - 它最好用于已经存在的具有更多功能通信方法的社区。

功能

• 透明地广播您的终端会话，可选地使用 TLS 加密和安全身份验证
• 在网络连接丢失时自动在后台重新连接，而不会中断您正在终端会话中执行的工作
• 记录和回放 ttyrec 文件

安装

如果您已经安装了 rust，则可以通过运行 cargo install teleterm 从源安装 teleterm。否则，我们为几个操作系统提供预构建的包

Arch Linux

Ubuntu/Debian

所有包都已签名，可以使用 minisign 使用公钥 RWTM0AZ5RpROOfAIWx1HvYQ6pw1+FKwN6526UFTKNImP/Hz3ynCFst3r 进行验证。

使用方法

流式传输

您可以通过简单地运行 tt（或 tt stream） 来开始流式传输。它会提示您输入一些关于您想要连接的服务器的信息，并将这些信息存储在您家目录下的配置文件中。（请注意，我没有运行任何公开可访问的服务器，因为我认为它更适合作为为较小的现有社区的工具，因此您需要先运行自己的服务器或找到其他人来托管一个。）

观看

要观看现有流，请运行 tt watch。这将显示当前活跃流的菜单 - 选择一个，它将在您的终端中显示。按 q 返回菜单。

录制

您可以通过运行 tt record 将您的终端会话录制到文件中。这使用的是标准的 ttyrec 文件格式，许多不同的应用程序（包括 tt play）都可以理解。请注意，tt stream 和 tt record 都可以接受一个命令来运行，而不是仅限于shell，因此您可以通过运行 tt stream tt record 来同时广播您的终端并将会话录制到文件中。

回放

您可以使用 tt play 来回放之前录制的 ttyrec 文件。

配置

命令行标志

这些可以通过 tt help 进行文档说明。

环境变量

tt 尊重 RUST_LOG 环境变量来调整日志的详细程度。默认情况下，tt server 在 info 级别显示日志，其余命令在 error 级别显示日志，但您可以通过运行类似 RUST_LOG=tt=info tt stream 的命令来查看更多信息。注意，对于像 tt stream 这样的交互式命令，这可能会造成干扰，但您可以通过重定向 STDERR（因为所有进程输出都写入 tt 的 STDOUT，所有日志输出都写入 tt 的 STDERR）来将输出发送到文件，如下所示： RUST_LOG=tt=info tt stream 2>>stream.log。

配置文件

teleterm 也可选地从配置文件中读取配置。此文件应采用 TOML 格式，并存储在 ~/.config/teleterm/config.toml 或 /etc/teleterm/config.toml 中。如果不存在配置文件，tt stream 和 tt watch 将自动为您创建一个。配置有多个部分

[server]（由 tt server 使用）

• listen_address
  • 服务器监听的本地地址，格式为 HOST:PORT。
  • 默认值：127.0.0.1:4144
• buffer_size
  • 每个连接的缓冲区维护的最大大小，当新客户端连接时发送（以便能够完全重绘当前终端状态）。
  • 默认值：4194304
• read_timeout
  • 等待从客户端接收数据的时间（以秒为单位），如果没有数据接收则断开该客户端的连接。注意，除了在终端输出中发送数据外，客户端还会每30秒发送一个心跳消息以保持连接活跃。
  • 默认值：120
• tls_identity_file
  • 如果指定此选项，服务器将使用TLS加密传入的连接（连接到此服务器的客户端必须启用tls客户端选项）。此选项的值应该是包含TLS私钥以及到受信任根的证书链的文件的路径，格式为PKCS #12。此文件可以使用如下命令从现有的私钥和证书链生成：

    openssl pkcs12 -export -out identity.pfx -inkey key.pem -in cert.pem -certfile chain_certs.pem
    

  • 默认值：未设置（服务器将接受明文TCP连接）
• allowed_login_methods
  • 允许从传入连接中使用的登录方法列表。必须非空。有效的登录方法包括：
    • plain：客户端提供用户名，服务器直接使用。允许模拟，但如果这不是问题，则可以正常使用。
    • recurse_center：客户端通过Recurse Center的OAuth流程进行认证，并从Recurse Center API检索用户名。
  • 默认值：["plain", "recurse_center"]
• uid
  • 如果设置且服务器以root运行，则在绑定端口并读取TLS密钥后，服务器将切换到此用户名或uid。这允许您使用低编号端口或root拥有的TLS密钥，而无需服务器本身以root的身份处理连接请求。
  • 默认值：未设置
• gid
  • 与uid相同，但设置用户的初始组。
  • 默认值：未设置

[oauth.<method>]（由tt server使用）

<method>对应于使用OAuth的登录方法 - 例如，一个部分可能会命名为类似于[oauth.recurse_center]的名称。请注意，OAuth登录方法必须使用https://127.0.0.1:44141作为它们的重定向URL。

• client_id
  • OAuth客户端ID。
• client_secret
  • OAuth客户端密钥。

[client]（由tt stream和tt watch使用）

• auth
  • 要使用的登录方法（必须是服务器已配置为接受的其中一种方法）。
  • 默认值：plain
• username
  • 如果使用plain登录方法，则指定要登录的用户名。
  • 默认值：在本地运行的 tt 进程所使用的本地用户名（从 $USER 环境变量中获取）
• connect_address
  • 连接到的地址，格式为 HOST:PORT。注意，当连接到使用 TLS 的服务器时，HOST 组件必须对应于服务器使用的 TLS 证书上的一个名称。
  • 默认值：127.0.0.1:4144
• tls
  • 是否使用 TLS 连接到服务器。
  • 默认值：false

[command]（由 tt stream 和 tt record 使用）

• buffer_size
  • 要维护的缓冲区最大大小，当连接断开后再连接到服务器时会发送给服务器（以便能够完全重绘当前终端状态）。
  • 默认值：4194304
• command
  • 要执行的命令。
  • 默认值：当前正在运行的 shell（从 $SHELL 环境变量中获取）
• args
  • 传递给 command 的参数列表。
  • 默认值：[]

[ttyrec]（由 tt record 和 tt play 使用）

• filename
  • 保存到或从中读取的 TTYrec 文件名。
  • 默认值：teleterm.ttyrec

故障排除

我试图观看某人，但输出是一团糟！

这种情况有三个主要原因

1. 您的本地终端大小与流式传输的人的终端大小不同。 较小的终端几乎肯定会导致这里出现问题（如果这种情况发生，tt watch 菜单将以红色显示终端大小），但过大的终端偶尔也会引起问题，如果这个人正在运行一个依赖于终端换行行为细节的全屏应用程序。
2. 您的终端类型与流式传输的人的终端类型不兼容。 不同的终端使用不同的转义序列来表示各种行为（如移动光标或清除屏幕），尽管许多这些在终端之间是共享的，但也有很多不是。在这种情况下，您应该切换到使用兼容的终端。请注意，screen 或 tmux 在这种意义上被视为终端，因此一个简单的解决方案通常是始终在 screen 或 tmux 会话中运行 tt，无论是流式传输还是观看（并说服您正在观看的人也这样做）。
3. 您正在观察的人产生了大量终端输出而没有清除屏幕。 终端输出是由一系列从空白终端开始的绘图命令（通过转义序列发出）组成的，这意味着根据输出，可能需要任意大量的数据才能准确重建当前的终端。然而，teleterm 对保存的数据量设置了限制（以避免内存耗尽），因此长时间连续输出而没有屏幕清除可能会导致显示损坏。这可以通过要求流媒体清除屏幕（通过在命令行中运行 reset 或 clear，或者使用他们正在运行的应用程序的重新绘制功能，通常绑定到 ^L 或 ^R）来修复。

贡献

我对贡献非常感兴趣！我在这个存储库的 TODO.md 中有一个待办事项列表，但我也愿意接受任何你认为可以使这个项目更有用的补丁。请给我发邮件，或在 Github 或 Gitlab 上打开一个工单或拉取请求。