概述#

本指南概述了在各种目标平台上部署完整 Tokkio 工作流程的过程。Tokkio 工作流程设置包含多个组件，成功的部署需要多个协同工作的配置。在本节中，我们将引导您了解设置中涉及的组件、部署脚本的构建模块以及使用部署脚本启动功能性 Tokkio 环境的工作流程。

组件#

请花一点时间阅读下图。此图详细说明了构成典型 Tokkio 工作流程部署的组件的简化视图。

以下是 Tokkio 运行所需的核心组件。但是，根据我们选择的目标环境（例如 AWS 或裸金属），我们可能需要一些额外的组件才能使端到端管道工作。例如，在 AWS 上部署 Tokkio 时，我们必须设置应用程序负载均衡器，以便以安全的方式访问 Tokkio 后端。当我们使用裸金属机器部署 Tokkio 时，则不需要此应用程序负载均衡器。

客户端#

最终用户设备（如手机或笔记本电脑）上的浏览器应用程序，我们在此应用程序上与应用程序进行交互。

Tokkio 前端#

一个 Web 应用程序前端，包含与 Tokkio 后端交互的必要组件。有关 Tokkio 前端的更多详细信息，请参见前端部分。

Tokkio 后端#

Tokkio 后端作为 Helm Chart 部署在 Kubernetes 环境中。除了 Kubernetes 之外，后端机器还包含以下软件堆栈。

媒体中继服务#

此组件负责在客户端浏览器和 Tokkio 后端之间中继媒体。特别是当客户端浏览器和 Tokkio 后端无法直接连接时，它们会将数据发送到诸如 TURN 服务器之类的实体，然后该实体将数据中继到另一台设备。即使直接连接由于诸如它们位于 NAT 或防火墙之后等原因而被阻止，此过程也可确保通信能够发生。截至今天，Tokkio 部署支持以下选项。

COTURN 服务
反向代理服务
Twilio

LLM RAG / NVIDIA NIM#

此组件帮助 Tokkio 后端获取用户查询的响应。虽然 NVIDIA NIM 在每个默认安装中都已配置，但您可以轻松地将其替换为您自己的 LLM RAG。

设置这些组件并在它们之间建立适当的连接可能非常复杂，并且需要一些时间和专业知识。这些部署脚本有助于简化初始设置，并让您快速启动 Tokkio 工作流程以进行交互。目标机器上的所有必要组件都将被设置。

与部署脚本交互#

脚本的典型用法将像任何其他 bash 脚本一样。这遵循 <命令子命令选项> 样式。我们将在后续章节中介绍其他子命令。

安装子命令的示例用法

./envbuild.sh install --component all

构建模块#

使用部署脚本涉及处理以下组件

控制器实例
配置文件
环境变量文件

控制器实例#

指将从中启动部署脚本的机器。任何运行 Ubuntu OS 版本 22.04 或 24.04 OS 的机器都可以用作控制器实例。至少，此机器应具有互联网连接并且应运行 bash 脚本。

为了确保成功执行，这些部署脚本依赖于特定的软件组件。如果实例上尚不存在，脚本将尝试安装或升级以下内容

所需软件#

带有 tfswitch 的 Terraform

管理多个 Terraform 版本
自动切换到每个项目的相应版本

Python

脚本中使用的核心编程语言

Python 模块

安装在虚拟环境中
将项目依赖项与系统范围的软件包隔离

jq

命令行 JSON 处理器
用于解析和操作 JSON 数据

yq

jq 的 YAML 对等物
高效处理 YAML 文件

部署脚本旨在检查这些依赖项并在必要时安装它们，从而确保平稳的执行环境。

配置文件#

此文件捕获有关目标环境的所有信息，例如目标平台、要使用的 Helm Chart 版本、设置 Tokkio UI 时要使用的 UI 参数等。默认情况下，脚本期望在启动脚本的当前目录中有一个 config.yml 文件。如果您的配置文件具有不同的名称，则可以在安装和卸载子命令期间使用 -f 或 --config-file 选项提供它。

虽然您可以在 config.yml 中调整大量参数，但我们建议您从我们随脚本提供的示例配置模板的副本开始。查找每个支持的目标环境的 config-template-examples 文件夹。例如，azure/config-template-examples。

环境变量文件#

此文件有助于抽象出在安装时提供的重用参数和密钥类值。因此，在运行 envbuild.sh 命令之前，您需要确保将这些环境变量提供给当前的 bash shell。这可以通过使用 source <my-env-file.env> 命令来完成。

将这些值与配置文件分离的主要原因是允许对配置文件进行版本控制，并以不同的方法维护密钥类值。

部署脚本的工作流程#

典型的 Workflow 涉及以下阶段，如下图所示

准备
设置
维护
拆卸

准备#

准备工作包括确定要用于控制器实例的机器。根据您选择的目标平台（AWS、裸金属等），从提供的示例中复制示例模板和环境文件，并根据您的需要进行修改。

例如，如果您选择使用裸金属示例，您最终可能会得到以下文件。

dev1-baremetal-configs.yml
dev1-baremetal-env-vars.env

注意

文件名是完全任意的。但为简单起见，在以下章节中显示示例时，我们将使用这些示例文件名。

设置#

在此阶段，您将把密钥值加载到 bash 环境中，并使用上面创建的配置文件启动部署脚本。

加载环境变量

$ source ./dev1-baremetal-env-vars.env

启动部署脚本

$ ./envbuild.sh install --component all -f dev1-baremetal-configs.yml

在本脚本结束时，您将看到结果摘要和将来需要的关键 URL。这是一个示例输出

<..logs trimmed for brevity>
<..logs trimmed for brevity>
<..logs trimmed for brevity>
access_urls:
 app:
   app: http://10.62.172.41:80/
   grafana: http://10.62.172.41:32300/login
   kibana: http://10.62.172.41:31565/app/kibana
   prometheus: http://10.62.172.41:30090/graph
 turn: {}
ssh_command:
 app:
   master: ssh -i /home/metroadmin/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null horde@10.62.172.41
 turn:
   master: ssh -i /home/metroadmin/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null horde@10.62.172.41

以下是输出的快速浏览及其含义。这与其他目标平台类似。

输出描述#
access_urls -> app -> app	Tokkio UI 可以从这里访问。
access_urls -> app -> grafana	作为平台服务一部分安装的 Grafana 仪表板。可用于监视 GPU 使用率等指标。
access_urls -> app -> kibana	作为平台服务一部分安装的 Kibana 仪表板。可用于从 Kubernetes 访问应用程序组件日志。
access_urls -> app -> prometheus	作为平台服务一部分安装的 Prometheus 服务。
ssh_command -> app -> master	预填充的 SSH 命令，可用于访问您的应用程序实例
ssh_command -> turn -> master	预填充的 SSH 命令，可用于访问您的 TURN 服务器实例。在裸金属设置的情况下，TURN 服务器安装在同一应用程序实例上，因此它将是相同的。

维护#

这是应用程序自定义发生的阶段。当您自定义应用程序时，您可以使用部署脚本通过使用适当的子命令将其更新到目标环境中。以下是您在此过程中将执行的步骤

更新配置文件
应用目标环境中的更改

例如，如果您的配置更改是针对 Tokkio 后端的，则可以运行以下子命令以应用这些更改。

./envbuild.sh install --component app -f dev1-baremetal-configs.yml

请注意，--component 开关现在指的是 app 而不是 all。根据您希望应用哪些配置模板的更改，您可以从 --component 的不同选项中进行选择，例如 all、infra、platform、app 。

此命令的输出将与我们在设置阶段看到的类似。

在维护阶段，您可能想要查看给定部署的结果摘要。在这种情况下，您可以使用 info 子命令，方法是提供环境变量和正确的配置文件，如下所示。

加载环境变量

$ source ./dev1-baremetal-env-vars.env

启动 info 子命令

./envbuild.sh info -f dev1-baremetal-configs.yml

此命令的输出格式将与我们在设置阶段讨论的格式相同。例如

access_urls:
 app:
   app: http://10.62.172.41:80/
   grafana: http://10.62.172.41:32300/login
   kibana: http://10.62.172.41:31565/app/kibana
   prometheus: http://10.62.172.41:30090/graph
 turn: {}
ssh_command:
 app:
   master: ssh -i /home/metroadmin/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null horde@10.62.172.41
 turn:
   master: ssh -i /home/metroadmin/.ssh/id_rsa -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null horde@10.62.172.41

拆卸#

当需要从该设置中卸载某些组件或整个设置本身时，您可以使用带有 --component 的适当选项的 uninstall 子命令。

例如，如果您选择仅卸载应用程序组件，则可以运行以下命令

./envbuild.sh uninstall --component app -f dev1-baremetal-configs.yml

此外，如果您选择卸载整个设置，则可以运行以下组合的命令。请注意 --component 选项的值为 all，并且在使用此选项时要小心，因为这基本上会逆转您从开始以来所做的所有步骤。

./envbuild.sh uninstall --component all -f dev1-baremetal-configs.yml

有关更多详细信息，您可以运行带有 --help 选项的命令，如下所示。

$ ./envbuild.sh --help
Usage: ./envbuild.sh (-v|--version)
  or: ./envbuild.sh (-h|--help)
  or: ./envbuild.sh (install/uninstall) (-c|--component <component>) [options]
  or: ./envbuild.sh (info) [options]

install/uninstall components:
-c, --component        one or more of all/infra/platform/app, pass arg multiple times for more than one

install/uninstall options:
-f, --config-file      path to file containing config overrides, defaults to config.yml
-i, --skip-infra       skip install/uninstall of infra component
-p, --skip-platform    skip install/uninstall of platform component
-a, --skip-app         skip install/uninstall of app component
-d, --dry-run          don't make any changes, instead, try to predict some of the changes that may occur
-h, --help             provide usage information

info options:
-f, --config-file      path to file containing config overrides, defaults to config.yml
-h, --help             provide usage information

部署选项#

目前，我们有适用于以下环境的部署脚本

注意

虽然这些脚本可以作为初始设置（例如开发环境）的参考，但我们建议您在启动用于扩展和安全性的类似生产环境之前，彻底审查这些脚本。