Wallos 5.10.2 常用 CLI 命令与工具详解

目标：讲清 Wallos v5.10.2 自带的全部命令行工具——endpoints/cronjobs/ 下 13 个定时任务脚本、endpoints/db/ 下 4 个数据库维护端点、以及 sqlite3 直连数据库的查询方法，每个工具给出用途、用法与实测回显。已在 Ubuntu 22.04.5 LTS + Wallos 5.10.2（PHP 8.3.36 + SQLite 3.37.2）实测通过（2026-10-25）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
系统架构：x86_64
Wallos 版本：v5.10.2，部署路径 /var/www/html
PHP CLI：8.3.36
数据库：SQLite 3.37.2，单文件 /var/www/html/db/wallos.db
定时任务配置：/etc/cron.d/wallos（裸机 10 条）
演示账号：admin / q1w2e3r4（user_id=1）
部署方式参考：《Ubuntu 22.04 安装 Wallos 5.10.2 指南》

二、工具概览

Wallos 没有独立的 CLI 二进制，命令行能力由两组 PHP 脚本承担，外加一个健康检查端点与 sqlite3 直连：

工具组	位置	数量	用途
定时任务脚本	`endpoints/cronjobs/*.php`	13 个	付款日更新、汇率、通知、AI 推荐、版本检查、库初始化等
数据库维护端点	`endpoints/db/*.php`	4 个	迁移、备份、恢复、导入
健康检查	`/health.php`	1 个	供负载均衡/监控探活，返回 `OK`
sqlite3 直连	db/wallos.db	—	排障与批量核对

关键差异解读：cron 脚本用于「无人值守的周期性维护」，db 端点用于「升级/迁移/备份恢复」这类一次性运维动作；日常排障查数据用 sqlite3。

三、前置条件

已部署 Wallos 5.10.2 并完成首个账号注册（本文示例基于该实测环境）。
所有脚本在 Wallos 部署根目录下以 PHP CLI 执行：

cd /var/www/html

需要用 sqlite3 直连时先安装客户端：

sudo apt-get install -y sqlite3
sqlite3 --version

输出（实测）：

3.37.2 2022-01-06 13:25:41 872ba256cbf61d9290b571c0e6d82a20c224ca3ad82971edc46b29818d5dalt1

⚠️ 注意：cron 脚本由 PHP CLI 执行，与 Web 请求（php-fpm）是两套进程环境；TZ 等环境变量对两边的影响不同（见 4.11 与"八、常见问题"）。

四、定时任务脚本详解（endpoints/cronjobs/）

4.1 脚本清单与调度配置

目录下共 13 个脚本（实测）：

ls /var/www/html/endpoints/cronjobs/

输出（实测）：

checkforupdates.php
cleanupresettokens.php
createdatabase.php
generaterecommendations.php
sendcancellationnotifications.php
sendnotifications.php
sendresetpasswordemails.php
sendverificationemails.php
settimezone.php
storetotalyearlycost.php
updateexchange.php
updatenextpayment.php
validate.php

裸机部署的调度配置 /etc/cron.d/wallos（实测全文，共 10 条；createdatabase.php/settimezone.php/validate.php 属一次性或启动期脚本，不进 crontab）：

# Wallos 定时任务（每天 01:00 更新下次付款日期，02:00 更新汇率，09:00 发送到期通知）
0 1 * * * root php /var/www/html/endpoints/cronjobs/updatenextpayment.php >> /var/log/cron/updatenextpayment.log 2>&1
0 2 * * * root php /var/www/html/endpoints/cronjobs/updateexchange.php >> /var/log/cron/updateexchange.log 2>&1
0 8 * * * root php /var/www/html/endpoints/cronjobs/sendcancellationnotifications.php >> /var/log/cron/sendcancellationnotifications.log 2>&1
0 9 * * * root php /var/www/html/endpoints/cronjobs/sendnotifications.php >> /var/log/cron/sendnotifications.log 2>&1
*/2 * * * * root php /var/www/html/endpoints/cronjobs/sendverificationemails.php >> /var/log/cron/sendverificationemail.log 2>&1
*/2 * * * * root php /var/www/html/endpoints/cronjobs/sendresetpasswordemails.php >> /var/log/cron/sendresetpasswordemails.log 2>&1
0 */6 * * * root php /var/www/html/endpoints/cronjobs/checkforupdates.php >> /var/log/cron/checkforupdates.log 2>&1
30 1 * * 1 root php /var/www/html/endpoints/cronjobs/storetotalyearlycost.php >> /var/log/cron/storetotalyearlycost.log 2>&1
30 3 * * 1 root php /var/www/html/endpoints/cronjobs/generaterecommendations.php weekly >> /var/log/cron/generaterecommendations.log 2>&1
0 4 1 * * root php /var/www/html/endpoints/cronjobs/generaterecommendations.php monthly >> /var/log/cron/generaterecommendations.log 2>&1

💡 说明：使用官方镜像的容器部署形态下，镜像已内置 crond 与 /etc/cron.d/cronjobs（11 条，比上表多一条每天 03:00 的 cleanupresettokens.php），无需手工配置；裸机部署才需要这张 crontab（配置方法见《Ubuntu 22.04 安装 Wallos 5.10.2 指南》）。以下 4.2–4.13 逐个脚本给出用途与手工执行的实测回显——手工执行常用于「改了配置想立即生效」或排障。

4.2 updatenextpayment.php：滚动更新下次付款日期

用途：按订阅的周期/频率把所有到期的 next_payment 滚动到下一个未来日期，是首页「即将付款」与日历视图准确的前提。调度：每天 01:00。

cd /var/www/html
php endpoints/cronjobs/updatenextpayment.php

输出（实测）：

2026-10-25 01:09:56<br />
UTC<br />
Updated next payment dates

回显解读：时间戳 + 当前生效时区（CLI 进程未注入 TZ 时回落到 UTC，不影响逻辑）+ 结果行。

4.3 updateexchange.php：更新汇率

用途：通过 Fixer API 拉取最新汇率写入 currencies 表，供多币种折算。调度：每天 02:00。

php endpoints/cronjobs/updateexchange.php

输出（实测，未配置 Fixer API Key 时）：

2026-10-25 01:09:56<br />
For user: admin<br />Exchange rates update skipped. No fixer.io api key provided<br />

⚠️ 注意：脚本按用户逐个处理；显示 skipped 表示该用户未在设置页配置 Fixer API Key，多币种折算对该用户不可用。配置方法见《Wallos 5.10.2 配置参数详解》 5.4 节。

4.4 sendnotifications.php：发送到（到）期提醒

用途：按各用户设置的通知渠道与「提前 N 天」规则，发送订阅到期提醒。调度：每天 09:00。

php endpoints/cronjobs/sendnotifications.php

输出（实测，当前无进入提醒窗口的订阅时仅打印时间戳）：

2026-10-25 01:09:56<br />

4.5 sendcancellationnotifications.php：发送取消窗口提醒

用途：对标记了取消期限的订阅发送提醒。调度：每天 08:00。

php endpoints/cronjobs/sendcancellationnotifications.php

输出（实测）：无输出，退出码 0（无待办时静默）。

php endpoints/cronjobs/sendcancellationnotifications.php; echo "exit=$?"

exit=0

4.6 sendverificationemails.php / sendresetpasswordemails.php：邮件外发泵

用途：Wallos 把「邮箱验证邮件」与「密码重置邮件」先入队，再由这两个脚本外发（每 2 分钟一次，避免 Web 请求阻塞在 SMTP 上）。

php endpoints/cronjobs/sendverificationemails.php; echo "exit=$?"
php endpoints/cronjobs/sendresetpasswordemails.php; echo "exit=$?"

输出（实测，队列为空时静默）：

exit=0
exit=0

⚠️ 注意：这两条每 2 分钟跑一次，依赖 SMTP 配置；若用户反馈收不到验证/重置邮件，先看这两个脚本的日志（/var/log/cron/ 下对应文件）再查 SMTP 参数。

4.7 checkforupdates.php：检查新版本

用途：每 6 小时向官方检查一次新版本，结果写入 admin 表 latest_version 字段（界面顶部据此提示升级）。

php endpoints/cronjobs/checkforupdates.php; echo "exit=$?"

输出（实测）：静默成功。

exit=0

验证结果已写库（实测）：

sqlite3 /var/www/html/db/wallos.db "SELECT latest_version FROM admin;"

v5.10.2

4.8 storetotalyearlycost.php：沉淀年度总花费

用途：每周一 01:30 把每个用户的年度订阅总花费写入 total_yearly_cost 表，供统计页绘制历史趋势。

php endpoints/cronjobs/storetotalyearlycost.php

输出（实测，演示环境有一条 Netflix 标准版订阅，月付 68 元 × 12 = 816）：

2026-10-25 01:09:56<br />
Inserted total yearly cost for user 1 with cost 816<br />

4.9 generaterecommendations.php：生成 AI 订阅建议

用途：调用用户在设置页配置的 AI 提供方（ChatGPT / Gemini / Ollama）生成订阅优化建议，结果写入 ai_recommendations 表。调度：每周一 03:30 跑 weekly、每月 1 日 04:00 跑 monthly。

php endpoints/cronjobs/generaterecommendations.php weekly

输出（实测，未配置 AI 提供方时处理数为 0）：

Running weekly AI Recommendations generation.
{"success":true,"run_type":"weekly","processed":0,"successes":0,"failures":[]}

php endpoints/cronjobs/generaterecommendations.php monthly

输出（实测）：

Running monthly AI Recommendations generation.
{"success":true,"run_type":"monthly","processed":0,"successes":0,"failures":[]}

回显解读：JSON 中 processed 为处理了配置 AI 的用户数，failures 非空时会列出失败用户与原因——配了 AI 但建议没更新时先手工跑这条看输出。

4.10 cleanupresettokens.php：清理过期密码重置令牌

用途：删除 password_resets 表中的过期令牌（安全卫生）。容器镜像内置调度为每天 03:00，裸机可自行追加到 crontab。

php endpoints/cronjobs/cleanupresettokens.php

输出（实测）：

Expired password reset tokens cleaned up successfully.

4.11 settimezone.php：启动期时区校准

用途：供启动/初始化阶段校准 PHP 运行时默认时区，取值顺序为 TZ 环境变量 → date_default_timezone_get() → UTC。手工执行验证（实测）：

php endpoints/cronjobs/settimezone.php; echo "exit=$?"

exit=0

静默属正常；确认实际生效时区用 4.2 的回显第二行（CLI 未注入 TZ 时显示 UTC）。

4.12 createdatabase.php：初始化空库（一次性）

用途：数据库文件不存在时创建初始 schema 并生成恢复令牌（setup_token.db），是首次安装链路的底层脚本（Web 注册流程会自动触发等价逻辑，正常无需手工执行）。为安全起见，在隔离副本中实测执行：

Database does not exist. Creating it...
Database created.
Setup token for database restore: 84f27a4df843f08119a8716931c3ca0358e061591417a31067b8bdac0972e6c2

随后副本目录下生成 wallos.db 与 setup_token.db（64B），库内含 user、subscriptions、categories、currencies 等 13 张初始表。

⚠️ 注意：严禁在已有数据的部署上手工执行——脚本仅在 db/wallos.db 不存在时才建库，但也没有二次确认交互；setup_token 是恢复端点（5.3）的校验令牌，泄露意味着任何人可覆盖你的数据库。

4.13 validate.php：环境自检

用途：校验 PHP 环境（必需扩展、目录可写性等）是否满足运行要求，常用于部署后自检。实测当前环境全部通过、无输出：

php endpoints/cronjobs/validate.php; echo "exit=$?"

exit=0

检查不通过时会逐条输出缺失项，按提示补装即可。

五、数据库维护端点详解（endpoints/db/）

目录清单（实测）：

ls /var/www/html/endpoints/db/

backup.php
import.php
migrate.php
restore.php

5.1 migrate.php：数据库迁移（升级必用）

用途：版本升级后执行未跑过的迁移脚本，把库结构升到当前版本。CLI 与 Web 双入口（Web 入口要求管理员登录）。

cd /var/www/html
php endpoints/db/migrate.php

输出（实测，当前已是最新结构）：

No migrations to run.

有迁移待执行时，每完成一条打印一行（格式源自迁移器源码）：

Migration migrations/000XXX.php completed successfully.

💡 说明：裸机升级流程是「覆盖源码 → 执行本脚本」；容器部署则由启动脚本自动调用，无需手工执行（见《Wallos 5.10.2 Docker Compose 部署指南》第十章）。

5.2 backup.php：整库备份下载

用途：管理员在 Admin 页触发，把数据库与上传的 Logo 打包为 zip 流式下载（不在服务器落临时文件）。该端点仅限 Web 管理员会话调用，无 CLI 用法；命令行等价做法：

sudo tar czf wallos-backup-$(date +%F).tar.gz -C /var/www/html db images/uploads/logos
ls -lh wallos-backup-*.tar.gz

5.3 restore.php / import.php：恢复与导入

restore.php：把 backup.php 产出的 zip 上传恢复；Web 端点会校验 setup_token（即 4.12 生成、db/setup_token.db 中保存的令牌），防止未授权覆盖。
import.php：从其他订阅管理工具导入数据，仅在空库状态下可用，同样校验 setup_token。

两者均为 Web 管理端点，无 CLI 参数；排障要点是确认 db/setup_token.db 文件存在且内容与界面提示一致。

六、sqlite3 直连数据库查询

所有配置与业务数据都在单文件 /var/www/html/db/wallos.db 中，直连查询是最高效的排障手段。改库前先备份：cp db/wallos.db db/wallos.db.bak。

查全量表清单（实测 40 张）：

sqlite3 /var/www/html/db/wallos.db ".tables"

admin                          notification_settings        
ai_recommendations             notifications                
ai_settings                    ntfy_notifications           
categories                     oauth_settings               
currencies                     password_resets              
custom_colors                  payment_methods              
custom_css_style               push_notifications           
cycles                         push_subscriptions           
discord_notifications          pushover_notifications       
email_notifications            pushplus_notifications       
email_verification             serverchan_notifications     
fixer                          settings                     
frequencies                    subscription_categories      
google_search                  subscription_payers          
gotify_notifications           subscriptions                
household                      telegram_notifications       
last_exchange_update           total_yearly_cost            
last_update_next_payment_date  totp                         
login_tokens                   uploaded_avatars             
mattermost_notifications       user                         
migrations                     webhook_notifications

查用户与主币种（实测）：

sqlite3 /var/www/html/db/wallos.db "SELECT id,username,email,main_currency FROM user;"

1|admin|admin@example.com|21

查迁移历史（确认升级是否到位，实测最近 2 条）：

sqlite3 /var/www/html/db/wallos.db "SELECT * FROM migrations ORDER BY id DESC LIMIT 2;"

60|migrations/000061.php|2026-10-25 00:51:45
59|migrations/000060.php|2026-10-25 00:51:45

查订阅清单（实测，演示数据 1 条）：

sqlite3 /var/www/html/db/wallos.db "SELECT id,name,price,currency_id,next_payment FROM subscriptions;"

1|Netflix 标准版|68.0|21|2026-11-15

未安装 sqlite3 时的兜底写法（用 PHP CLI 查，实测等价）：

php -r '$db=new SQLite3("/var/www/html/db/wallos.db"); $r=$db->query("SELECT id,username,email FROM user"); while($row=$r->fetchArray(SQLITE3_ASSOC)){ echo json_encode($row).PHP_EOL; }'

输出（实测）：

{"id":1,"username":"admin","email":"admin@example.com"}

七、注意事项

先备份再动库：任何 sqlite3 写操作前 cp db/wallos.db db/wallos.db.bak；Web 界面能完成的操作优先走界面。
CLI 与 Web 是两个进程环境：cron 脚本以 PHP CLI 运行，TZ、SMTP 等环境变量若只配在 php-fpm 池里，CLI 侧读不到；反之亦然。两边时区不一致只影响日志时间戳，不影响业务逻辑。
脚本幂等可重跑：4.2–4.11 的周期脚本均可安全手工重跑（重复执行只产生重复日志行，不产生重复数据——storetotalyearlycost.php 例外，多次执行会插入多条同日记录，排障重跑后建议删除多余行）。
createdatabase.php 只在空库时用：见 4.12 的安全提示。
邮件类脚本静默≠异常：队列为空时 sendverificationemails.php 等无任何输出，属正常；判故障看退出码与 /var/log/cron/ 日志。
容器形态路径：官方镜像内脚本路径与裸机一致（/var/www/html/endpoints/ 下同名脚本），用 docker exec wallos-5.10.2-app php endpoints/cronjobs/updatenextpayment.php 方式执行。

八、常见问题

8.1 手工跑 cron 脚本报 `Could not open input file`？

当前目录不对。先 cd /var/www/html 再用相对路径，或直接用绝对路径 php /var/www/html/endpoints/cronjobs/updatenextpayment.php。

8.2 页面时间/ cron 日志时间戳与本地差 8 小时？

CLI 进程未注入 TZ（见 4.2 回显第二行的 UTC）。在 crontab 行首加 TZ=Asia/Shanghai 或给 cron 守护进程配置时区；Web 侧时区由 php-fpm 环境决定，互不影响。

8.3 升级后功能报错/字段不存在？

先跑 php endpoints/db/migrate.php（回显 No migrations to run. 才说明结构已最新），再用 6 节的 migrations 查询核对最新迁移号与源码 migrations/ 目录最大编号一致。

8.4 忘了管理员密码，SMTP 又没配？

直连改库重置（实测通过，以重置 admin 为 q1w2e3r4 为例）：

# 1. 生成哈希并通过 shell 变量传递（避免哈希中的 $ 被展开）
HASH=$(php -r 'echo password_hash("q1w2e3r4", PASSWORD_DEFAULT);')

# 2. 更新 admin 记录
sqlite3 /var/www/html/db/wallos.db "UPDATE user SET password=\"$HASH\" WHERE username=\"admin\";"

# 3. 验证写入（长度 60、$2y$10 前缀即 bcrypt 哈希）
sqlite3 /var/www/html/db/wallos.db "SELECT username, length(password), substr(password,1,7) FROM user;"

输出（实测）：

admin|60|$2y$10$

8.5 如何确认定时任务真的在跑？

看 /var/log/cron/ 下各日志的修改时间与新追加内容，例如：

ls -l /var/log/cron/
tail -3 /var/log/cron/updatenextpayment.log

日志每天 01:00 后应有新行；没有则检查 crond 服务状态与 /etc/cron.d/wallos 语法（每行 6 段、用户字段 root 不可省）。

九、参考链接

官方仓库（cron 脚本源码在 endpoints/ 目录）：https://github.com/ellite/Wallos
官方演示站：https://demo.wallosapp.com
本站相关文档：《Wallos 介绍与选型指南》、《Ubuntu 22.04 安装 Wallos 5.10.2 指南》、《Wallos 5.10.2 Docker Compose 部署指南》、《Wallos 5.10.2 配置参数详解》

Wallos 5.10.2 常用 CLI 命令与工具详解

Wallos 5.10.2 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、定时任务脚本详解（endpoints/cronjobs/）

4.1 脚本清单与调度配置

4.2 updatenextpayment.php：滚动更新下次付款日期

4.3 updateexchange.php：更新汇率

4.4 sendnotifications.php：发送到（到）期提醒

4.5 sendcancellationnotifications.php：发送取消窗口提醒

4.6 sendverificationemails.php / sendresetpasswordemails.php：邮件外发泵

4.7 checkforupdates.php：检查新版本

4.8 storetotalyearlycost.php：沉淀年度总花费

4.9 generaterecommendations.php：生成 AI 订阅建议

4.10 cleanupresettokens.php：清理过期密码重置令牌

4.11 settimezone.php：启动期时区校准

4.12 createdatabase.php：初始化空库（一次性）

4.13 validate.php：环境自检

五、数据库维护端点详解（endpoints/db/）

5.1 migrate.php：数据库迁移（升级必用）

5.2 backup.php：整库备份下载

5.3 restore.php / import.php：恢复与导入

六、sqlite3 直连数据库查询

七、注意事项

八、常见问题

8.1 手工跑 cron 脚本报 Could not open input file？

8.2 页面时间/ cron 日志时间戳与本地差 8 小时？

8.3 升级后功能报错/字段不存在？

8.4 忘了管理员密码，SMTP 又没配？

8.5 如何确认定时任务真的在跑？

九、参考链接

8.1 手工跑 cron 脚本报 `Could not open input file`？