Skip to content

OpenDWeb v0.4.2：逻辑网络，不是系统级 VPN

jixoai v0.4.2 opendweb

OpenDWeb v0.4.2 是 opendweb 仓库的第一份 GitHub Release：六个 npm 包全部发布。它做应用级组网，设备经邀请加入，只连通这个应用需要的流量；服务端一条命令，客户端只配一个入口，QUIC 直连优先、自托管 relay 回退。

$ curl http://localhost:8787/healthz
200

OpenDWeb v0.4.2 发布了（2026-09-06，jixoai/opendweb 仓库的第一份 GitHub Release）。它把多台设备连成一个应用级的逻辑网络：设备要经邀请才能加入，网络只承载这个应用的流量，不必为一条连接给整台机器装系统级 VPN、把全部设备的全部流量都交出去。

服务端一条命令，客户端只配一个入口

两台机器上的同一个应用要互相通信，服务端起来一次，客户端配一次，就通了。

# 1. 起服务端（gateway + relay）
npx opendweb server
#   或：docker run -p 8787:8787 -p 3340:3340 ghcr.io/jixoai/opendweb:0.4.2

# 2. 每台客户端一次性配置（持久化到 ~/.opendweb/config.json）
npx @jixo/opendweb-example config set relay http://192.168.2.13:8787

客户端只需要知道 gateway 的地址（8787）。relay 的地址经 gateway 的 /services.json 自动发现，客户端永远不必知道 3340 端口的存在。

服务端起来了可以用两条 curl 验：curl http://localhost:8787/healthz 得 200，curl http://localhost:8787/services.json 得服务清单。端到端回归有手册 EXAMPLE.md（中文版），每次发布后照走一遍。

示例：两端各开一个终端，兑换邀请并聊天 
# 3. 终端 A：初始化并保持 chat 会话（签发邀请）
npx @jixo/opendweb-example init --data ~/.dweb-a
npx @jixo/opendweb-example invite --data ~/.dweb-a --ttl 30m   # 复制令牌
npx @jixo/opendweb-example chat --data ~/.dweb-a

# 4. 终端 B（另一目录/设备）：兑换邀请并聊天
npx @jixo/opendweb-example join --data ~/.dweb-b <token>
npx @jixo/opendweb-example chat --data ~/.dweb-b

设备经邀请加入，且邀请方必须在线

新设备不能自己撞进来，得拿一张邀请令牌兑换。兑换时邀请方的进程要在运行（例如上一步 A 那边开着 chat 会话），这是受控邀请的硬条件：令牌只能兑一次，兑的时候邀请方得在场。

加入失败带稳定错误码，按 error[join/<code>] 返回。NO_REACHABLE_PATH 立即失败并给出指引，DIAL_TIMEOUT 提示邀请方可能已离线。

四层分工如下，每层的信任来源都不同。

  • 身份：每台设备一个 Ed25519 密钥对，即 EndpointId。它与网络地址解耦，机器换 IP 身份不变；对外展示为 z-base-32 串。

  • 名册：谁在网络里由一组签名事实决定（Genesis/Grant/Join/Revoke），BLAKE3 内容寻址，多份副本按 union-merge 收敛。邀请兑换走 challenge-response 证明确实持有密钥，并以 invite_id 的 CAS 消费保证只兑一次。

  • 会话：iroh 1.1 提供 QUIC 直连、NAT 穿透与自托管 relay 回退；双 ALPN 分开常规流量与 redeem 兑换；两侧先门控后传数据；帧资源有上限。

  • 同步：不透明 envelope 双向收发，上层协议自己解释。Automerge 适配器作为后续独立的 change。

六个 npm 包，各管一件事

npm 包版本角色
opendweb0.4.2服务端 CLI：npx opendweb server 起自托管 gateway（8787）+ relay（3340）；插件市场宿主
@jixo/opendweb-server-binary0.3.2CLI 使用的服务端二进制包装；另暴露可编程 startServer()
@jixo/opendweb-client-sdk0.3.2在你自己的应用里嵌入 opendweb 组网内核的 Node SDK（napi-rs；darwin-arm64 / win32-x64）
@jixo/opendweb-example0.3.2双进程参考客户端 CLI（init / invite / join / chat）
@jixo/opendweb-config0.1.0本地插件文件的 definePlugin helper（运行时无关：deno / bun / node）
@jixo/opendweb-ext-cf1.0.3Cloudflare Tunnel 插件：API 推送 ingress、DNS 路由与端到端校验，可选托管 cloudflared

Windows 工件（dweb-server exe + napi dll）由 tag workflow 现场构建（mingw 交叉编译），直接装进 npm tarballs，不需要单独下载。

其余变更

  • 装插件时显式钉住版本：opendweb plugin add cf 安装并锁定 name@version。祖先目录里一份带过期依赖范围的 package.json 再也不能劫持版本解析。

  • ext-cf 1.0 重写：把没有公网 IP 的服务端接到 Cloudflare Tunnel，浏览器登录一次，或贴一个 API token。控制面走 SDK，cloudflared 可交给插件托管，token 粘贴支持整块或单条。重写经过一轮 Codex 复核整改（SDK 叶子导入、config-merge PUT、OAuth 持久化契约、安装路径与竞态修复）。

    opendweb cf plan --hostname dweb.example.com    # 零副作用预览（setup 亦有 --dry-run）
opendweb cf setup --hostname dweb.example.com   # 非交互：API 推 ingress、路由 DNS、端到端自检

  • 发布自动化：从下一个 tag 起，release workflow 的自动 release notes 接管变更记录的生成。

升级

npx opendweb@0.4.2 server          # 或：npm i -g opendweb@0.4.2
npm i @jixo/opendweb-client-sdk@0.3.2
docker run -d -p 8787:8787 -p 3340:3340 ghcr.io/jixoai/opendweb:0.4.2

镜像现在统一在 ghcr.io/jixoai/opendweb：v0.4.2 当年发布在改名前的历史命名空间 ghcr.io/gaubee/dweb，改名后全部历史 tag 已原样迁移过来（digest 不变），旧地址暂可拉取但请迁移。

致谢

会话层站在 iroh 1.1 之上：QUIC 直连、NAT 穿透与自托管 relay 回退都由它提供；SDK 的绑定来自 napi-rs。

链接

jixoai logo jixoai jixoai.com