混合部署与专属主机
支持混合部署架构，通过专属主机实现计算与数据的灵活分布
混合部署与专属主机
概述
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 安装、镜像拉取、服务启动
详见 远程主机一键安装
分配组织
- 在宿主机操作菜单中选择 组织分配
- 选择需要绑定的组织
- 绑定后该组织的所有沙箱将自动调度到此主机
一台宿主机可分配给多个组织，一个组织同时只绑定一台宿主机。未分配专属主机的组织使用平台默认主机。
资源监控
宿主机列表会展示每台机器的资源摘要，帮助管理员判断当前节点是否还能继续承载任务：
- 资源健康：根据负载、内存和数据盘使用率展示正常、紧张、危险、无数据或已过期
- 负载 / core：展示 1 分钟负载除以逻辑核心数，便于跨机器比较
- 内存：展示使用率和可用内存
- 数据盘：展示主数据盘使用率和剩余空间
- 容器数：展示当前运行的 Sandbox 数量
- 最近心跳：用于判断指标是否新鲜
点击资源摘要可查看趋势图和磁盘明细。历史趋势默认保留 7 天，管理员可在系统配置中关闭历史指标存储，关闭后仍会保留最新资源状态。
数据与资源隔离
组织绑定专属主机后：
- 文件隔离：工作空间文件、知识库、插件等数据存储在专属主机本地
- 计算隔离：沙箱容器运行在专属主机上，不与其他组织共享计算资源
- 网络隔离：仅控制指令和会话数据经过平台，文件内容不离开宿主机
数据迁移
当组织需要从默认主机迁移到专属主机（或反向迁移）时：
- 进入 宿主机管理 → 数据迁移
- 选择组织和目标主机，启动迁移
- 迁移过程中读操作不受影响，系统后台异步拷贝文件
- 迁移完成后自动切换绑定，后续操作透明路由到新主机
备份节点
对于专属主机部署场景，建议配置备份节点以保障数据安全和业务连续性。备份节点通过 rsync 定时同步专属主机的最新数据目录，并使用 Borg 在备份节点本地保留历史快照。默认每 30 分钟同步最新镜像，每 4 小时创建一次历史快照。主节点故障时可以使用最新镜像快速接管；发生误删、误改时可以从历史快照导出或恢复指定目录。
架构
部署方式
纯数据备份
仅定时同步数据，不在备份节点上运行 Agent Service。适用于只需数据容灾、不需要自动故障切换的场景。该方式会保留：
/data/knodo/data：最新数据镜像，用于快速接管/data/knodo/borg-repo：历史快照仓库，用于找回旧版本数据
第一步：下载备份脚本
在备份机上执行：
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"脚本已内置 Borg 版本选择、sha256 和下载镜像 fallback，会按系统 glibc 自动选择尽可能新的兼容版本。CentOS 7 / glibc 2.17 默认使用 Borg 1.2.9，较新的系统默认使用 Borg 1.4.4。正常情况下优先使用 gh.llkk.cc 镜像源，无需手工下载 Borg，也无需手工配置 GitHub 镜像；如果系统已存在且可运行的 borg 命令会自动跳过安装。需要优先 GitHub 时，可执行 BORG_DOWNLOAD_PREFER=github /data/knodo/backup.sh install。
第三步：配置 SSH 免密
ssh-keygen -t ed25519 -N ''
ssh-copy-id root@<专属主机IP>第四步：一键初始化
/data/knodo/backup.sh installinstall 是可重入命令，重复执行不会覆盖 Borg 仓库口令、不会重置 Borg 仓库、不会重复写入定时任务。它会自动完成：
- 安装 Borg，已安装则跳过
- 初始化 Borg 仓库，已初始化则跳过
- 执行环境检查
- 安装每 30 分钟一次的定时同步任务，已存在则跳过。该任务每次执行 rsync，默认每 4 小时创建一次 Borg 快照
初始化会生成 Borg 仓库口令文件 /data/knodo/.borg-passphrase，必须妥善备份。该文件丢失后，历史快照无法恢复。
默认 Borg 快照使用 lz4 压缩，并通过 nice/ionice 降低 CPU 和 IO 调度优先级。可通过 BORG_SNAPSHOT_INTERVAL_SECONDS、BORG_COMPRESSION、BORG_NICE、BORG_IONICE_CLASS、BORG_IONICE_LEVEL 调整。
第五步：首次同步
# 预览同步内容
/data/knodo/backup.sh dry-run
# 后台执行一次正式同步并创建历史快照（推荐，避免 SSH 断开影响）
/data/knodo/backup.sh -d-d 表示后台执行一次 sync，进度可通过 tail -f /data/knodo/logs/backup-daemon.log 查看。安装后定时任务会每 30 分钟自动同步最新镜像，默认每 4 小时创建一次 Borg 历史快照。
历史查询、导出与恢复
查看备份状态和历史快照：
/data/knodo/backup.sh status
/data/knodo/backup.sh snapshots查找某个文件或目录在哪些快照中存在：
/data/knodo/backup.sh find org/main/workspaces/<workspace-id>/path/to/file从历史快照导出目录，不影响最新镜像：
/data/knodo/backup.sh export <snapshot-id> org/main/workspaces/<workspace-id>
/data/knodo/backup.sh export-tar <snapshot-id> org/main/workspaces/<workspace-id> --to /data/knodo/exports/workspace.tar.gz从历史快照恢复目录到指定目录，不影响最新镜像：
/data/knodo/backup.sh restore-preview <snapshot-id> org/main/workspaces/<workspace-id> --to /data/knodo/restore/<workspace-id>
/data/knodo/backup.sh restore <snapshot-id> org/main/workspaces/<workspace-id> --to /data/knodo/restore/<workspace-id>热备节点
在数据备份的基础上，备份节点同时部署 Agent Service 并连接平台。适用于需要快速接管、缩短故障恢复时间的场景。
- 按纯数据备份方式配置数据同步
- 在备份节点上安装 Agent Service（Inbound 模式连接平台），详见 远程主机一键安装
- 备份节点不分配给任何组织，作为备用宿主机
故障恢复
当专属主机不可用时：
- 确认故障：在平台管理中确认专属主机状态为离线
- 切换组织绑定：将组织从故障主机重新分配到备份节点（或平台默认主机）
- 恢复数据：如备份节点已同步最新数据，工作空间可直接使用；如需要找回历史数据，可先从 Borg 快照导出或恢复指定目录
- 恢复主节点：修复后重新部署 Agent Service，通过数据迁移切回
注意事项
- rsync 同步期间会短暂占用网络带宽，建议在业务低峰期安排首次全量同步
- Borg 快照会扫描本地镜像目录，大量小文件场景下耗时较长；默认通过 4 小时间隔、
lz4、nice和ionice降低持续负载 - 备份节点的磁盘空间应大于专属主机数据目录，需额外预留 Borg 历史快照空间
- Borg 仓库口令文件必须妥善备份，丢失后无法恢复历史快照
- 备份脚本下载地址：
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：不会。迁移采用异步拷贝方式，读写操作不受影响，迁移完成后自动切换。