OSSN 10.1 常用 CLI 命令与工具详解

目标：盘点 OSSN 10.1 的全部命令行面。OSSN 是 Web 优先的软件，没有独立的 CLI 命令集——它的 CLI 面由两个 PHP 入口脚本（system/handlers/cli 统一入口、system/handlers/cron 预留入口）、Web 安装器/升级器的 curl 非交互等价操作、以及围绕 LAMP 的系统工具链（mysql 客户端、apache2ctl、php CLI）构成。本文把每个入口的机制、参数、全部可用 handler 与实测回显逐一固化，并沉淀"root 身份跑 CLI 打坏缓存属主"等排障实录。全部命令与输出取自 10.1 实装站点（PHP 8.2.35 + MySQL 8.0.46，2026-11-02）。

📐 篇型说明：OSSN 官方无 ossn-cli 之类命令工具，本文按"CLI 入口脚本 / 定时任务机制 / 安装与升级的非交互命令 / API 与运维操作"四块组织，这是该软件 CLI 面的真实边界。

一、环境信息

• OSSN：10.1，站点根目录 /var/www/html（Apache DocumentRoot）
• PHP CLI：8.2.35（php -r 'echo PHP_VERSION;' 实测回显 8.2.35）
• MySQL：8.0.46，业务账号 ossn/q1w2e3r4，库名 ossn
• Web 服务：Apache 2.4，mod_rewrite 已启用（apache2ctl -M 实测回显含 rewrite_module (shared)）
• 管理员演示账号：admin / q1w2e3r4
• 站点 URL：http://127.0.0.1:8139/
• 部署与配置背景：见《OSSN 10.1 Docker Compose 部署指南》《OSSN 10.1 配置参数详解》

二、工具概览

CLI 入口与 cron 入口被 .htaccess 显式屏蔽 HTTP 访问（RedirectMatch 404 ^/system/handlers/cli$ 与 ^/system/handlers/cron$），实测：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8139/system/handlers/cli
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8139/system/handlers/cron

实测回显：

404
404

三、前置条件

1. 用 Web 用户身份执行：所有会写 cache/、ossn_data/ 的 handler 必须以 www-data 运行——sudo -u www-data php /var/www/html/system/handlers/cli ...。root 直跑会把缓存文件属主写成 root，后续站点与 www-data 的 CLI 运行将报权限异常（完整事故实录见 7.1）；
2. handler 名必须是纯字母数字（ctype_alnum 校验，resetpassword/AdsCron/DisplayErrors 都合规，含 -/_ 的名字会被入口静默拒绝）；
3. php-cli 与站点同版本（8.2），扩展齐全（gd mysqli zip mbstring pdo_mysql opcache exif，php -m 可核对）；
4. 涉及登录态的 handler（upgrade）需要管理员用户名与口令；命令行传口令会暴露于进程列表，执行后可 history -d / 用低权专用账号（见六.2）。

四、CLI 入口机制

system/handlers/cli 全文逻辑（读源码，共 15 行）：定义 OSSN_ALLOW_SYSTEM_START → require system/start.php 完整启动站点框架 → ossn_is_from_cli() 校验（非 CLI 直接 exit）→ ossn_cli_handler()。后者做四件事：

1. 解析 --handler=<name>（getopt，必需参数）；缺失时输出 Invalid handler supplied make sure you supplied --handler={name of handler}（实测回显见 5.1.6）；
2. ctype_alnum($handler) 校验，不合规静默返回；
3. 在 ossn_data/cli/last_activty 记录本次时间戳（运维可据此判断 CLI 最近活动时间）：

cat /var/www/ossn_data/cli/last_activty; date +%s

实测回显（两次输出一致 = 刚跑过）：

1793608859
1793608859

4. ossn_trigger_callback('cli', 'loaded', args) 广播给各注册方——handler 的实现分散在核心库与组件：ossn.lib.admin.php（错误显示/缓存 4 个）、ossn.lib.users.php（resetpassword）、ossn.lib.upgrade.php（upgrade）、components/OssnAds/ossn_com.php（AdsCron）。第三方组件可注册自己的 handler，这是 OSSN CLI 的扩展方式。

五、各工具详解

5.1 CLI handler 全量实测

以下命令均以 sudo -u www-data php /var/www/html/system/handlers/cli 为前缀（实测环境用站点运行身份执行），回显含 ANSI 色码（\033[32m 绿=成功、\033[31m 红=错误、\033[33m 黄=提示）。

5.1.1 调试开关（写 ossn_site_settings 的 display_errors 行）

php /var/www/html/system/handlers/cli --handler=DisplayErrors
php /var/www/html/system/handlers/cli --handler=DoNotDisplayErrors

实测回显：

Error reporting enabled!
Errors reporting disabled

5.1.2 缓存开关（写 setting_id=4 的 cache 行，Disable 同时清空 cache 文件）

php /var/www/html/system/handlers/cli --handler=DisableCache
php /var/www/html/system/handlers/cli --handler=EnableCache

实测回显：

Cache has been disabled
Cache has been enabled

5.1.3 重置用户口令（忘密救援，无需登录任何账号）

php /var/www/html/system/handlers/cli --handler=resetpassword --username=admin --password=q1w2e3r4

实测回显：

Password has been changed

三条失败路径全部实测：

The password must be more than 5 characters.     # 弱口令（--password=123）
Invalid user, no such a user exists              # 用户不存在（--username=nouser）
Username or Password can not be empty!           # 缺参数

5.1.4 执行数据库升级（需管理员凭据）

php /var/www/html/system/handlers/cli --handler=upgrade --username=admin --password=q1w2e3r4

实测回显（站点已是最新，无待执行脚本）：

Upgrade process has started at Monday 2nd of November 2026 08:44:12.480
No upgrades!
Upgrade process completed at Monday 2nd of November 2026 08:44:12.481

凭据错误实测回显：

Admin login details are invalid unable to login

机制：先 OssnUser::Login() 验证凭据，通过后 ossn_trigger_upgrades() 遍历 upgrade/upgrades/*.php（38 个时间戳脚本），跳过 ossn_site_settings.upgrades JSON 已记账的，执行增量并回写记账。等价 Web 入口 upgrade/upgrade.php（用当前登录会话，执行期写 /_upgrading_process 标记文件，实测完成后自动删除）。

5.1.5 广告过期任务 AdsCron（OssnAds 组件，唯一的内置"定时"handler）

php /var/www/html/system/handlers/cli --handler=AdsCron

实测回显（无到期广告）：

No ads found for expiration

有到期广告时逐条输出 Ad with ID marked expired : <guid> 并汇总 All found ads marked expired。它同时把组件设置 last_time 刷为当前时间。官方设计意图就是挂 crontab：

*/30 * * * * www-data php /var/www/html/system/handlers/cli --handler=AdsCron >/dev/null 2>&1

5.1.6 非法/未知 handler 行为

php /var/www/html/system/handlers/cli
php /var/www/html/system/handlers/cli --handler=nonexistent

实测回显：前者输出 Invalid handler supplied make sure you supplied --handler={name of handler}；后者无任何输出、退出码 0（回调广播后无人认领该 handler，静默结束）——脚本化调用时不要依赖退出码判断 handler 是否存在。

5.2 cron 入口：预留钩子，核心无实现

php /var/www/html/system/handlers/cron

实测回显（致命错误 + OSSN 异常页，节选）：

[#1793608131|0B221CE7C9AFE463734A61943C5F50D1] Error: Call to undefined function ossn_cron_handler() in /var/www/html/system/handlers/cron:14
Stack trace:
#0 {main}

源码事实：入口脚本仅 define('OSSN_ALLOW_SYSTEM_START', TRUE) → 启动框架 → if(ossn_is_from_cli()){ ossn_cron_handler(); }，而 ossn_cron_handler() 在开源核心没有任何定义（全仓库 grep 仅命中调用点）——它是留给插件/商业组件的实现钩子。结论：开源 OSSN 的"定时任务"正确姿势是给 5.1.5 这类 CLI handler 配 crontab，而不是跑 cron 入口（会 fatal）。

5.3 系统工具链

查库（11 张表全清单）：

mysql -uossn -pq1w2e3r4 ossn -N -e "SHOW TABLES;"

实测回显：

ossn_annotations ossn_components ossn_entities ossn_entities_metadata ossn_likes ossn_messages ossn_notifications ossn_object ossn_relationships ossn_site_settings ossn_users

逻辑备份：

mysqldump -uossn -pq1w2e3r4 --no-tablespaces ossn | wc -l

实测回显（安装并浏览后的空站 dump 规模）：

390

生产备份 = 此 dump + ossn_data/ 目录打包 + configurations/ 三件套（口径见部署指南第五章）。

环境自检：

apache2ctl -M | grep rewrite     # 期望 rewrite_module (shared)
php -m                            # 核对 gd mysqli zip mbstring pdo_mysql opcache exif
php -l /var/www/html/configurations/ossn.config.db.php   # 改配置后语法自检

5.4 安装器的非交互命令化

OSSN 没有 CLI 安装器，但安装 = 三个 HTTP 请求，curl 可全等价（字段、会话、验证回显完整实录见《OSSN 10.1 Docker Compose 部署指南》4.6–4.8）：

curl -s -c cj.txt 'http://<站点>/installation/?page=settings' -o /dev/null
curl -s -b cj.txt -c cj.txt -X POST 'http://<站点>/installation/?action=install' \
  -d 'dbuser=ossn' -d 'dbpwd=<口令>' -d 'dbhost=127.0.0.1' -d 'dbname=ossn' \
  -d 'url=http://<站点>/' -d 'datadir=/var/www/ossn_data/' \
  -d 'owner_email=<邮箱>' -d 'notification_email=<邮箱>' -d 'sitename=<站名>'
curl -s -b cj.txt -c cj.txt -X POST 'http://<站点>/installation/?action=account' \
  -d 'username=admin' -d 'firstname=Admin' -d 'lastname=User' \
  -d 'email=<邮箱>' -d 'email_re=<邮箱>' -d 'password=<口令>' \
  -d 'gender=male' -d 'birthday=2' -d 'birthm=11' -d 'birthy=1990'
curl -s -b cj.txt -L 'http://<站点>/installation?action=finish'

要点：account 十字段全必填；finish 写 installation/INSTALLED 锁死安装器（再访问返回 It seems the Open Source Social Network is already installed，实测）。

5.5 API 与运维操作

开源核心的 CLI/HTTP 编程面边界（源码与 README 实查，2026-11-02）：核心内置 OssnJWT 类（classes/OssnJWT.php，encode/decode）作为令牌底座，README 后台特性列有 "WebServices API"，但开源包内没有任何 REST 端点实现——完整 API 由官方商业组件交付。核心留给二次开发的命令式扩展点即 4.1 所述 ossn_register_callback('cli', 'loaded', ...) 机制：组件注册自己的 handler 名与参数，即可把任意运维操作搬进 system/handlers/cli 统一入口（usage example 就写在 libraries/ossn.lib.cli.php 文件尾部注释里）。

六、注意事项

1. 身份一致性：CLI 与 Web 进程共享 cache/ 与 ossn_data/，两者必须同用户（www-data）。实测事故与修复见 7.1；
2. 口令入参可见性：--password=xxx 在 ps 与 shell history 中明文可见，生产救援后建议再次用 resetpassword 轮换，或为 CLI 建专用低权管理员账号；
3. 退出码不可靠：未知 handler 静默 0（5.1.6），脚本判断成功与否应 grep 输出中的错误行（红色前缀）而非 $?。

七、常见问题

7.1 root 跑 CLI 后站点/CLI 报缓存权限异常（实测事故）

以 root 执行 --handler=EnableCache 成功，但它用 root 属主重建了 cache/css|js 文件；随后以 www-data 再执行同命令即抛：

Exception: The file "/var/www/html/cache/css/1793608859/view/bootstrap.min.css" could not be opened for writing. Check if PHP has enough permissions. in /var/www/html/libraries/minify/Minify.php:510

修复（把缓存与 CLI 记账目录交回 www-data 后复测成功）：

chown -R www-data:www-data /var/www/html/cache /var/www/ossn_data/cli
sudo -u www-data php /var/www/html/system/handlers/cli --handler=EnableCache

实测回显：

Cache has been enabled

7.2 cron 入口执行报 undefined function

见 5.2——开源核心无 ossn_cron_handler() 实现属设计现状而非故障；需要定时任务就 crontab 挂具体 CLI handler（AdsCron 模板见 5.1.5）。

7.3 upgrade handler 与 Web 升级器怎么选

两者共用 ossn_trigger_upgrades()，差别只在鉴权：CLI 版每次显式传管理员凭据（适合脚本/CI），Web 版复用当前登录会话（适合手工）。记账都在 ossn_site_settings.upgrades，重复执行安全（已应用脚本直接跳过，实测输出 No upgrades!）。

7.4 resetpassword 改了管理员口令，后台仍登不上

resetpassword 直接落库新 bcrypt 散列，立即生效；若登录仍失败，检查是否触发登录限流/会话缓存——先 --handler=DisableCache 再 --handler=EnableCache 清一遍再生成（实测两条命令回显见 5.1.2），并确认用户名而非邮箱（ossn_user_by_username 精确匹配 username 列）。

八、参考链接

• OSSN 源码仓库（CLI 机制：system/handlers/cli、libraries/ossn.lib.cli.php；handler 注册点：libraries/ossn.lib.admin.php、libraries/ossn.lib.users.php、libraries/ossn.lib.upgrade.php、components/OssnAds/ossn_com.php）：https://github.com/opensource-socialnetwork/opensource-socialnetwork
• 官方升级 wiki：https://www.opensource-socialnetwork.org/wiki/view/708/how-to-upgrade-ossn
• 站内系列：《OSSN 介绍与选型指南》 https://www.quzuo.net/document/5mUplLNya9Wy 、《OSSN 10.1 Docker Compose 部署指南》 https://www.quzuo.net/document/CnQYxGvz0VQN 、《OSSN 10.1 配置参数详解》 https://www.quzuo.net/document/rLIu69MQTcOk