远程主机一键安装

功能概述

一键安装功能允许管理员在后台生成安装命令，将其复制到远程服务器上执行，即可自动完成 Agent Service 的部署。整个过程无需手动配置环境变量或编写 Docker 命令。

适用场景

• 在外网或防火墙内的机器上部署 Agent Service（Inbound 反向连接模式）
• 快速扩展宿主机集群
• 替代手动 SSH + Docker 部署流程

如果远程主机需要通过 HTTP/HTTPS 代理访问 Knodo 平台，请先阅读 通过代理安装远程主机，按代理和镜像前缀步骤完成安装。

使用流程

1. 创建宿主机

在 平台管理 → 宿主机管理 中创建一台新的宿主机，连接模式选择"反向连接"（Inbound）。

2. 生成安装命令

1. 在宿主机列表中找到目标主机，点击"连接 Token"按钮
2. 在弹出的对话框中，点击"生成安装命令"
3. 系统会生成一条 curl | bash 格式的安装命令

3. 执行安装命令

将安装命令复制到目标服务器的终端中执行：

安装脚本会自动完成以下操作：

1. 检测操作系统类型（Ubuntu/Debian/CentOS）
2. 安装 Docker（如未安装）
3. 配置 Docker 镜像加速（国内服务器）
4. 收集机器指纹并绑定
5. 拉取 Agent Service 和 Sandbox 镜像
6. 生成配置文件（.env）
7. 启动 Agent Service 容器
8. 验证服务健康状态

4. 验证部署

安装完成后，脚本会显示部署结果。在后台宿主机列表中，该主机的状态应变为"在线"。

安全机制

机器绑定

每条安装命令只能绑定一台物理机器。绑定基于机器指纹（machine-id + hostname 的哈希值）：

• 首次执行：自动绑定当前机器
• 同一机器重复执行：允许（支持重装/升级）
• 不同机器执行：拒绝，需要管理员在后台重置绑定

重置机器绑定

如需将安装命令用于其他机器：

1. 在连接 Token 对话框中点击"重置机器绑定"
2. 将安装命令复制到新机器执行

Token 安全

• 安装命令中的 Token 本身不包含敏感信息
• 敏感配置（WebSocket 地址、API Token 等）在脚本执行时动态获取
• 重新生成安装命令会使旧命令失效

重入与故障恢复

安装脚本支持幂等执行（可重复运行）：

• Docker 已安装则跳过安装步骤
• 容器已运行则先停止再重启
• 配置文件已存在则覆盖更新
• 镜像已拉取则跳过下载

如果安装过程中断（网络故障、磁盘空间不足等），修复问题后重新执行安装命令即可。

部署维护

安装完成后，系统会在目标机器上放置部署脚本：

后续可通过此脚本进行：

• 镜像版本升级
• 容器重启
• 配置更新

权限要求

• 生成安装命令和重置绑定需要平台管理员权限
• 执行安装命令需要目标机器的 root 权限

系统要求

• 操作系统：Ubuntu 24.04.4 LTS
• Docker：安装前请确认远程主机已安装 Docker（version 29.3.0+），并且 docker 服务可正常使用
• CPU：32 核以上，需使用 x86_64 架构并支持 Claude Code 运行所需指令集；至少需要支持并在虚拟化环境中透传 avx，建议支持并透传 avx2、fma、bmi1、bmi2
• 内存：32GB 以上（视同时存活空间数决定，一个空间一个docker容器，一个docker正常使用1~2G，看空间性质，如开发空间、文档空间消耗是不同的）
• 磁盘：SSD，500GB 以上（视组织空间数及空间知识库存储决定）。Knodo 服务默认使用 /opt 目录部署和存储数据，需确保 /opt 所在分区有足够可用空间；同时 Docker 数据目录（通常为 /var/lib/docker）也需要预留足够可用空间，用于保存镜像、容器数据和运行日志
• 磁盘规划：建议将 Docker 数据目录与 Knodo 服务目录放在同一块容量充足的磁盘上，便于统一规划容量，避免服务数据和容器数据分散在不同磁盘后出现单盘空间不足
• 网络：具备对外联通能力，需访问以下服务：
  • Knodo 云端管理平台：https://knodo.vip（443）
  • Knodo 镜像仓库：registry.cn-guangzhou.aliyuncs.com（443，阿里云容器镜像服务默认使用 HTTPS）