安装

OAR 是一个你在自己机器上运行的中继。安装它会把 oar 命令放到那台机器上。在 macOS 和 Linux 上，一行命令就能完成全部工作：它会找到或获取 Node.js、安装 OAR、写入配置并启动中继。在 Windows 上，安装器要求 Node.js 已经安装好。此外，你始终可以用 npm 或从 git 检出进行安装。

要求 #

安装不再需要其他任何东西。等 OAR 运行起来之后，你再添加提供商。

macOS 和 Linux #

curl -fsSL oar.sh/install | sh

你可以先到 oar.sh/install 阅读该脚本。它需要 curl 或 wget，在需要获取 Node.js 时还需要 tar。它拒绝以 root 身份运行：OAR 按用户安装，任何操作都不需要 root 权限。

它会做什么 #

1. 它查看机器上的现有内容并打印一份计划：它使用哪个 Node.js、把 OAR 安装到哪里、往你的 shell 配置文件中写入什么，以及中继将如何启动。
2. 它询问 Continue? [Y/n]。按 Enter 或输入 y 继续；其他任何回答都不会做任何改动。
3. 它安装 @oar-sh/oar 包（除非你指定了某个版本或渠道，否则安装最新版本）。
4. 它运行 oar setup --defaults --start：写入配置（一个新的认证令牌、仅限本机访问、从 3333 开始的第一个空闲端口，或你用 OAR_PORT 设置的端口）并启动中继。它会打印中继 URL 和一个二维码。
5. 它打印版本号，告诉你中继正在运行，并列出 oar、oar setup 和 oar doctor 命令。

在有 systemd 用户会话的 Linux 上，中继会作为 systemd 用户服务启动，因此重启后它会自动回来。在其他地方（macOS、容器、没有 systemd 的 WSL），它在后台启动，重启后需要 oar start 再次启动它。

安装位置 #

适用三种情况中的哪一种，取决于机器上的 Node.js。

只有 OAR 使用它自己的 Node.js。~/.local/bin 中的 oar 命令把那个 Node.js 放在 PATH 的最后，因此你自己的 Node.js 在中继的会话中仍然优先。

在后两种情况下，当 ~/.local/bin 不在你的 PATH 中时，安装器会在计划中列出这一改动，然后向你的 shell 启动文件追加一行注释（# added by the OAR installer）和一行 export PATH：zsh 是 ~/.zshrc，macOS 上的 bash 是 ~/.bash_profile，Linux 上的 bash 是 ~/.bashrc，其他情况是 ~/.profile。新终端能找到 oar；在当前终端中，运行安装器打印的那行 export PATH=...。

选项 #

标志放在 sh -s -- 之后。变量放在 sh 之前。

其他任何标志都会让安装器以 unknown option 停止。

curl -fsSL oar.sh/install | sh -s -- --yes
curl -fsSL oar.sh/install | OAR_VERSION=0.9.19 OAR_PORT=3400 sh
curl -fsSL oar.sh/install | OAR_DRY_RUN=1 sh

再次运行 #

安装器随时可以再次运行。它会再次安装包（除非你指定了某个版本，否则安装最新版本），因此它也可以用来更新。它保留现有配置，如果 OAR 自己的 Node.js 仍然足够新就复用它，重写 oar 启动器，并且只会向你的 shell 配置文件添加一次 PATH 行。

在没有终端的情况下运行 #

通过 curl 管道传入时，脚本会在终端上提问。没有终端时（例如在 CI 作业中），它会以 no terminal to ask on 停止，且不做任何改动。此时请传入 --yes。

无法处理的情况 #

• 对于 Alpine 这类 musl 系统，以及 x64 和 arm64 之外的 CPU，它没有 Node.js 构建。请自行安装 Node.js 22.13 或更新版本，然后再次运行安装器。
• 如果无法访问 nodejs.org、下载或校验和失败，或下载的 Node.js 无法运行，它会停止且不安装任何东西。
• 0.9.8 之前的版本安装方式相同，但它们的 oar setup 无法启动中继。此时安装器只会写入配置而不会启动中继。

Windows #

irm oar.sh/install.ps1 | iex

这需要已安装 PowerShell 5 或更新版本，以及 Node.js 22.13 或更新版本。与 macOS 和 Linux 的安装器不同，它不会获取 Node.js、不会要求确认，也不会启动中继。它会做以下事情：

1. 检查 node 和 npm 是否存在，以及 Node.js 是否足够新。
2. 打印计划。
3. 运行 npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar。
4. 运行 oar setup。在终端中，它会询问是否生成新的认证令牌、访问方式（仅本机，还是局域网）、端口，以及 0.9.15 新增 中继如何启动：登录时、在任何人登录之前开机时（一次管理员提示），或根本不启动。然后它写入配置并打印中继 URL。

之后运行 oar start 启动中继；你选择的自启动方式会在下次登录或开机时启动它。oar autostart 可以稍后更改模式。接下来的内容见首次运行。

在命令之前，于同一个 PowerShell 窗口中设置变量。Windows 安装器没有 OAR_PORT；oar setup 会询问端口，或者你运行 oar setup --port <port>。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

如果安装成功但找不到 oar，请打开一个新终端，然后运行 oar.cmd setup。

npm #

npm install -g --allow-scripts=@oar-sh/oar,better-sqlite3,koffi @oar-sh/oar
oar setup

npm 12 不会运行未明确允许的安装脚本。OAR 的两个依赖（better-sqlite3、koffi）会在安装脚本中获取它们的原生二进制文件：不运行这些脚本，在 npm 12 上安装仍会成功，但中继随后无法启动。0.9.14 新增 OAR 自己的安装脚本（@oar-sh/oar）会在 npm 删除包之前，把早期版本存放在包内的数据复制出来；参见 0.9.14 升级说明。npm 10 和 11 接受该标志，但并不需要它。安装器、oar update 和 Update（更新）按钮会自行传入该标志。

oar setup 会创建配置并打印中继 URL，但除非你传入 --start，否则它不会启动中继。之后使用 oar start。npm 的全局文件夹必须可写，且其 bin 文件夹必须在你的 PATH 中；npm prefix -g 会显示它的位置。如果它需要 root 权限，不要使用 sudo：在 macOS 或 Linux 上请改用安装器。之后要更新，运行 oar update。

从 git 检出 #

git clone https://github.com/oar-sh/oar
cd oar
npm install
node bin/oar.js setup   # writes server/config.json with a fresh auth token
npm start               # the same as: node server/server.js

检出与全局安装有三点不同：

• 状态存放在仓库内部： server/config.json、server/data/、server/uploads/ 和 server/logs/。全局安装把它的状态保存在 ~/.oar（参见 OAR 文件的存放位置和文件与文件夹）。
• 它从不会自我更新。 用 git pull、npm install 更新，然后在对话的 ⋯ 菜单中用 🌄 Restart web relay（重启网页中继）重启中继。oar update 用于全局安装。
• oar start、oar stop 和 oar restart 仅用于全局安装。 在检出中，npm start 会在前台运行中继。

node server/server.js --port <port> --token <token> 会在这一次运行中覆盖配置，但不会保存。

按平台 #

重启后，oar start 会启动一个在后台运行的中继。

WSL #

在发行版内部运行 Linux 安装器，而不是在 Windows 中。在 WSL 的默认网络中，一个端口在发行版内部可能是空闲的，但 Windows 程序却在监听它，此时 Windows 浏览器中的 localhost:<port> 会访问到那个程序。因此新配置会选择在两侧都空闲的第一个端口，而 oar setup 会拒绝 Windows 占用的端口。当 Windows 占用中继的端口时，oar status、oar start 和 oar doctor 会发出警告。要解决它，请选择另一个端口：

oar setup --port 3400

WSL 内部的局域网地址仅对 WSL 内部可见。要在手机上访问，请使用隧道或 WSL 的镜像网络模式。

移除 OAR #

0.9.15 新增 oar uninstall 会把 OAR 从机器上移除，并保留你的数据：

oar uninstall

它会停止中继（等待正在运行的轮次）、移除 OAR 生成的自启动条目（systemd 单元，或 Windows 登录条目和开机任务，其中开机任务需要一次管理员提示）以及 OAR 写入的 Copilot 扩展包装，并在命令结束后让 npm 移除该包。你手动创建或编辑的条目会被保留并列出名称。你的配置、数据库、上传文件和日志保留在状态文件夹中，命令会打印其位置；以后重新安装会再次读取它们。oar uninstall 包含详细信息及每条消息。

要一并删除数据：

oar uninstall --purge

在你输入 delete 之后，它会删除状态文件夹；在删除其外部的数据文件夹、git 检出中的数据文件夹或 rescued-package-data 之前，它会单独询问。它会拒绝驱动器根目录、你的主文件夹、系统文件夹，以及任何不含 OAR 配置或数据库的文件夹。这会删除你的对话。

oar uninstall 不会撤销 macOS 和 Linux 安装器在包外添加的内容：

• ~/.local/bin 中的 oar 脚本，如果安装器把它放在那里（即它的第二种和第三种情况）；
• 它向你的 shell 启动文件添加的两行（如果有的话）（注释 # added by the OAR installer 和其下的 export PATH 行）；
• ~/.oar/runtime，即 OAR 自己的 Node.js，如果它在那里。它位于状态文件夹中，因此不使用 --purge 时它会保留。

在 0.9.15 之前，或当 oar 不再能运行时，手动移除这些部分：用 oar stop 停止中继，在设置了服务或 Windows 自启动的地方运行 oar service remove；用 npm uninstall -g @oar-sh/oar 移除包，或对于安装器的其他两种情况，删除 ~/.oar/npm；然后是上述各部分，最后只有在你想要删除数据时才删除 ~/.oar 或 %APPDATA%\oar。

OAR 文件的存放位置 #

全局安装把它的状态保存在 ~/.oar（Windows 上是 %APPDATA%\oar；OAR_STATE_ROOT 可以移动它）：

• config.json
• data/，包含数据库和上传文件
• logs/，当 oar 启动中继时包含 server.log 和 server-err.log，并为每个 Node 会话 worker 提供一个 worker-<session>.log

用 npm 更新包绝不会触及这些内容。macOS 和 Linux 安装器可能会在那里添加两个不属于状态的文件夹：npm/（当 npm 的全局文件夹不可写时存放包）和 runtime/node/（OAR 自己的 Node.js）。oar doctor 会打印正在使用的路径。

之后你会拥有什么 #

• oar 命令。在终端中，单独输入 oar 会打开一个菜单，显示中继的状态和其他命令。oar setup 可以更改设置（其他设备的访问方式、端口、令牌），oar url 会再次打印中继 URL。
• 一份带有新认证令牌的配置。使用默认访问方式时，中继只能在本机访问，地址是 http://localhost:3333/ 或下一个空闲端口。
• 在 macOS 和 Linux 上：一个正在运行的中继。在 Windows 上和手动 npm 安装后：一个你用 oar start 启动的中继。

检查已安装的内容：

oar --version
oar doctor

oar doctor 会打印版本、Node.js、安装模式、状态文件夹、配置路径、端口、是否设置了令牌、数据库路径和大小，以及哪些提供商 CLI 有响应。它不会做任何改动。

疑难解答 #

有关安装后的问题，参见疑难解答。