17.7 OpenList

• 功能请求：做成 Port。

安装

官方二进制包

请以普通用户执行：

$ mkdir openlist
$ cd openlist
$ fetch https://github.com/OpenListTeam/OpenList/releases/download/v4.0.8/openlist-freebsd-amd64.tar.gz
$ tar zxvf openlist-freebsd-amd64.tar.gz
$ rm openlist-freebsd-amd64.tar.gz

注意

根据 手动安装 所述及实际测试，无需额外配置后端 OpenList-Frontend。

编译安装（可选）

安装依赖

• 使用 pkg 安装

# pkg install git go

• 或者使用 Ports 安装

# cd /usr/ports/devel/git/ && make install clean
# cd /usr/ports/lang/go/ && make install clean

编译构建

请以普通用户执行：

• 下载源码

$ git clone -b v4.0.8 https://github.com/OpenListTeam/OpenList # 写作本文时，最新版本为 v4.0.8
$ cd OpenList/public/dist
$ fetch https://github.com/OpenListTeam/OpenList-Frontend/releases/download/v4.0.8/openlist-frontend-dist-v4.0.8.tar.gz  # 这是前端部分，官方已经编译好的，注意要和后端版本相对应，即也是 v4.0.8
$ tar zxvf openlist-frontend-dist-v4.0.8.tar.gz  # 解压缩
$ rm openlist-frontend-dist-v4.0.8.tar.gz # 清理垃圾
$ cd ../..

• 开始构建

$ mkdir build
$ cd build
$ go build -ldflags="-w -s" -tags=jsoniter ..

编译后的文件即在 build 下。叫 OpenList，为了方便使用，在以下教程中笔者将其重命名为 openlist。

编写 RC 脚本

创建并编辑 /usr/local/etc/rc.d/openlist：

#!/bin/sh
. /etc/rc.subr

name="openlist"
rcvar="openlist_enable"
command_path=/home/ykla/OpenList     # 可执行文件 openlist 所在目录
command="${command_path}/openlist"   # 命令路径
command_args="start"                 # 启动命令参数
stop_cmd=do_stop                     # 停止命令参数

do_stop()
{
    ${command} stop
}

load_rc_config $name                 # 载入 rc.conf 文件中定义的变量
: ${openlist_enable:=no}             # 如果未设置 openlist_enable 则设为 no
run_rc_command "$1"                  # 运行 service 命令

增加执行权限

# chmod +x /usr/local/etc/rc.d/openlist

使用 openlist 服务

# service openlist enable

增强安全，使用普通用户执行进程（ykla 是我的普通用户名，改成你自己的）：

# sysrc openlist_user=ykla

警告

注意 OpenList 目录的属主和组都必须是 ykla，即你的普通用户名。否则会报错：

FATA[2025-07-06 11:27:56] 1511: failed to open start log file:open /home/ykla/OpenList/daemon/start.log: no such file or directory。

修改命令类似于（修改 OpenList 目录及其中所有文件的属主为 ykla）：

# chown -R ykla:ykla /home/ykla/OpenList

初始化

# service openlist start # 先启动服务
Starting openlist.
INFO[2025-07-06 11:32:41] success start pid: 1566

重置 admin 密码为 1：

root@ykla:/home/ykla/OpenList # ./openlist admin set 1 
INFO[2025-07-06 11:39:39] reading config file: data/config.json        
INFO[2025-07-06 11:39:39] load config from env with prefix: OPENLIST_  
INFO[2025-07-06 11:39:39] init logrus...                               
INFO[2025-07-06 11:39:39] admin user has been updated:                 
INFO[2025-07-06 11:39:39] username: admin                              
INFO[2025-07-06 11:39:39] password: 1  

登录

http://ip:5244，请将 ip 改为你的局域网地址。用户名是 admin。

OpenList in FreeBSD

OpenList in FreeBSD

参考文献

• alist 指定 --data 运行不起作用。

• 另外 start 等静默启动 会强制 --force-bin-dir。对于 start 指定任何 data 均会在后面附带 --force-bin-dir。但是仍然是无效的。

为 OpenList 指定外部播放器（vlc）

地址解码

一组用于对任意数据流进行 URL 编码和解码的工具，可从命令行或标准输入读取数据。我们需要这个 Port 对我们的地址进行解码。

• 使用 pkg 安装：

pkg install urlendec

• 或者使用 Ports 安装：

# cd /usr/ports/net/urlendec/ 
# make install clean

配置 vlc 外部播放器

OpenList 中的内嵌播放器有时不能播放某些视频，但 OpenList 可以通过 URI 调用外部程序（通过 xdg-open )。OpenList 为 vlc 指定的视频地址形如 vlc://http://xxx，只要为 vlc:// 开头的 URI 指定 vlc 程序即可。请自行安装 vlc。

xdg-open 向 vlc 传递 URI 时会包含 vlc:// , vlc 不能打开这样的地址，需要在打开视频地址前先去除，然后调用 vlc，下面是要调用的脚本：

safreya ~ % cat ~/.local/share/applications/vlc-noschema.sh
#!/bin/sh
url="$1"
clean_url='http:'"${url#vlc://http}"           # 去除 vlc:// 头
vlc "$clean_url"

增加执行权限

$ chmod u+x ~/.local/share/applications/vlc-noschema.sh

新建 userapp-xxx.desktop（你只可改动字段 xxx 为你想要的名字，其他字段不可改变。如 userapp-abc.desktop）文件，以便 xdg-open 调用上面的脚本，在本文中为 userapp-vlc.desktop：

safreya ~ % cat ~/.local/share/applications/userapp-vlc.desktop
[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
NoDisplay=true
Exec=/home/safreya/.local/share/applications/vlc-noschema.sh %U
Name=vlc
Comment=Custom definition for vlc

注册 vlc:// URI 的调用程序

$ update-desktop-database ~/.local/share/applications
$ xdg-mime default userapp-vlc.desktop x-scheme-handler/vlc

配置 mpv 外部播放器

mpv-noschema.sh：

safreya ~ % cat ~/.local/share/applications/mpv-noschema.sh
#!/bin/sh
url="$1"
clean_url=$(urldecode "${url#mpv://}")          
vlc "$clean_url"

本机存储的多属主权限管理

以普通用户身份运行服务是一种安全的方式，如上文使用了用户 ykla。

有这样的一种情况，在 OpenList 中挂载的本地目录及其子目录和文件属主并非 ykla：如通过 http 服务上传的目录及文件，通过以 daemon 方式运行的 aria2 或 qBitTorrent 下载的目录及文件，还有其它各种情况。这时访问这些目录及其子目录和文件可能会存在权限问题。

常用的解决方案：

• 通过设置（组和其他）访问权限使 OpenList 的运行用户可以访问。

• 一开始就规划好，使各种可能的服务都使用同一个用户运行，但这个方法比较麻烦，也会让各种服务的专有文件失去隔离性。

上面的方案在属主不同的情况比较少的时候还是可以的，情况多了就不太方便。这时使 bindfs 就比较方便。Bindfs 类似于 nullfs，但在挂载目标目录到其他位置时，你可以覆盖文件的所有权。

安装 bindfs

• 使用 pkg 安装：

# pkg install fusefs-bindfs

• 使用 Ports 安装：

# cd /usr/ports/filesystems/bindfs/
# make install clean

测试用例

• 以普通用户权限运行

$ mkdir -p /home/ykla/extdata/wwwupload 

• 以 root 用户权限运行

# bindfs -u ykla -g ykla /var/www/upload /home/ykla/extdata/wwwupload

这里 /var/www/upload 的属主是 www。

该命令将 /var/www/upload 挂载到了 /home/ykla/extdata/wwwupload。

用户 ykla 在访问 /var/www/upload 时目录下的目录和文件属主维持不变（仍是 www），访问 /home/ykla/extdata/wwwupload 时目录下的目录和文件属主都认为是 ykla。这时 OpenList 只要用本机存储挂载 /home/ykla/extdata/wwwupload 即可轻松解决访问权限问题。

也可以用 --map 选项，使用类似于 NFS 的 UID/GID 映射机制（用于将某些用户/组映射成其他的用户/组），这在某些时候可能是更好的选择。

参考文献

• 具体用法参考 bindfs

影视刮削

此方案使用 zsh，请自行安装。

此处的刮削意指获取本地多媒体文件的相关信息，如海报，制作人信息，配音，字幕等周边内容。

OpenList 未内置原生的刮削功能。

但是利用好 OpenList 的 markdown（top.md、bottom.md、readme.md）就能提供简单的刮削功能。

使用 inotify-tools 监控目录

inotify-tools 为 shell 脚本提供了用于文件系统事件的简单接口。

安装 inotify-tools

• 使用 pkg 安装：

# pkg ins inotify-tools

• 还可以使用 Ports 安装：

# cd /usr/ports/sysutils/inotify-tools/ 
# make install clean

监按脚本

#!/usr/bin/zsh

zmodload zsh/datetime

WATCH_DIR="/home/ykla/extdata/media"
EVENTS="create,moved_to" # 监控事件类型
ACTION_SCRIPT="/home/ykla/searchtmdb.zsh" # 刮削脚本位置

inotifywait -m -r --format "%w%f %e" -e "$EVENTS" "$WATCH_DIR"| while read -r target event
do
        timestamp=$(strftime '%F %T')
        echo "[${timestamp}]${event}:${target}" >>dir.log
        echo "${event}"|grep -q 'ISDIR'
        if [[ $? == 0 ]];then
           zsh "$ACTION_SCRIPT" >>dir.log
        fi
done

在后台启用监控脚本

$ nohup  ./monitor.zsh &

或

$ ./monitor.zsh & # 这里按回车，再输入下面的 disown
disown # 从 shell 分离进程

参考文献

• inotifywait 用法参见 inotifywait

写入刮削的信息

将刮削的信息写入视频所在目录下的 top.md 等文件。

tmdb 在国内是可用的，但会受到 dns 污染，解决 dns 污染即可。具体刮削脚本参见 https://gist.github.com/ykla/91e27db14e68ba60903e97fe1c437246。

效果如下：

OpenList in FreeBSD

OpenList in FreeBSD

故障排除与未竟事宜

日志

OpenList 的日志在 daemon/start.log。

bindfs 的 fstab 挂载

待解决

bindfs 的多线程模型有缺陷

如果 bindfs 以多线程模式运行（使用 --multithreaded 选项），可能存在安全问题。

待解决。