快速开始 — Raemote

1 开始之前

你的应用能用吗？十秒钟就能确认。 在运行它的那台电脑上，用浏览器打开 http://localhost:<端口>—— 就是你平时在本机用的那个地址。能打开，Raemote 就能连上。

在终端里就是一行：

curl -I http://localhost:3000

这个检查其实就是 Raemote 的工作方式：它去问每个本地端口要它的页面，只保留那些真的返回网页的。所以你能打开，它就能找到。

Raemote 使用普通 HTTP——不少自托管软件默认就是这样。已经配好证书、只提供 HTTPS 的应用暂时还连不上，这是我们接下来要做的事。

现在还没有任何应用在跑？没关系，以后也可以手动添加： raemote apps add <名字> <端口>。

你还需要准备

一台 Mac（Apple Silicon 或 Intel）或 Linux 机器（x86_64、arm64，树莓派也行），上面跑着你想在手机上访问的网页应用。
一台 iPhone。App 需要 iOS 27 或更高版本。
不会有任何东西暴露到公网：Raemote 把一切都留在你的机器上，只交给你配对过的设备。

现在一个应用都没跑？开发服务器就够了—— 随便起一个能提供网页的东西，Raemote 就会把它列出来。

2 安装服务端

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh

GitHub 不顺或者被墙时，用 Gitee 镜像：

curl -fsSL https://gitee.com/pppkin/raemote_cli/raw/main/install.sh | sh

安装脚本会把 raemote 和 raemoted 放进 ~/.local/bin，注册并启动后台服务（macOS 用 launchd，Linux 用 systemd），最后打印你的配对链接。

安装选项与 AI Agent

常用参数：--no-service、--bin-dir <目录>、 --proxy <url>、--source gitee|github、 --tag <版本>、--quiet。

给 AI Agent 或脚本用时，加 --json：标准输出只有一个 JSON 对象（含节点 ID 和配对用的 uri），过程信息走标准错误，失败时退出码非零：

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh -s -- --json

完整约定见 agent-install.md。

想先读一遍？把 install.sh 下载下来再 sh install.sh 即可。

3 安装手机 App

在 iPhone 上从 TestFlight 安装 Raemote（iOS 27+），然后打开。不用注册账号，也不用填任何信息。

浏览器是同等的选择：raemote connect 会给一台电脑配对、提供同样的应用——第 6 步。同一个链接可以两者都配对。

第一次打开出现 Safari 的「非安全连接」提示页？ 那是 Safari 对 Raemote 在 App 内部使用的 HTTP 回环地址发出的提示—— 到你电脑的那一跳依然是端到端加密的。可以关掉它： 设置 → App → Safari → 隐私与安全性 → 非安全连接警告。

4 配对手机

在运行服务端的那台电脑上：

raemote pair

它会打印一个 raemote:// 链接和二维码。在 App 里点 + 扫描，或者用手动添加粘贴链接。每台设备配对一次就够了。

同一个链接也能配对电脑：运行 raemote connect '<来自 raemote pair 的链接>'，它就会成为另一台配对设备（第 6 步）。

这个链接是短期的（默认五分钟），在过期前可以配对多台设备。随时运行 raemote pair 就能打印一个新的。

更长效的链接，或之后再添加设备

如果需要一个长期有效的链接，在 ~/.raemote/config.toml 里固定 token 和较长的有效期：

[bind]
token = "…64 位十六进制…"
token_ttl_secs = 3153600000

然后再运行一次 raemote pair。请把这个链接当作密钥保管：拿到它的人就能配对。也可以完全绕开服务端——在已配对的设备上用 … → 邀请设备… 生成一次性邀请码。

只让某台设备访问部分应用

默认情况下，配对链接授予服务端能看到的全部应用。只想给一部分时，把端口列出来：

raemote pair --ports 8096,3000

这台设备的应用列表里只会出现这些应用，打开别的会被拒绝。之后也可以收紧或放宽某台已配对设备的权限，改动立即生效：

raemote devices access <id> --ports 8096
raemote devices access <id> --all

邀请遵守同样的规则：权限受限的设备用 … → 邀请设备… 时，可以交出它拥有的全部权限，或者更小的一部分——绝不会超出它自己的范围。权限按端口划分，所以同一个端口后面的应用总是同进同退。

5 开始使用

已配对的服务端会出现在 App 里，点进去就能看到 raemoted 发现的应用。
点应用就在 Safari 里打开。每个应用都有自己的源，登录状态和站点数据都会保留。
可以再打开一个应用，两个都会继续运行——最近那一行可以瞬间切换，页面状态原样保留。
回到 App 时列表会自动刷新；想立刻重新扫描就用 … → 刷新应用。

某个应用一直不出现，就手动固定：

raemote apps add jellyfin 8096
raemote apps list

6 用浏览器使用

raemote connect 是一个完整的客户端，和手机 App 完全一样：用同一个链接给这台电脑配对，然后在浏览器里提供你的应用：

raemote connect '<来自 raemote pair 的链接>'   # 配对并打开
raemote connect                              # 打开上次用的服务端

应用列表跑在 127.0.0.1:7788（用 --port 改端口），每个应用还会分到自己的回环端口，所以 URL、Cookie 和登录状态与在服务端一致。配对后的电脑会出现在 raemote devices list 里，和手机一样——可以起名字、限制、撤销。加 --no-open 可以不自动打开浏览器。

7 常用命令

命令	作用
`raemote status`	服务是否在跑、发现了几个应用
`raemote doctor`	体检守护进程、权限、配置、发现和中继
`raemote discover`	立刻重新扫描（加 `--verbose` 看每个被跳过的端口和原因）
`raemote apps list`	合并后的应用列表，含每条记录的来源
`raemote apps hide <名字>`	隐藏误识别的应用（`unhide` 恢复）
`raemote devices list`	已配对设备，含名称、节点 ID 和各自的访问权限
`raemote devices rename <id> "客厅"`	给设备起个可读的名字
`raemote devices revoke <id>`	立刻断开某台设备
`raemote devices access <id> --ports 8096`	把该设备限制在指定应用（`--all` 恢复全部）
`raemote config set name "Mac mini"`	改服务端在已配对设备上显示的名字
`raemote logs -n 50`	最近日志（`--follow` 持续输出）
`raemote restart`	改完配置后重启服务

8 出问题了

先从这里开始：

raemote doctor

现象	处理
应用没出现在列表里	先 `raemote discover --verbose` 看原因，再 `raemote apps add <名字> <端口>`
应用打不开	确认它能在 `http://localhost:<端口>` 上响应；只提供 HTTPS 的应用暂不支持
手机提示未被授权	它被撤销过，或服务端身份变了——重新运行 `raemote pair` 再扫一次
doctor 说中继连不上	受限网络里设置出站代理：`raemote config set network.proxy http://host:port`，然后 `raemote restart`
Safari 显示「非安全」页面	这是 Safari 对回环地址的提示，按上文在设置里关掉即可
改完配置没生效	多数设置用 `raemote reload`；网络或身份相关的改动要 `raemote restart`

更多内容见 troubleshooting.md。

9 卸载

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh -s -- --uninstall

加上 --purge 会一并删除 ~/.raemote——服务端身份和已配对设备列表。如果只是想断开某台设备，用 raemote devices 撤销即可，不必卸载。

把 Raemote 跑起来

本页目录