环境搭建

从源码构建 HolyArrs，然后在浏览器里通过端口 6262 打开它。

开始之前

• Go，版本以 go.mod 里写的为准。
• Node 24 和 npm。
• 一个位于仓库根部的终端。

不需要 C 编译器。构建用的是 CGO_ENABLED=0。

构建并运行

1. 安装 Web 应用的依赖包：

   npm --prefix app/frontend ci

2. 构建 Web 应用：

   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 应用之后，要先重新构建 Web 应用，再构建程序，不然看到的还是旧页面。

-config 接受一个本地磁盘上的文件夹，默认是 /config。-addr 用来改监听地址，默认是 :6262。

开发 Web 应用

让程序一直运行着。在第二个终端里启动开发服务器：

npm --prefix app/frontend run dev

开发服务器会在保存时重新加载，并把 API 调用发给正在运行的程序。你应该会在 2 s 内在浏览器里看到你的改动。

选项

使用 Makefile

命令	作用
make ui	安装 Web 依赖包并构建 Web 应用
make build	先 make ui，再构建 bin/holyarrs
make test	带 25 分钟超时的 go test
make vet	go vet ./...
make docker	把镜像构建为 holyarrs:dev
make e2e	运行端到端测试

打开一个暂未开放的功能

有些功能暂未开放，默认关着。在 HOLYARRS_FLAGS 里写上它们的名字，用逗号分隔：

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

功能关着时，页面会隐藏它，它的路由也不存在。用户可以在暂未开放的功能里读到相关说明。

用演示数据填充媒体库

演示工具会往一个配置文件夹里填入一套演示收藏。它只能用在已停止的 HolyArrs 上，而且只能用在你标记为实验环境的文件夹上。标记一次就行：

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

之后 seed -config ./config 会添加演示媒体库，seed -config ./config -reset-demo 只会删掉它添加的内容。媒体文件夹必须是 /data/media，除非你传入 -force。开发工具不会进镜像。见开发工具。

如果不成功

现象。 改了 Web 应用之后，页面看起来还是旧的。 原因。 程序提供的是它内嵌的那份构建。 解决办法。 先运行 Web 构建，再运行 Go 构建，然后启动程序。

现象。 go build 因为缺少 app/frontend/dist 而失败。 原因。 Web 应用还没有构建。 解决办法。 先做第 2 步。

现象。 程序提示端口已被占用。 原因。 另一个 HolyArrs 或别的应用占着 6262。 解决办法。 传入另一个地址：./bin/holyarrs -config ./config -addr :6263。

进阶

暂未开放功能的开关

开关	功能
plex_watchlists	Plex 待看列表变成请求
row_title_stats	给所有者看的探索页各行统计
trakt_lists	Trakt 列表
alert_channels_more	Discord 和邮件之外的通知渠道
subtitle_sites	字幕站和字幕搜索
emby_signin	用 Emby 登录
go_back	回退到上一个版本的步骤

要加一个开关，先用 startup.RegisterFeature 注册它的名字，并在注册它的路由之前检查 startup.FeatureOn。这些名字放在 app/backend/internal/core/startup（feature.go）里。

开发工具

工具	命令	作用
演示	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 路由

构建镜像

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

镜像以 FROM scratch 开头，里面有程序、CA 证书和许可证。它运行 -config /config -addr :6262。

相关页面

• 参与贡献
• 测试
• 模块