混合部署与专属主机
支持混合部署架构，通过专属主机实现计算与数据的灵活分布
混合部署与专属主机
概述
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 安装、镜像拉取、服务启动
详见 远程主机一键安装
分配组织
- 在宿主机操作菜单中选择 组织分配
- 选择需要绑定的组织
- 绑定后该组织的所有沙箱将自动调度到此主机
一台宿主机可分配给多个组织，一个组织同时只绑定一台宿主机。未分配专属主机的组织使用平台默认主机。
数据与资源隔离
组织绑定专属主机后：
- 文件隔离：工作空间文件、知识库、插件等数据存储在专属主机本地
- 计算隔离：沙箱容器运行在专属主机上，不与其他组织共享计算资源
- 网络隔离：仅控制指令和会话数据经过平台，文件内容不离开宿主机
数据迁移
当组织需要从默认主机迁移到专属主机（或反向迁移）时：
- 进入 宿主机管理 → 数据迁移
- 选择组织和目标主机，启动迁移
- 迁移过程中读操作不受影响，系统后台异步拷贝文件
- 迁移完成后自动切换绑定，后续操作透明路由到新主机
运维监控
心跳检测
系统对所有宿主机进行定期心跳检测：
- 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：不会。迁移采用异步拷贝方式，读写操作不受影响，迁移完成后自动切换。