v2.0.0 – 2026 年 3 月

Komodo v2 是一个重大版本，包含显著的架构变更和新功能。

更新日志

• Docker Swarm 支持：管理 Swarm 集群、节点、服务、堆栈、配置（configs）和密钥（secrets）。
• 出站 Periphery（Outbound periphery）：Periphery 现在可以主动发起与 Komodo Core 的连接。
• PKI 身份认证：Core 和 Periphery 现在使用自动生成的密钥对和自动轮换进行认证。Passkey 已被弃用。
• Onboarding keys（接入密钥）：通过可复用的密钥简化服务器接入流程。
• 改进的终端：终端仪表板、km ssh，以及改进的动作（Action）脚本能力。
• 改进自动更新：使用更好的机制，基于镜像 digest 处理自动更新。
• 全新 UI：改进的外观，对比度更高，UI 原语更优。
• Passkey / TOTP 2FA：内置的双因素认证，用于用户名 / 密码登录。
• 多登录关联（Multi-login Linking）：用户现在可以将多个登录提供商（Local、OIDC、Github 等）关联到自己的账户。
• 完整 OpenAPI 文档：交互式 API 文档 现已可用。

🚨 破坏性变更

• Debian Bullseye EOL：Bullseye 在 2024 年停止接收安全更新，并计划进入 EOL。二进制现在基于 Debian Bookworm 构建，其使用 openssl v3，Periphery 在运行 openssl v1（包括 Debian Bullseye / Ubuntu 20.04 及更早版本）的系统上可能存在兼容性问题。如有需要，你仍可以自行为这些系统编译 Periphery（或使用容器化的 Periphery），但官方发行版将使用更安全、更现代的选项。

升级到 Komodo v2

Komodo v2 在 Komodo Core 与运行在你服务器上的 Periphery 代理之间引入了一种新的连接和认证方式。在 此处了解 Komodo v2。

它在很大程度上与 Komodo v1 配置向后兼容，用户可以就地从 v1 升级，按照以下步骤操作即可。

note

从 v2 开始，Komodo 将不再发布带有 latest 标签的镜像，转而使用 Semver（2、2.0、2.0.0）。 这可以防止使用自动更新器时出现非预期的主版本升级。使用 :2 即可跟上 未来所有的 Komodo v2 发布版本。

1. 将 Core 和 Periphery 升级到 v2

第一步是将 Core 和 Periphery 都升级到 v2 版本，并 进行少量配置变更。

升级 Core

在 Komodo Core 的 compose 服务中，将镜像更新为 :2 标签，并 新增对 /config/keys 的挂载。

services:
  core:
    image: ghcr.io/moghtech/komodo-core:2
    init: true # 无论哪个版本都应添加此项
    volumes:
      - keys:/config/keys
      - (...unchanged)
    (...unchanged)

volumes:
  keys:
  (...unchanged)

warning

确保 Komodo Core 服务 以及 所有 Periphery 服务 / 容器都包含 init: true， 如上所示。否则可能导致僵尸进程累积， 而早期发布的示例 compose 文件中并未包含它。

升级 Periphery：容器

如果你在容器中运行 Komodo Periphery，你同样需要镜像的 :2 标签， 密钥将默认存储在 /config/keys。

services:
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:2
    init: true # 无论哪个版本都应添加此项
    volumes:
      - keys:/config/keys
      - (...unchanged)
    (...unchanged)

volumes:
  keys:
  (...unchanged)

升级 Periphery：Systemd

Systemd 版 Periphery 用户只需更新其 Periphery 二进制版本。密钥将存储在你的 root_directory（默认：/etc/komodo/keys）。

在 Core 和 Periphery 都运行起来后，此时一切应该已经正常工作。

2a. 迁移到公钥认证

如果你想 反转代理连接方向，请跳过此步骤，前往 2b。

如果你想保持 Core 到 Periphery 的连接方向，可以通过 从 passkey 认证迁移到公钥认证 来提升安全性。

进入 Settings 页面，在顶部你会看到 Core 公钥（以 MCow... 开头）。 复制此密钥，并 使用更新后的配置重新部署 Periphery 代理：

## 接受允许 Core 连接的公钥。
## Periphery 通过 noise 握手获取 Core 公钥知识。
## 如果既未提供这些也未提供 passkey，入站连接将不会通过认证。
## 直接接受 Spki base64 DER 和 PEM 文件。使用 `file:/path/to/core.pub` 从文件加载。
## Env: PERIPHERY_CORE_PUBLIC_KEYS
## 可选，无默认值。
core_public_keys = "<YOUR_CORE_PUBLIC_KEY>"

确认连接仍然正常后，你可以移除 Core 和 Periphery 任何遗留的 passkey 配置，因为已不再需要。

2b. 反转代理连接

Periphery 代理现在能够建立到 Komodo Core 的出站连接。 升级到 Komodo v2 后，你可以按照以下步骤迁移到使用公钥认证的出站连接。 注意：你必须是 Komodo 上的管理员（Admin）用户。

1. （仅 Periphery 容器。）确保自动生成的私钥通过挂载到 Periphery 容器的 /config/keys 而持久化，如上所述。
2. 进入 Settings / Onboarding，创建一个新的 onboarding key（接入密钥）。保存以备后用。
3. 在新的 Onboarding Key 上启用 privileged mode（特权模式）。
4. 使用更新后的配置重新部署 Periphery 代理：

## Komodo Core 的地址。必须可从该主机访问。
## 如果提供，Periphery 将以出站模式运行。
## Env: PERIPHERY_CORE_ADDRESS
## 默认值：None
core_address = "<YOUR_KOMODO_CORE_ADDRESS>" # 示例：demo.komo.do，ws://localhost:9120

## 该 Periphery 代理应当 "以什么身份连接" 的服务器。
## Systemd periphery 可通过设置 `connect_as = "$(hostname)"` 使用系统主机名。
## Env: PERIPHERY_CONNECT_AS
## 默认值：None
connect_as = "<SERVER_NAME>"

## 在服务器设置中创建 Onboarding Keys。
## 如果以已存在的服务器身份连接则不需要。
## Env: PERIPHERY_ONBOARDING_KEY
onboarding_key = "<YOUR_ONBOARDING_KEY>"

连接后，特权 onboarding key 将允许更新该现有服务器的预期公钥， 从而使 Periphery 代理能够连接。 一般来说，在接入 新 服务器时，不需要特权模式。

3. 修复 Actions 中的 komodo.execute_terminal

info

如果你不知道这是什么，你不需要做任何事。恭喜，你已经完成了。

将 execute_terminal 重命名为 execute_server_terminal。

所以在 v1 的 Action 中：

// 这在 v1 中需要 2 次调用
await komodo.write("CreateTerminal", {
  server: "my-server",
  name: "my-terminal",
  command: "bash",
  recreate: "Always",
});
await komodo.execute_terminal(
  { server: "my-server", terminal: "my-terminal", command: "ls -l" },
  { onLine: (line) => console.log(line) },
);

在 v2 中变为：

// 带有 init 选项的精简终端执行。
await komodo.execute_server_terminal(
  {
    server: "my-server",
    terminal: "my-terminal",
    command: "ls -l",
    init: { command: "bash", recreate: "Always" },
  },
  { onLine: (line) => console.log(line) },
);