连接更多服务器

您想要用 Komodo 管理的每台服务器都需要安装 Periphery 代理。 Periphery 是一个小型的无状态二进制文件，通过双向 websocket 连接接收来自 Komodo Core 的命令。

连接一台服务器有 3 个步骤：

1. 通过 Komodo Core API / UI 创建接入密钥（onboarding key）。
2. 安装 Periphery 代理到服务器或虚拟机上，并传入接入密钥。
3. 确认连接状态为 OK。

安装外围

您可以将 Periphery 安装为 systemd 管理的进程，将其作为 docker 容器 运行，或者直接通过其他进程管理器运行二进制文件。

Systemd

info

这是运行 Periphery 的推荐且最简单的方法。 它避免了在容器中运行 Periphery 时可能出现的若干复杂问题。 参见此讨论。

Root 安装

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

User 安装

Periphery 也可以安装为运行系统用户服务（systemd user service，针对调用用户）。

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - --user \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

启用 Periphery 服务在重启后自动启动。

sudo systemctl enable periphery

Important

对于 systemctl 用户安装：为确保 periphery 在您的用户注销后保持运行，请务必启用 linger：

sudo loginctl enable-linger $USER

配置文件

配置文件位置取决于 root 安装还是用户安装：

• Root 安装：/etc/komodo/periphery.config.toml
• User 安装：$HOME/.config/komodo/periphery.config.toml

完整示例配置文件在此。

您可以在 script readme 中找到更多信息（并查看脚本）。

info

此脚本可以多次运行而不会出现问题，并且在第一次运行后不会更改现有配置。在 Komodo 版本发布后再次运行它，它将更新外围版本。

tip

对于部署到多台服务器，应使用 Ansible 等工具。 此类设置的示例可以在此处找到：https://github.com/bpbradley/ansible-role-komodo

容器

您可以使用 docker compose 文件：

https://github.com/moghtech/komodo/blob/main/compose/periphery.compose.yaml

二进制文件

1. 从最新的发行版下载外围二进制文件。

2. 创建并编辑您的配置文件，遵循配置示例。

note

有关配置外围的更多信息，请参阅外围配置文档。

3. 确保通过所选的连接方式可以与 Komodo Core 通信。因此需要满足以下之一：

   • Periphery 能够在配置的 core_address 处访问 Komodo Core。
   • Komodo Core 能够在指定端口（默认 8120）访问 Periphery。

4. 安装 docker。请参阅docker 安装文档。

note

确保运行 periphery 的用户在没有 sudo 的情况下可以访问 docker 组。

5. 使用您首选的进程管理器（例如 systemd）启动外围二进制文件。

外围启动命令示例

periphery --config-path /path/to/periphery.config.toml

info

您可以运行 periphery --help 查看手册。

在 docker 中运行 periphery 时，使用 command 传递额外的参数。

command: periphery --config-path /path/in/container/to/periphery.config.base.toml

认证与密钥轮换

Core 和 Periphery 使用自动生成的公钥/私钥对进行认证。无需手动管理密钥。

工作原理

1. 当您在 UI 或 API 中创建接入密钥时，Komodo Core 会生成一对密钥，私钥作为“接入密钥”一次性返回给用户。
2. 当 Periphery 首次使用接入密钥连接时，它会生成自己的密钥对，并仅将公钥发送给 Core。Core 会为每个服务器存储该公钥。
3. 所有后续通信都通过执行 加密握手 并进行验证，确认传输的公钥匹配来完成认证。

初始连接后不再需要接入密钥，并且 Periphery 私钥永远不会离开服务器。

默认密钥位置

组件	安装方式	默认路径
Core	容器	/config/keys/core.key
Periphery	容器	/config/keys/periphery.key
Periphery	Systemd	${root_directory}/keys/periphery.key

密钥也可以在配置中以内联方式指定，而不是作为文件路径。

自动密钥轮换

Komodo 支持自动轮换 Periphery 密钥对。 触发后，已连接的 Periphery 代理会生成新的密钥对，并将公钥发送给 Komodo Core，Core 会更新该服务器期望的公钥。

每个服务器都有一个 auto_rotate_keys 设置（默认值：true），用于控制其是否参与批量 RotateAllServerKeys 操作。 您也可以随时通过 API 或 UI 为单个服务器轮换密钥。

接入密钥选项

接入密钥可重复使用，并支持以下选项：

选项	描述
enabled	启用或禁用该密钥。
expires	过期时间戳（0 = 永不过期）。
tags	使用此密钥创建的服务器所应用的默认标签。
copy_server	用于复制配置的模板服务器。
create_builder	为新服务器自动创建 Builder 资源。
privileged	允许该密钥更新现有服务器上的公钥。

配置

配置也可以作为 YAML 或 JSON 传递。 您可以使用 it-tools 将此 TOML 文件转换为您喜欢的格式：

• YAML: it-tools.tech/toml-to-yaml
• JSON: it-tools.tech/toml-to-json

快速下载到 ./komodo/periphery.config.toml：

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/periphery.config.toml

https://github.com/moghtech/komodo/blob/main/config/periphery.config.toml

传递配置文件

可以将文件路径或目录路径传递给 --config-path（别名：-c）。默认情况下，不使用任何路径，这意味着配置完全通过环境变量加载。

使用目录时，文件条目可以使用 --config-keyword 参数按名称过滤，该参数可以多次传递以添加更多关键字。 这些都是匹配文件名的通配符模式。 只有包含关键字的文件名才会合并，匹配后定义关键字的文件在字段冲突时具有更高的优先级。 默认情况下，唯一关键字是 *config*.*。这匹配 config.toml、periphery.config.yaml 等文件。

当传递多个配置文件时，命令中后面给出的 --config-path 将始终覆盖前面的配置文件。 目录配置文件按名称按字母顺序合并，因此 config_b.toml 将覆盖 config_a.toml。

有两种合并配置文件的方式。 默认行为是完全用覆盖配置中存在的任何字段替换任何基本字段。 因此，如果您在覆盖配置中传递 allowed_ips = []，则最终的 allowed_ips 也将是一个空列表。

--merge-nested-config true 将递归合并配置字段并扩展配置数组字段。

例如，使用 --merge-nested-config true，您可以在基本配置中指定一个允许的 ip，在覆盖配置中指定另一个，它们都将出现在最终配置中。

同样，您可以指定一个基本 Docker / GitHub 帐户对，并使用覆盖配置中的其他帐户对其进行扩展。