Many Notes 0.18.1 常用 CLI 命令与工具详解
Many Notes v0.18.1 服务器侧 CLI 命令全解：artisan 环境自检（about/db:show/migrate:status/tinker）、upgrade:* 五命令组、scout:import 搜索索引重建、缓存与维护模式、reload 服务重载、队列观测，全部命令实测回显照抄，含模型解析报错实录。
Many Notes 0.18.1 常用 CLI 命令与工具详解
目标：把 Many Notes v0.18.1 部署实例上真正用得着的
php artisan命令族逐项讲清——环境自检、升级修复、搜索索引重建、缓存与维护模式、队列观测，每条命令附实测回显。实例环境为 Ubuntu 24.04 + Docker Compose 部署（采集日期 2026-11-01），部署过程见《Many Notes Docker Compose 部署指南》。
一、环境信息
- 操作系统：Ubuntu 24.04（x86_64）
- 应用：Many Notes v0.18.1，镜像
brufdev/many-notes:latest（digestsha256:4a61723eca84...） - 运行时：PHP 8.4.27，Laravel Framework 13.29.0（
php artisan --version实测） - 数据库：SQLite 3.46.1（默认，19 张表）
- compose 项目目录：
/opt/many-notes（compose 服务名为php） - 演示账号：
admin/q1w2e3r4（SUPER_ADMIN）
Many Notes 没有对外 REST API，服务器侧的全部运维操作都收敛在容器内的 php artisan 命令族上。本文统一执行形态：
docker compose exec php php artisan <命令>
二、工具概览
php artisan list 实测输出中与 Many Notes 运维直接相关的命令分四组：
| 组 | 命令 | 来源 | 用途 |
|---|---|---|---|
| 环境自检 | about、db:show、db:table、migrate:status、tinker | Laravel 框架 | 版本/驱动/库结构/迁移状态核查 |
| 升级修复组 | upgrade:run、upgrade:set-super-admin、upgrade:sync-database-notes、upgrade:reimport-data-into-typesense、upgrade:create-startup-vault、upgrade:process-links | Many Notes 项目自定义 | 版本升级后的数据修复与重建（UPGRADING.md 指定的补救手段） |
| 搜索索引 | scout:import、scout:flush、scout:index、scout:delete-index、scout:delete-all-indexes、scout:queue-import | Laravel Scout（Typesense 驱动） | 全文搜索索引重建与清理 |
| 服务控制 | reload、down、up、cache:clear、config:cache、queue:failed | 基座自定义 + Laravel | 重载内置服务、维护模式、缓存、队列观测 |
其中 reload（Description: Reload running services）是 Many Notes 自定义命令，upgrade:* 六条是项目升级命令组——这两组是 Many Notes 区别于一般 Laravel 应用的运维核心。框架标准命令（migrate、storage:link 等）正常部署时由镜像初始化流程自动执行，无需手工介入。
三、前置条件
实例须处于健康状态。核对：
docker compose ps
回显（实测）：
NAME IMAGE STATUS PORTS
many-notes-0.18.1-app brufdev/many-notes:latest Up 14 minutes (healthy) 8443/tcp, 9000/tcp, 0.0.0.0:8144->8080/tcp
docker compose exec php php artisan --version
回显（实测）：
Laravel Framework 13.29.0
⚠️ 注意：
docker compose exec以镜像默认用户 www-data 进入，工作目录固定在/var/www/html，无需额外指定用户或路径。
四、环境自检命令详解
4.1 about：应用与驱动总览
排查任何异常前先跑 about，一屏看清版本、模式、缓存状态与全部驱动选型：
docker compose exec php php artisan about
回显（实测节选）：
Environment ................................................................
Application Name ................................................ Many Notes
Laravel Version .................................................... 13.29.0
PHP Version ......................................................... 8.4.27
Composer Version .................................................... 2.10.3
Environment ..................................................... production
Debug Mode ............................................................. OFF
URL ......................................................... localhost:8144
Maintenance Mode ....................................................... OFF
Cache ......................................................................
Config .............................................................. CACHED
Drivers ....................................................................
Broadcasting ........................................................ reverb
Cache ............................................................. database
Database ............................................................ sqlite
Mail ................................................................... log
Queue ............................................................. database
Scout ............................................................ typesense
Session ........................................................... database
Storage ....................................................................
public/storage ...................................................... LINKED
解读要点：Drivers 段直接印证全家桶形态——队列/会话/缓存全走 database 驱动、搜索走 typesense、广播走 reverb，没有一项依赖外部中间件；Config: CACHED 说明配置已被 php artisan optimize 固化，改环境变量后必须重建容器才生效（见第五章注意事项）。
4.2 db:show 与 db:table：库结构核查
docker compose exec php php artisan db:show
回显（实测节选）：
SQLite .............................................................. 3.46.1
Connection .......................................................... sqlite
Database ................................... database/sqlite/database.sqlite
Tables .................................................................. 19
Schema / Table ........................................................ Size
main / vault_nodes ................................................... —
main / vaults ........................................................ —
main / users ......................................................... —
...
（输出节选（实测首尾）：完整 19 表清单含 cache、jobs、settings、social_accounts、tags、upgrades、user_vault 等。）
单表结构用 db:table，以笔记节点表为例：
docker compose exec php php artisan db:table vault_nodes
回显（实测）：
main.vault_nodes ...........................................................
Columns .................................................................. 9
Column ................................................................ Type
id integer, autoincrement .......................................... integer
vault_id integer ................................................... integer
parent_id integer, nullable ........................................ integer
is_file integer .................................................... integer
name varchar ....................................................... varchar
extension varchar, nullable ........................................ varchar
content text, nullable ................................................ text
created_at datetime, nullable ..................................... datetime
updated_at datetime, nullable ..................................... datetime
Foreign Key .......................................... On Update / On Delete
parent_id references id on vault_nodes ............... no action / no action
vault_id references id on vaults ..................... no action / no action
vault_nodes 就是双写模型的数据库侧镜像：树形结构（parent_id 自关联）、文件标志（is_file）、正文（content）全在库里，与 private 卷的 .md 文件一一对应。
4.3 migrate:status：迁移状态
升级镜像后确认迁移是否全部落库：
docker compose exec php php artisan migrate:status
回显（实测节选）：
Migration name .............................................. Batch / Status
0001_01_01_000000_create_users_table ............................... [1] Ran
2024_07_16_025200_create_vaults_table .............................. [1] Ran
2025_07_01_142208_add_role_to_users_table .......................... [1] Ran
2025_07_08_234735_create_settings_table ............................ [1] Ran
2025_08_25_205738_remove_access_token_field_from_social_accounts_table [1] Ran
全部 [1] Ran 表示初始化迁移已完整执行。若升级后出现 Pending，手动补跑 docker compose exec php php artisan migrate --force。
4.4 tinker：一次性数据查询
tinker --execute 适合脚本化核查用户、Vault、节点数量：
docker compose exec php php artisan tinker --execute="echo App\Models\User::count().' users; first='.App\Models\User::first()->name.'; role='.App\Models\User::first()->role->name.PHP_EOL; echo App\Models\Vault::count().' vaults, App\Models\VaultNode::count()='.\App\Models\VaultNode::count().PHP_EOL;"
回显（实测）：
1 users; first=admin; role=SUPER_ADMIN
2 vaults, App\Models\VaultNode::count()=17
角色枚举实测印证官方定义：首个注册用户 role=SUPER_ADMIN（USER=1 / ADMIN=2 / SUPER_ADMIN=3）。交互式排查可直接 docker compose exec php php artisan tinker 进入 REPL。
五、upgrade:* 升级修复命令组
这组命令是官方 UPGRADING.md 指定的版本升级补救手段，正常自动升级流程（镜像启动时自动迁移）不需要手工跑；但升级后出现权限丢失、笔记不同步、搜索无结果时，按下方对应命令修复。
5.1 命令清单（--help 实测）
docker compose exec php php artisan list --raw | grep upgrade
回显（实测）：
upgrade:create-startup-vault Create startup vault for existing users
upgrade:process-links Process links from existing vaults
upgrade:reimport-data-into-typesense Reimport existing data into Typesense
upgrade:run Run all upgrade commands
upgrade:set-super-admin Set the oldest user as Super Admin
upgrade:sync-database-notes Sync database notes to disk
各命令 --help 均无专属参数（只有 Laravel 通用选项 -h/-q/-v/--env 等），直接执行即可。
5.2 upgrade:set-super-admin
--help 实测：
Description:
Set the oldest user as Super Admin
Usage:
upgrade:set-super-admin
用途：早期版本升级上来、或首用户判定异常时，把注册时间最早的用户重置为超级管理员。
5.3 upgrade:sync-database-notes（库→盘 同步）
数据库与文件系统双写出现不一致（如库里有笔记、private 卷里缺文件）时，以库为准把全部笔记重新落盘：
docker compose exec php php artisan upgrade:sync-database-notes
回显（实测）：
All notes were successfully synced to disk
⚠️ 方向注意：该命令是 database → disk 单向同步；反向（从文件恢复库）官方未提供 CLI，需走界面 Import Vault（ZIP）。
5.4 upgrade:reimport-data-into-typesense（搜索索引重建）
搜索无结果的第一修复手段（官方 FAQ 指定）：
docker compose exec php php artisan upgrade:reimport-data-into-typesense
回显（实测）：
All data was successfully reimported into Typesense
部署实测中首次启动日志出现两行 Something went wrong reimporting existing data into Typesense（初始化时序问题），待健康检查转 healthy 后补跑本命令即恢复——完整排障记录见《Many Notes Docker Compose 部署指南》 4.3 节。
5.5 upgrade:create-startup-vault 与 upgrade:process-links
upgrade:create-startup-vault（Description: Create startup vault for existing users）：给存量用户补建 Starter Vault（该特性 v0.6 引入，老用户升级后不会自动获得）。upgrade:process-links（Description: Process links from existing vaults）：重建存量笔记的链接/反链索引（vault_node_vault_node表）。
两者执行逻辑与 5.3/5.4 相同：无参数、幂等、输出成功即完成。
5.6 upgrade:run（聚合执行）
Description: Run all upgrade commands——按序执行上述全部 upgrade 命令。跨多个小版本升级后不确定该跑哪条时，直接跑它：
docker compose exec php php artisan upgrade:run
5.7 缓存刷新配套：reload / cache:clear / config:cache
配置变更后基座服务的重载命令 reload（Many Notes 自定义）实测：
docker compose exec php php artisan reload
回显（实测）：
INFO Reloading services.
queue ......................................................... 15.59ms DONE
schedule ...................................................... 2.58ms DONE
reverb ........................................................ 2.52ms DONE
只重载队列 worker、计划任务与 Reverb 广播三个常驻服务，不重启 nginx/PHP-FPM，是改环境变量后比重启容器更轻的手段（Web 层配置仍受 Config: CACHED 约束，需 docker compose up -d 重建）。
缓存族两条实测：
docker compose exec php php artisan cache:clear
docker compose exec php php artisan config:cache
回显（实测）：
INFO Application cache cleared successfully.
INFO Configuration cached successfully.
六、scout:* 搜索索引命令详解
Many Notes 的搜索模型只有一个：App\Models\VaultNode（笔记/文件节点）。
6.1 scout:import：全量导入
docker compose exec php php artisan scout:import "App\Models\VaultNode"
回显（实测）：
Imported [App\Models\VaultNode] models up to ID: 17
All [App\Models\VaultNode] records have been imported.
短类名形式同样有效（Scout 自动解析到 App\Models 命名空间，实测）：
docker compose exec php php artisan scout:import "VaultNode"
Imported [App\Models\VaultNode] models up to ID: 17
All [App\Models\VaultNode] records have been imported.
--help 实测参数：
Usage:
scout:import [options] [--] <model>
Arguments:
model Class name of model to bulk import
Options:
--fresh Flush the index before importing
-c, --chunk[=CHUNK] The number of records to import at a time (Defaults to
configuration value: `scout.chunk.searchable`)
--fresh 先清空索引再导入——索引脏了（删过的笔记仍被搜到）时用这条。
6.2 其余 scout 子命令
php artisan list 实测全集：scout:delete-all-indexes（删全部索引）、scout:delete-index（删指定索引）、scout:flush（清空模型索引数据但保留索引本身）、scout:index（建索引）、scout:queue-import（分块队列化导入，大库避免超时用这条）。日常只需要 import 与 flush 两条；upgrade:reimport-data-into-typesense 是项目封装的等价入口，语义相同。
七、维护模式与队列观测
7.1 down / up：维护模式
升级前挂维护模式挡流量：
docker compose exec php php artisan down
docker compose exec php php artisan up
回显（实测）：
INFO Application is now in maintenance mode.
INFO Application is now live.
维护模式期间 Web 返回 503，about 的 Maintenance Mode 行同步显示 ON。
7.2 队列 worker 与 queue:failed
队列 worker 由镜像 s6 监督自动运行，进程证据（实测 ps 输出）：
www-data 213 0.0 0.4 369868 76800 ? Ss 15:44 0:00 php /var/www/html/artisan queue:work --tries=3
同一行还能看到 s6 监督的 nginx/php-fpm/typesense 三组服务。不要在 exec 里再手动起 queue:work——双 worker 并行消费同一 database 队列会造成任务重复处理。
失败任务观测：
docker compose exec php php artisan queue:failed
回显（实测）：
INFO No failed jobs found.
有失败任务时按提示用 queue:retry <id> 重投、queue:forget <id> 丢弃。
八、注意事项
- 配置缓存优先级：
about实测Config: CACHED——镜像构建期已跑php artisan optimize。任何environment:改动都要docker compose up -d重建生效，cache:clear只清应用缓存、不清配置缓存的固化值。 - OPcache 不校验时间戳：基座默认
PHP_OPCACHE_VALIDATE_TIMESTAMPS=0，直接改代码文件不会生效（正常运维不涉及改码）。 - tinker 转义：在 bash 双引号里传 PHP 代码时
$需写成\$（本文 4.4 示例即实测写法），否则变量被 shell 吞掉。 - 幂等性：
upgrade:*与scout:import均可重复执行，实测多次运行回显一致、数据无副作用。 - 执行身份：所有命令通过
docker compose exec php以 www-data 身份运行，与 Web 应用同权限，不存在 root 写文件导致的属主漂移。
九、常见问题
9.1 scout:import 报 Model not found
实测错误回显：
In ImportCommand.php line 44:
Model [App\Models\App\Models\Nope] not found.
原因：Scout 先把输入按 App\Models\<输入> 解析，落空再按原名解析；两次都找不到类就报错（消息里显示的是第一次拼接后的候选名）。Many Notes 可导入的模型只有 App\Models\VaultNode，确认类名拼写即可。
9.2 命令执行报 SQLSTATE 或连接错误
实例尚未初始化完成（首次启动迁移进行中）时执行 CLI 会连不上库。先 docker compose ps 确认 (healthy) 再执行；健康检查未过可 docker compose logs php 看初始化进度。
9.3 reload 后搜索仍无结果
reload 只重载 queue/schedule/reverb 三个服务，不触发索引重建。搜索问题走第六章：scout:import "VaultNode" --fresh 或 upgrade:reimport-data-into-typesense。
9.4 想核查运行时生效配置
tinker 之外更直接的是 config:show（实测可用）：
docker compose exec php php artisan config:show database
回显（实测节选）：
database ...................................................................
default ............................................................. sqlite
connections ⇁ sqlite ⇁ driver ....................................... sqlite
connections ⇁ sqlite ⇁ database ............ database/sqlite/database.sqlite
connections ⇁ sqlite ⇁ foreign_key_constraints ........................ true
connections ⇁ sqlite ⇁ transaction_mode ........................... DEFERRED
connections ⇁ mysql ⇁ driver ......................................... mysql
connections ⇁ mysql ⇁ host ....................................... 127.0.0.1
default 行即当前生效连接，可确认环境变量是否真的注入成功。参数含义逐项说明见《Many Notes 0.18.1 配置参数详解》。
十、参考链接
- Laravel Artisan 命令行文档：https://laravel.com/docs/artisan
- Laravel Scout（Typesense 引擎）：https://laravel.com/docs/scout
- Many Notes 升级指南（upgrade 命令背景）：https://github.com/brufdev/many-notes/blob/main/UPGRADING.md
- 官方 FAQ（搜索排障）：https://github.com/brufdev/many-notes/blob/main/docs/support/faqs.md
- 基座镜像 serversideup/php：https://serversideup.net/open-source/docker-php/