概念
本页解释 Signal Lab 所依据的理念，以便更轻松地阅读文档的其余部分。每一节都链接到详细讲述该主题的页面。
界面与实验
Signal Lab 有两种工作方式，您两种都会用到。
- 界面是您当下手动工作的工具：发送这条消息、监听那个端口、启动这个模拟器、看看代理里有什么。您尝试、观察、改点什么，然后再试。每种协议和工具都有一个界面；参见窗口。
- 实验是您构建一次、反复运行且每次方式都相同的流程：发送请求、等待回复、检查它、继续或分支。每次运行都会逐步报告并保存。参见实验。
两者在多个地方交汇。在 HTTP 和 OSC 界面上，添加到实验 会把您刚发送的内容变成实验的下一步。在 OSC 监视器和 MQTT 界面上，等待此消息 会把您收到的消息变成等待它的步骤。库中的信号也可以变成步骤——除了以十六进制书写的原始 UDP 字节之外的任何信号。
信号与库
信号是您保存的消息：名称、文件夹、说明它应引发什么的备注，以及它发送的内容——一条 OSC 消息、原始 UDP 字节、一个 HTTP 请求或一次 MQTT 发布。信号库把它们存放在可以嵌套、重命名和拖动的文件夹中。
- 您可以从 OSC、HTTP 和 MQTT 界面保存信号（保存…），在 信号 界面上新建信号，或把检查器捕获的一帧保存为信号（保存为信号），之后它会逐字节重放。
- 您可以从 信号 界面发送，在任何地方用 Ctrl+K 发送，作为实验的一个步骤发送，或在终端中用
signallab fire发送。 - 信号发送的内容与其所属界面完全相同：相同的字节，经由相同的路径，在检查器中以其真实协议显示。
库是数据文件夹中的一个文件 signals.json：纯 JSON，您可以阅读、编辑、复制到另一台机器，或保存在仓库中。它一开始带有一组示例信号，全部指向 127.0.0.1。参见信号。
任务
按下按钮后仍在运行的一切都是任务：OSC 监视器或生成器、代理或 WebSocket 连接、信标或发现监听器、HTTP 负载突发、模拟器、损伤中继、风暴、扫描、实验运行。
- 每个任务在底部面板的任务条中都有一个胶囊标签，显示其编号、类型，并带有停止按钮。侧边栏显示每个界面有多少任务正在运行。
- 顶栏中的 全部停止 会立即停止所有任务。
- 自行结束的任务——完成的一次扫描、通过的一次运行、端口出错的监视器——会留在任务条中，控制台会说明它是如何结束的。
- 您在其他界面上工作时，任务会继续运行。
- 安装更新会先停止所有任务。
在服务器上，任务属于服务器：登录它的每个页面都看到相同的任务，也都能停止它们。
捕获与检查器
每个工具——发送器、监视器、监听器、模拟器、中继、实验运行——都会把它发送或接收的每一帧交给同一个捕获，而检查器在同一条时间线上显示它。
- 捕获在您用 启用捕获 开启之前是关闭的，关闭期间不产生任何开销。无论您在哪个界面，它都会一直开启，直到您关闭它。
- 它最多保留 8192 帧和其中 64 MiB 的字节；最旧的帧会为新帧腾出空间。每帧最多保留 256 KiB 的字节，列表显示其前 1 KiB。
- 暂停视图 会让列表停止移动，以便您阅读；捕获仍在后台继续。
- 运行使用的机密值会在每一帧中被遮蔽。
- 整个捕获都可以导出为
.jsonl或.txt文件，保留每一个字节。
模拟器
模拟器扮演另一端：您的系统所对接的 API、设备或服务。每个模拟器都是一个文档，包含协议、监听的地址，以及规定如何应答的规则：
| 协议 | 模拟什么 |
|---|---|
| HTTP | API：按方法和路径路由，响应按顺序、轮流或随机，带延时和故障 |
| OSC | 按地址和参数应答 OSC 消息的设备 |
| UDP | 按载荷应答数据报的设备 |
| TCP | 在 TCP 连接上按行应答、并带有问候语的设备 |
| MQTT | 把客户端发布的内容路由出去、并像设备一样按规则应答的代理 |
模拟器可以缓慢应答、出错、关闭连接、发送格式错误的正文，或按计划停机。每次交互都会被计数、列在其界面上，并为检查器捕获。
您可以从 模拟器 界面启动模拟器，在那里它作为任务运行；也可以从实验的 模拟器 节点启动，在那里它为整个运行应答；或使用 signallab emulate。模拟器库是数据文件夹中的 emulators.json。它一开始每种各有一个模拟器，全部位于 127.0.0.1：
| 模拟器 | 监听于 | 作用 |
|---|---|---|
| 演示 API | 127.0.0.1:8080（HTTP） | 一次健康检查、按 id 取用户、创建、慢速应答，以及一条失败两次后才成功的路由 |
| 演示 OSC 设备 | 127.0.0.1:9100（OSC） | 用 /pong 和计数应答 /ping，用 /ack 确认 /fader/…，对 /cue/… 不作任何回应 |
| 演示 UDP 设备 | 127.0.0.1:7100（UDP） | 用 PONG 和计数应答 PING，用收到的字节数应答其他任何内容 |
| 演示 TCP 设备 | 127.0.0.1:7200（TCP） | 类似投影机的按行协议：用 READY 问候，报告和切换电源，收到 QUIT 时说 BYE 并挂断 |
| 演示 MQTT 代理 | 127.0.0.1:1883（MQTT） | 保留的 lab/status，以及一盏灯：发布到 lab/<name>/set 的 ON 或 OFF 会在 lab/<name>/state 上得到应答 |
参见模拟器。
损伤中继
损伤中继位于客户端与其目标之间。您把客户端指向中继的监听地址，而不是真实目标；中继双向转发，并按配置文件劣化经过的内容：
- 在 UDP 上，每个数据报都有各自的命运：延迟和抖动、丢包和突发丢包、重复、损坏、乱序、带宽限制，或者完全不通（离线）；
- 在 TCP 上，每条连接都会与一条自己的、通往目标的连接相接，两个方向的流都会被延迟、限制带宽、重置，或保持半开。
预设一键设置一个配置文件，从有线到卫星链路。更改会在中继运行期间生效，而不会释放其端口。每个决定都从种子中抽取，因此相同的流量会再次遇到相同的命运。
在 网络损伤 界面上，中继作为任务运行。在实验中，网络损伤 节点会为本次运行打开一个中继，更改损伤 则在运行中途切换其配置文件。参见网络损伤和故障。
实验
节点与连线
实验是由连线连接的节点构成的图。每个节点是一个步骤：它发送某些内容、等待某些内容、检查一个值、提取一个值、改变流程，或建立本次运行——模拟器、损伤中继。每个实验都恰好有一个 开始 和一个 结束，最多容纳 64 个节点。编辑器中打开的实验会随您的编辑而保存。参见节点。
输出
连线从节点的输出连接到另一个节点的输入。大多数节点只有一个输出；其他节点会在多个之间选择：分支用 是 和 否，等待用 已匹配 和 超时，循环用 循环体、完成 和 上限，并行分支用 分支 1 和 分支 2。
一个输出可以有多条连线：每条都作为自己的分支并行运行，而 汇合分支 会等待所有汇入它的连线。只有 循环 的主体可以回连；其他任何环都是错误。参见流程。
参数与配置文件
参数是有名称的值——主机、端口、用户名——在 参数 下写一次，即可在任何字段中用 {{name}} 使用。配置文件会一次更改若干参数：一个用于笔记本电脑，一个用于舞台，一个用于场馆。您可以选择运行使用的配置文件，或用 自定义运行… 为单次运行指定某个配置文件、其他值或种子，而不更改实验。一个实验最多容纳 64 个参数和 32 个配置文件。参见数据。
模板
节点的大多数文本字段都是模板：带双花括号表达式的纯文本，在步骤运行时填充。
{{host}}——一个参数，或运行中早先设置的变量，例如 提取值 节点从响应中取得的值，或等待收到的回复（{{reply.args[0]}}）。{{secret.API_TOKEN}}——一个机密。{{run.id}}、{{run.seed}}、{{now}}、{{now.iso}}、{{counter}}——本次运行和当下时刻。{{uuid}}、{{random_int(1, 10)}}、{{random_float(0, 1, 2)}}、{{pick("a", "b")}}——生成的值。
只有引擎会填充模板，因此一个字段在运行中、在编辑器的预览中以及在 立即发送 中含义相同。未知名称是错误，绝不会变成空字符串。参见数据。
机密
机密是实验使用但从不存储的值——令牌、密码。实验只保存它的名称；字段用 {{secret.NAME}} 使用它；运行报告的每一段文本、每个步骤、报告以及每一帧检查器内容，都显示为已遮蔽。任何命令都不会把机密的值交还出来。
值存放的位置取决于 Signal Lab 的运行方式：
- Windows 上的桌面应用把它们保存在 Windows 凭据管理器中。您在 参数 → 机密 下设置它们。
- Linux 上的桌面应用没有可保存它们的凭据存储，因此那里使用机密的实验需从命令行或服务器运行。
- 服务器以只读方式从其环境（
SIGNALLAB_SECRET_<NAME>）或机密文件夹中每个名称对应的文件（默认为/run/secrets/signallab/<NAME>）读取它们；无法从浏览器设置。 - 命令行像服务器一样读取它们，或在要求时从系统的凭据存储读取。参见命令行。
种子
每次运行都有一个种子，这个数字决定其中所有随机内容：生成的值、重复的抖动、模拟器随机的响应选择、损伤中继的每个决定。相同的种子和相同的流量会得到相同的运行。每次运行都会抽取一个新种子，除非实验固定了种子——运行时间线中的 固定 会固定上一次运行的种子，参数 下的 种子 则设置一个种子。
运行与报告
运行从 开始 开始，沿着连线前进，在没有步骤失败的情况下到达 结束 时通过。如果耗时超过 300 秒，它会被停止。每个步骤在开始和结束时都会出现在运行时间线中。
结束的运行，无论通过还是失败，都会在数据文件夹的 runs 文件夹中写入一份报告：实验的名称、种子、使用的配置文件和值、开始和结束的时间、结果及其错误、每个步骤，以及其模拟器和中继统计到的内容。同一个实验的两次运行可以对比。参见运行与报告。
数据文件夹
Signal Lab 保存的一切都是同一个文件夹中的文件：Windows 和 Linux 上都是主文件夹中的 Documents/SignalLab。服务器保留自己的文件夹，由您在启动时选择（Docker 镜像中为 /data）。
| 文件或文件夹 | 保存的内容 |
|---|---|
experiment.json | 编辑器中打开的实验 |
signals.json | 信号库 |
emulators.json | 模拟器库 |
runs/ | 每次运行一份报告 |
exports/ | 从实验对话框导出的实验 |
capture-….jsonl、capture-….txt | 检查器导出 |
这些文件是 JSON，整体写入。如果其中一个无法读取，Signal Lab 会说明是哪个文件以及错在哪里，并保持原样，而不是重新开始。参见文件和文件夹。
桌面应用与服务器
桌面应用和服务器在相同的界面背后运行相同的引擎。不同之处：
| 桌面应用 | 服务器，在浏览器中 | |
|---|---|---|
| 流量从何处发出、监视器在何处监听 | 本机 | 服务器 |
| 数据文件夹 | Documents/SignalLab | 服务器的；将指针悬停在顶栏的 服务器 上即可看到 |
| 机密 | Windows 凭据管理器，在应用中设置；Linux 上没有 | 只读，来自服务器的环境或机密文件 |
| 报告、导出、捕获 | 写入数据文件夹；显示路径 | 由浏览器下载 |
| 登录 | — | 当服务器有访问令牌时，使用它登录 |
| 任务、HTTP 界面的 Cookie 存储 | 本应用的 | 服务器的，由登录它的每个页面共享 |
| 防火墙 | 会出现提示，询问是否允许 Signal Lab（Windows） | Signal Lab 从不更改 |
| 更新 | 在您点击时安装已签名的发布版本 | 随其镜像更新 |
Signal Lab 不会自行做的事
- 只在您操作时才发送，而且只发往您输入的地址。启动应用不会发送任何内容——唯一的例外是桌面应用每天一次的更新检查，可以将其关闭。只有在您发送表单时才会发出反馈。
- 它的示例都留在本机。 初始信号、初始模拟器、新建的模拟器和实验模板都使用
127.0.0.1。您启动的监听器——OSC 监视器、发现监听器、损伤中继——默认为0.0.0.0，即所有网卡，以便其他机器能访问它们；输入127.0.0.1可让其中一个只留在本机。 - 只有在您点击 允许 并确认 Windows 的管理员提示，或运行
signallab firewall allow时，它才会更改防火墙。服务器从不更改其主机的防火墙。 - 没有访问令牌的服务器只监听
127.0.0.1，并拒绝在任何其他地址上启动。 - 它遵守防护上限：一次广播遍历最多覆盖 1024 台主机，一个信标在所有目标上合计每秒最多发送 50,000 个数据包。