docs: capture WSL provider bootstrap notes
This commit is contained in:
Lyon
@@ -32,12 +32,22 @@ WSL provider 的最小环境文件应放在节点本地私有路径，例如 `/h
|
||||
|
||||
WSL 本身会在没有前台进程时被 Windows 回收；如果该节点要作为长期在线算力，必须通过 Windows 启动项、计划任务或后台 `wsl.exe -d <distro> -u root -- bash -lc "systemctl start docker unidesk-provider-gateway-<ID>.service; exec sleep infinity"` 这类 keepalive 进程保持发行版运行。仅启用 WSL 内 systemd service 不等价于 Windows 层面的常驻守护。
|
||||
|
||||
## WSL Network And Proxy Bootstrap
|
||||
|
||||
WSL 节点出网异常时，先把代理设置固化到目标 WSL 用户的 `~/.bashrc`，而不是只在当前 shell 临时 `export`。长期可复用的写法是在每次交互 shell 启动时从 `/etc/resolv.conf` 读取 Windows 宿主在 WSL NAT 中的 nameserver IP，再导出 `http_proxy`、`https_proxy`、`HTTP_PROXY`、`HTTPS_PROXY`、`all_proxy` 和 `ALL_PROXY` 指向 `http://<windows-host-ip>:7890` / `socks5://<windows-host-ip>:7890`，并保留 `no_proxy=localhost,127.0.0.1,::1,host.docker.internal`。不要把某次启动看到的宿主 IP 当成永远不变的常量；动态读取可以避免 WSL 网络重建后代理失效。
|
||||
|
||||
Windows 代理程序常见默认只监听 `127.0.0.1:7890`，此时 WSL 访问 `<windows-host-ip>:7890` 会失败。可选修复是让代理程序监听 WSL 可达网卡，或在 Windows 用户态启动一个幂等 TCP relay，把 `<windows-host-ip>:7890` 转发到 `127.0.0.1:7890`；`netsh interface portproxy` 通常需要管理员权限，不应作为普通节点 bootstrap 的唯一方案。`.bashrc` 可以在发现 `<windows-host-ip>:7890` 不可达时调用 Windows 侧脚本启动该 relay，但 relay 脚本、临时 apt source、日志和节点私钥都属于本地运行态，必须留在 `.state` 或用户目录，不能提交到仓库。
|
||||
|
||||
apt 或镜像构建遇到 `archive.ubuntu.com` 超时、代理 `503` 或 registry metadata 拉取失败时，优先使用节点侧临时镜像源或临时 apt sources 完成 bootstrap，例如把 Ubuntu 源临时替换到可达镜像后安装 `openssh-server`。这类网络兜底只解决节点初始化，不改变 `PROVIDER_SERVER_URL`、provider token、Docker socket、Host SSH 透传和 remote CLI 验收标准。
|
||||
|
||||
## WSL Image Build Fallback
|
||||
|
||||
标准镜像构建路径使用 `src/components/provider-gateway/Dockerfile`，基础镜像为 `oven/bun:1-alpine`，并在镜像内安装 Bun、Docker CLI、Compose plugin、`df` 和 provider-gateway 源码。WSL 或 Docker Desktop 环境中的 registry mirror、DNS 或代理配置可能导致 `oven/bun` 元数据拉取失败；此时不要修改 provider ingress 协议或服务端配置，应改用节点侧镜像交付兜底。
|
||||
|
||||
可复用的兜底方式是使用本机已存在的 Debian/Node 基础镜像，复制 WSL 本地 `bun`、`docker` 和 `docker-compose` plugin 到镜像内，再复制 `src/components/provider-gateway/src` 与 `src/components/shared/src`。该镜像必须能在容器内执行 `bun --version`、`docker version`、`docker compose version`、`ssh -V`，并通过挂载的 `/var/run/docker.sock` 执行 `docker info` 和 `docker ps`；只有这些命令通过后才能作为 `unidesk_provider-gateway:<provider-id>` 运行。该兜底镜像只改变节点侧交付方式，不改变 `PROVIDER_SERVER_URL`、token、heartbeat、labels、Docker socket、SSH 私钥只读挂载和服务端验收标准。
|
||||
|
||||
如果兜底镜像还要承载 WSL SSH 透传，必须同时复制 `/usr/bin/ssh`、`/etc/ssh/ssh_config`、`/etc/ssh/ssh_config.d` 以及 `ldd /usr/bin/ssh` 输出的全部动态库，尤其不能漏掉 `/lib64/ld-linux-x86-64.so.2` 这类 ELF loader。只在 rootfs 中看到 `/usr/bin/ssh` 文件不代表可执行；验收必须运行 `docker run --rm <image> /bin/sh -lc '/usr/bin/ssh -V && /usr/bin/docker compose version'`，再以实际 provider 容器执行 `ssh -T -i /run/host-ssh/id_ed25519 -p 22 ubuntu@host.docker.internal hostname`。若 Compose 使用 Docker bridge 网络，WSL 节点必须在 compose 文件中加入 `extra_hosts: ["host.docker.internal:host-gateway"]`，否则容器内可能无法把 `host.docker.internal` 解析到 WSL 宿主。
|
||||
|
||||
## Deployment Verification
|
||||
|
||||
provider-gateway 部署是否成功必须以 UniDesk frontend 中可见的 Provider 信息为准，不能只看节点容器 `running`。验证时访问 `http://74.48.78.17:18081/`，使用配置中的账号密码登录，进入 `资源节点 / 节点清单`，确认目标 `PROVIDER_ID`、`PROVIDER_NAME`、`online` 状态、`lastHeartbeat` 和 labels 可见；点击该节点的 `查看原始JSON`，确认 raw payload 中的 `providerId`、`name`、`status`、`labels` 与部署环境变量一致。随后进入 `资源节点 / 资源监控`，确认该 Provider 有 CPU、实际内存和硬盘采样曲线；进入 `资源节点 / Docker 状态`，确认 Docker daemon、containers、images、volumes、networks 已渲染出来，且 `dockerSocketPresent` 或 Docker ready 状态与预期一致。只有这些前端信息都能通过 UniDesk 正常读取，才说明 provider-gateway 已经真正挂载到主 server。
|
||||
|
||||
Reference in New Issue
Block a user