InvoiceShelf 2.4.7 常用 CLI 命令与工具详解

InvoiceShelf 2.4.7 命令行工具体系详解：artisan 命令清单与分组、6 条应用专属命令逐个实测、备份恢复、维护模式、数据库检查、队列排障实录与配置优化速查。

InvoiceShelf发票管理自托管配置2026/10/24

InvoiceShelf 2.4.7 常用 CLI 命令与工具详解

目标：系统梳理 InvoiceShelf 2.4.7 的命令行工具体系——artisan 命令清单与分组、应用专属命令逐个详解、备份恢复、维护模式、数据库检查、队列排障与配置优化的实操用法。已在 InvoiceShelf 2.4.7（PHP 8.4.27 / Laravel 13.15.0，SQLite 与 MariaDB 双形态）实测通过。

一、环境信息

本文实测环境与口径：

  • 应用版本：InvoiceShelf 2.4.7 stable（2026-10-21 发布，2026-10-24 实查为官方最新稳定版）；运行时 PHP 8.4.27、Laravel Framework 13.15.0（php artisan about 实测）
  • 数据库形态：SQLite 3.53.4（44 表）与 MariaDB 11.8.9（44 表，2.38 MB）双形态实测，命令行为一致（差异在第六章单独标注）
  • 命令总数：应用根目录执行 php artisan list 实测注册命令 180 条（含 Laravel 框架与第三方包命令），其中 InvoiceShelf 应用专属命令 6 条
  • 实测已装数据：管理员 1 名（admin@example.com）、发票 0 张（安装向导完成后的初始态），tinker 实测计数确认
  • 执行视角：除特别说明外，所有命令均在应用根目录 /var/www/html 下执行 php artisan <命令>；随打包形态部署时，通过部署编排工具进入应用执行（见本专栏部署篇），传统服务器部署则直接在根目录执行

二、前置条件

  1. 已有一套可运行的 InvoiceShelf 2.4.7（部署方法见本专栏《InvoiceShelf Docker Compose 部署指南》）；
  2. 命令执行者需能进入应用根目录，且以运行应用的同一系统用户身份执行（避免生成属主错乱的缓存文件）；
  3. 修改性命令（migrate、reset:app、backup:run 等）执行前建议先了解第四章的只读检查命令，先查状态再动手；
  4. 本文涉及的 .env 参数含义见本专栏《InvoiceShelf 2.4.7 配置参数详解》。

三、命令体系总览

3.1 入口与清单

cd /var/www/html && php artisan list

实测输出为分组列表，头部显示框架版本（节选）：

Laravel Framework 13.15.0

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for a command
  ...
Available commands:
  about                    Display basic information about your application
  ...

统计口径下的 180 条命令按命名空间分组（实测节选）：框架通用组（about/migrate/config/route/schedule/queue/db/tinker/down/up 等）、备份组（backup:*，由 spatie/laravel-backup 提供）、权限组（permission:*）、以及应用专属组（check/core/recurring-invoices/reset，见第五章）。

单条命令的帮助随时可查：

php artisan <命令> --help

3.2 应用专属命令清单

php artisan list 中 InvoiceShelf 自有命令共 6 条（实测）：

命令描述（官方原文）用途
check:invoices:statusCheck invoices status.发票逾期状态批量刷新
check:estimates:statusCheck invoices status.报价单过期状态批量刷新
core:updateAutomatically update your InvoiceShelf Core App应用升级后的核心更新
make:template <name>Create estimate or invoice pdf template.生成 PDF 模板脚手架
recurring-invoices:generateGenerate invoices for every recurring invoice whose next run has come.周期发票按计划生成
reset:appClean database and public/storage folder清空业务数据（高危）

这 6 条命令同时是调度器的执行单元：schedule:list 实测显示调度器每分钟调用 recurring-invoices:generate、每天零点调用两条 check:* 命令（见 3.3）。也就是说，业务命令通常由调度器自动跑；手动执行主要用于调试、补跑与验证。

3.3 调度任务清单

php artisan schedule:list

实测回显：

  0 0 * * *  php artisan check:invoices:status ... Next Due: 19 hours from now
  0 0 * * *  php artisan check:estimates:status .. Next Due: 19 hours from now
  * * * * *  php artisan recurring-invoices:generate  Next Due: 27 seconds from now

解读：三条 cron 任务——两条 check:* 每日零点（发票置 OVERDUE、报价置 EXPIRED），周期发票生成每分钟一次。Next Due 显示下次执行时间，可用于确认调度是否注册。若任务应跑未跑，先看这里；再按部署形态确认调度驱动（打包形态内置调度器 / 手动部署 crontab php artisan schedule:run），配置细节见本专栏配置篇 5.6。

四、状态查看命令（只读）

4.1 php artisan about：应用概貌

php artisan about

实测回显（节选，Drivers 区块速查价值最高）：

  Environment ................................................................
  Application Name .............................................. InvoiceShelf
  Laravel Version .................................................... 13.15.0
  PHP Version ......................................................... 8.4.27
  Environment ..................................................... production
  Debug Mode ............................................................. OFF
  URL ......................................................... localhost:8129
  Maintenance Mode ....................................................... OFF

  Cache ......................................................................
  Config .......................................................... NOT CACHED
  Views ............................................................... CACHED

  Drivers ....................................................................
  Cache ................................................................. file
  Database ............................................................ sqlite
  Mail ................................................................... log
  Queue ................................................................. sync
  Session ............................................................... file

用法要点：Maintenance Mode 一眼确认应用是否在维护态；Config: CACHED/NOT CACHED 决定改 .env 后要不要 config:clear；Drivers 区块五个驱动当前值与 .env 参数一一对应。

4.2 php artisan db:show：数据库概貌

php artisan db:show

SQLite 形态实测回显（节选）：

  SQLite .............................................................. 3.53.4
  Connection .......................................................... sqlite
  Database ....................................... storage/app/database.sqlite
  Tables .................................................................. 44

MariaDB 形态实测回显（节选）：

  MariaDB ............................................................. 11.8.9
  Connection ........................................................... mysql
  Database ...................................................... invoiceshelf
  Host .................................................................... db
  Port .................................................................. 3306
  Username ...................................................... invoiceshelf
  Tables .................................................................. 44
  Total Size ......................................................... 2.38 MB

db:show 同时列出全部表名，是核对部署完整性的第一命令：44 张表与官方迁移基线一致即安装完整。

4.3 php artisan db:table：表结构检查

php artisan db:table users

实测回显（节选）：

  main.users .................................................................
  Columns ................................................................. 19

  Column ................................................................ Type
  id integer, autoincrement .......................................... integer
  name varchar ....................................................... varchar
  email varchar, nullable ............................................ varchar
  phone varchar, nullable ............................................ varchar
  password varchar, nullable ........................................ varchar
  role varchar ................................................ 'user' varchar
  ...
  enable_portal tinyint, nullable ................................. tinyint(1)
  currency_id integer, nullable ...................................... integer
  company_id integer, nullable ....................................... integer

排障场景：怀疑字段缺失（老库升级后）、核对迁移是否生效、确认某业务字段类型时用它；不带表名时列出全部表供选择。

4.4 php artisan migrate:status：迁移状态

php artisan migrate:status

实测回显（节选）：

  Migration name .............................................. Batch / Status
  2014_10_11_071840_create_companies_table ........................... [1] Ran
  2014_10_11_125754_create_currencies_table .......................... [1] Ran
  2014_10_12_000000_create_users_table ............................... [1] Ran
  2016_05_13_060834_create_settings_table ............................ [1] Ran
  2017_04_12_090759_create_invoices_table ............................ [1] Ran
  ...（中间省略）...
  2026_09_23_100000_reissue_public_link_tokens ................. [1] Ran

解读：[批次号] Ran 表示已执行；升级版本后若出现 Pending 即待执行迁移，执行 php artisan migrate 补跑（打包形态 AUTORUN_LARAVEL_MIGRATION=true 时启动自动补跑）。

4.5 php artisan module:list：模块清单

php artisan module:list

实测回显（初始安装无第三方模块）：

+------+--------+----------+------+
| Name | Status | Priority | Path |
+------+--------+----------+------+
+------+--------+----------+------+

空表即初始态。InvoiceShelf 的模块机制允许以 Modules 目录挂载扩展（该目录独立持久化，见部署篇第七章），装了第三方模块后会在此列出并显示启用状态。

五、应用专属命令详解

5.1 check:invoices:status / check:estimates:status：状态刷新

php artisan check:invoices:status
php artisan check:estimates:status

行为：扫描全部未结发票（或报价单），把超过到期日的记录状态置为 OVERDUE（报价单为 EXPIRED）。实测为静默执行（无回显即成功）。

手动执行场景：调度器停摆期间补状态、刚批量导入历史数据后刷新、调试状态联动逻辑时验证。直接重跑幂等，无副作用。

5.2 recurring-invoices:generate：周期发票生成

php artisan recurring-invoices:generate

行为：扫描全部启用状态的周期发票计划，凡「下次生成时间」已到的按计划生成新发票。实测为静默执行。

验证是否在自动跑（推荐流程）：

php artisan schedule:list          # 确认任务注册（见 3.3）

并观察应用日志每分钟有无执行记录（实测节选）：

  2026-10-24 00:42:00 Running ['artisan' recurring-invoices:generate]  288.75ms DONE

⚠️ 多实例部署时只能让一个实例跑调度（打包形态 SCHEDULER_ENABLED=true 的那一个），否则周期发票会重复生成；手动补跑同样要注意与调度器的时点错开。

5.3 core:update：核心更新

php artisan core:update

官方描述：Automatically update your InvoiceShelf Core App。用途：通过后台在线升级替换代码后（或手动覆盖代码升级后），执行核心数据的收尾更新（配置合并、缓存刷新等升级动作）。

帮助信息实测（core:update --help）：

Description:
  Automatically update your InvoiceShelf Core App

Usage:
  core:update

适用场景：手动部署（无打包层自动升级流程）的升级收尾；升级完成后配合 migrate:status 确认迁移全部 Ran。

5.4 make:template：PDF 模板脚手架

php artisan make:template new_theme --type=invoice

帮助信息实测（make:template --help）：

Description:
  Create estimate or invoice pdf template.

Usage:
  make:template [options] [--] <name>

Arguments:
  name

Options:
      --type[=TYPE]

行为：按名称生成一个自定义 PDF 模板骨架（--type 指定 invoice 或 estimate），生成后在应用存储的模板目录中，经后台设计器进一步编辑使用。适合想基于官方模板二次定制票据版式的场景；纯后台可视化定制则不需要此命令。

5.5 reset:app：清空业务数据（高危命令）

php artisan reset:app --force

帮助信息实测（reset:app --help）：

Description:
  Clean database and public/storage folder

Usage:
  reset:app [options]

Options:
      --force

行为：清空数据库全部业务数据并清空公共存储目录，应用回到「安装完成但无任何业务数据」的初始态（公司与管理员记录一并清除，需重走安装向导）。

⚠️ 三重高危提示：其一，此命令不可逆，执行前必须确认已有可用备份（第六章）；其二，必须显式加 --force 才执行（无交互确认设计）；其三，只应在新装环境试跑向导后重置，生产数据一律用备份恢复回滚，绝不用 reset:app。实测本环境未执行该命令，仅通过 --help 确认行为定义。

六、备份与恢复命令

6.1 backup:run：执行备份

php artisan backup:run

实测回显（SQLite 形态，全新安装后首次备份）：

Starting backup...
Dumping database /var/www/html/storage/app/database.sqlite...
Determining files to backup...
Zipping 1751 files and directories...
Created zip containing 1751 files and directories. Size is 6.46 MB
Copying zip to disk named local...
Successfully copied zip to disk named local.
Backup completed!

解读：备份包包含数据库导出与应用存储文件（storage/app/ 下附件、上传物），落到本地磁盘（storage/app/backup/，随存储卷持久化）。MariaDB 形态行为一致（数据库导出自动走 mysqldump 类工具）。备份包可配置推送到远端存储（S3 兼容等，经后台文件磁盘配置），本文实测为默认本地磁盘。

6.2 backup:list：备份清单与健康检查

php artisan backup:list

实测回显（已有 2 次备份后执行）：

+--------------+-------+-----------+---------+--------------+--------------------+--------------+
| Name         | Disk  | Reachable | Healthy | # of backups | Newest backup      | Used storage |
+--------------+-------+-----------+---------+--------------+--------------------+--------------+
| InvoiceShelf | local | ✅        | ✅      |            2 | 0.15 (3 hours ago) |     12.91 MB |
+--------------+-------+-----------+---------+--------------+--------------------+--------------+

该命令同时执行备份健康检查（Reachable/Healthy 两列）：目标磁盘不可达或备份损坏时对应列变 ❌；从未执行过备份时，实测会先输出告警行「⚠️ A backup has not been run yet! Consider running one now.」并列出空清单。

💡 运维建议：把 backup:list 纳入巡检——Healthy 列变 ❌ 或清单为空即触发一次 backup:run；backup:run 本身可放进系统 crontab 定时执行（注意与调度器的每分钟任务区分，备份频率按数据量自定，小团队每日一次常见）。

6.3 备份清理与恢复

  • php artisan backup:clean：按保留策略清理过期备份包，防止磁盘被逐日备份撑满；
  • 恢复操作没有 artisan 命令，标准流程为手工操作：解包备份 zip → 数据库部分导入目标库（SQLite 用 sqlite3 恢复 database.sqlite，MariaDB 用 mysql 客户端导入 dump）→ 文件部分覆盖回 storage/app/ 对应目录 → 核对 .env 中 APP_KEY 与备份时的值一致（见配置篇 Q4）。

七、维护模式命令

php artisan down

实测回显与效果验证：

   INFO  Application is now in maintenance mode.

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8129/

实测回显：

503

恢复：

php artisan up

实测回显与效果验证：

   INFO  Application is now live.

200

用法要点：维护模式下所有访问返回 503，是数据库结构变更、数据导入导出、备份恢复前的标准保护动作；down 支持 --secret=<令牌> 参数（带令牌可绕过维护页继续访问，便于维护中自测）；打包形态下应用由自动重启策略托管，维护操作尽量用 down/up 软开关而非重启服务。

八、队列任务命令

8.1 queue:failed 与一次真实排障

php artisan queue:failed

实测回显（SQLite 初始态直接执行）：

In Connection.php line 841:

  SQLSTATE[HY000]: General error: 1 no such table: failed_jobs (Connection:
  sqlite, Database: /var/www/html/storage/app/database.sqlite, SQL: select *
  from "failed_jobs" order by "id" desc)

In Connection.php line 421:

  SQLSTATE[HY000]: General error: 1 no such table: failed_jobs

排障解读（实测沉淀）：这不是应用故障——InvoiceShelf 默认队列驱动为 sync（同步执行，config:show queue 实测确认），任务失败直接在请求内报错，从不写入失败表；初始迁移基线里也没有创建 failed_jobs 表，所以队列相关命令在这张表上必然报错。结论分两层：

  • 默认形态（QUEUE_CONNECTION=sync）：忽略 queue:failed 的报错，队列运维命令均无实际对象，邮件等任务失败直接查应用日志；
  • 启用数据库队列后（.env 改 QUEUE_CONNECTION=database 并执行 php artisan queue:batches-table/迁移补齐 failed_jobs 等队列表）：queue:work 常驻消费、queue:failed 查失败清单、queue:retry <id> 重试、queue:flush 清空，全套命令才可用。

8.2 tinker：交互式调试

php artisan tinker

进入交互式 PHP Shell（应用上下文全量加载），可直接调用模型与查询。实测一次计数验证（--execute 一行式）：

php artisan tinker --execute="echo 'users: '.\DB::table('users')->count().PHP_EOL; echo 'invoices: '.\DB::table('invoices')->count().PHP_EOL;"

实测回显：

users: 1
invoices: 0

适用场景：核对数据量（上例即「安装向导完成后的初始态应有 1 名管理员、0 张发票」）、手工修改个别字段、验证模型行为。> ⚠️ tinker 直连数据库绕过界面校验，写操作仅限排障与小修，生产改动优先走应用界面。

九、配置与优化命令

命令作用实测要点
php artisan config:show <组>查看某组配置生效值session/mail/cache/queue 均实测可用（回显样例见配置篇）
php artisan config:clear清除配置缓存改 .env 后的标准动作，实测回显 INFO Configuration cache cleared successfully.
php artisan optimize生成配置/路由等缓存打包形态 AUTORUN_LARAVEL_OPTIMIZE=true 时启动自动执行；手动执行后 about 的 Config 变 CACHED
php artisan route:list列出全部路由实测 255 条路由；grep api/v1 可速查接口路径
php artisan key:generate --show生成加密密钥（仅显示）每次返回随机新串；写入需去 --show（迁移必须保留旧值，见配置篇 3.4）

💡 route:list 是接口排查的瑞士军刀：实测 api/v1/customers 系列即有 index/store/show/update/destroy 等完整 CRUD 路由（255 条总数含全部资源与后台路由），接口联调前先查这里确认路径与方法。

十、命令速查表

场景命令
应用版本/驱动速查php artisan about
数据库完整性与表清单php artisan db:show
查某张表结构php artisan db:table <表名>
迁移是否齐php artisan migrate:status（Pending 则 php artisan migrate）
调度任务注册确认php artisan schedule:list
发票/报价状态补刷php artisan check:invoices:status / check:estimates:status
周期发票补跑php artisan recurring-invoices:generate
升级收尾php artisan core:update && php artisan migrate:status
立即备份php artisan backup:run
备份巡检php artisan backup:list
清理旧备份php artisan backup:clean
维护开关php artisan down / php artisan up
改配置后生效php artisan config:clear
交互排障php artisan tinker

十一、常见问题

Q1：queue:failed 报 no such table: failed_jobs。 默认队列驱动为 sync（同步），失败任务从不落表，该命令在默认形态下无对象可查，报错可忽略（第八章 8.1 实测详解）。启用数据库队列并补齐迁移后即恢复正常。

Q2：命令执行后没有任何输出，算成功吗？ check:*、recurring-invoices:generate 等业务命令设计为静默执行，无回显即成功。验证效果用对应查询：状态刷新后查 migrate:status/数据库，周期发票生成后看应用日志的 Running ['artisan' ...] DONE 记录。

Q3：周期发票没有自动生成。 按序排查：schedule:list 确认三条任务注册 → 确认调度驱动在跑（打包形态内置调度器，看日志每分钟执行记录；手动部署确认 crontab 有 schedule:run）→ 多实例部署确认只有一个实例开调度 → 手动执行 recurring-invoices:generate 验证命令本身可用。

Q4：备份包在哪里、怎么挪走？ 默认在应用存储的 app/backup/ 目录（随存储持久化）。实测首次备份 1751 个文件 6.46 MB。挪走即拷贝该目录文件；恢复流程见第六章 6.3。

Q5：reset:app 之后还能恢复吗？ 不能自愈——它清空数据库与公共存储，无回收机制。唯一恢复途径是提前做过的备份（backup:run）。因此该命令只建议在测试环境使用。

Q6：migrate:status 出现 Pending 怎么办？ 升级后正常现象，php artisan migrate 补跑；打包形态且 AUTORUN_LARAVEL_MIGRATION=true 时重启应用服务自动补跑。补跑前建议先备份。

Q7：手动部署和打包部署执行这些命令有区别吗？ 命令本身完全一致（本文在两种形态均实测）。区别只在进入方式：手动部署在服务器应用根目录直接执行；打包部署通过部署编排工具进入应用执行（见部署篇）。调度与迁移的自动行为由部署层环境变量控制（配置篇 5.8）。

十二、参考链接

  1. Laravel 13 artisan 官方文档（框架命令语义溯源）：https://laravel.com/docs/artisan
  2. spatie/laravel-backup（backup:* 命令来源）：https://github.com/spatie/laravel-backup
  3. InvoiceShelf 主仓库（命令实现源码）：https://github.com/InvoiceShelf/InvoiceShelf
  4. 2.4.7 发布公告：https://github.com/InvoiceShelf/InvoiceShelf/releases/tag/2.4.7
  5. 本专栏部署篇：《InvoiceShelf Docker Compose 部署指南》
  6. 本专栏配置篇：《InvoiceShelf 2.4.7 配置参数详解》
  7. 本专栏认知篇：《InvoiceShelf 介绍与选型指南》