Pydio Cells 常用 CLI 命令详解

目标：把 Pydio Cells 5.1.0 的官方命令行工具 cells 的常用子命令逐条讲清——每个命令给出真实输入与实测回显（Ubuntu 22.04 实机执行，实测日期 2026-10-22），覆盖主命令、服务管理、安装配置、用户管理、配置管理、文件与元数据操作、数据源维护、ACL 查询及更新迁移等，并以实测口径标注每个命令的行为边界与坑点。安装与环境背景见 《Ubuntu 22.04 安装 Pydio Cells 指南》，配置文件含义见 《Pydio Cells 配置参数详解》。

一、环境信息

二、工具概览

cells 是单二进制多子命令工具。cells --help 实测的子命令清单：

全局旗标（实测 help 原文）：--cluster（节点所属集群名，默认 default）、--config（配置存储 URL，默认 file:///var/cells/pydio.json，支持 etcd|file|grpc|mem|vault|vaults|xds）。

环境变量要点（cells --help 实测摘录）：CELLS_WORKING_DIR 替换整个应用目录（本文实机为 /var/cells），CELLS_DATA_DIR/CELLS_LOG_DIR/CELLS_SERVICES_DIR 分别替换数据、日志、服务数据子目录；日志级别用 --log（debug/info/warn/error），JSON 格式 --log_json=true。

三、前置条件

1. 已完成安装并启动服务（systemctl is-active cells 为 active）；admin 子树的命令直连 gRPC 服务、不走 HTTP 认证（cells admin --help 原文：「These commands require a running Cells instance... They are not authenticated」），因此服务未启动时全部失败；
2. 以 pydio 用户执行（配置与数据目录属主）；远程批量场景应在 Cells 所在服务器本机执行；
3. 敏感操作（建用户、发令牌、删数据）建议使用专用管理员而非共享 admin 账号；本文演示用 admin / q1w2e3r4。

四、常用命令详解

4.1 cells version——版本确认

cells version

实测输出：

Pydio Cells Home Edition
 Version:       5.1.0
 Built:         30 Sep 26 12:11 +0000
 Git commit:    56383d15577f371a463d3692408532ab49e909ac
 OS/Arch:       linux/amd64
 Go version:    go1.26.7

4.2 cells start——服务启停

生产环境由 systemd 托管（systemctl start/stop/restart cells），cells start 的价值在于按标签/正则选择性拉起服务。实测 help 关键内容：

• 无参数启动全部服务；参数可跟服务名正则，如 cells start pydio.grpc；
• --tags 按类别过滤，可选值实测 help 原文：broker, data, datasource, discovery, frontend, gateway, idm, scheduler；
• --exclude 排除指定服务；
• 官方示例：cells start --tag=scheduler（只起调度器）、cells start --exclude=pydio.grpc.idm.role（除角色服务全起）；
• 运行要求（help 原文）：ulimit 打开文件数 ≥2048（生产建议 ≥8192，systemd 单元已设 LimitNOFILE=65536）；绑 80/443 需 setcap 'cap_net_bind_service=+ep'；
• 前台运行，停止用 CTRL + C（官方知识库明确提醒，重复 start 前必须先停）。

4.3 cells configure——安装与站点配置

首次安装向导与站点管理入口（完整交互实录见安装指南 4.5 节）：

cells configure              # 交互式安装向导（CLI/浏览器二选一）
cells configure --cli        # 直接进入 CLI 问答模式
cells configure --bind 0.0.0.0:12345   # 浏览器向导换端口
cells configure --yaml /var/cells/install.yaml --exit_after_install   # 非交互自动安装
cells configure sites        # 站点列表/编辑/新建/删除（绑定地址、TLS、外部 URL）

configure --help 实测明确数据库要求：MariaDB ≥ 10.3、MySQL ≥ 5.7（8.0.22 除外）；--site_* 旗标族可直改站点绑定与 TLS（--site_bind、--site_no_tls、--site_tls_cert_file/--site_tls_key_file、--site_le_email/--site_le_agree/--site_le_staging）。

cells configure sites 的 help 实测给出站点四要素：绑定地址（可多个）、TLS 设置、外部 URL（反代场景）、维护模式开关，并附五种典型组合示例（自签名 8080 / 自备证书 / Let's Encrypt 443 / 内外端口分离 / 纯 HTTP）。

4.4 cells update——在线更新

cells update

实测输出（5.1.0 即最新稳定版时）：

No updates are available for this version

旗标（help 实测）：--dry-run 只下载到临时目录不替换二进制；--version <版本号> 应用指定版本升级。更新源与验签公钥来自配置（defaults/update/updateUrl），服务器需能访问外网；走代理时设置 CELLS_UPDATE_HTTP_PROXY（cells start --help 实测提及）。

4.5 cells migrate——上下文迁移

cells migrate --help 实测：用于「Migrate current context」，旗标仅 --name（指定要迁移的上下文名）。常规单机部署用不到，多节点/集群改造时使用。

4.6 cells ctl——注册表浏览与日志级别

cells ctl 直连注册表（默认 --discovery grpc://:8030）列出活动服务/节点/端点等。实测行为：在无交互终端的环境（如脚本/管道）执行报错：

Error: open /dev/tty: no such device or address
...（usage 输出）...
open /dev/tty: no such device or address

需在有 TTY 的终端运行。子命令 service-level（help 实测）可调服务日志级别：-e/--enable 打开 debug（默认）、-r/--reset 重置、-s/--services 指定服务（支持正则）。

4.7 cells admin user——用户管理

子命令清单（cells admin user --help 实测）：create、delete、search、set-profile、set-pwd、token、unlock。

列出全部用户（实测输出）：

cells admin user search

+-----------------+----------+---------+------+--------------------------------------+
|      NAME       | IS GROUP | PROFILE | PATH |                 UUID                 |
+-----------------+----------+---------+------+--------------------------------------+
| /               |   X      |         | /    | ROOT_GROUP                           |
| admin           |          | admin   | /    | 67f533a1-3811-4441-a4e2-293e0bd19041 |
| pydio.anon.user |          | anon    | /    | 4ea93ade-fd90-43e6-b8c6-86a63a989218 |
+-----------------+----------+---------+------+--------------------------------------+
Showing 3 results

search -u <关键字> 按登录名模糊过滤（-u admin 实测只返回 admin 一行）。

创建用户（create -u <登录名> -p <密码>；help 原文：登录名大小写敏感，不带 -p 会交互式索要密码；支持 /组/用户 路径形式建到组里）。实测：

cells admin user create -u demo -p q1w2e3r4

Successfully inserted user demo
Successfully inserted associated role with UUID 256c511e-3955-41a0-b30e-6d817026592b

生成个人令牌（可替代 OAuth2 Bearer 调 REST API，也可作 WebDAV 等 basic-auth 接口的密码；-e 硬过期 / -a 滑动窗口，help 实测示例 -e 24h、-a 10m）。实测：

cells admin user token -u demo -e 24h

✔ This token for demo will expire on Friday, 23-Oct-26 05:00:13 UTC.
✔ gwjJGV5bzNkE7JTnXeLETnSXXNIqmIh4mm2TYqVkJMI.4SmsK4i9Hw9fnBSvL363QSsOydAUpaebc-MBVYYJOls

⚠ Make sure to secure it as it grants access to the user resources!

删除用户。help 原文带警告：「Policy checks are not yet implemented for the CLI... use with extra care」。实测发现（重要）：cells admin user delete -u demo 与 -u /demo 均静默退出（EXIT=0、无任何输出）且用户实际未被删除（删后 search 仍可见，含伪终端 script 环境下同样复现）。删除用户请走 Web 管理界面的用户管理，或改用禁用/降权（set-profile）方案，勿依赖该 CLI 子命令。

改密/改档/解锁：set-pwd -u <用户> -p <新密码>、set-profile -u <用户> -p <standard|admin|anon 等>、unlock -u <用户>（锁定用户解锁；参数以对应 --help 为准）。

4.8 cells admin config——配置管理

子命令（help 实测）：check（配置有效性）、list（PATH/VALUE 全表）、set（服务名 参数名 JSON值 三段式，文件+数据库双写）、delete、history（文件存储下实测返回 no revisions store found）、copy（跨存储迁移）、db（服务级数据库连接 list/move/set）。

实测写读闭环：

cells admin config set pydio.grpc.update channel STABLE

✔ Config set
Delaying exit to make sure write operations are committed.

cells admin config check

Checking config at file:///var/cells/pydio.json?readOnly=true
✔ Default datasource set. A config process has already been performed.

逐段参数解释见 《Pydio Cells 配置参数详解》。

4.9 cells admin file——文件与元数据直操作

子命令（help 实测）：ls（列节点）、meta-put / meta-read（节点元数据写/读）、create-bench（批量生成随机文件压测）。

列目录。注意路径必须用 --path 旗标：实测直接把数据源名当位置参数（cells admin file ls pydiods1）会被忽略、实际列出根层（输出「Listing nodes at /」及五个数据源目录）。正确用法与实测输出：

cells admin file ls --path pydiods1 --uuid

Listing nodes at pydiods1
+------+-------------+--------------------------------------+------+-----------------+
| TYPE |    PATH     |                 UUID                 | SIZE |    MODIFIED     |
+------+-------------+--------------------------------------+------+-----------------+
| File | b1dav.txt   | 6042f09c-7929-4f08-84dc-b9b8be172500 | 73 B | 22 Oct 26 04:49 |
| File | davtest.txt | 1980516b-826f-4839-9041-462e3701dffd | 63 B | 22 Oct 26 04:38 |
+------+-------------+--------------------------------------+------+-----------------+
Showing 2 results

常用旗标：--uuid 显示 UUID、--hidden 显示隐藏文件、--recursive 递归、--limit（默认 100）/--offset 分页。

写元数据（值为 JSON 编码，纯字符串也要带引号，help 原文示例 --value='"custom-value"'）。实测：

cells admin file meta-put --uuid=1980516b-826f-4839-9041-462e3701dffd --key=doc-note --value='"written-by-cli"'

Successfully updated meta

读元数据（实测，可见刚写入的键与系统内置键）：

cells admin file meta-read --uuid=1980516b-826f-4839-9041-462e3701dffd

Listing meta for node 1980516b-826f-4839-9041-462e3701dffd
+--------------+------------------------------------+
|     NAME     |               VALUE                |
+--------------+------------------------------------+
| x-cells-hash | "6ef3f0351d06ba4b90de6f09abdc0d61" |
| doc-note     | "written-by-cli"                   |
| mime         | "text/plain; charset=utf-8"        |
+--------------+------------------------------------+

4.10 cells admin datasource——数据源维护

子命令清单（cells admin datasource --help 实测）：

索引不一致（文件计数对不上、搜索缺条目）时优先 resync；换存储/批量改文件后用 rehash。

4.11 cells admin acl——权限清单查询

子命令（help 实测）：create、delete、patch-recycle-personal（修补个人目录回收站）、search。官方 help 同时提醒：ACL 在前端管理更直观，CLI 适合批量/脚本场景。实测检索当前所有 READ 权限：

cells admin acl search -a READ

+----+------------------------+---------------------+------------+--------------------------------------+
| ID |         ACTION         |       NODE ID       |  ROLE ID   |             WORKSPACE ID             |
+----+------------------------+---------------------+------------+--------------------------------------+
|  3 | Name:"read"  Value:"1" | my-files            | ROOT_GROUP | 1deba984-9bee-4671-a580-e545e2336bdb |
|  7 | Name:"read"  Value:"1" | DATASOURCE:pydiods1 | ROOT_GROUP | f3a090f7-68e0-456c-9792-1bab9d2b805d |
|  9 | Name:"read"  Value:"1" | homepage-ROOT       | ROOT_GROUP | homepage                             |
| 11 | Name:"read"  Value:"1" | directory-ROOT      | ROOT_GROUP | directory                            |
| 14 | Name:"read"  Value:"1" | settings-ROOT       | ADMINS     | settings                             |
+----+------------------------+---------------------+------------+--------------------------------------+
Showing 5 results

4.12 cells admin cert / clean / seed——证书、清理与造数

五、注意事项

1. admin 子树不认证：直连 gRPC（8030），只应在 Cells 服务器本机、以运行账号执行；不要把该端口暴露给不受信网络。
2. 登录名大小写敏感：User 与 user 是两个账号（create help 原文）。
3. file ls 必须用 --path：位置参数不报错但被忽略（实测列出根层），容易误判。
4. user delete 当前版本静默无效：exit 0 但不删除（实测复现），以 Web 界面操作为准。
5. 个人令牌等同密码：token 输出务必保密；需要吊销时对应用户改密或重新生成。
6. 前台 start 与 systemd 互斥使用：排障可临时前台跑（CTRL+C 停），常驻一律 systemd，避免端口占用冲突。
7. config set 三段式：服务名 参数名 JSON 值，字符串值要带引号（如 '"zh-cn"'），写错会存进畸形值。

六、常见问题

Q1：cells admin user delete -u <用户> 没有任何输出但用户还在。 5.1.0 CLI 实测行为（EXIT=0、无输出、不删除；demo 与 /demo 两种写法、含伪终端环境均复现；官方 help 亦声明 CLI 未实现 policy checks）。删除用户改走 Web 管理界面；或先用 set-profile 降级禁用。

Q2：cells ctl 报 open /dev/tty: no such device or address。 该命令需要交互终端（实测在脚本/管道环境必然报此错）。换到有 TTY 的会话执行；仅查日志级别可用其子命令 ctl service-level。

Q3：admin 系列命令全部连接失败。 先确认服务在跑：systemctl is-active cells、ss -tlnp | grep 8030。admin 命令直连 gRPC 注册表（默认 grpc://:8030），服务停了或 8030 不通即失败；cells admin config check 可先验证配置层可用。

Q4：cells update 长时间无响应或失败。 更新源 https://updatecells.pydio.com/ 需外网可达；服务器走代理时设 CELLS_UPDATE_HTTP_PROXY 后重试（cells start --help 实测记载的环境变量）。升级前先 --dry-run。

Q5：config set 后行为没变。 确认改的是正确的服务键（用 config list 按 PATH 找），并重启对应服务或整体 systemctl restart cells；字符串值必须 JSON 编码带引号。

七、参考链接

• 官方文档（Admin Guide 总览）：https://docs.pydio.com/latest/admin-guide/
• 官方文档《Install Static Binaries》（命令运行要求 ulimit/setcap）：https://docs.pydio.com/latest/admin-guide/quick-start/cells-installation/install-static-binaries/
• 官方知识库《Install Cells on Debian/Ubuntu》：https://docs.pydio.com/latest/knowledge-base/deployment/install-cells-on-debian-ubuntu/
• 站内相关文档：《Ubuntu 22.04 安装 Pydio Cells 指南》、《Pydio Cells 配置参数详解》、《Pydio Cells 介绍与选型指南》