設定開發環境

從原始碼建置 HolyArrs，並在瀏覽器中以 port 6262 開啟它。

開始之前

• Go，版本以 go.mod 指定的為準。
• Node 24 和 npm。
• 一個開在 repo 根目錄的終端機。

你不需要 C 編譯器。建置使用 CGO_ENABLED=0。

建置並執行

1. 安裝 Web App 的套件：

   npm --prefix app/frontend ci

2. 建置 Web App：

   npm --prefix app/frontend run build

   你應該會看到建置完成，而且 app/frontend/dist 裡有了檔案。

3. 建置程式：

   go build -o bin/holyarrs ./app/backend/cmd/holyarrs

4. 用你自己的設定資料夾執行它：

   ./bin/holyarrs -config ./config

5. 開啟 http://localhost:6262。

   你應該會看到首次執行的設定精靈。建立擁有者帳號。

警告

程式會內嵌 app/frontend/dist。Web App 有變更之後，請先重新建置 Web App 再建置程式，否則你看到的還是舊頁面。

-config 接受本機磁碟上的資料夾，預設為 /config。-addr 用來變更監聽位址，預設為 :6262。

開發 Web App

讓程式保持執行。在第二個終端機裡啟動開發伺服器：

npm --prefix app/frontend run dev

開發伺服器會在你儲存時重新載入，並把 API 呼叫送到執行中的程式。你應該會在 2 秒內於瀏覽器中看到你的修改。

選項

使用 Makefile

指令	作用
make ui	安裝 Web 套件並建置 Web App
make build	先 make ui，再建置 bin/holyarrs
make test	以 25 分鐘的逾時時間執行 go test
make vet	go vet ./...
make docker	把 image 建置為 holyarrs:dev
make e2e	執行端對端測試

開啟暫緩的功能

有些功能是暫緩的，預設保持關閉。把它們的名稱寫進 HOLYARRS_FLAGS，以逗號分隔：

HOLYARRS_FLAGS=subtitle_sites,ai_apps ./bin/holyarrs -config ./config

功能關閉時，頁面會隱藏它，它的路由也不存在。使用者可以在 暫緩的功能 讀到相關說明。

用示範資料填滿媒體庫

示範工具會用一組示範收藏填滿設定資料夾。它只能用在已停止的 HolyArrs，而且只能用在你標記為 lab 的資料夾。標記一次就好：

go run ./app/backend/tools/demo seed -config ./config -init-lab

接著 seed -config ./config 會加入示範媒體庫，而 seed -config ./config -reset-demo 只會移除它加入的內容。除非你傳入 -force，否則媒體資料夾必須是 /data/media。開發工具不會放進 image。見 開發工具。

如果沒有成功

症狀。 你改了 Web App 之後，頁面看起來還是舊的。 原因。 程式提供的是它內嵌的那一版建置。 解決方式。 先執行 Web 建置，再執行 Go 建置，然後啟動程式。

症狀。 go build 因為找不到 app/frontend/dist 而失敗。 原因。 Web App 還沒有建置。 解決方式。 先執行步驟 2。

症狀。 程式說 port 已被使用。 原因。 另一個 HolyArrs 或 App 佔用了 6262。 解決方式。 傳入另一個位址：./bin/holyarrs -config ./config -addr :6263。

給進階使用者

暫緩功能的開關

開關	功能
row_title_stats	給擁有者看的探索資料列統計
trakt_lists	Trakt 清單
alert_channels_more	Discord 和 email 以外的通知管道
subtitle_sites	字幕網站與字幕搜尋
emby_signin	使用 Emby 登入
go_back	退回前一個版本的步驟

要新增一個，用 startup.RegisterFeature 註冊它的名稱，並在註冊它的路由之前檢查 startup.FeatureOn。名稱放在 app/backend/internal/core/startup（feature.go）。

開發工具

工具	指令	作用
Demo	go run ./app/backend/tools/demo <command> -config DIR	作用於已停止的設定資料夾。指令：inspect（計數）、fingerprint、query "SELECT ..."（唯讀）、doctor、seed、showcase
假的字幕網站	go run ./app/backend/tools/fakesubs	在 127.0.0.1:18727 為測試提供假的字幕網站。-addr 可以移動它；-accounts-addr 會加入帳號網站的假服務
路由清單	go run ./app/backend/tools/apidoc	重寫 API 路由

建置 image

docker build --file deploy/Dockerfile --tag holyarrs:dev .
docker run -p 6262:6262 -v ./config:/config holyarrs:dev

這個 image 從 FROM scratch 開始，裡面有程式、CA 憑證和授權文件。它執行 -config /config -addr :6262。

相關頁面

• 參與貢獻
• 測試
• 模組