# 帮助 — herdr-web

> herdr-web 上手三件事：在本机跑起来、从公网连回家里那台机器（Tailscale 或自己的云端中继、把 agent 起的本地端口也放出去、几个人共用一台中继怎么分）、安卓 App 怎么装怎么登录。

[herdr-web](/) [能力](/tour.md) [安全](/security.md) [帮助](/help.md) [指南](/guides.md) [常见问题](/faq.md) [更新](/changelog.md)

帮助

# 三步用起来

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

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

复制 Markdown 地址

[1在本机跑起来](#local) [2从公网访问](#public) [3安卓 App](#app)

## 1\. 在本机跑起来

前提：这台电脑上已经装好了 [herdr](https://github.com/zbysir/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](https://github.com/zbysir/herdr-web/blob/master/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](https://github.com/zbysir/herdr-web/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 里点「分享 → 添加到主屏幕」，效果接近。

还是卡住了，先看 [常见问题](/faq.md)；全部配置项在 [使用说明](https://github.com/zbysir/herdr-web/blob/master/docs/USAGE.zh-CN.md) 里。

[herdr-web](/) MIT · @bysir/herdr-web

[能力](/tour.md) [全部特性](/features.md) [安全](/security.md) [帮助](/help.md) [指南](/guides.md) [常见问题](/faq.md) [更新历史](/changelog.md) [GitHub](https://github.com/zbysir/herdr-web)

> 全站页面清单：[/llms.txt](/llms.txt)