跳到正文

命令行 ​

Keepbay 程序自带一套管理命令。首次设置、安装系统服务、查看状态、检查环境、更新、重设密码、备份和恢复数据库、重新扫描文件夹,都可以在终端中完成。

无法登录网页时(忘记密码、两步验证所用的手机丢失、帐号被锁定),也可以用命令行处理。

基本用法 ​

bash
keepbay                        # 按分组列出全部命令
keepbay help <命令>            # 查看命令的详细用法,同 keepbay <命令> --help
keepbay <命令> [选项] [参数]

下文的 keepbay 指安装目录中的程序。按安装中的布局,命令要以运行服务的用户执行:

bash
sudo -u keepbay /opt/keepbay/keepbay status

建议都用这个用户运行。服务在运行时,root 也能通过控制通道执行在线命令。

但服务没有运行、命令需要直接打开数据库,而数据目录又属于其他用户时,root 会被拒绝。因为命令新建的文件会属于 root,之后服务将无法读写这些文件,所以 Keepbay 会提示您换成数据目录所属的用户。

安装、卸载系统级服务(setup 最后一步、service:install、service:uninstall)要以 root 运行;用普通用户运行时,安装的是这个用户自己的服务。

通用选项 ​

选项说明
-h、--help显示命令的用法
-n、--no-interaction不弹出交互:缺参数时直接报错
--data-dir 目录数据目录,也可以用环境变量 KEEPBAY_DATA_DIR;不写时 Linux 用 /var/lib/keepbay

交互和退出码 ​

只有输入和输出都是终端、并且没有加 -n 时,缺少的参数才会在终端里弹出选择或输入框。在脚本中运行时,缺参数直接报错,并显示该命令的用法。

会改动数据的命令(如 user:reset-password、db:restore)在终端里先确认,加 --force 跳过确认。

退出码含义
0成功
1执行失败,原因输出到标准错误
2用法错误:没有这个命令、缺参数、选项不正确
130按 Ctrl+C 中断,或在确认时取消

在线命令和离线命令 ​

数据库同一时间只能由一个进程写入,服务运行时,命令行不能直接修改数据库。

因此命令行会先尝试连接数据目录中的控制通道 keepbay.sock:连接成功时交给服务执行,连接失败时由命令行自己执行。按命令的性质分三类:

类型命令
在线命令:服务在运行时由服务执行,未运行时由命令行执行status、doctor、user:list、user:unlock、user:2fa-off、db:backup、db:check、mount:list、index:status、update:check
离线命令:要独占数据库,必须先停止服务user:reset-password、db:restore、db:vacuum
只能由运行中的服务执行index:rescan、setup:token、update

控制通道的权限是 0600,服务只接受同一用户或 root 的连接。

数据目录的路径太长时(系统对 socket 路径的长度有限制)不创建控制通道,这时在线命令要先停止服务再运行。

命令一览 ​

安装与服务

命令说明
setup在终端里完成首次设置:数据目录、端口、所有者帐号,可安装为系统服务
setup:token显示首次设置的令牌(还没有完成设置时)
service:install安装为系统服务,开机自动启动
service:uninstall卸载系统服务,数据目录不删除
status查看服务是否在运行、地址、版本、数据库和备份
doctor检查依赖、沙箱、目录权限和端口
update:check检查有没有新版本
update更新到新版本
serve启动服务(由系统服务调用,一般不需要手动运行)
version显示版本

帐号

命令说明
user:list列出全部用户:用户名、名称、身份、两步验证、状态
user:reset-password忘记密码时重设(需要先停止服务)
user:unlock解除登录锁定
user:2fa-off关闭两步验证

数据库

命令说明
db:backup立即备份数据库
db:restore用备份恢复数据库(需要先停止服务)
db:check完整检查数据库
db:vacuum压缩数据库(需要先停止服务)

索引与文件夹

命令说明
mount:list列出文件夹、在线状态和文件数
mount:grant给运行 Keepbay 的用户访问文件夹的权限
index:rescan重新扫描文件夹
index:status查看后台任务各阶段的进度

启动参数 ​

keepbay serve 启动服务。启动参数只有启动前必须知道的几项,其余设置都存在数据库中,在网页上修改。

选项环境变量默认值说明
--listenKEEPBAY_LISTEN0.0.0.0:8899监听地址
--data-dirKEEPBAY_DATA_DIR/var/lib/keepbay数据目录
--trusted-proxiesKEEPBAY_TRUSTED_PROXIES空可信反向代理的 IP 或网段,逗号分隔,见外网访问
--base-pathKEEPBAY_BASE_PATH/部署的子路径,如 /keepbay/,见外网访问
--log-levelKEEPBAY_LOG_LEVELinfo日志级别:debug、info、warn、error

优先级:命令行参数 > 环境变量 > 默认值。

另有 --license-server、--model-manifest 两项(授权中心和远程模型清单的地址),一般不需要设置。

装成系统服务后,监听地址和数据目录写在服务文件的启动命令中。其他参数建议用环境变量追加,升级时不会被覆盖:

bash
sudo systemctl edit keepbay
ini
[Service]
Environment=KEEPBAY_TRUSTED_PROXIES=127.0.0.1,::1
Environment=KEEPBAY_LOG_LEVEL=debug
bash
sudo systemctl restart keepbay

日志同时写到数据目录的 logs/keepbay.log 和标准错误(systemd 下用 journalctl -u keepbay 查看)。单个文件 5 MB 后换新文件,保留 3 个旧文件。

程序崩溃的信息另外写到 logs/crash.log。

安装与服务 ​

setup ​

代替浏览器中的设置向导:选择数据目录和端口、创建所有者帐号,最后可以安装为系统服务。

服务已经在运行时,只创建所有者帐号。

bash
# 以 root 运行,服务以 keepbay 用户运行
sudo /opt/keepbay/keepbay setup --user keepbay

# 在脚本中运行:用户名和密码都要写明
echo "$PASSWORD" | sudo /opt/keepbay/keepbay setup --username admin --password-stdin --service --user keepbay
选项说明
--listen 地址服务的监听地址,默认 0.0.0.0:8899
--username 用户名所有者的用户名:字母、数字和 . _ -
--display-name 名称显示在网页上的名称,默认同用户名
--password-stdin从标准输入读取所有者的密码(一行)
--service设置完成后安装为系统服务
--user 用户以 root 运行时,指定运行服务的系统用户

各步骤的说明见首次设置。

setup:token ​

显示设置向导的令牌。令牌在服务启动时生成,只保存在服务的内存中,因此服务需要处于运行状态。

已经完成设置时,输出"已经完成首次设置"。

service:install ​

安装为系统服务并立即启动。Linux 用 systemd,macOS 用 launchd。

以 root 运行时安装为系统级服务(开机即启动,以 --user 指定的用户运行),否则安装为当前用户的服务。

选项说明
--user 用户以哪个系统用户运行服务;以 sudo 运行时默认是运行 sudo 的用户
--listen 地址服务的监听地址,默认 0.0.0.0:8899
--force已经安装过时直接覆盖并重启服务,不再确认

以 root 安装系统级服务时,会把数据目录交给运行服务的用户。数据目录不能是符号链接,上级目录要让这个用户能进入。

生成的 systemd 服务文件在 /etc/systemd/system/keepbay.service:

ini
[Unit]
Description=Keepbay
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=keepbay
Group=keepbay
ExecStart=/opt/keepbay/keepbay serve --data-dir /var/lib/keepbay --listen 0.0.0.0:8899
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
LockPersonality=true
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

服务文件中没有 ProtectHome、ProtectSystem=strict。您的文件夹可能在 /home、/mnt、/media 等任何地方,加上这两项会导致服务无法读取这些文件夹。

系统没有使用 systemd 时(如部分 NAS)不能安装,会提示按安装文档手动配置开机启动,见安装。

service:uninstall ​

停止服务、取消开机启动并删除服务文件。数据目录不会删除。加 --force 不再确认。

status ​

显示服务是否在运行、访问地址(监听所有网卡时列出 localhost 和局域网地址)、启动时间、版本、数据目录、数据库大小、上次备份的时间或失败原因、磁盘剩余空间。

命令行与服务的版本不同时,会提示"重启服务后生效"。还没有完成首次设置时,提示运行 keepbay setup 或在浏览器中打开地址。

doctor ​

检查运行环境,分三部分输出:

部分检查内容
目录数据目录、logs/、backups/ 是否存在、能否写入;权限比 0700 宽时提示其他用户能读到数据库
端口服务在运行时确认正在监听;未运行时尝试监听 --listen 指定的地址,报告是否被占用、是否没有权限(1024 以下的端口要 root)
依赖libvips、ffmpeg、沙箱、ONNX Runtime、yt-dlp

依赖各项的结果:

依赖说明
libvips处理照片,随安装包提供。缺 libraw 时相机 RAW 照片只用内嵌预览,缺 librsvg 时 SVG 没有缩略图
ffmpeg可选,系统中自行安装。没有时视频没有缩略图、TS 视频不能在线播放、HEIC 照片不能显示,版本要求见安装。不检查实况照片视频的转码,是否可用见「系统设置 › 媒体处理」
沙箱处理不可信文件的子进程所用的系统调用过滤和 Landlock,见隐私与安全
ONNX Runtime本地 AI 模型的运行库,不在安装包中,在网页的「系统设置 › AI 模型」中下载
yt-dlp可选。没有时不能从视频网站离线下载

沙箱一项:

结果含义
正常系统调用过滤和 Landlock 都已启用
部分可用系统调用过滤已启用,Landlock 没有启用(要 Linux 7.0 及以上的内核)。不影响使用
不可用系统调用过滤没有启用(内核不支持 seccomp,见于部分 NAS):不生成缩略图、不做需要服务端转换的预览、不识别图片中的文字;浏览器能直接显示的图片和视频照常预览

内核不支持 seccomp、所有者打开了「照样处理照片和视频」时,这一项也显示"部分可用",安全性降低,见隐私与安全。

数据目录不能写入、端口不能使用时,退出码为 1;可选依赖没有安装只提示。

服务在运行时,依赖由服务检测,与服务的实际情况一致。

update:check 和 update ​

update:check 向授权中心查询已发布的版本,有新版本时显示版本号、发布时间和更新日志。

update 先检查新版本,确认后由运行中的服务下载、核对、切换到新版本并重新启动,与网页上「系统设置 › 维护」中的「立即更新」相同。

服务需要处于运行状态;加 --force 不再确认。过程和不能自动更新的情况见升级。

帐号 ​

user:list ​

列出全部用户。状态一列可能是:正常、已停用、已暂停(免费版的用户数已满)、锁定到某个时间。

user:reset-password ​

忘记密码时使用。设置一个随机的新密码并显示出来,同时关闭两步验证、解除登录锁定、退出所有设备上的登录。

要先停止服务:

bash
sudo systemctl stop keepbay
sudo -u keepbay /opt/keepbay/keepbay user:reset-password alice
sudo systemctl start keepbay

登录后请尽快修改密码,并重新开启两步验证。

user:unlock ​

登录失败次数过多导致帐号被锁定时使用:解除锁定,之前的失败不再计数。服务在运行时也可以执行。

user:2fa-off ​

手机丢失、恢复码也找不到时使用:关闭两步验证,之后只需密码即可登录。

不会退出已有的登录。服务在运行时也可以执行。

所有者无法登录时

  • 忘记密码:停止服务,运行 user:reset-password(同时关闭两步验证)
  • 记得密码,但无法完成两步验证:运行 user:2fa-off,无需停止服务
  • 被锁定:运行 user:unlock,或者等待锁定时间结束

数据库 ​

db:backup ​

立即备份数据库,写到备份设置中的目录(默认是数据目录下的 backups/),并按保留份数清理旧的备份。

备份用 SQLite 的 VACUUM INTO 生成完整的副本,服务运行时也可以执行,不影响使用。

备份的文件名:

文件名来源
keepbay-auto-<时间>.db自动备份
keepbay-manual-<时间>.db立即备份(网页上的按钮或 db:backup)
pre-migrate-<时间>-v<版本>.db升级数据库前
before-restore-<时间>.db用 db:restore 恢复前

db:restore ​

用备份恢复数据库,要先停止服务。不指定备份文件时,在终端中列出所有备份供选择。

bash
sudo systemctl stop keepbay
sudo -u keepbay /opt/keepbay/keepbay db:restore /var/lib/keepbay/backups/keepbay-auto-20261101-030012.db
sudo systemctl start keepbay

恢复的过程:

  1. 把备份复制到临时文件并检查:数据库完整、确实是 Keepbay 的数据库、版本不比当前程序新(比程序新时先升级 Keepbay)
  2. 把现在的数据库保存为 backups/before-restore-<时间>.db
  3. 通过一次改名替换为新数据库:中途中断时,数据库要么是原来的,要么是恢复后的,不会处于不完整的状态

备份文件本身不会被改动。旧版本的备份在下次启动时自动升级到当前版本。

secret.key 不在备份中

恢复到另一台设备时,请把数据目录中的 secret.key 一并复制过去,否则 AI 厂商的 API Key 等配置要重新填写,开了两步验证的帐号要用恢复码登录。详见备份和维护。

db:check ​

逐页核对数据库的结构和索引,数据库较大时需要几分钟。

发现问题时列出问题(最多 100 个),退出码为 1,可以用 db:restore 从备份恢复。

db:vacuum ​

回收删除数据后留下的空间,要先停止服务。

通常不需要运行,SQLite 会自动复用这些空间。删除了大量文件或更换过向量模型后,如需缩小数据库文件,可以运行这个命令。

索引与文件夹 ​

mount:list ​

列出已添加的文件夹:ID、名称、路径、状态、文件数、上次扫描。

状态是在线、正在扫描或离线。离线时附原因,如目录不存在、磁盘没有连接、目录突然变空;远程文件夹另有无法连接远程存储、存储位置不存在、访问密钥被拒绝或无法解密、服务器的主机指纹变了(SFTP)。服务未运行时,显示的是停止前记录的状态。

mount:grant ​

给运行 Keepbay 的用户访问一个文件夹的权限,添加文件夹之前运行。只支持 Linux,要以 root 运行。

bash
sudo /opt/keepbay/keepbay mount:grant /srv/photos
sudo /opt/keepbay/keepbay mount:grant --read-only /srv/photos
选项说明
--read-only只授予读取权限,添加文件夹时选择只读方式的使用这个选项
--user授权给哪个系统用户,默认是数据目录的所有者,也就是运行服务的用户

它会设好文件夹及其中全部文件的权限、以后新建文件的默认权限,上级目录缺少进入权限的也会补上。无需另外安装 acl,不改动文件的所有者和原有权限。

这个命令不访问数据库,服务运行时也可以使用。中途按 Ctrl + C 中断后,再运行一次会继续设置。其他说明见安装。

index:rescan ​

重新扫描文件夹,参数写文件夹的名称或 ID,可以写多个;--all 扫描全部。

只能由运行中的服务执行。

bash
sudo -u keepbay /opt/keepbay/keepbay index:rescan 照片 文档
sudo -u keepbay /opt/keepbay/keepbay index:rescan --all

一般不需要手动扫描:本地磁盘上的改动会实时监听,另有定期补扫,见技术架构。

在 SMB 共享上一次修改了大量文件、需要立即更新索引时,可以手动扫描。

index:status ​

查看后台任务各阶段的进度(已完成 / 总数、失败数)。

阶段包括扫描、识别内容、生成缩略图、提取文字、识别图片中的文字、生成向量、打 AI 标签。服务未运行时显示停止时的进度,启动后继续。