通过代理安装远程主机
在需要通过 HTTP/HTTPS 代理访问 Knodo 的环境中安装远程主机
通过代理安装远程主机
适用场景
远程主机不能直接访问 Knodo 平台，需要通过 HTTP/HTTPS 代理出站访问。
该场景请选择 反向连接（Inbound） 模式。平台不需要访问内网主机，专属主机所在网络也不需要开放入站端口。
部署前准备
请先确认以下信息：
| 项目 | 说明 |
|---|---|
| 平台访问地址 | Knodo 平台域名：https://knodo.vip |
| 代理地址 | HTTP/HTTPS 代理地址，例如 http://proxy.example.com:8080 |
| NO_PROXY | 内网域名、内网 IP 段、localhost、127.0.0.1、::1 |
| 镜像仓库前缀 | 内网可访问的镜像仓库前缀，例如 registry.customer.local/knodo |
| 主机权限 | 安装需要 root 或具备 sudo 权限的管理员账号 |
如果使用内网镜像仓库，请确保专属主机可以通过 docker pull 从该仓库拉取 Agent Service 和 Sandbox 的新版本镜像。
代理服务器需要满足以下要求：
- 放行
https://knodo.vip及其子域名。 - 支持 WebSocket 长连接。
- 支持 SSE 流式响应。
第一步：获取安装命令
先参考 远程主机一键安装 创建反向连接（Inbound）模式的远程主机，并生成安装命令。
如果平台管理员已经提供安装命令，可以直接进入下一步。
第二步：在主机上设置临时环境变量
登录专属主机，进入 root shell 或具备 sudo 权限的管理员账号后执行：
export HTTP_PROXY="http://<proxy-host>:<proxy-port>"
export HTTPS_PROXY="http://<proxy-host>:<proxy-port>"
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,::1,.internal,<内网域名>,<内网IP段>"
export no_proxy="$NO_PROXY"如果使用内网镜像仓库，继续设置镜像前缀：
export SANDBOX_IMAGE_PREFIX_EXTERNAL="registry.customer.local/knodo"验证当前 shell 能通过代理访问平台：
curl -I https://knodo.vip安装需要管理员权限，是因为脚本会写入 /opt/knodo、拉取和启动 Docker 容器、创建 Docker 网络；如果启用 Docker daemon 代理，还会写入 Docker 的 systemd 代理配置并重启 Docker。
如果使用 sudo 执行安装命令，请使用能保留环境变量的方式，例如 sudo -E。
第三步：执行安装命令
在同一个 shell 中执行平台生成的安装命令：
curl -fsSL https://knodo.vip/api/v1/public/install/<token> | bash安装脚本会自动完成：
- 检测当前 shell 中的代理变量。
- 激活专属主机。
- 将代理配置写入
/opt/knodo/.env。 - 将
SANDBOX_IMAGE_PREFIX_EXTERNAL、最终 Agent Service 镜像和 Sandbox 镜像写入/opt/knodo/.env。 - 拉取镜像并启动 Agent Service。
安装完成后检查容器状态：
docker ps --filter name=knodo-agent-service-inbound
docker logs --tail 100 knodo-agent-service-inbound可选：启用 Docker daemon 代理
默认不需要配置 Docker daemon 代理。推荐通过内网镜像仓库和 SANDBOX_IMAGE_PREFIX_EXTERNAL 解决镜像拉取。
只有在 Docker 必须通过代理服务器访问镜像仓库时，才在执行安装命令前增加：
export KNODO_CONFIGURE_DOCKER_PROXY=true安装脚本检测到该变量后，会写入 Docker systemd 代理配置并重启 Docker。
第四步：检查安装配置
安装完成后，检查 /opt/knodo/.env：
grep -E 'HTTP_PROXY|HTTPS_PROXY|NO_PROXY|UPSTREAM_PROXY|SANDBOX_IMAGE_PREFIX_EXTERNAL|AGENT_SERVICE_FULL_IMAGE|SANDBOX_IMAGE' /opt/knodo/.env应能看到：
HTTP_PROXY=http://<proxy-host>:<proxy-port>
HTTPS_PROXY=http://<proxy-host>:<proxy-port>
NO_PROXY=...
UPSTREAM_PROXY=http://<proxy-host>:<proxy-port>
SANDBOX_IMAGE_PREFIX_EXTERNAL=registry.customer.local/knodo
AGENT_SERVICE_FULL_IMAGE=registry.customer.local/knodo/knodo-agent-service:<tag>
SANDBOX_IMAGE=registry.customer.local/knodo/knodo-sandbox:<tag>如果未设置镜像前缀，SANDBOX_IMAGE_PREFIX_EXTERNAL 可以为空。
第五步：向平台管理员提供 Sandbox 隔离代理配置
安装成功后，Sandbox 网络隔离代理需要由平台管理员在后台配置。请将本次安装使用的代理信息和访问范围提供给平台管理员。
需要提供：
HTTP_PROXY/HTTPS_PROXY：代理地址，例如http://proxy.example.com:8080。NO_PROXY：需要直连、不经过 HTTP/HTTPS 代理的内网域名或 IP 段。- allow 规则：允许 Sandbox 访问的公网域名、内网域名、IP 或网段；allow 为空时表示允许访问所有目标。
平台管理员保存配置后，新建或重启工作空间 Sandbox，新的网络隔离代理配置才会生效。
NO_PROXY 和访问 allow 规则不是同一个配置：
NO_PROXY用于决定哪些地址不走 HTTP/HTTPS 代理。- allow 规则用于决定 Sandbox 允许访问哪些目标；为空时表示不限制访问目标。
两者需要按专属主机所在网络要求分别配置。
第六步：验证
回到 Knodo 平台确认：
- 宿主机状态为 在线。
- 最近心跳时间持续更新。
- 组织已绑定该专属主机。
- 新建工作空间后，Sandbox 能正常启动。
- 对话、文件读写、Git 操作和流式输出正常。
可让 Agent 执行只读连通性检查：
curl -I https://knodo.vip
curl -I http://<内网Git或API地址>常见问题
安装命令下载失败
检查：
- 当前 shell 是否已 export 代理变量。
curl -I https://knodo.vip是否成功。- 代理服务器是否放行
https://knodo.vip及其子域名。 - 代理是否需要账号密码。
镜像拉取失败
优先检查：
- 是否已设置
SANDBOX_IMAGE_PREFIX_EXTERNAL。 - 内网镜像仓库是否支持通过
docker pull拉取 Agent Service 和 Sandbox 的新版本镜像。 - 专属主机是否能访问内网镜像仓库。
如果必须通过代理拉取镜像，再使用 KNODO_CONFIGURE_DOCKER_PROXY=true 重新安装或手动配置 Docker daemon 代理。
宿主机一直离线
检查 Agent Service 日志：
docker logs -f knodo-agent-service-inbound常见原因：
- 代理服务器不支持 WebSocket、SSE 或 HTTPS
CONNECT。 https://knodo.vip及其子域名未放行。- 安装 Token 过期或已重置。
/opt/knodo/.env中代理配置不正确。
Sandbox 不能访问内网
检查：
- 平台管理员是否已为当前组织保存 Sandbox 隔离代理配置。
NO_PROXY是否包含内网域名或 IP 段。- allow 规则是否允许访问目标地址；如果 allow 为空，则表示允许访问所有目标。
- 内网服务是否对专属主机网段放行。
交付检查清单
- 宿主机使用反向连接（Inbound）模式。
- 安装前已在 shell 中设置
HTTP_PROXY、HTTPS_PROXY、NO_PROXY。 - 如使用内网镜像仓库，已设置
SANDBOX_IMAGE_PREFIX_EXTERNAL。 - 安装命令已在同一个 shell 中执行成功。
-
/opt/knodo/.env中已写入代理和镜像配置。 - 平台宿主机状态为在线。
- 平台管理员已为当前组织配置 Sandbox 隔离代理；如需限制访问范围，已配置 allow 规则。
- Sandbox 可启动，AI 对话流式输出正常。
- Sandbox 能访问内网 Git / API / 数据库。