herdr-web
帮助

三步用起来

先在电脑上跑起来，再决定要不要从外面连，最后按需装 App。每一步都只写必须做的。

懒得自己看？把这页的 Markdown 地址发给你的 agent，让它照着帮你装。

1. 在本机跑起来

前提：这台电脑上已经装好了 herdr。 herdr-web 支持 macOS 和 Linux，Windows 请在 WSL 里装。

$npm install -g @bysir/herdr-web
$herdr-web

启动后终端里会打印一条带配对码的链接，用浏览器打开它就进去了，进去会自动运行 herdr。 没装 node 的话，换成这一行：

$curl -fsSL https://raw.githubusercontent.com/zbysir/herdr-web/master/install.sh | sh

同一个 Wi-Fi 下用手机 / 平板

$HERDR_WEB_HOST=0.0.0.0 herdr-web

用手机扫启动时打印的二维码。证书是自签的，第一次要点一下「继续访问」。 每台设备只需要配对一次，之后换 Wi-Fi、重启电脑都不用再配。

开机自动运行

$herdr-web service install

运行这条命令时，当前 shell 里所有 HERDR_WEB_* 环境变量都会被写进服务配置。 以后要改哪一项，就带着那一项再运行一次这条命令，其余配置会沿用。升级用 herdr-web update。

要给新设备配对，在电脑上运行 herdr-web pair 拿一个新配对码；herdr-web devices 列出已配对的设备，herdr-web revoke <id> 踢掉其中一台。

2. 从公网访问

人在外面也想连家里那台电脑，有两种做法。只是自己用的话，选第一种。

A. Tailscale：最省事，不用服务器

  1. 电脑和手机都装上 Tailscale，登录同一个账号。
  2. 电脑上照「同一个 Wi-Fi」那样用 HERDR_WEB_HOST=0.0.0.0 herdr-web 启动。
  3. 手机上打开 https://<电脑的 Tailscale IP>:7788，配对一次。

这样走的是 VPN，端口不会出现在公网上。缺点是每台设备都要装 Tailscale，而且装不了安卓 App（App 需要正式证书）。

B. 云端中继：用一个固定的 https 地址

需要一台 VPS 和一个托管在 Cloudflare 等 DNS 服务商上的域名。手机直接打开https://mac.h.example.com 就能连，不用装 VPN。中继只转发加密数据，TLS 在你自己的电脑上解开， 所以 VPS 就算被攻破，也看不到你的终端。

  1. 在 DNS 里把中继自己的域名 relay.example.com 指向 VPS，然后在 VPS 上用 Docker 启动中继：
$docker run -d --name herdr-relay --restart always -p 443:443 -v /root/data/herdr-relay:/data -e HERDR_RELAY_DOMAIN=relay.example.com ghcr.io/zbysir/herdr-relay

/data 里存着注册过的电脑，换容器时别丢。中继启动后，给你的电脑起一个名字（比如mac.h.example.com，用你自己域名下的任意名字），生成一个邀请码：

$docker exec herdr-relay herdr-relay invite mac.h.example.com
  1. 在你的电脑上用这个邀请码注册。这一条命令会顺便把 herdr-web 装成开机自启的服务， 所以申请证书用的 DNS 服务商和 token 要写在同一行里：
$HERDR_WEB_ACME_DNS=cloudflare HERDR_WEB_CLOUDFLARE_DNS_API_TOKEN=xxx herdr-web relay join https://relay.example.com mac.h.example.com <邀请码>
  1. 最后在 DNS 里添加它打印出来的记录：一条 A 记录，把 mac.h.example.com 指向 VPS； 再加两条 CAA 记录（作用是只允许你的电脑为这个域名申请证书）。 手机连的是这个名字，中继收到连接后按名字转给你的电脑，所以这个名字必须解析到 VPS。

证书会自动申请、自动续期。VPS 上 443 端口已经被 nginx / Traefik 占用时怎么配，见 DEPLOY.md。

把本机端口也放出去

agent 起了一个开发服务，比如 http://localhost:5173。配好下面这项之后， 手机上打开 https://5173.mac.h.example.com 就能看到它；终端和对话里的 localhost 链接， 点一下就会自动跳过去。打开前要先登录 herdr-web，别人拿到链接也进不来。需要先配好上面的中继。

  1. DNS 里加一条 *.mac.h.example.com 的通配 A 记录，指向 VPS。每个端口一个子域名，所以这里要用通配。
  2. 把 h.example.com 上的 CAA issuewild 记录从 ;（禁止申请通配证书）改成允许你的电脑申请：
$issuewild "letsencrypt.org; accounturi=<你的 ACME 账户>; validationmethods=dns-01"
  1. 环境变量里加上 HERDR_WEB_PORT_DOMAIN=mac.h.example.com，再运行一次 herdr-web service install。 电脑会多申请一张 *.mac.h.example.com 的证书。
第 2 步必须在第 3 步之前做完。CAA 没改的话证书签不下来，herdr-web 会拒绝启动。 只能代理 1024 以上的端口，herdr-web 自己用的几个端口除外。

几个人共用一台中继

一台中继可以同时给好几台电脑用：每台电脑一个自己的名字、一条自己的隧道，中继按名字转发。 各台电脑的设备和配对互相独立，A 配对过的手机进不了 B 的电脑。

  1. 管理员给每个人分一个名字，在 VPS 上各生成一个邀请码。邀请码 30 分钟内有效，只能用一次，并且只能注册这一个名字：
$docker exec herdr-relay herdr-relay invite alice.h.example.com
  1. 每个人在自己的电脑上，用自己的名字照上面第 2 步做一遍。
  2. CAA 记录要每人加一条：每台电脑会用自己的 ACME 账户申请证书， 有几个人，h.example.com 上就要有几条 issue 记录，否则只有第一个人能签下证书。 A 记录也是每人一条，把各自的名字指向 VPS。人多了可以换成一条 *.h.example.com 通配记录： 所有名字都解析到 VPS，以后加人就不用再改 DNS。
  3. 管理：docker exec herdr-relay herdr-relay hosts 列出所有注册过的电脑，把 hosts 换成 remove <名字> 就是把某台踢掉，30 秒内断开它的隧道。
现在这种做法只适合互相信任的人：每台电脑都要用 DNS 记录来申请证书，而 Cloudflare 的 token 一给就是整个域名的修改权；而且域名的主人随时能改 CAA，给别人的名字签一张证书。 让每个人用自己的域名、不用信任管理员的方案还在开发中。在那之前，不熟的人请各自搭一台中继。

3. 安卓 App

App 的界面和网页一样，另外多了几样网页做不到的：agent 跑完或等你回答时弹出系统通知、通知栏常驻和桌面小部件里能看到所有 agent 的状态、音量键可以当 ↑ / ↓ 用。

  1. 从 GitHub Releases 下载 herdr-web_<版本>.apk 装到手机上。
  2. 打开 App，填你自己那台电脑的地址，比如 mac.h.example.com；也可以直接粘贴 herdr-web pair 打印的那条配对链接。
  3. 用配对码登录（在电脑上运行 herdr-web pair），或者用已经注册的 passkey 登录。
  4. 第一次回到前台时会请求通知权限，请允许。
App 只认正式签发的证书。第 2 节里的云端中继（或者你自己有域名和正式证书）可以直接用；局域网自签证书和 Tailscale 的 IP 地址打不开。

在家时自动走局域网

在电脑上的环境变量里加上 HERDR_WEB_LAN_PORT=7790，再运行一次 service install。 之后手机和电脑在同一个 Wi-Fi 下时，App 会自动走局域网连接，出门后再自动切回中继，地址和登录状态都不变。 左上角的小点可以看当前走的是哪条：绿色是局域网直连，蓝色是中继。

收不到通知

国产系统会在后台把 App 杀掉。请在 App 的设置里关掉「电池优化」，并在系统设置里允许它「自启动」和「后台运行」。

升级时直接安装新版 APK 覆盖旧版就行，登录状态不会丢。iPhone 暂时没有 App：在 Safari 里点「分享 → 添加到主屏幕」，效果接近。

还是卡住了，先看常见问题；全部配置项在 使用说明里。

Render diagnostics