Cypht 2.13 常用 CLI 命令与工具详解

‍‍​​‌​> 目标：讲清 Cypht 2.13 自带 scripts/ 目录下运维类命令行工具的用法——账号管理（建号/改密/删号）、数据库初始化迁移、配置重建与系统初始化编排，全部命令与回显在 Ubuntu 22.04 + Cypht 2.13.0 环境实测通过。Cypht 是 PHP Web 应用，没有独立二进制 CLI，这些 php ./scripts/*.php 脚本就是它的管理入口。

一、环境信息

• 软件版本：Cypht v2.13.0
• 运行环境：Ubuntu 22.04.5 LTS + PHP 8.1.2（cli）+ MariaDB 10.6.23
• 应用目录：/var/www/cypht（本文所有命令均在该目录执行）
• 数据库：cypht_db / 账号 cypht；演示管理账号 admin / q1w2e3r4
• 前置形态：.env 中 AUTH_TYPE=DB、USER_CONFIG_TYPE=DB、SESSION_TYPE=DB（账号存库，脚本才能管理）

二、工具概览

scripts/ 目录共 12 个脚本，按用途分两类：

三、前置条件

1. 已安装并可登录 Cypht（安装流程见本站《Ubuntu 22.04 安装 Cypht 2.13 指南》）
2. 执行账号需能读 .env、写数据库（推荐 root 或应用属主 www-data 之外的特权管理账号执行 CLI）
3. 所有脚本强制 CLI 模式运行，Web 访问会直接报错 Must be run from the command line

四、setup_database.php：数据库初始化与迁移

建库建表 + 版本迁移一体工具。读 .env 的 DB_* 配置连接数据库，首装时建 hm_user、hm_user_session、hm_user_settings、hm_login_attempts、migrations 五张表；再次执行只做增量迁移。

4.1 用法

php ./scripts/setup_database.php
# 指定其他配置文件（如测试环境）
php ./scripts/setup_database.php --env=.env.test

4.2 实测回显

首次安装（节选关键行）：

Migrations table created.
Migrations table populated for new installation.

Db setup finished

重复执行（幂等，升级场景同理）：

Database connection successful ...
Database detected. Running migrations...
Running migrations...
Migrations completed.

Db setup finished

4.3 验证

mysql -ucypht -pq1w2e3r4 cypht_db -e 'show tables;'

Tables_in_cypht_db
hm_login_attempts
hm_user
hm_user_session
hm_user_settings
migrations

⚠️ 注意：.env 缺失时脚本直接退出并提示 Environment file .env not found. Please create it from the example file.——先 cp .env.example .env 再执行。

五、config_gen.php：配置重建

把 .env 翻译成运行时配置（config/dynamic.php）并打包生产态前端资源到 site/。改任何 .env 项后必跑。

php ./scripts/config_gen.php

实测回显：

site.js file created
dynamic.php file written
creating production site
KindEditor assets copied successfully
copying assets directory...

验证生效（改 APP_NAME 后页面标题实测变为新值，详见本站《Cypht 2.13 配置参数详解》第三章）。

六、create_account.php：创建账号

6.1 用法

php ./scripts/create_account.php <用户名> <密码>

6.2 实测

php ./scripts/create_account.php admin q1w2e3r4

User account created successfully.

落库验证：

mysql -ucypht -pq1w2e3r4 cypht_db -e 'select username from hm_user;'

username
admin

参数不全时的用法报错（实测）：

php ./scripts/create_account.php

Incorrect usage

php ./scripts/create_account.php <username> <password>

七、update_password.php：修改密码

7.1 两种模式

# 模式一：带旧密码（保留用户全部配置数据；操作他人账号需 sudo）
php ./scripts/update_password.php <用户名> <旧密码> <新密码>

# 模式二：不带旧密码（强制重置，用户配置数据将丢失，需交互确认）
php ./scripts/update_password.php <用户名> <新密码>

7.2 实测

先建测试号：

php ./scripts/create_account.php testuser q1w2e3r4

User account created successfully.

模式二（强制重置，输入 y 确认）：

echo y | php ./scripts/update_password.php testuser newpass456

Not providing old password will result in LOSS OF ALL USER CONFIGURATION DATA!
Are you sure you want to continue? Type 'y' or 'yes' to confirm: Password updated successfully.

模式一（带旧密码，无确认直接改）：

php ./scripts/update_password.php testuser newpass456 q1w2e3r4

Password updated successfully.

参数不全时的完整用法提示（实测节选）：

Incorrect usage

Usage:
  With old password (preserves user config and needs [sudo]):
    php ./scripts/update_password.php <username> <old_password> <new_password>

⚠️ 注意：用户配置（含已保存的邮箱服务器密码）用登录口令派生加密，「不带旧密码重置」会让旧数据无法解密——这就是脚本警告 LOSS OF ALL USER CONFIGURATION DATA 的原因。找回密码场景务必先告知用户此代价。

八、delete_account.php：删除账号

php ./scripts/delete_account.php <用户名>

实测：

php ./scripts/delete_account.php testuser

User deleted

删后库表验证：

mysql -ucypht -pq1w2e3r4 cypht_db -e 'select username from hm_user;'

username
admin

九、setup_system.sh：系统初始化编排脚本

新部署环境的一键初始化编排：按 USER_CONFIG_TYPE 创建用户设置目录（默认 /var/lib/hm3/users）与附件目录（/var/lib/hm3/attachments），当 USER_CONFIG_TYPE=DB 且设置了 AUTH_USERNAME/AUTH_PASSWORD 环境变量时自动调用 create_account.php 建初始账号，最后调用 config_gen.php 重建配置。典型用法：

cd /var/www/cypht
AUTH_USERNAME=admin AUTH_PASSWORD=q1w2e3r4 USER_CONFIG_TYPE=DB sh ./scripts/setup_system.sh

执行后依次输出目录创建与配置重建回显（与第四、五章相同）。官方一体化交付形态（见本站《Cypht 2.13 Docker Compose 部署指南》）的启动入口正是串行执行 setup_database.php → setup_system.sh 完成自动初始化。

十、注意事项

1. 全部脚本必须从应用根目录执行（脚本内部以 dirname(dirname(__FILE__)) 推导 APP_PATH），切换目录前先 cd /var/www/cypht
2. 账号三件套（create/update/delete）只操作 hm_user 表；用户邮箱服务器配置在 hm_user_settings，删号会连带清理
3. update_password.php 模式二的确认提示需 stdin 输入 y/yes，脚本化时用 echo y | 管道
4. 密码以明文参数出现在命令行，会留在 shell history——生产操作建议 history -d <行号> 清理或用 HISTIGNORE 规避
5. 升级版本后第一件事跑 setup_database.php（迁移）与 config_gen.php（重建资源）

十一、常见问题

Q1：执行脚本报 Must be run from the command line？

脚本被 Web SAPI 执行了（如通过浏览器访问）。这些脚本只能在终端用 php ./scripts/<脚本名>.php 形式运行。

Q2：setup_database.php 报连接失败？

先确认 .env 的 DB_HOST/DB_USER/DB_PASS 正确且 MariaDB 已启动；socket 模式（DB_CONNECTION_TYPE=socket）需确认 DB_SOCKET 路径真实存在。

Q3：改了 .env 但脚本行为没变？

脚本每次执行都现读 .env，无需重建；但 Web 侧需要 config_gen.php 重建。两边生效机制不同，别混淆。

Q4：能否用这些脚本批量开户？

create_account.php 单次只建一个账号；批量开户可在管理脚本里逐个调用（逐条执行、逐条检查回显），勿跳过失败项。

十二、参考链接

• 脚本源码目录：https://github.com/cypht-org/cypht/tree/master/scripts
• 官方安装页（含初始化步骤上下文）：https://www.cypht.org/install/
• 配置参数与 .env 详解见本站《Cypht 2.13 配置参数详解》