LinkStack 4.8.8 常用 CLI 命令与工具详解
以 php83 artisan 为主体逐条实测 LinkStack 4.8.8 的 CLI 命令族：应用信息、迁移与库表、spatie 备份族、缓存、维护模式、路由调度与翻译工具，含 config:cache 禁用根因、backup:list 健康盲区与 6 则排障实录。
LinkStack 4.8.8 常用 CLI 命令与工具详解
目标：LinkStack 构建在 Laravel 9 之上，CLI 运维面就是
php83 artisan命令族。本文按命令族实测 20+ 条命令的真实回显——应用信息（about/env/tinker）、数据库与迁移（migrate 族/db:show/db:table/db:monitor）、spatie 备份族（backup:run/clean/list/monitor，含 MySQL 形态两处必修配置）、缓存与性能（含 config:cache 在本应用不可用的根因）、维护模式（artisan down与.env的MAINTENANCE_MODE差异实测）、路由与调度、用户数据清理、翻译工具，并沉淀 6 则排障实录。已在 Ubuntu 22.04（x86_64）服务器、LinkStack 4.8.8（MariaDB 11.4 系统库，Docker Compose 形态）上全量实测通过。部署见《LinkStack 4.8.8 Docker Compose 部署指南》，配置体系见《LinkStack 4.8.8 配置参数详解》。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64）
- LinkStack：v4.8.8（官方镜像
linkstackorg/linkstack:v4.8.8） - 框架内核：Laravel Framework 9.52.22（
php83 artisan --version实测） - PHP：8.3.36（
php83 artisan about --only=environment实测）；Alpine 基础镜像，CLI 二进制名为php83，PATH 中没有裸php（见第十一章 Q1） - 系统数据库：MariaDB 11.4（
DB_CONNECTION=mysql），缓存/会话驱动均为file - 应用目录：容器内
/htdocs；本文所有命令的宿主机执行形态：
cd /opt/linkstack-stack && docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan <命令>'
非容器（源码直装）形态则直接 cd 到应用根目录用 php artisan 执行，回显一致。
💡 技术拓展：artisan 是 Laravel 框架自带的命令行工具（基于 Symfony Console），凡构建在 Laravel 上的产品都继承这一整套命令：安装初始化、数据库迁移、缓存清理、维护模式、密钥管理都走
php artisan <命令>。LinkStack 没有自研独立 CLI（如 Nextcloud 的occ），artisan 就是它唯一的运维螺丝刀；LinkStack 的增量在于以 Composer 包形式挂进来的专属命令族（backup:*、visits:clean、translate等）。
二、命令族总览
php83 artisan list 实测输出共 159 行、约 130 条命令。与运维相关的族与本文实测小节：
| 命令族 | 代表命令 | 来源 | 本文实测小节 |
|---|---|---|---|
| 应用信息 | about / env / tinker | Laravel | 三 |
| 数据库与迁移 | migrate / migrate:status / db:show / db:table / db:monitor | Laravel | 四 |
| 备份 | backup:run / backup:clean / backup:list / backup:monitor | spatie/laravel-backup（LinkStack 捆绑） | 五 |
| 缓存与性能 | cache:clear / config:clear / config:cache / view:clear / package:discover | Laravel | 六 |
| 维护模式 | down / up | Laravel | 七 |
| 路由与调度 | route:list / schedule:list | Laravel | 八 |
| 用户与数据 | auth:clear-resets / visits:clean / storage:link / key:generate | Laravel + laravel-visits | 九 |
| 翻译工具 | translate / translation-check | LinkStack 自有 | 十 |
| GeoIP | geoip:clear / geoip:update | laravel-localization 系 | 九.2（含排障） |
make:* 脚手架族（39 条）与 livewire:* 开发族用于二次开发，运维场景用不到，不展开。
2.1 查看单命令帮助
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan help backup:run'
实测输出（节选）：
Description:
Run the backup.
Usage:
backup:run [options]
Options:
--filename[=FILENAME]
--only-db
--db-name[=DB-NAME] (multiple values allowed)
--only-files
--only-to-disk[=ONLY-TO-DISK]
--disable-notifications
--timeout[=TIMEOUT]
三、应用信息类
3.1 about（运行环境快照）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan about --only=environment'
实测输出：
Environment ................................................................
Application Name ................................................. LinkStack
Laravel Version .................................................... 9.52.22
PHP Version ......................................................... 8.3.36
Composer Version ......................................................... -
Environment .......................................................... local
Debug Mode ......................................................... ENABLED
URL ........................................................................
Maintenance Mode ....................................................... OFF
Debug Mode ENABLED 即 .env 的 APP_DEBUG=true——生产收工前用这行回显自查（改法见配置篇第八章）。
3.2 env（当前环境名）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan env'
实测输出：
INFO The application environment is [local].
3.3 tinker（一次性 PHP 交互/求值）
查业务数据统计（实测）：
docker compose exec linkstack sh -c \
"cd /htdocs && HOME=/tmp php83 artisan tinker --execute='echo \App\Models\User::count().\" users, \".\App\Models\Link::count().\" links, \".\App\Models\Button::count().\" buttons\";'"
实测输出：
1 users, 0 links, 117 buttons
（1 个管理员用户、0 条链接、117 个内置按钮类型记录。）
⚠️ 必须带 HOME=/tmp：镜像内 apache 用户的 HOME（/var/www）对进程不可写，psysh（tinker 的 REPL 引擎）启动即报错（详见第十一章 Q3）。
四、数据库与迁移类
4.1 migrate（升级后补跑迁移必用）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan migrate'
实测输出（已是最新时）：
INFO Nothing to migrate.
换镜像 tag 升级 LinkStack 版本后，此命令（加 --force）把新版本的迁移补齐，是官方 Docker 升级流程的固定一步（见部署篇第十章）。
4.2 migrate:status（迁移台账）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan migrate:status'
实测输出（全 12 条，安装向导时批量执行，Batch 全为 1）：
Migration name .............................................. Batch / Status
2014_10_12_000000_create_users_table ............................... [1] Ran
2014_10_12_100000_create_password_resets_table ..................... [1] Ran
2019_08_19_000000_create_failed_jobs_table ......................... [1] Ran
2021_03_17_044922_create_buttons_table ............................. [1] Ran
2021_03_18_082008_create_links_table ............................... [1] Ran
2021_03_18_082232_create_pages_table ............................... [1] Ran
2022_09_20_110657_sociallogin ...................................... [1] Ran
2022_09_20_143006_social_accounts .................................. [1] Ran
2022_09_21_115126_create_visits_table .............................. [1] Ran
2022_09_22_123137_link-type ........................................ [1] Ran
2023_03_08_184401_remove_unique_constraint_from_users_table ........ [1] Ran
2023_03_09_121613_update_columns_to_text_type ...................... [1] Ran
4.3 db:show（库级信息）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan db:show'
实测输出（节选）：
Database ......................................................... linkstack
Host .................................................................... db
Port .................................................................. 3306
Username ......................................................... linkstack
Open Connections ......................................................... 1
Tables .................................................................. 10
Total Size ......................................................... 0.30MiB
Table ........................................................... Size (MiB)
users ................................................................. 0.05
link_types ............................................................ 0.02
buttons ............................................................... 0.02
pages ................................................................. 0.02
migrations ............................................................ 0.02
visits ................................................................ 0.03
password_resets ....................................................... 0.03
social_accounts ....................................................... 0.05
failed_jobs ........................................................... 0.03
links ................................................................. 0.05
4.4 db:table（表结构速查）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan db:table users'
实测输出（节选）：
users ......................................................................
Columns ................................................................. 17
Size ............................................................... 0.05MiB
Column ................................................................ Type
id autoincrement, bigint, unsigned .................................. bigint
name string ......................................................... string
email string ........................................................ string
email_verified_at datetime, nullable .............................. datetime
password string, nullable ........................................... string
littlelink_name string, nullable .................................... string
littlelink_description text, nullable ................................. text
role string .................................................... user string
block string ..................................................... no string
...
Index ......................................................................
PRIMARY id ................................................. unique, primary
users_email_unique email ............................................ unique
users_littlelink_name_unique littlelink_name ........................ unique
role（user/admin）与 block（yes/no）是字符串枚举而非布尔——排查"用户登不进"时可直接查这两列。
4.5 db:monitor（连接数巡检）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan db:monitor --databases=mysql'
实测输出：
Database name .................................................. Connections
mysql ............................................................... [1] OK
五、备份命令族（backup:*，spatie/laravel-backup）
LinkStack 捆绑 spatie/laravel-backup 提供"应用文件+数据库"整包备份，产物为 zip。
5.1 前置修复（MySQL 形态必做，否则必失败）
镜像默认按 SQLite 形态出厂：/htdocs/config/backup.php 的数据库列表硬编码 ['sqlite']（实测第 84 行），且镜像未带 mysqldump。MySQL/MariaDB 部署需两步修复（排障全记录见部署篇第十一章 Q3）：
docker compose exec -u root linkstack sh -c "sed -i \"s/'sqlite',/'mysql',/\" /htdocs/config/backup.php"
docker compose exec -u root linkstack apk add --no-cache mariadb-client
第一处改动在 /htdocs 卷内、持久；第二处装在容器层、重建容器后丢失，固化需自建衍生镜像。
5.2 backup:run（执行整包备份）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan backup:run'
实测输出（尾部）：
Starting backup...
Dumping database linkstack...
Determining files to backup...
Zipping 10746 files and directories...
Created zip containing 10746 files and directories. Size is 21.43 MB
Copying zip to disk named backups...
Successfully copied zip to disk named backups.
Sending notification failed
Backup completed!
--only-db/--only-files可分别只备库或只备文件（实测--help见 2.1）；Sending notification failed无害——未配置通知渠道，不影响产物；- 产物落点（实测
find）：/htdocs/backups/updater-backups/，文件名形如M7LPHX5HgpIIqL4S-2026-11-02-17-12-27.zip（该目录同时是内置更新器的备份池，backup.php第 13 行'name' => 'updater-backups'）。
5.3 backup:list / backup:monitor（健康视图有盲区）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan backup:list'
实测输出（backup:run 刚成功之后）：
+-----------+-------+-----------+---------+--------------+--------------------+--------------+
| Name | Disk | Reachable | Healthy | # of backups | Newest backup | Used storage |
+-----------+-------+-----------+---------+--------------+--------------------+--------------+
| LinkStack | local | ✅ | ❌ | 0 | No backups present | 0 KB |
+-----------+-------+-----------+---------+--------------+--------------------+--------------+
盲区根因（读 config/backup.php 实测）：健康检查统计的是 source 所在默认盘 local（storage/app/），而 zip 实际复制到 backups 盘（base_path('backups')）——两盘不同路径，list 永远报 0。判断备份是否成功请直接看 /htdocs/backups/updater-backups/ 下的 zip 文件。
backup:monitor 实测输出：
The LinkStack backups on the local disk are considered unhealthy!
Spatie\Backup\Exceptions\NotificationCouldNotBeSent
There is no notification class that can handle event `Spatie\Backup\Events\UnhealthyBackupWasFound`.
两条告警叠加：盘盲区判"不健康" + 未配通知类导致连告警都发不出去。要修可把 backup.php 的 monitoral_health 检查盘与落盘对齐（改 destination.disks 为 local 或在 health_check 里换盘），个人实例直接 cron 跑 backup:run + 文件级监控更省事。
5.4 backup:clean（按保留策略清理）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan backup:clean'
实测输出（目录里有两份 zip、相隔 14 分钟时运行）：
Starting cleanup...
Cleaning backups of updater-backups on disk backups...
Deleted backup `updater-backups/M7LPHX5HgpIIqL4S-2026-11-02-17-12-27.zip`.
Cleanup failed because: There is no notification class that can handle event `Spatie\Backup\Events\CleanupWasSuccessful`..
Spatie\Backup\Exceptions\NotificationCouldNotBeSent
There is no notification class that can handle event `Spatie\Backup\Events\CleanupHasFailed`.
删除动作真实成功（跑完只剩最新一份 zip），报错只是"清理成功的通知发不出去"（未配通知渠道，同 5.2 的 Sending notification failed，无害）。⚠️ 保留策略实测坑：LinkStack 出厂 backup.php 的 default_strategy 六档 keep_all_backups_for_days/keep_daily_backups_for_days/keep_weekly_backups_for_weeks/keep_monthly_backups_for_months/keep_yearly_backups_for_years 全为 0（实测 208-236 行），意味着 backup:clean 会把除最新一份以外的所有历史备份立即删光（策略注释原文："never delete the newest backup"）。想留历史必须先把对应天数改大于 0 再挂 cron。
六、缓存与性能类
6.1 可用：cache:clear / config:clear / view:clear / package:discover
实测输出：
INFO Application cache cleared successfully. # php83 artisan cache:clear
INFO Configuration cache cleared successfully. # php83 artisan config:clear
INFO Compiled views cleared successfully. # php83 artisan view:clear
INFO Discovering packages. # php83 artisan package:discover
改 .env 后一般无需清缓存（LinkStack 配置每请求现读，见配置篇第五章）；但若曾误跑过 config:cache 留下半成品，用 config:clear 兜底。
6.2 禁用：config:cache 与 optimize（本应用 fatal）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan config:cache'
实测输出：
PHP Fatal error: Cannot redeclare locales() (previously declared in /htdocs/config/app.php:3) in /htdocs/config/app.php on line 3
Symfony\Component\ErrorHandler\Error\FatalError
Cannot redeclare locales() (previously declared in /htdocs/config/app.php:3)
at config/app.php:3
根因：LinkStack 在 config/app.php 文件顶层直接定义了函数 locales()（供 languages 配置项调用）。config:cache 会把所有 config 文件合并进单个缓存文件，同一文件被加载两次即触发重复声明 fatal。这是 LinkStack 源码结构决定的硬限制——任何性能优化都不要对它跑 config:cache；optimize 命令内部第一步就是 config:cache，同样禁用。若误跑后行为异常，用 config:clear 清掉半成品缓存即可恢复（实测站点全程正常）。
七、维护模式：artisan down/up 与 MAINTENANCE_MODE 是两套
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan down'
curl -s -o /dev/null -w 'GET / http=%{http_code}\n' http://127.0.0.1:8132/
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan up'
curl -s -o /dev/null -w 'GET / http=%{http_code}\n' http://127.0.0.1:8132/
实测输出：
INFO Application is now in maintenance mode.
GET / http=503
INFO Application is now live.
GET / http=200
与 .env 的 MAINTENANCE_MODE=true（配置篇 5.6 实测：HTTP 200 + 维护占位页）不同，artisan down 走 Laravel 框架标准机制（写 storage/framework/down），返回真 503——给 LB/监控看的就是这个。两者用途：down/up 用于计划内运维窗口（配合 --render 可自定义模板）；MAINTENANCE_MODE 是 LinkStack 产品层开关（后台可见性）。
八、路由与调度类
8.1 route:list（路由表审计）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan route:list'
实测输出（节选；全表 GET/POST 路由 121 条）：
GET|HEAD +{littlelink} ....... littlelink › UserController@littlelink
GET|HEAD / ............................... home › HomeController@home
GET|HEAD @ ..........................................................
GET|HEAD @{littlelink} ....... littlelink › UserController@littlelink
GET|HEAD admin/advanced-config showFileEditor › AdminController@show…
POST admin/advanced-config ...... editAC › AdminController@editAC
GET|HEAD admin/backups .... showBackups › AdminController@showBackups
GET|HEAD admin/config ....... showConfig › AdminController@showConfig
POST admin/config ....... editConfig › AdminController@editConfig
两个实用发现：① 用户页同时注册了 +{littlelink} 与 @{littlelink} 两条路由——这就是配置篇实测 /@root 与 /+root 都 200 的原因；② admin/config（POST editConfig）即后台设置页的落点，等价于手改 .env。
⚠️ 实测坑：Laravel 9 的 route:list 没有 --columns 选项（传了直接报 The "--columns" option does not exist.），想精简输出用管道 grep/head。
8.2 schedule:list（计划任务）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan schedule:list'
实测输出：
INFO No scheduled tasks have been defined.
LinkStack 未定义任何 Laravel 调度任务——访客清理、备份等都不自动跑，需要定时请在宿主机 crontab 调本文命令（示例：每日备份 0 3 * * * cd /opt/linkstack-stack && docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan backup:run' >> /var/log/linkstack-backup.log 2>&1）。
九、用户与数据维护类
9.1 auth:clear-resets / storage:link / key:generate
实测输出：
INFO Expired reset tokens cleared successfully. # php83 artisan auth:clear-resets
ERROR The [storage] link already exists. # php83 artisan storage:link
storage:link 幂等报错无害（public/storage → ../storage 软链已由安装流程建好）。
key:generate --show 实测输出：
base64:MxJYdtwW0ASfQtcsRkHMQKPcjiAYO6o0wJpi60cW5IU=
--show 只打印新密钥不写盘，安全；不带 --show 会直接覆盖 .env 的 APP_KEY——已加密数据（社交登录凭据等）立即不可解，生产严禁乱跑。
9.2 visits:clean 与 geoip:clear
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan visits:clean'
实测无输出（静默成功）：清理 laravel-visits 的过期统计键。
geoip:clear 实测报错（排障见第十一章 Q5）：
BadMethodCallException
This cache store does not support tagging.
9.3 db（进数据库 CLI）
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan db'
实测输出：
Symfony\Component\Process\Exception\RuntimeException
TTY mode requires /dev/tty to be read/writable.
at vendor/symfony/process/Process.php:1019
db 命令强制 TTY，docker compose exec（不带 -T 也不分配伪终端给子进程链）下不可用。进 MariaDB 更直接的方式仍是 docker compose exec db mariadb -ulinkstack -pq1w2e3r4 linkstack（部署篇 4.6）。
十、翻译工具（LinkStack 自有）
translate 批量翻译语言文件、translation-check 校验某语言包与基准的差异（社区贡献 PR 前的自检工具）：
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan translation-check'
docker compose exec linkstack sh -c 'cd /htdocs && php83 artisan translation-check en'
实测输出：
Not enough arguments (missing: "language").
[OK] en translation file is up to date!
参数为语言目录名；实测 /htdocs/lang 共 14 个语言：ar bg de el en es fr gl pt-BR ru sv vi zh zh-TW（简体中文 zh）。日常运维基本用不到，参与翻译贡献时才跑。
十一、排障实录
Q1：php artisan ... 报 sh: line 0: php: not found？
Alpine 镜像的 PHP 包只装带版本号二进制 /usr/bin/php83。一律改用 php83 artisan（php83 -m 同理）。
Q2：在容器根目录跑 artisan 报 Could not open input file: artisan？
artisan 脚本在应用根 /htdocs，先 cd /htdocs（本文命令模板已内置）。
Q3：tinker 报 Writing to directory /var/www/.config/psysh is not allowed.？
实测报错出处 vendor/psy/psysh/src/ConfigPaths.php:456：apache 用户 HOME=/var/www 不可写，psysh 要写配置目录即失败。解决：前缀 HOME=/tmp（3.3 节实测通过）。
Q4：backup:run 报 sh: line 1: sqlite3: not found（Exitcode 127）？
config/backup.php 硬编码 ['sqlite'] 而实际库是 MySQL，且镜像无 mysqldump。两步修复见 5.1（完整排障过程在部署篇 Q3）。
Q5：geoip:clear 抛 This cache store does not support tagging.？
根因：默认 CACHE_DRIVER=file，而 geoip 位置缓存用 tag 机制，file/array 驱动不支持 tag（报错出处 Illuminate/Cache/Repository.php:507）。影响面仅"清 GeoIP 缓存"这一动作，不影响访客统计功能本身；确需此命令把缓存驱动改 redis 后再用。
Q6：route:list --columns=method,uri 报 The "--columns" option does not exist.？
Laravel 9 无此选项（10+ 才有），直接 route:list | grep <关键词> 过滤。
十二、参考链接
- 源码仓库：
https://github.com/LinkStackOrg/LinkStack（v4.8.8，2026-10-22） - Laravel 9 artisan 文档：
https://laravel.com/docs/9.x/artisan - spatie/laravel-backup：
https://github.com/spatie/laravel-backup - 本文实测记录：2026-11-02，LinkStack v4.8.8 + MariaDB 11.4，Ubuntu 22.04 宿主机