安裝

OAR 是你在自己機器上執行的中繼。安裝它，就是把 oar 指令放到那台機器上。在 macOS 和 Linux 上，一行指令就能完成所有工作：它會找到或下載 Node.js、安裝 OAR、寫入設定檔並啟動中繼。在 Windows 上，安裝程式需要事先裝好 Node.js；此外，你隨時都可以改用 npm 或從 git checkout 安裝。

需求 #

安裝不需要其他任何東西。供應商可以在 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：寫入設定檔（新的驗證 token、僅限本機存取、從 3333 起第一個空閒的連接埠，或你用 OAR_PORT 設定的連接埠）並啟動中繼。它會印出中繼網址和 QR 碼。
5. 它會印出版本、告訴你中繼正在執行，並列出 oar、oar setup 和 oar doctor 這幾個指令。

在有 systemd 使用者 session 的 Linux 上，中繼會以 systemd 使用者服務的形式啟動，所以重開機後會自動恢復。在其他環境（macOS、容器、沒有 systemd 的 WSL）中，它會在背景啟動，重開機後用 oar start 再次啟動它。

安裝到哪裡 #

適用三種情況中的哪一種，取決於機器上的 Node.js。

只有 OAR 會使用它自己的 Node.js。~/.local/bin 裡的 oar 指令會把那個 Node.js 放在 PATH 的最後，所以在中繼的 session 裡，你自己的 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 啟動器，而 PATH 那幾行只會加進你的設定檔一次。

在沒有終端機的環境執行 #

透過管線從 curl 執行時，腳本會在終端機上提出詢問。沒有終端機時（例如在 CI 工作中），它會以 no terminal to ask on 停止，不做任何變更。這種情況請加上 --yes。

它會在哪裡停下 #

• 它沒有適用於 musl 系統（例如 Alpine）的 Node.js 版本，也沒有適用於 x64 和 arm64 以外 CPU 的版本。請自行安裝 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。在終端機中，它會詢問是否建立新的驗證 token、存取範圍（僅限本機或區域網路）、連接埠，以及 0.9.15 新增 中繼的啟動方式：登入時、開機時在任何人登入之前（需確認一次系統管理員提示），或完全不自動啟動。接著它會寫入設定檔並印出中繼網址。

之後請執行 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 會建立設定檔並印出中繼網址，但除非你加上 --start，否則不會啟動中繼。之後請用 oar start。npm 的全域資料夾必須可寫入，而且它的 bin 資料夾必須在你的 PATH 上；npm prefix -g 會顯示它的位置。如果它需要 root，請不要使用 sudo，改在 macOS 或 Linux 上執行安裝程式。日後要更新時，請執行 oar update。

從 git checkout 安裝 #

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

checkout 和全域安裝有三點不同：

• 狀態存放在儲存庫內：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 只適用於全域安裝。 在 checkout 中，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 內部有效。要從手機存取，請使用 tunnel 或 WSL 的鏡像網路模式。

移除 OAR #

0.9.15 新增 oar uninstall 會把 OAR 從機器上移除，但保留你的資料：

oar uninstall

它會停止中繼（等候執行中的回合結束），移除 OAR 產生的自動啟動項目（systemd unit，或 Windows 的登入項目與開機任務，移除開機任務時需確認一次系統管理員提示）和 OAR 寫入的 Copilot 擴充功能包裝程式，並在指令結束後讓 npm 移除套件。你手動建立或編輯過的項目會保留，並列出名稱。你的設定檔、資料庫、上傳的檔案和記錄會留在狀態資料夾中，指令會印出位置；之後重新安裝時會再次使用它們。詳細內容和所有訊息請見 oar uninstall。

要連同資料一起刪除：

oar uninstall --purge

你輸入 delete 後，它會刪除狀態資料夾；如果有位於狀態資料夾之外的資料目錄、git checkout 中的資料目錄，或 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 session worker 各有一個 worker-<session>.log

用 npm 更新套件絕不會動到這些檔案。macOS 和 Linux 安裝程式可能會在那裡加入兩個不屬於狀態的資料夾：npm/（npm 的全域資料夾無法寫入時，套件放在這裡）和 runtime/node/（OAR 自己的 Node.js）。oar doctor 會印出實際使用的路徑。

安裝完成後你會有什麼 #

• oar 指令。在終端機中，單獨執行 oar 會開啟選單，顯示中繼的狀態和其他指令。oar setup 可以變更設定（其他裝置的存取、連接埠、token），oar url 會再次印出中繼網址。
• 一個含有全新驗證 token 的設定檔。在預設的存取設定下，只有這台機器能連到中繼，網址是 http://localhost:3333/ 或下一個空閒的連接埠。
• 在 macOS 和 Linux 上：一個正在執行的中繼。在 Windows 上，以及手動用 npm 安裝之後：一個需要你用 oar start 啟動的中繼。

檢查安裝了什麼：

oar --version
oar doctor

oar doctor 會印出版本、Node.js、安裝模式、狀態資料夾、設定檔路徑、連接埠、是否已設定 token、資料庫路徑和大小，以及哪些供應商 CLI 有回應。它不會變更任何東西。

疑難排解 #

安裝之後的問題請見疑難排解。