混合部署与专属主机

支持混合部署架构，通过专属主机实现计算与数据的灵活分布

混合部署与专属主机

概述

Knodo 平台采用混合部署架构，支持将 AI 对话的执行环境（沙箱）部署在不同位置的宿主机上。平台控制面（Backend）统一管理任务调度和用户交互，而数据面（Agent Service + Sandbox）可以灵活部署在本地机房、云主机或客户自有服务器上。

控制面：平台 Backend 负责用户管理、任务调度、会话管理
数据面：各宿主机上的 Agent Service 负责沙箱容器管理和文件操作

应用场景

数据合规

敏感数据不出客户网络，仅通过安全通道与平台通信。适用于金融、政务等对数据驻留有严格要求的行业。

连接客户本地环境

将专属主机部署在客户网络内，让 AI 沙箱直接访问客户本地资源：

场景	说明
本地 Git 仓库	连接客户自建的 GitLab、Gitea、Gogs 等，克隆和推送代码
内部 API	调用客户内网中的业务系统接口
内部数据库	通过内网直连客户的数据库进行数据查询和分析
内部文件服务	访问 NAS、对象存储等内部文件系统

工作原理：沙箱容器运行在客户网络内，Agent 可以直接访问内网资源，无需额外配置代理或端口转发。

连接本地 Git 仓库

将工作空间的远程仓库指向客户自建的 Git 服务：

在工作空间设置中，找到 Git 远程仓库 配置
填写客户内网 Git 仓库地址（如 http://gitlab.internal.com/group/project.git）
配置访问凭据：
- 用户名 + 密码：适用于基础认证
- Personal Access Token：适用于 GitLab、Gitea 等支持 PAT 的平台
点击 测试连接 确认可访问后保存

网络要求

确保专属主机上的 Agent Service 能访问目标资源：

要求	说明
网络可达	Agent Service 所在服务器需与目标服务在同一内网，或有路由可达
DNS 解析	如使用域名访问，需确保 DNS 可正确解析
防火墙放行	目标服务的端口需对 Agent Service 所在网段放行
凭据配置	各服务的访问令牌、账号密码需正确配置

就近计算

将执行环境部署在靠近数据源的位置，减少传输延迟。适用于需要频繁访问本地数据或与本地系统交互的场景。

弹性扩展

按需增加宿主机节点，水平扩展并发处理能力。适用于用户量增长或需要更多计算资源的场景。

资源隔离

不同组织使用独立的计算和存储资源，互不干扰。适用于多租户环境或对资源独占性有要求的客户。

宿主机连接模式

根据网络环境，宿主机支持两种连接模式：

Outbound 模式

Backend 主动连接宿主机上的 Agent Service，适用于平台可直接访问宿主机的场景（同一内网、VPN 互通等）。

配置简单：填写宿主机地址和 API Token 即可
实时通信：通过 HTTP/WebSocket 双向交互
适合内网部署和云上扩展节点

Inbound 模式（反向连接）

宿主机上的 Agent Service 主动连接平台的 WebSocket 网关，适用于宿主机在外网、防火墙内或客户机房等无法被平台直接访问的场景。

无需开放宿主机端口：由宿主机主动建立出站连接
穿透防火墙：只需宿主机能访问平台地址即可
适合跨网络部署和客户自有服务器场景

管理与配置

添加宿主机

以管理员身份进入 平台管理 → 宿主机管理
点击 添加宿主机
填写信息：
- 名称：宿主机显示名称
- 连接模式：Outbound 或 Inbound
- URL（Outbound 模式）：Agent Service 地址
- API Token（Outbound 模式）：认证令牌
- 外网主机：是否为外网部署（影响镜像拉取策略）
测试连接确认连通后保存

一键部署宿主机

对于 Inbound 模式的宿主机，平台提供一键安装能力（系统要求）：

在宿主机列表中点击"连接 Token"
生成安装命令
在目标服务器上执行安装命令，自动完成 Docker 安装、镜像拉取、服务启动

详见远程主机一键安装

分配组织

在宿主机操作菜单中选择 组织分配
选择需要绑定的组织
绑定后该组织的所有沙箱将自动调度到此主机

一台宿主机可分配给多个组织，一个组织同时只绑定一台宿主机。未分配专属主机的组织使用平台默认主机。

数据与资源隔离

组织绑定专属主机后：

文件隔离：工作空间文件、知识库、插件等数据存储在专属主机本地
计算隔离：沙箱容器运行在专属主机上，不与其他组织共享计算资源
网络隔离：仅控制指令和会话数据经过平台，文件内容不离开宿主机

数据迁移

当组织需要从默认主机迁移到专属主机（或反向迁移）时：

进入 宿主机管理 → 数据迁移
选择组织和目标主机，启动迁移
迁移过程中读操作不受影响，系统后台异步拷贝文件
迁移完成后自动切换绑定，后续操作透明路由到新主机

备份节点

对于专属主机部署场景，建议配置备份节点以保障数据安全和业务连续性。备份节点通过定时同步专属主机的数据目录，在主节点故障时可以快速接管服务。

架构

部署方式

纯数据备份

仅定时同步数据，不在备份节点上运行 Agent Service。适用于只需数据容灾、不需要自动故障切换的场景。

第一步：下载备份脚本

在备份机上执行：

mkdir -p /data/knodo
wget -O /data/knodo/backup.sh https://knodo.vip/scripts/remote-host-backup.sh
chmod +x /data/knodo/backup.sh

第二步：修改配置

编辑 backup.sh，修改前 3 行为专属主机的实际信息：

SOURCE_HOST="<专属主机IP>"    # 替换为专属主机的实际 IP
SOURCE_USER="root"
SOURCE_DIR="/opt/knodo/data"

第三步：配置 SSH 免密

ssh-keygen -t ed25519 -N ''
ssh-copy-id root@<专属主机IP>

第四步：首次同步

# 预览同步内容
/data/knodo/backup.sh dry-run

# 后台执行首次同步（推荐，避免 SSH 断开影响）
/data/knodo/backup.sh -d

第五步：安装定时任务

/data/knodo/backup.sh install

安装后每 30 分钟自动同步。

热备节点

在数据备份的基础上，备份节点同时部署 Agent Service 并连接平台。适用于需要快速接管、缩短故障恢复时间的场景。

按纯数据备份方式配置数据同步
在备份节点上安装 Agent Service（Inbound 模式连接平台），详见远程主机一键安装
备份节点不分配给任何组织，作为备用宿主机

故障恢复

当专属主机不可用时：

确认故障：在平台管理中确认专属主机状态为离线
切换组织绑定：将组织从故障主机重新分配到备份节点（或平台默认主机）
恢复数据：如备份节点已同步最新数据，工作空间可直接使用；否则需等待同步完成
恢复主节点：修复后重新部署 Agent Service，通过数据迁移切回

注意事项

rsync 同步期间会短暂占用网络带宽，建议在业务低峰期安排首次全量同步
备份节点的磁盘空间应大于或等于专属主机的数据目录
备份脚本下载地址：https://knodo.vip/scripts/remote-host-backup.sh

运维监控

心跳检测

系统对所有宿主机进行定期心跳检测：

Outbound 模式：通过 HTTP 健康检查
Inbound 模式：通过 WebSocket 心跳帧
连续失败超过阈值后自动标记为离线

运行指标

心跳响应中包含宿主机运行状态：

CPU / 内存 / 磁盘使用率
运行中的容器数量

管理员可在宿主机列表中直观查看各节点状态，及时发现异常。

常见问题

Q：沙箱能访问客户内网的任意服务吗？

A：沙箱容器与 Agent Service 在同一 Docker 网络内，默认可访问 Agent Service 能访问的所有网络资源。如需限制，可通过 Docker 网络策略或防火墙规则进行管控。

Q：Git 仓库地址需要是内网 IP 还是域名？

A：都可以。只要 Agent Service 所在主机能解析和访问即可。

Q：如何排查连接失败？

A：1) 确认专属主机状态为在线；2) 在宿主机上手动测试目标地址的连通性（如 curl 或 ping）；3) 检查防火墙和 DNS 配置。

Q：一台宿主机能分配给多少个组织？

A：不设上限，但建议根据主机硬件资源合理规划，避免资源争抢。

Q：数据迁移期间服务会中断吗？

A：不会。迁移采用异步拷贝方式，读写操作不受影响，迁移完成后自动切换。