Seafile 12.0.14 常用 CLI 命令详解

目标：把 Seafile CE 12.0.14 的命令行工具一次讲全——服务端启停脚本（seafile.sh/seahub.sh）、维护脚本（seaf-gc.sh/seaf-fsck.sh/seaf-fuse.sh/reset-admin.sh）、内置二进制清单，以及客户端 seaf-cli 的全部子命令，每条命令配 Ubuntu 22.04.5 实测回显与踩坑提示。安装与配置见《Ubuntu 22.04 安装 Seafile 指南》、《Seafile 12.0.14 配置参数详解》。

一、环境信息

本章列出本篇命令实测环境的基线：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Seafile：社区版（CE）12.0.14，安装根目录 /opt/seafile（版本目录 seafile-server-12.0.14，符号链接 seafile-server-latest 指向它）
服务由 systemd 托管：seafile.service 与 seahub.service（active）
演示服务器地址：http://10.89.59.2；Seahub 端口 8130、FileServer 8131
数据库：MariaDB 10.6.23；管理员 admin@seafile.local/q1w2e3r4
客户端：seaf-cli 8.0.5-1（官方 deb 源安装，与 12.0.14 服务端同机演示）

二、工具概览

先给全景：12.0.14 的命令行工具分三层（实测目录与文件清单见 4.7）：

层	工具	用途
服务端包装脚本（`/opt/seafile/seafile-server-latest/`）	`seafile.sh`	存储引擎启停（start/stop/restart）
同上	`seahub.sh`	Web 应用启停与首次建管理员
同上	`seaf-gc.sh`	垃圾块回收
同上	`seaf-fsck.sh`	资料库一致性检查/修复/导出
同上	`seaf-fuse.sh`	把资料库挂载为本地文件系统
同上	`reset-admin.sh`	重置/重建管理员账号
同上（内部，不直接调用）	`seafile-monitor.sh`、`check_init_admin.py`、`migrate_ldapusers.py`	监控守护/建号辅助/LDAP 用户迁移
服务端二进制（`seafile/bin/`）	`seaf-server`、`seafile-controller`、`fileserver` 等	实际进程，由脚本拉起，不手动调用
客户端	`seaf-cli`	命令行同步客户端（init/start/download/status…）

关键差异解读：日常运维 90% 只用 systemctl + seafile.sh/seahub.sh；gc/fsck/fuse 属低频维护工具；seaf-cli 是装在另一台（或同台）Linux 机器上的客户端，与服务端无关。

三、前置条件

3.1 服务端侧

已按安装篇完成安装并 systemd 托管（验证实测回显）：

systemctl is-active seafile.service
systemctl is-active seahub.service

active
active

3.2 客户端 seaf-cli 的安装

seaf-cli 只在官方 deb 源提供（PyPI 无此包，实测 pip install seaf-cli 报 No matching distribution found）。写入官方源（实测源定义，[trusted=yes] 原因见下）：

echo "deb [trusted=yes] https://linux-clients.seafile.com/downloads/deb/ubuntu/seafile-official jammy main" > /etc/apt/sources.list.d/seafile.list
apt update
apt install -y seafile-cli

⚠️ 实测踩坑：该源不带 [trusted=yes] 时 apt update 会报证书告警（实测回显）：

W: Failed to fetch https://linux-clients.seafile.com/downloads/deb/ubuntu/seafile-official/dists/jammy/InRelease  Certificate verification failed: The certificate is NOT trusted. The name in the certificate does not match the expected.  Could not handshake: Error in the certificate verification. [IP: 3.86.184.216 443]

安装结果验证（实测回显）：

dpkg -l seafile-cli | tail -1

ii  seafile-cli    8.0.5-1      all          Client CLI for the Seafile Client

四、各工具详解

4.1 seafile.sh：存储引擎启停

无参数时打印用法（实测回显）：

bash /opt/seafile/seafile-server-latest/seafile.sh


usage :
seafile.sh { start | stop | restart }

restart 实测（会依次执行 stop 与 start 流程）：

cd /opt/seafile/seafile-server-latest
./seafile.sh restart


Stopping seafile server ...
Cannot find JWT_PRIVATE_KEY value from environment, try to read .env file.
Starting seafile server, please wait ...
Seafile server started

Done.

验证存储引擎在监听（实测回显）：

ss -tlnp | grep 8131

LISTEN 0      128          0.0.0.0:8131       0.0.0.0:*    users:(("seaf-server",pid=8321,fd=10))

⚠️ 实测坑：手动重复 ./seafile.sh start 会报 Seafile monitor is already running, pid xxxx 并退出 1（monitor 进程已存在）；由 systemd 托管后应统一用 systemctl 控制，避免脚本与 systemd 打架。

4.2 seahub.sh：Web 应用启停

无参数时打印用法（实测回显，端口为可选参数）：

bash /opt/seafile/seafile-server-latest/seahub.sh


Usage:

  seahub.sh { start <port> | stop | restart <port> }

<port> is optional, and defaults to 8000

首次启动交互建管理员（实测回显，问题原文）：

cd /opt/seafile/seafile-server-latest
./seahub.sh start

Starting seahub at port 8000 ...

----------------------------------------
It's the first time you start the seafile server. Now let's create the admin account
----------------------------------------

What is the email for the admin account?
[ admin email ]
What is the password for the admin account?
[ admin password ]
Enter the password again:
[ admin password again ]

输入 admin@seafile.local/q1w2e3r4/q1w2e3r4 后成功回显（实测）：

Successfully created seafile admin

gunicorn 起动标志（实测回显节选，改绑 8130 后）：

[2026-10-22 02:15:01 +0000] [6486] [INFO] Starting gunicorn 23.0.0
Listening at: http://0.0.0.0:8130

⚠️ 两条实测坑：① 重复启动报 Error: Already running on PID 6395 (or pid file '/opt/seafile/pids/seahub.pid' is stale)——确认无进程后删 /opt/seafile/pids/seahub.pid 再启动；② seahub.sh 依赖 monitor 进程判断服务端状态，先启 seahub 会报 Warning: seafile server not running. Have you run ./seafile.sh start?——必须先 seafile 后 seahub。依赖问题（ModuleNotFoundError: sqlalchemy）与 PYTHON=/usr/bin/python3.11 的解法见安装篇 4.8/4.12。

4.3 reset-admin.sh：重置/重建管理员

忘记管理员密码时用它重建（本例用相同账号密码重跑，实测回显）。脚本交互三问，管道喂三行答案：

cd /opt/seafile/seafile-server-latest
printf 'admin@seafile.local\nq1w2e3r4\nq1w2e3r4\n' | bash reset-admin.sh

E-mail address:
Password:
Password (again):
Superuser created successfully.

💡 说明：回显中伴随 GetPassWarning: Can not control echo on the terminal 与 Warning: Password input may be echoed. 属管道喂入时的正常告警；在真实终端交互执行则无此告警。若原管理员已存在，该脚本会按输入重建同名账号（密码覆盖语义），执行后用新密码登录验证。

4.4 seaf-gc.sh：垃圾块回收

删除资料库后，其占用的文件块不会立即物理删除，用 gc 回收。用法（--help 实测回显）：

cd /opt/seafile/seafile-server-latest
bash seaf-gc.sh --help


usage :
seaf-gc.sh [--dry-run | -D] [--rm-deleted | -r] [repo-id1] [repo-id2]

参数说明：--dry-run/-D 只统计不删除（推荐先用）；--rm-deleted/-r 同时清回收站内容；[repo-id...] 可只回收指定资料库，省略则全库。⚠️ 完整 gc 流程未在本环境实跑；生产执行前先停 seahub/seafile 服务并备份数据目录。

4.5 seaf-fsck.sh：资料库检查/修复/导出

用法（--help 实测回显）：

cd /opt/seafile/seafile-server-latest
bash seaf-fsck.sh --help


usage :
seaf-fsck.sh [-h/--help] [-r/--repair] [-E/--export path_to_export] [repo_id_1 [repo_id_2 ...]]

参数说明：不带参数=只检查全部资料库；-r=检查并修复；-E <目录>=把指定资料库导出为普通文件树（数据抢救用）；[repo_id...] 指定库。⚠️ 完整 fsck 流程未在本环境实跑；修复属写操作，执行前务必停服备份。

4.6 seaf-fuse.sh：挂载为本地文件系统

用法（--help 实测回显）：

cd /opt/seafile/seafile-server-latest
bash seaf-fuse.sh --help


usage :
seaf-fuse.sh { start <mount-point> | stop | restart <mount-point> }

说明：start <挂载点> 把资料库以 FUSE 方式挂到本地目录只读访问；需要系统安装 fuse 内核支持。⚠️ 挂载流程未在本环境实跑（依赖宿主 fuse 支持）；使用前确认 /dev/fuse 可用。

4.7 bin 内置二进制清单

服务端实际进程都在 seafile/bin/ 下（实测清单）：

ls /opt/seafile/seafile-server-12.0.14/seafile/bin/

fileserver
parse_seahub_db.py
seaf-fsck
seaf-fuse
seaf-server
seafile-admin
seafile-controller
seafserv-gc
searpc-codegen.py

seaf-server/seafile-controller/fileserver/seafserv-gc/seaf-fsck/seaf-fuse 是进程与维护工具本体（gc/fsck/fuse 由同名包装脚本设置好环境后调用）；seafile-admin、parse_seahub_db.py、searpc-codegen.py 为辅助/开发工具。⚠️ 实测坑：不要直接调用 bin 下的二进制——缺自带库路径会报错（实测回显）：

/opt/seafile/seafile-server-12.0.14/seafile/bin/seaf-fsck: error while loading shared libraries: libcrypto.so.1.1: cannot open shared object file: No such file or directory

包装脚本会 export SEAFILE_LD_LIBRARY_PATH=<版本目录>/seafile/lib/... 解决该问题，所以统一走包装脚本。

4.8 seaf-cli：命令行同步客户端

总览（--help 实测全量回显）：

seaf-cli --help

usage: seaf-cli [-h]
                {init,start,stop,list,list-remote,status,download,download-by-name,sync,desync,create,config}
                ...

options:
  -h, --help            show this help message and exit

subcommands:

  {init,start,stop,list,list-remote,status,download,download-by-name,sync,desync,create,config}
    init                Initialize config directory
    start               Start seafile daemon
    stop                Stop seafile daemon
    list                List local libraries
    list-remote         List remote libraries
    status              Show syncing status
    download            Download a library from seafile server
    download-by-name    Download a library defined by name from seafile server
    sync                Sync a library with an existing foler
    desync              Desync a library with seafile server
    create              Create a library
    config              Configure seafile client

典型流程实测（服务端同机演示，-c 客户端配置目录，-d 下载目录）：

seaf-cli init -c /root/seafile-client -d /root/seafile-client

Writen seafile data directory /root/seafile-client/seafile-data to /root/seafile-client/seafile.ini
New device id created

⚠️ 实测坑：init 的两个目录必须事先不存在，否则报 already exists；Writen 为官方脚本原文拼写（非笔误）。

seaf-cli start -c /root/seafile-client

Starting seafile daemon ...
Started: seafile daemon ...

seaf-cli download -l 9762efe0-96d5-4406-adcb-cfaf5205f6ea -s http://127.0.0.1:8130 -d /root/Documents -c /root/seafile-client -u admin@seafile.local -p q1w2e3r4

Starting to download ...
Library 9762efe0-96d5-4406-adcb-cfaf5205f6ea will be downloaded to /root/Documents

（-l 为资料库 ID，可从 Web 端资料库链接或 seaf-cli list-remote 获取。）

seaf-cli stop -c /root/seafile-client

daemon 未启动时直接跑 list/status 会报 RPC 错误（实测回显首行）：

Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/pysearpc/named_pipe.py", line 85, in _get_transport
    transport = self._pool.get(False)

⚠️ 兼容性实测：本环境 seaf-cli 8.0.5-1 连接 12.0.14 服务端，download 能建立任务但 status 显示 Docs error Cannot connect to server——客户端 daemon 与 12.0 服务端的连接存在兼容性问题。排查方向：确认服务端 8130/8131 两端口可达、SERVICE_URL 正确、客户端与服务端版本组合做升配实测。生产使用前务必先验证你当前客户端/服务端版本组合。

五、注意事项

启动顺序：seafile.service → seahub.service（systemd 单元 After= 已固化；手动跑脚本时必须遵守）；
用 systemd 而不是裸脚本：Type=oneshot + RemainAfterExit=yes 已适配脚本行为，日常一律 systemctl start/stop/restart，避免 monitor/pid 残留冲突；
seaf-server 重启后的连带动作：存储引擎重启后 RPC socket 会更换，gunicorn 侧持有的旧连接失效，未重启 seahub 时经 Web API 取上传链接会报 500（Page unavailable）——重启过 seafile 后顺手 systemctl restart seahub.service；
维护工具先停服：gc/fsck 属写操作，执行前停 seahub/seafile 并备份 /opt/seafile/seafile-data 与三个数据库；
配置相关：参数含义与生效方式见《Seafile 12.0.14 配置参数详解》，改配置后按对应单元重启。

六、常见问题（FAQ）

Q1：seaf-cli list/status 报 pysearpc named pipe Empty traceback daemon 没在跑。先 seaf-cli start -c <配置目录> 再执行查询类子命令。

Q2：seaf-cli download 建立任务后 status 显示 error Cannot connect to server seaf-cli 8.0.5 与 12.0.14 服务端存在连接兼容性问题（实测复现）。排查：两端口可达性、SERVICE_URL、换用桌面客户端或与官方论坛确认版本兼容矩阵。

Q3：systemctl start seafile.service 报 Seafile monitor is already running, pid xxxx 此前手动 ./seafile.sh start 过。先 ./seafile.sh stop 或 systemctl stop seafile.service，再由 systemd 启动。

Q4：Error: Already running on PID 6395 (or pid file '/opt/seafile/pids/seahub.pid' is stale) 重复启动或 pid 残留。确认无 gunicorn 进程后删除 /opt/seafile/pids/seahub.pid 再启动；长期方案交给 systemd。

Q5：直接执行 seafile/bin/ 下工具报 error while loading shared libraries: libcrypto.so.1.1 ... 缺自带库路径。统一使用 seaf-gc.sh/seaf-fsck.sh/seaf-fuse.sh 包装脚本（内部已 export 库路径）。

Q6：reset-admin.sh 在脚本/管道里执行报 termios 相关 traceback 脚本用 getpass 读密码，非交互终端会回退并告警；按 4.3 用 printf 喂三行（邮箱、密码、确认密码）即可，出现 Superuser created successfully. 即成功。

七、参考链接

官方手册（Seafile CLI 客户端文档）：https://manual.seafile.com/
Linux 客户端下载（seaf-cli deb 源）：https://linux-clients.seafile.com/
GitHub 仓库：https://github.com/haiwen/seafile
官方论坛：https://forum.seafile.com/
站内延伸：《Seafile 介绍与选型指南》、《Ubuntu 22.04 安装 Seafile 指南》、《Seafile 12.0.14 配置参数详解》