From 9f09d68fc5a1cae2217d293618fb7cccba067a5f Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 24 May 2026 14:34:08 +0000 Subject: [PATCH] Document G14 local VPN proxy --- AGENTS.md | 1 + docs/reference/g14.md | 33 ++++++++++++++++++++++++++++++ docs/reference/provider-gateway.md | 2 +- 3 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 docs/reference/g14.md diff --git a/AGENTS.md b/AGENTS.md index bd4f00e6..0bad1dfb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - `docs/reference/secretary-reference.md`：秘书日程管理、时间盒、短期待办捕获和 Todo Note / Decision Center 分流规则。 - `docs/reference/code-queue-supervision.md`：Code Queue 居中调度、并发队列拆分、运行中监控、基础设施缺陷分流和验收收口规则。 - `docs/reference/hwlab.md`：HWLAB 指挥侧固定 workspace、D601 原生 k3s 口径、16666/16667 DEV 入口、DEV CD wrapper 和受控发布边界。 +- `docs/reference/g14.md`：G14 provider 节点、k3s 控制桥、迁移后 Code Queue/CI 基础设施目标和节点本地 VPN proxy bootstrap 边界。 - `docs/reference/observability.md`：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。 - `docs/reference/microservices.md`：用户服务（兼容命名 `microservice`）的配置、代理、安全边界、unidesk-direct/k3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、k3s Control/Code Queue/MDTODO/Decision Center/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。 - `docs/reference/windows-passthrough.md`：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。 diff --git a/docs/reference/g14.md b/docs/reference/g14.md new file mode 100644 index 00000000..4690f3da --- /dev/null +++ b/docs/reference/g14.md @@ -0,0 +1,33 @@ +# G14 Provider Node + +G14 is a UniDesk provider node for migrated infrastructure workloads. Its UniDesk provider id is `G14`; the local UniDesk worktree is `/root/unidesk`, and the native k3s kubeconfig is `/etc/rancher/k3s/k3s.yaml`. + +G14's long-lived k3s control bridge is `k3sctl-adapter-g14`, a UniDesk direct service outside the k3s fault domain. It listens on the G14 host loopback port `127.0.0.1:4266` and is registered separately from the D601 `k3sctl-adapter`, so G14 infrastructure services can move without taking over user services that still run on D601. + +For Code Queue and CI/CD migration, G14 uses native k3s labels `unidesk.ai/node-id=G14` and `unidesk.ai/provider-id=G14`. The migrated Code Queue execution plane uses `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k8s.yaml` and the managed-service catalog `src/components/microservices/k3sctl-adapter/k3s/code-queue.g14.k3s.json`. + +## Node-Local VPN Proxy + +G14 has a node-local VPN/proxy stack for infrastructure bootstrap and recovery downloads: + +- Primary mixed HTTP/SOCKS proxy: `127.0.0.1:10808`. +- Backup Hysteria2 HTTP proxy: `127.0.0.1:11809`. +- Backup Hysteria2 SOCKS5 proxy: `127.0.0.1:11808`. +- Operator-only local details remain on G14 under `/root/docs/vpn-proxy-ops.md`; subscription URLs, node credentials and GUI database contents must not be copied into the UniDesk repository. + +The primary proxy can be used for G14 target-side image bootstrap when Docker Hub, npm, GitHub or Playwright downloads are unreliable through direct network or provider-gateway WS egress. For Docker build steps that use `127.0.0.1`, build with host networking so the build container reaches the host proxy: + +```bash +docker build --network host \ + --build-arg HTTP_PROXY=http://127.0.0.1:10808 \ + --build-arg HTTPS_PROXY=http://127.0.0.1:10808 \ + --build-arg ALL_PROXY=socks5h://127.0.0.1:10808 \ + --build-arg http_proxy=http://127.0.0.1:10808 \ + --build-arg https_proxy=http://127.0.0.1:10808 \ + --build-arg all_proxy=socks5h://127.0.0.1:10808 \ + ... +``` + +The backup proxy uses `HTTP_PROXY=http://127.0.0.1:11809`, `HTTPS_PROXY=http://127.0.0.1:11809` and `ALL_PROXY=socks5h://127.0.0.1:11808`. + +This proxy is not a replacement for UniDesk runtime egress. k3s workloads such as Code Queue must still use the cataloged `g14-provider-egress-proxy` Kubernetes Service and `g14-tcp-egress-gateway` for normal runtime access to PostgreSQL, OA Event Flow and external APIs. The node-local VPN proxy is allowed only for G14 host-side bootstrap, image build, cache prewarm or recovery steps, and those steps should record the proxy choice in issue or deployment evidence. diff --git a/docs/reference/provider-gateway.md b/docs/reference/provider-gateway.md index aaeeaf72..001f4630 100644 --- a/docs/reference/provider-gateway.md +++ b/docs/reference/provider-gateway.md @@ -102,7 +102,7 @@ provider-gateway 可以提供 egress HTTP CONNECT 代理，用于让 Code Queue 该能力属于 provider-gateway 通道能力，register/heartbeat 的 `unideskCapabilities` 必须包含 `network.egress-proxy`，labels 必须上报 `providerGatewayEgressProxy*` 状态。不得再为某个用户服务单独注册伪 provider 来实现出网代理；否则节点列表会出现虚假 provider，且代理、统计、升级路径会形成多套通道。代理健康检查使用 `GET /__unidesk/egress-proxy/health`，返回 `connected`、`providerId`、`activeTunnels`、`pendingTunnels`、`oldestTunnelAgeMs`、`openTimeoutMs`、`idleTimeoutMs` 和监听端口；业务服务自己的 `/health` 应把该结果作为排障证据透出。 -egress proxy 的长期边界是“统一 provider 通道，不引入第二控制面”。backend-core 只接受在线 provider socket 上的 `egress_tcp_*` 消息，并在该 socket 关闭时销毁全部对应 TCP relay；provider-gateway 只维护本地 HTTP proxy 与 WebSocket 消息映射，不保存业务状态，不参与任务调度、统计或节点注册以外的控制面。执行容器、用户服务、Pipeline runner 和 provider-side deploy build 不允许直接连接 backend-core provider ingress，也不允许携带 provider token 自行注册；需要出网时只能连接同节点 provider-gateway 的私有 proxy endpoint。当前 k3s/k8s Code Queue 通过 `d601-provider-egress-proxy` Kubernetes Service 连接 D601 provider-gateway egress endpoint，这是 Pod 内的出网入口，不是业务 HTTP 代理入口，也不能替代 Kubernetes API service proxy。部署构建同样不得新建 SSH SOCKS、公网 master proxy 或宿主全局代理；构建脚本只能把 provider-gateway WS egress 作为短生命周期环境变量和 Docker build-arg 注入，并配合目标节点本地 BuildKit/image cache 避免重复下载大依赖层。 +egress proxy 的长期边界是“统一 provider 通道，不引入第二控制面”。backend-core 只接受在线 provider socket 上的 `egress_tcp_*` 消息，并在该 socket 关闭时销毁全部对应 TCP relay；provider-gateway 只维护本地 HTTP proxy 与 WebSocket 消息映射，不保存业务状态，不参与任务调度、统计或节点注册以外的控制面。执行容器、用户服务、Pipeline runner 和 provider-side deploy build 不允许直接连接 backend-core provider ingress，也不允许携带 provider token 自行注册；需要出网时只能连接同节点 provider-gateway 的私有 proxy endpoint。当前 k3s/k8s Code Queue 通过 `d601-provider-egress-proxy` 或 `g14-provider-egress-proxy` Kubernetes Service 连接同节点 provider-gateway egress endpoint，这是 Pod 内的出网入口，不是业务 HTTP 代理入口，也不能替代 Kubernetes API service proxy。部署构建同样不得新建 SSH SOCKS、公网 master proxy 或未登记的宿主全局代理；构建脚本默认只能把 provider-gateway WS egress 作为短生命周期环境变量和 Docker build-arg 注入，并配合目标节点本地 BuildKit/image cache 避免重复下载大依赖层。G14 的节点本地 VPN proxy 是已登记的基础设施 bootstrap 例外，只允许按 `docs/reference/g14.md` 用于 G14 host-side 镜像构建、cache prewarm 或恢复下载；k3s runtime Pod 仍必须使用 `g14-provider-egress-proxy` 和 `g14-tcp-egress-gateway`。 egress tunnel 必须有生命周期边界：provider-gateway 发出 `egress_tcp_open` 后如果主 server 未在 `openTimeoutMs` 内返回 `egress_tcp_opened` 或 close，必须主动关闭本地 client 并向 core 发送 `egress_tcp_close`；provider-gateway 与 backend-core 都必须对长时间无数据的 relay 执行 idle 清理，避免 provider WebSocket 抖动、TCP connect 卡住或上游未关闭时留下 stale tunnel。排障时如果 `activeTunnels` 持续增长、`pendingTunnels` 非零或 `oldestTunnelAgeMs` 明显超过业务请求耗时，应先看 provider-gateway 与 backend-core egress 清理日志，再判断 Code Queue、PostgreSQL 或 OA Event Flow 本身是否慢。