安裝方式

Walis 是一個自帶執行檔。不同部署方式的差別只在資料放在哪，以及有幾個節點在讀它。

挑一種拓撲

拓撲	資料庫	API 節點	什麼時候選它
單機 + SQLite	SQLite 檔案	1	預設。除了 Walis 本身沒有別的要跑。
單機 + 資料庫	PostgreSQL / MySQL / SQL Server	1	你本來就有資料庫，或想保留日後擴充的餘地。
多節點	PostgreSQL / MySQL / SQL Server	2 以上	API 必須在單一節點掛掉時還活著。
遠端執行器	上面任一種	—	建置需要另一台機器、另一種作業系統或架構。

遠端執行器跟前三種是正交的：不管你用哪一種拓撲都可以加，不必改資料庫或節點數。

一行安裝

curl -fsSL https://walis.io/install.sh | sh

它會判斷平台、下載對應的壓縮檔、比對 SHA256SUMS.txt 再安裝——以 root 執行時裝到 /usr/local/walis，否則裝到 ~/.walis，並在 PATH 上放一個 walis 符號連結。

要把一台機器變成建置機，改裝執行器並註冊成服務：

curl -fsSL https://walis.io/install.sh | sudo sh -s -- \
  --runner --service --server http://walis.internal:11120 --name pi-01 --token <權杖>

--service 會寫一份 systemd unit 並啟動。每個版本各自一個目錄，server-current 指向現行版本， 升級就是換一個符號連結。腳本是 POSIX sh 寫的——Debian 與 Ubuntu 的 /bin/sh 是 dash。

Windows 不走這支腳本，請下載下面的 zip。機器連不到 GitHub 時，用 --base-url 指到自己的檔案位置。

你會下載到什麼

deploy/release.sh 每個平台產出一個壓縮檔，外加一份 SHA256SUMS.txt：

壓縮檔	內容	執行檔
walis-<版本>-<平台>	API，管理介面已打包在內	Walis.Api
walis-runner-<版本>-<平台>	執行器代理程式	walis-runner

平台：win-x64、win-arm64、osx-x64、osx-arm64、linux-x64、linux-arm64、linux-arm （32 位元樹莓派）、linux-musl-x64、linux-musl-arm64（Alpine）。全部 self-contained， 目標機器不必先裝 .NET。

單機 + SQLite

預設值，也是 Walis 的重點：什麼都不必先裝。

tar xzf walis-<版本>-linux-x64.tar.gz
./Walis.Api --urls http://0.0.0.0:11120

資料庫在第一次啟動時建立，位置是相對於 API content root 的 data/walis.db。管理介面跟 API 同一個 port、同一個來源。

macOS 有現成的服務安裝腳本：

sudo ./deploy/install.sh --user <帳號> --port 11120

它註冊兩個 LaunchDaemon——服務本體以一般帳號而非 root 執行，以及一個盯著觸發檔的 restarter， 好讓自我更新任務能在自己的程序樹之外重啟服務。Windows 與 Linux 就用你原本的 init 系統把執行檔 跑起來。

GET /health 會回報 clustered: false。這不是你現在就得規劃的限制——它只是個起點， 日後一次備份加一次還原就能離開。

什麼時候該換：想把資料移出這台機器，或者需要不只一個節點。

單機 + 資料庫

一樣是單一程序，差別在於資料不再是這台機器上的一個檔案。

export ConnectionStrings__Walis='Host=db.internal;Database=walis;Username=walis;Password=…'
export Database__Provider=postgresql
./Walis.Api --urls http://0.0.0.0:11120

Database__Provider 接受 sqlite、postgresql、mysql、sqlserver（也認 postgres、 npgsql、mariadb、mssql、azuresql 這些別名）。不設定的話 Walis 會從連線字串猜； 猜錯的代價是啟動就失敗，比跑到一半才發現方言不合便宜得多。

把既有資料搬過去

備份檔與資料庫種類無關，所以搬家就是一次備份加一次還原：

1. 在 SQLite 的部署上做一次備份——系統設定 → 備份。
2. 把節點指向新的資料庫。
3. 還原備份。還原會先清空目標，所以要在導入流量之前做。

多節點

兩個以上的 API 節點對同一個資料庫，前面放一台負載平衡器。

前提：要用資料庫伺服器，不能是 SQLite。SQLite 是單一檔案，把兩個節點指到同一個檔不會得到 高可用，只會得到損毀的資料，所以 Walis 直接把它視為單節點，不做任何協調。

每個節點給同一組連線字串，各自一個名字：

export ConnectionStrings__Walis='Host=db.internal;Database=walis;Username=walis;Password=…'
export Database__Provider=postgresql
export Database__Node=walis-a          # 不設就用機器名稱
./Walis.Api --urls http://0.0.0.0:11120

確認剛剛是哪一台回應：

GET /health
{ "status": "ok", "database": "PostgreSQL", "node": "walis-a", "clustered": true }

多節點幫你做到的事：

• 建置以原子操作認領。 兩個節點可以搶同一筆佇列中的建置，但只有一個能完成 Queued → Running，另一個直接放手。
• 只該做一次的工作靠租約。 Cron 觸發、離線執行器偵測、保留期限清理與排程備份， 由當下持有租約的節點負責。租約會過期，持有者掛掉之後下一輪自然換人—— 不需要額外跑一個協調服務，也就沒有那個服務可以掛掉。
• 回收只認自己的節點。 節點重啟時只回收自己在跑的建置。

細節與「HA 買不到什麼」記在高可用。

遠端執行器

內建的 local 執行器只跑在 API 那台機器上。要在別處建置——另一種作業系統、另一種架構、 或是放著簽章金鑰的那台機器——就註冊一台執行器。

walis-runner \
  --server https://walis.example.com/ \
  --name builder-01 \
  --labels linux,docker \
  --slots 4 \
  --token walis_xxxxxx_yyyyyyyy

參數	說明
--server	API 位址。環境變數 WALIS_SERVER，預設 http://127.0.0.1:11126。
--name	執行器名稱。環境變數 WALIS_RUNNER_NAME，預設為機器名稱。
--labels	逗號分隔的標籤，純描述用。
--slots	同時可執行的建置數，預設 2，範圍 1–32。
--token	API 金鑰。環境變數 WALIS_TOKEN。啟用登入後必填。
--user / --password	改用帳號密碼登入。認領需要管理員身分，正式環境請改用綁定的金鑰。
--workdir	任務沒指定工作目錄時的預設值。
--interval	輪詢間隔秒數，預設 5，範圍 1–300。

金鑰要綁定執行器名稱。 在帳號頁建立金鑰時綁定這台執行器，它就只能認領與回報這台的建置， 外洩了也拿不到別的東西。

執行器是主動連出的——依你設定的間隔去輪詢 POST /api/runners/{name}/claim——所以建置機器 不必開對外連接埠，也不需要公開位址。回應 204 代表沒有等著的工作；200 會一併帶回規劃好的 步驟與該任務要注入的環境變數。

只有「執行器」欄位指定為這台的任務才會被它認領。沒有指定執行器的任務一律交給內建的 local。

步驟迴圈本機與遠端是同一份程式，所以步驟兩邊行為一致，差別只在寫資料庫還是送 HTTP。