Hubzilla 11.4.2 常用 CLI 命令与工具详解

目标：把 Hubzilla 11.4.2 自带的命令行工具（站点根目录 util/ 下 60 余个文件 + 守护进程入口 Zotlabs/Daemon/Master.php）逐条实测讲清楚：每个工具的子命令、真实回显、适用场景与坑点。已在 Hubzilla 11.4.2（DB build 1265，PHP 8.3.36 CLI）实测通过；配置参数的三层模型见 《Hubzilla 11.4.2 配置参数详解》，部署形态见 《Hubzilla Docker Compose 部署指南》。

一、环境信息

本文全部命令在部署完成的编排内、站点根目录执行：docker compose exec -w /var/www/html web php util/<工具> <参数>（bash 脚本把 php 换成 bash）。

二、工具概览

实测逐条运行后的分类总览：

三、前置条件

1. 已按 《Hubzilla Docker Compose 部署指南》 完成部署（站点可访问、.htconfig.php 已生成）；
2. 必须从站点根目录运行：所有 PHP 工具首行检查 include/cli_startup.php，实测在 /tmp 下运行回显——

Run dcp from the top level Hubzilla web directory, as util/dcp <args>
Run config from the top level Hubzilla web directory, as util/config <args>

编排内用 -w /var/www/html 固定工作目录即可；

3. bash 脚本（safemode/udall/hz/add_addon_repo 等，首行 #!/usr/bin/env bash）用 bash 执行，不要用 php 执行（见第六章 Q1）；
4. 涉及写操作的命令（config/pconfig/service_class）会直接落数据库，生产环境执行前确认参数。

四、各工具详解

4.1 util/config——站点配置读写

用法（官方 util/config.md 全文见配置篇 3.2）：无参全量 dump、<family> 列类别、<family> <key> 读单键、<family> <key> <value> 写入。实测：

$ docker compose exec -w /var/www/html web php util/config system curl_timeout
config[system][curl_timeout] = 5

$ docker compose exec -w /var/www/html web php util/config system sitename "Quzuo Test Hub"
config[system][sitename] = Quzuo Test Hub

写入即落 config 表并覆盖 .htconfig.php 文件层同名值（三层模型与删除 DB 行的方法见 《Hubzilla 11.4.2 配置参数详解》 第三章）。

⚠️ 注意：无参全量 dump 会把站点 RSA 私钥 prvkey 整段打进终端（实测如此），生产环境避免裸跑。

4.2 util/pconfig——账号级配置

无参数时列出全部账号 uid 与名称（实测）：

$ docker compose exec -w /var/www/html web php util/pconfig
   2 admin
   1 System

语法 util/pconfig <uid> <family> <key> [value]，读回显格式 pconfig[<uid>][<family>][<key>] = <值>（实测）：

$ docker compose exec -w /var/www/html web php util/pconfig 2 system permissions_role
pconfig[2][system][permissions_role] = personal

两个实测坑：参数多于 4 个只取前 4 个（util/pconfig 2 admin system test_key hello 实际写入 family=admin、key=system、value=test_key，不报错）；值设空串不删除行，清理需 SQL delete from pconfig where uid=2 and cat='admin'。

4.3 util/update_db——数据库结构升级

版本升级后必跑（幂等），实测：

$ docker compose exec -w /var/www/html web php util/update_db
DB up to date: 1265

1265 即 config 表 db_version 值；有增量时按序执行 Zotlabs/Update/_<版本号>.php 系列脚本（实测目录内为 _1000.php 至 _1265.php）并推进版本号。另有 list 子命令查看待执行升级（实测）：

$ docker compose exec -w /var/www/html web php util/update_db list
CURRENT: 1265
LATEST: 1265

升级流程：替换代码 → 跑 util/update_db → 重启 poller（见 4.15）。

4.4 util/admins——管理员名单

子命令（官方 CLI_tools.md）：util/admins list、util/admins add <account_id>、util/admins remove <account_id>；无参等同 list。实测输出：

$ docker compose exec -w /var/www/html web php util/admins
   1 root@example.com *

行格式为「account_id 邮箱 *」（星号标记当前管理员）。面板失守时用它紧急加回管理员是核心用途。

4.5 util/addons——插件管理

子命令：list（已装）、list all（已装 * / 因不兼容停用的 !）、install foo、uninstall foo、reinstall。实测：

$ docker compose exec -w /var/www/html web php util/addons list
（无输出）

根因实测：核心源码包解压后站点根目录没有 addon/ 目录（ls addon → No such file or directory）——Hubzilla 插件在独立的 hubzilla/addons 仓库，需先用 util/add_addon_repo <repo_url> <nickname> 注册仓库（bash 脚本，实测 usage 行 usage: util/add_addon_repo repo_url nickname），装完插件后 addons list 才有内容。

4.6 util/fresh——交互式 REPL

官方定位 "The Freaking REd Shell"：交互式管道，支持 version、login <email>、finger <channel address>、channel <nickname>、conn（无参列全部连接，带 ID 参数看详情）。非交互用法（实测管道喂命令）：

$ printf 'version\nquit\n' | php util/fresh
fresh% version
Fresh version 0.1fresh% quit

⚠️ 注意：不带输入直接执行 php util/fresh 会进入 fresh> 交互 REPL 永久阻塞——实测在无 tty 的自动化环境里刷屏并挂住会话，最后 pkill -f util/fresh 才脱身。脚本化调用务必像上面这样管道喂命令并以 quit 收尾。

4.7 util/storageconv 与 util/thumbrepair——缩略图存储

storageconv 无参打印用法：

Hubzilla thumbnails storage convertor

Usage:
	util/storageconv stats  # show current stats
	util/storageconv fs     # move thumbnails from SQL to filesystem
	util/storageconv db     # move thumbnails from filesystem to SQL

stats 实测（全新站点）：

Current storage set to: filesystem
Local images: 0
Image thumbnails: 0
Imported profiles thumbnails: 0
Thumbnails total: 0
Thumbnails to convert: 0

thumbrepair 重建本地缩略图，实测无照片站点静默完成（rc=0）；照片多时是 CPU 密集操作，建议低峰执行。

4.8 util/safemode——插件安全模式（bash）

用途：排障时一键卸载全部插件、事后原样恢复。实测 bash util/safemode 无参回显：

Usage: util/safemode on | util/safemode off
on saves current addons to addons-safemode and uninstalls all of them
off installs all addons in addons-safemode

on 把当前已装插件清单存 addons-safemode 文件后全卸，off 按清单装回。

4.9 util/udall——git 全量更新（bash）

逻辑（实测脚本源码）：核心目录 git pull，再遍历 extend/ 下 theme/addon/widget 各子仓库逐个 git pull。tarball 安装实测：

$ docker compose exec -w /var/www/html web bash util/udall
Unable to update /var/www/html

因为脚本第一步检查 if [ ! -d .git ]——非 git 检出直接退出。git 方式部署的站点用它一条命令同步核心+全部扩展仓库。

4.10 util/service_class——服务类配额

源码三种形态（实测）：argc>3 写入（util/service_class basic photos 5）；argc==3 按 --account=<id> 或 --channel=<address> 查询；无参仅打印启动调试行。实测：

$ docker compose exec -w /var/www/html web php util/service_class --account=1
--account=1:

$ docker compose exec -w /var/www/html web php util/service_class basic photos 5
Updated service class "basic" service "photos" to 5

写入落 config 表（实测行，json: 前缀数组编码）：

cat	k	v
service_class	basic	json:{"photos":"5"}

服务类用于多租户 hub 按套餐限制各渠道配额（配合 baseurl/help/service_classes 帮助页）；测试完可 SQL 删除该行。

4.11 util/connect——命令行建立连接

无参 Usage（实测）：

Usage: util/connect channel_id|channel_address channel[@hub]

用本站渠道（ID 或地址）去连接远端 channel@hub，等价于网页 "Connect" 流程的 CLI 版，联邦排障时可用它绕开 UI 直接发起连接。

4.12 util/dcp 与 util/dmkdir——DAV 投递与建目录

无参 Usage（实测全文）：

Usage: util/dcp src dstdir
Always run from the toplevel web directory.
destination should begin with store/$nickname/desired/path or $nickname/desired/path
Example: util/dcp /etc/motd store/joe/etc

Usage: util/dmkdir directory
Always run from the toplevel web directory.
directory should begin with store/$nickname/desired/path or $nickname/desired/path
Example: util/dmkdir store/bob/photos/2017

源码逻辑：从路径解析渠道昵称 → channelx_by_nick() 查渠道（查不到直接 return，无任何报错）→ attach_mkdirp() 在 DAV 区建路径。实测向 store/admin/testdir 建目录：命令静默结束、attach 表无新行、目录未创建——该工具面向渠道 DAV 存储路径，CLI 环境下失败不提示，用后务必按 6.6 的方法验证。

4.13 util/hz——shell 发状态（bash）

极简 curl 工具（实测脚本头）：读配置文件（默认 ~/.hubzilla，或作第一参数传入），格式：

USER=<your username>
PASS=<your password>
HUB=<domain of the hub>

执行 hz 后输入正文、Ctrl-D 结束即通过 Hubzilla API 发布状态。适合脚本化广播。

4.14 util/shredder/ 与 util/zotsh/——工具套件目录

• shredder/：Diaspora 数据抹除套件，实测目录含 shredder（主脚本）、ShredOAuth.sh、OAuth.sh、JSON.sh 及依赖源码包 jansson-2.6.tar.gz、jshon.tar.gz（readme 指向 kmkeen.com/jshon，需先编译 jshon）。用途：把曾联邦出去的内容从对端彻底删除；
• zotsh/：Python DAV 客户端（zotsh.py + 内置 easywebdav 库 + README.txt），命令行挂载/操作渠道存储区。

4.15 Zotlabs/Daemon/Master.php——poller 入口

守护进程总入口，参数为 daemon 类名（源码实测：array_shift($argv) 后逐参数 Master::Release()；无参直接退出、无输出）。核心用法：

$ docker compose exec -w /var/www/html web php Zotlabs/Daemon/Master.php Cron
$ echo rc=$?
rc=0

静默 rc=0 即成功，同时刷新 config 表 lastcron/lastcroncheck/lastpoll 三个心跳（实测三值同步更新，见配置篇 5.6）。生产必须挂 crontab 每分钟执行（部署篇 4.8 有完整配置）。

4.16 仓库管理与开发杂项

实测 util/ 内其余脚本：add_addon_repo / update_addon_repo / add_theme_repo / add_widget_repo（均 bash，usage: <脚本> repo_url nickname，git clone 第三方仓库到 addon/、theme/、widget/ 的 extend 体系）；开发向工具 typo.php（util/README 原文："a crude syntax checker to avoid checking in files with simple typos"）、extract.php（i18n 字符串提取）、precompile_smarty3.php（模板预编译）、generate-hooks-index（钩子索引）。日常运维基本用不到，列出防止误跑。

五、注意事项

1. 工作目录是第一道门：所有 PHP 工具靠 include/cli_startup.php 相对路径自检，跑错目录只会得到 Run <工具名> from the top level Hubzilla web directory 一行提示；
2. 分清 PHP 与 bash：util/ 是混装目录，safemode、udall、hz、add_addon_repo 等首行 #!/usr/bin/env bash，用 php 执行只会原样打印脚本源码（见 Q1）；
3. 写操作直达数据库：config/pconfig/service_class 的写入立即生效且覆盖文件层，删除只能 SQL；daemon 侧参数生效要等下一轮 poller；
4. fresh 无输入即阻塞：自动化环境永远管道喂命令（4.6）；
5. 备份优先：update_db 跑在大版本升级前请先备份数据库——结构升级不可回滚。

六、常见问题

Q1 用 php 跑 safemode/udall 打印出一堆脚本源码

这些是 bash 脚本，php util/udall 把文件当 PHP 解析、没有 <?php 段就原样 echo 全文（实测输出正是脚本源码）。正确执行：bash util/safemode、bash util/udall。

Q2 sh 跑 util/safemode 报 [: ==: unexpected operator

实测 sh util/safemode 回显 util/safemode: 3: [: 0: unexpected operator——脚本用了 bashism（[ $# == 0 ]），Debian/Ubuntu 的 /bin/sh 是 dash，不支持 ==。必须显式 bash。

Q3 util/fresh 挂住终端/刷屏

无参执行进入 fresh> REPL 等交互输入，非 tty 环境会无限回显提示符（实测事故，pkill -f util/fresh 脱身）。用 printf '命令\nquit\n' | php util/fresh 方式调用。

Q4 util/addons list 什么都没有

核心 tarball 不含 addon/ 目录（实测 ls addon 报 No such file or directory），插件在独立仓库。先 bash util/add_addon_repo <repo_url> <nickname> 注册再安装。

Q5 util/udall 报 Unable to update /var/www/html

脚本要求 .git 目录存在（git 检出安装），tarball/自建镜像方式没有 .git。tarball 部署的升级路径：下载新包替换代码 → php util/update_db。

Q6 util/dcp / util/dmkdir 静默无输出，也不知道成没成

4.12 源码结论：渠道昵称解析失败或 DAV 建路径失败都不打印任何错误。验证方法：查 attach 表对应路径行（实测 SELECT id,attr_str,location FROM attach WHERE attr_str LIKE '%<目录名>%'），或直接到网页 Files 应用确认。

七、参考链接

• 官方 CLI 工具手册：https://github.com/hubzilla/hubzilla-project/blob/master/doc/en/adminmanual/CLI_tools.md
• 高级配置文档：https://github.com/hubzilla/hubzilla-project/blob/master/doc/en/advanced_configurations.md
• 站内互链：配置参数三层模型见 《Hubzilla 11.4.2 配置参数详解》；部署与 poller 定时任务见 《Hubzilla Docker Compose 部署指南》；选型背景见 《Hubzilla 介绍与选型指南》。