DreamFactory 7.7.1 artisan 命令详解
系统梳理 DreamFactory 7.7.1 内置 php artisan 运维命令族：应用信息、数据库迁移、数据库查询、缓存性能、维护模式、密钥、队列调度与 df:* 专属命令等 25 条逐个实测，含 schedule:list Redis 连接拒绝、db 命令 TTY 受限、intl 扩展缺失三则排障实录。已在 Ubuntu 22.04 服务器、DreamFactory 7.7.1（Laravel 13.33.0，MySQL 8.0 系统库 + Redis 缓存）上全量实测通过。
DreamFactory 7.7.1 artisan 命令详解
目标：系统梳理并逐条实测 DreamFactory 7.7.1 内置的
php artisan运维命令族——应用信息（about / env / tinker）、数据库迁移（migrate 族）、数据库查询（db:show / db:table / db:monitor）、缓存与性能（cache:* / config:show / optimize）、维护模式（down / up）、密钥（key:generate / jwt:secret）、队列与调度（queue:* / schedule:list）以及 DreamFactory 专属 df:* 命令，共 25 条命令的参数与真实回显，并沉淀三则排障实录（schedule:list 的 Redis 连接拒绝、db 命令的 TTY 受限、intl 扩展缺失）。已在 Ubuntu 22.04（x86_64）服务器、DreamFactory 7.7.1（Laravel Framework 13.33.0，MySQL 8.0 系统库 + Redis 缓存）上全量实测通过。部署过程见 《DreamFactory Docker Compose 部署指南》，环境变量体系见 《DreamFactory 7.7.1 配置参数详解》，选型背景见 《DreamFactory 7.7.1 介绍与选型指南》。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64）
- DreamFactory：7.7.1（官方安装包部署，应用目录
/opt/dreamfactory） - 框架内核：Laravel Framework 13.33.0（
php artisan --version实测） - PHP：8.5.11（
php artisan about实测） - Composer：2.10.3（
php artisan about实测） - 系统数据库：MySQL 8.0.46，库名
dreamfactory - 缓存：Redis 7（缓存驱动
redis，队列驱动database） - 对外 HTTP 端口：本实验环境为 8132（官方部署方式不同端口可能不同，源码部署默认 80）
💡 技术拓展：artisan 是 Laravel 框架自带的命令行工具（基于 Symfony Console），DreamFactory 完全构建在 Laravel 之上，因此安装初始化、数据库迁移、缓存清理、维护模式、密钥管理、队列调度等全部运维动作都通过
php artisan <命令>完成。同类基于框架的产品各有自己的 CLI 入口（如 Nextcloud 的occ、Lago 的rake），artisan 就是 DreamFactory 的那把"运维螺丝刀"。
二、artisan 工具概览
DreamFactory 7.7.1 的 artisan 命令约 130 个，分布在十几个命令族中。本章先给出全量命令清单与分族速查表，再说明如何查看单条命令的帮助。
2.1 命令清单总览（php artisan list）
在应用目录执行 php artisan list，实测输出（make:* 脚手架生成器一族共 39 条，与运维无直接关系，节选标注）：
Laravel Framework 13.33.0
Usage:
command [options] [arguments]
Options:
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
about Display basic information about your application
clear-compiled Remove the compiled class file
completion Dump the shell completion script
db Start a new database CLI session
dev Run the dev processes
docs Access the Laravel documentation
down Put the application into maintenance / demo mode
env Display the current framework environment
help Display help for a command
inspire Display an inspiring quote
list List commands
migrate Run the database migrations
optimize Cache framework bootstrap, configuration, and metadata to increase performance
reload Reload running services
serve Serve the application on the PHP development server
tinker Interact with your application
up Bring the application out of maintenance mode
auth
auth:clear-resets Flush expired password reset tokens
cache
cache:clear Flush the application cache
cache:forget Remove an item from the cache
cache:prune-stale-tags Prune stale cache tags from the cache (Redis only)
channel
channel:list List all registered private broadcast channels
config
config:cache Create a cache file for faster configuration loading
config:clear Remove the configuration cache file
config:publish Publish configuration files to your application
config:show Display all of the values for a given configuration file or key
db
db:monitor Monitor the number of connections on the specified database
db:seed Seed the database with records
db:show Display information about the given database
db:table Display information about the given database table
db:wipe Drop all tables, views, and types
df
df:access-usage-backfill Seed access_usage last-used times from agent_activity_ledger history (df-agents installs)
df:clear-file-cache Command to clear all DreamFactory file-based cache, locally or in hosted environment.
df:env Set Environment for DreamFactory
df:homestead-config Command description
df:import Import resources from files.
df:import-pkg Import resources from a DreamFactory package (dfpkg) or zip file.
df:request Perform a request on a service.
df:setup Setup DreamFactory
env
env:decrypt Decrypt an environment file
env:encrypt Encrypt an environment file
event
event:cache Discover and cache the application's events and listeners
event:clear Clear all cached events and listeners
event:list List the application's events and listeners
install
install:api Create an API routes file and install Laravel Sanctum or Laravel Passport
install:broadcasting Create a broadcasting channel routes file
jwt
jwt:secret Set the JWTAuth secret key used to sign the tokens
key
key:generate Set the application key
lang
lang:publish Publish all language files that are available for customization
make
（make:cast / make:command / make:config / make:migration / make:model / make:seeder 等 39 个
Laravel 脚手架生成器命令，用于二次开发创建类与迁移文件，运维场景用不到，此处节选）
mcp
mcp:prune-request-logs Delete MCP request audit log entries older than the retention period
migrate
migrate:fresh Drop all tables and re-run all migrations
migrate:install Create the migration repository
migrate:refresh Reset and re-run all migrations
migrate:reset Rollback all database migrations
migrate:rollback Rollback the last database migration
migrate:status Show the status of each migration
model
model:prune Prune models that are no longer needed
model:show Show information about an Eloquent model
optimize
optimize:clear Remove the cached bootstrap files
package
package:discover Rebuild the cached package manifest
queue
queue:clear Delete all of the jobs from the specified queues
queue:failed List all of the failed queue jobs
queue:flush Flush all of the failed queue jobs
queue:forget Delete a failed queue job
queue:listen Listen to a given queue
queue:monitor Monitor the size of the specified queues
queue:pause Pause job processing for a specific queue
queue:prune-batches Prune stale entries from the batches database
queue:prune-failed Prune stale entries from the failed jobs table
queue:restart Restart queue worker daemons after their current job
queue:resume [queue:continue] Resume job processing for a paused queue
queue:retry Retry a failed queue job
queue:retry-batch Retry the failed jobs for a batch
queue:work Start processing jobs on the queue as a daemon
route
route:cache Create a route cache file for faster route registration
route:clear Remove the route cache file
route:list List all registered routes
schedule
schedule:clear-cache Delete the cached mutex files created by scheduler
schedule:interrupt Interrupt the current schedule run
schedule:list List all scheduled tasks
schedule:pause Pause the scheduler
schedule:resume [schedule:continue] Resume the schedule
schedule:run Run the scheduled commands
schedule:test Run a scheduled command
schedule:work Start the schedule worker
schema
schema:dump Dump the given database schema
storage
storage:link Create the symbolic links configured for the application
storage:unlink Delete existing symbolic links configured for the application
stub
stub:publish Publish all stubs that are available for customization
vendor
vendor:publish Publish any publishable assets from vendor packages
view
view:cache Compile all of the application's Blade templates
view:clear Clear all compiled view files
命令分族速查表（关键差异在用途列，本文实测小节见右列）：
| 命令族 | 代表命令 | 用途 | 本文实测小节 |
|---|---|---|---|
| 应用信息 | about / env / tinker | 查看运行环境、执行一次性 PHP 代码 | 四 |
| 数据库迁移 | migrate / migrate:status / migrate:rollback | 建表、升级、回滚系统库结构 | 五 |
| 数据库查询 | db:show / db:table / db:monitor / db | 查库信息、表结构、连接数、进数据库 CLI | 六 |
| 缓存与性能 | cache:clear / config:show / optimize | 清缓存、看配置、预热引导缓存 | 七 |
| 维护与路由 | down / up / route:list | 维护窗口、路由表审计 | 八 |
| 密钥安全 | key:generate / jwt:secret | 生成应用密钥与 JWT 签名密钥 | 九 |
| DF 专属 | df:setup / df:env / df:import / df:request / df:clear-file-cache | 初始化、改环境、导入资源、内部请求、清文件缓存 | 十 |
| 队列与调度 | queue:failed / queue:monitor / queue:restart / schedule:list | 队列巡检与调度任务管理 | 十一 |
| 脚手架 | make:*（39 个） | 二次开发生成类文件，运维不涉及 | 不实测 |
2.2 单条命令的帮助查看
php artisan help <命令> 与 php artisan <命令> --help 两种写法等价。以 migrate 为例，实测 php artisan migrate --help 输出（这是 migrate 全部参数的权威清单）：
Description:
Run the database migrations
Usage:
migrate [options]
Options:
--database[=DATABASE] The database connection to use
--force Force the operation to run when in production
--path[=PATH] The path(s) to the migrations files to be executed (multiple values allowed)
--realpath Indicate any provided migration file paths are pre-resolved absolute paths
--schema-path[=SCHEMA-PATH] The path to a schema dump file
--pretend Dump the SQL queries that would be run
--seed Indicates if the seed task should be re-run
--seeder[=SEEDER] The class name of the root seeder
--step Force the migrations to be run so they can be rolled back individually
--graceful Return a successful exit code even if an error occurs
--isolated[=ISOLATED] Do not run the command if another instance of the command is already running [default: false]
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
关键参数解读：--pretend 只打印将执行的 SQL 而不执行（预演模式，5.3 节实测）；--force 在生产环境（APP_ENV=production）下跳过确认，交互终端无需该参数；--step 让每条迁移独立成批，便于逐批回滚；--isolated 防止同一命令并发重复执行，适合放进 cron。其他命令的帮助输出结构与此一致，下文各小节实测时一并给出。
三、前置条件
3.1 在应用目录下执行
所有 artisan 命令都在 DreamFactory 应用目录下执行，本文统一写法：
cd /opt/dreamfactory
php artisan <命令>
/opt/dreamfactory是官方默认应用目录，包含artisan入口文件与.env环境文件；artisan 启动时会读取该目录下的.env加载数据库、缓存等连接配置。- 执行账号需要对该目录有读写权限（root 或部署属主账号均可）。
- 若从其他目录执行，可用绝对路径
php /opt/dreamfactory/artisan <命令>，效果等价。
3.2 验证 artisan 就绪
php artisan --version
实测输出：
Laravel Framework 13.33.0
能打印框架版本号即说明 artisan 入口与 .env 加载正常。若此处报 could not find driver 或连接类错误，优先检查 .env 中数据库配置（环境变量逐项含义见 《DreamFactory 7.7.1 配置参数详解》第三章，该篇给出了完整的查看与修改方法）。
3.3 环境就绪判定
执行 php artisan migrate:status 不报连接错误、php artisan about 显示 Maintenance Mode 为 OFF，即认为环境就绪，可执行本文全部命令。本文所有命令实测时环境均为"已初始化、正常运行"状态。
四、应用信息与环境类命令
4.1 about：一屏总览运行环境
about 是巡检第一命令，把应用名、框架/PHP/Composer 版本、缓存/数据库/队列驱动、维护模式一屏打尽。实测 php artisan about：
Environment ................................................................
Application Name ................................................... Laravel
Laravel Version .................................................... 13.33.0
PHP Version ......................................................... 8.5.11
Composer Version .................................................... 2.10.3
Environment .......................................................... local
Debug Mode ............................................................. OFF
URL .............................................................. localhost
Maintenance Mode ....................................................... OFF
Timezone ............................................................... UTC
Locale .................................................................. en
Cache ......................................................................
Config .......................................................... NOT CACHED
Events .......................................................... NOT CACHED
Routes .......................................................... NOT CACHED
Views ............................................................... CACHED
Drivers ....................................................................
Broadcasting .......................................................... null
Cache ................................................................ redis
Database ............................................................. mysql
Logs ........................................................ stack / single
Mail ................................................................... log
Queue ............................................................. database
Session ............................................................... file
Storage ....................................................................
public/storage .................................................. NOT LINKED
字段解读：Maintenance Mode OFF 说明平台正常对外服务（若为 ON 说明处于维护窗口，见第八章）；Cache redis + Queue database 是 DreamFactory 的默认驱动组合；Config/Routes NOT CACHED 表示引导缓存未预热（七.3 节的 optimize 可改变这一状态）；Debug Mode OFF 是生产必要状态（打开会向前端暴露堆栈）。如何确认命令生效：任一字段（如 PHP Version）与实际环境一致、命令退出码为 0 即为生效。
4.2 env：查看当前应用环境
php artisan env
实测输出：
INFO The application environment is [local].
对应 .env 里的 APP_ENV。local 与 production 的差异在于：production 下破坏性 artisan 命令会要求 --force 才执行（这是 Laravel 的一层防呆）。注意该命令只显示环境名，不显示其他配置值，查具体配置用 config:show（七.2 节）。
4.3 tinker：交互式 REPL 与 --execute 单次执行
tinker 进入交互式 PHP shell，可执行任意 PHP 代码；配合 --execute 参数可以单次执行不进入交互。实测：
php artisan tinker --execute="echo PHP_VERSION;"
实测输出：
8.5.11
适用场景：临时验证一段 PHP 逻辑、查询模型数据、调用 DreamFactory 服务类。验证方式：输出与预期一致（此处打印了运行时 PHP 版本）。注意 --execute 内的引号嵌套需要转义，复杂脚本建议写成文件再 require。
五、数据库迁移类命令（migrate 族）
migrate 族负责 DreamFactory 系统库（68 张表）的建表与升级。首次安装、版本升级时都靠这一族命令。
5.1 migrate：执行数据库迁移
在已初始化的环境执行 php artisan migrate，实测输出：
INFO Nothing to migrate.
"Nothing to migrate." 表示所有迁移都已执行过（系统库已是最新结构），这是已初始化环境的正常回显，不是错误。在全新库上首次执行时，该命令会逐条打印每个迁移文件的 DONE 状态（DreamFactory 7.7.1 共 68 个迁移）。
配合 2.2 节的 --help 参数，常用形态：
php artisan migrate --pretend # 预演模式：只打印 SQL 不执行
php artisan migrate --force # 生产环境跳过确认（脚本化时用）
php artisan migrate --isolated # 防止与其他实例并发重复执行
验证方式：执行后再跑 php artisan migrate:status（5.2 节），所有迁移显示 [1] Ran 即为生效。
5.2 migrate:status：查看迁移状态
php artisan migrate:status
实测输出（68 行，此处节选首尾）：
Migration name .............................................. Batch / Status
2015_01_27_190908_create_system_tables ............................. [1] Ran
2015_01_27_190909_create_db_extras_tables .......................... [1] Ran
2015_01_27_190909_create_email_tables .............................. [1] Ran
……
2026_09_17_000000_add_tool_style_to_mcp_server_config .............. [1] Ran
2026_09_18_000000_add_allow_writes_to_mcp_server_config ............ [1] Ran
2026_09_18_000000_add_arg_columns_to_mcp_request_log ............... [1] Ran
2026_09_18_000000_add_require_role_access_to_mcp_server_config ..... [1] Ran
解读：每行一个迁移，Batch / Status 列中 [1] 表示第 1 批执行，Ran 表示已执行；若出现 Pending 表示该迁移尚未执行（版本升级后常见，跑一次 php artisan migrate 即可补齐）。从迁移名能直接读出系统演进史：2015 年的 create_system_tables 建系统核心表，2026 年的 add_*_to_mcp_server_config 是 7.7.x 为内置 MCP 服务新增的列。验证方式：无 Pending 行即系统库结构为最新。
5.3 migrate:rollback --pretend：回滚预演（重要排障视角）
migrate:rollback 会回滚上一批迁移，是 migrate 族里最危险的命令之一。本次实测先以 --pretend 预演（不执行任何 SQL）：
php artisan migrate:rollback --pretend
实测输出（节选首尾）：
INFO Rolling back migrations.
2026_09_18_000000_add_require_role_access_to_mcp_server_config .............
⇂ select column_name as `name`, data_type as `type_name`, column_type as `type`, collation_name as `collation`, is_nullable as `nullable`, column_default as `default`, column_comment as `comment`, generation_expression as `expression`, extra as `extra` from information_schema.columns where table_schema = schema() and table_name = 'mcp_server_config' order by ordinal_position asc
……
MergeLookups ...............................................................
⇂ drop table if exists `lookup`
……
CreateSystemTables .........................................................
⇂ drop table if exists `lookup`
⇂ drop table if exists `system_custom`
⇂ drop table if exists `system_config`
⇂ drop table if exists `service_cache_config`
⇂ drop table if exists `file_service_config`
⇂ drop table if exists `token_map`
⇂ drop table if exists `user_to_app_to_role`
⇂ drop table if exists `app`
⇂ drop table if exists `cors_config`
⇂ drop table if exists `email_template`
⇂ drop table if exists `role_service_access`
⇂ drop table if exists `role`
⇂ drop table if exists `service_doc`
⇂ drop table if exists `service`
⇂ drop table if exists `password_resets`
⇂ drop table if exists `user`
⚠️ 这段预演暴露了一个关键事实：本环境全部迁移都在同一批（Batch 1），不带参数的
migrate:rollback会回滚整批——预演显示它将DROP从user、role、service到lookup的几乎全部系统表。生产环境执行回滚前务必先用--pretend预演确认影响范围，并先备份数据库。
预演不会真正执行：复核 php artisan migrate:status，尾部迁移仍全部为 [1] Ran，数据完好（lookup 表查询结果为空集、平台 API 正常返回 200），证明 --pretend 只打印 SQL 不落库。
5.4 migrate 族其余子命令速查
| 命令 | 作用 | 破坏性 | 使用建议 |
|---|---|---|---|
| migrate:install | 创建迁移仓库表（migrations） | 无 | 首次迁移自动完成，无需手动跑 |
| migrate:refresh | 回滚后重新执行全部迁移 | 高 | 仅开发环境 |
| migrate:reset | 回滚全部迁移 | 极高 | 仅开发环境 |
| migrate:fresh | 先 DROP 全部表再重新迁移 | 极高 | 仅全新建库；生产禁用 |
| migrate:rollback | 回滚上一批迁移 | 高（见 5.3 预演） | 先 --pretend 预演 + 备份 |
| migrate:status | 查看迁移状态 | 无 | 巡检/升级前后例行检查 |
验证方式：破坏性命令本篇不做实际执行，其参数可通过 php artisan <命令> --help 实时查看，输出结构与 2.2 节一致。
六、数据库信息查询类命令（db:* 族）
db:* 族提供系统库的只读巡检能力，日常运维最常用。
6.1 db:show：查看数据库概况
php artisan db:show
实测输出：
MySQL ............................................................... 8.0.46
Connection ........................................................... mysql
Database ...................................................... dreamfactory
Host ................................................................. mysql
Port .................................................................. 3306
Username .......................................................... df_admin
URL ........................................................................
Open Connections ......................................................... 1
Tables .................................................................. 68
In Number.php line 476:
The "intl" PHP extension is required to use the [format] method.
主体信息完整可用：连接到 MySQL 8.0.46，库 dreamfactory，68 张表，当前 1 个连接。数据库名、主机、账号与 .env 的 DB_DATABASE/DB_HOST/DB_USERNAME 一一对应。
⚠️ 排障实录：尾部报
The "intl" PHP extension is required to use the [format] method.。定位过程：报错发生在Number.php，是 Laravel 在格式化"表数量/连接数"数字时调用了 PHP 的 intl 扩展（NumberFormatter 类），而当前 PHP 8.5.11 运行环境未安装该扩展。影响评估：仅影响 db:show / db:table 输出末尾的数字格式化环节，命令主体信息与退出前的全部统计已完整打印，不影响数据库本身。处理方式：自建环境时为 PHP 安装 intl 扩展（Ubuntu 上apt install php8.5-intl后重启 Web 服务）即可消除；使用官方安装包且不便加装扩展时，可忽略该尾部报错（主体巡检信息不受影响）。
6.2 db:table：查看指定表结构
php artisan db:table user
实测输出：
CACHE_HOST=redis
---
dreamfactory.user ..........................................................
Columns ................................................................. 21
In Number.php line 476:
The "intl" PHP extension is required to use the [format] method.
解读：user 表共 21 列。与 6.1 相同，尾部 intl 报错见上节排障实录。命令第一行打印了 .env 片段（CACHE_HOST=redis）为该命令启动时的环境加载回显，实测原样保留。验证方式：Columns 数与 information_schema.COLUMNS 中该表的列数一致。
6.3 db:monitor：监控数据库连接数
php artisan db:monitor
实测输出：
Database name .................................................. Connections
mysql ............................................................... [1] OK
解读：方括号内为当前连接数，OK 表示未超过告警阈值。该命令适合放进巡检脚本，配合 --max 参数可自定义告警阈值（超过时命令以非零退出码结束）。验证方式：与 db:show 的 Open Connections 数一致。
6.4 db：进入数据库 CLI 会话（TTY 限制排障实录）
db 命令用于直接进入系统库的命令行客户端（等价于 mysql -h <DB_HOST> -u <DB_USERNAME> -p <DB_DATABASE>）。实测在非交互管道下执行：
echo "SELECT 1; exit" | php artisan db
实测输出：
In Process.php line 1079:
TTY mode requires /dev/tty to be read/writable.
⚠️ 排障实录：
db命令要求交互式终端（TTY）。定位：该命令底层通过进程调用数据库客户端并分配伪终端，管道/重定向/cron 等非交互场景没有/dev/tty，因此报错。结论与正确用法：必须以真实登录会话进入应用目录执行php artisan db，按提示输入.env中DB_PASSWORD对应的密码后进入 SQL 交互界面；自动化脚本场景绕开该命令，改用数据库客户端直连（如mysql -u df_admin -p dreamfactory，密码交互输入或用配置文件免密）。
七、缓存与性能类命令
7.1 cache:clear 与 cache:prune-stale-tags：清应用缓存
php artisan cache:clear
实测输出：
INFO Application cache cleared successfully.
php artisan cache:prune-stale-tags
实测输出：
INFO Stale cache tags pruned successfully.
解读：cache:clear 清空整个应用缓存（本环境缓存驱动为 Redis，即清空 Redis 中 laravel-cache- 前缀的键）；cache:prune-stale-tags 是 Redis 驱动专属的过期标签清理（命令清单里也标注了 Redis only）。修改配置、排查缓存不一致后执行 cache:clear 是标准动作。验证方式：命令返回 INFO 即生效；可再次执行同一命令确认幂等。
7.2 config:show：查看运行时配置树
php artisan config:show cache
实测输出（完整配置树约 40 行，此处节选关键分支）：
cache ......................................................................
default .............................................................. redis
prefix ...................................................... laravel-cache-
default_ttl .......................................................... 18000
serializable_classes .................................................. true
stores ⇁ redis ⇁ driver .............................................. redis
stores ⇁ redis ⇁ connection .......................................... cache
stores ⇁ redis ⇁ lock_connection ................................... default
stores ⇁ file ⇁ driver ................................................ file
stores ⇁ file ⇁ path .......................... storage/framework/cache/data
解读：config:show <配置名> 打印该配置文件在运行时的实际生效值（含环境变量替换后的结果），是核对 .env 修改是否生效的最直接手段。此处可见缓存默认驱动 redis、键前缀 laravel-cache-、默认 TTL 18000 秒（5 小时）。验证方式：default 值与 .env 的 CACHE_DRIVER（或 DF 的 CACHE_HOST 体系）推导结果一致。
7.3 optimize 与 optimize:clear：引导缓存预热与清理
php artisan optimize
实测输出：
INFO Caching framework bootstrap, configuration, and metadata.
config ......................................................... 6.54ms DONE
events ......................................................... 0.59ms DONE
routes ......................................................... 8.79ms DONE
views ......................................................... 15.27ms DONE
INFO Clearing cached bootstrap files.
config ......................................................... 0.65ms DONE
cache .......................................................... 3.06ms DONE
compiled ....................................................... 0.66ms DONE
events ......................................................... 0.34ms DONE
routes ......................................................... 0.28ms DONE
views .......................................................... 2.42ms DONE
解读：optimize 一次性预置 config/events/routes/views 四类引导缓存，执行后 php artisan about 中对应项变为 CACHED，请求不再每次解析配置与路由，生产环境推荐保持预热状态。实测中 optimize 在缓存完成后又自动执行了清理段——这是该版本在非生产环境（APP_ENV=local）下的保护行为：local 环境缓存会立即清除，避免开发时改代码不生效；生产环境（APP_ENV=production）执行 optimize 后缓存会保留。
php artisan optimize:clear
实测输出：
INFO Clearing cached bootstrap files.
config ......................................................... 2.33ms DONE
cache .......................................................... 1.12ms DONE
compiled ....................................................... 2.52ms DONE
events ......................................................... 0.46ms DONE
routes ......................................................... 0.27ms DONE
views ......................................................... 15.01ms DONE
⚠️ 注意：预热状态与
.env强相关——执行 optimize 之后又修改了.env，必须php artisan optimize:clear（或至少 config:clear）让配置重新加载，否则新配置不生效。这是"改了配置没反应"的最常见原因。
八、维护模式与路由类命令
8.1 down：进入维护模式
php artisan down
实测输出：
INFO Application is now in maintenance mode.
立即用 curl 验证对外表现（端口见环境信息章）：
curl -s -o /dev/null -w '%{http_code}' http://localhost:8132/
实测输出：
503
抓取响应体（节选）：
<html>
<head>
<link href='//fonts.googleapis.com/css?family=Lato:100' rel='stylesheet' type='text/css'>
……
<div class="title">Service Unavailable</div>
解读：down 之后所有 HTTP 请求（含 /api/* 数据接口与管理台）统一返回 503 与 Laravel 默认维护页。生产使用建议加 --retry=60 让客户端拿到 Retry-After 响应头，或提前用 php artisan down --render="errors::503" 自定义维护页。
8.2 up：解除维护模式
php artisan up
实测输出：
INFO Application is now live.
恢复验证：
curl -s -o /dev/null -w '%{http_code}' http://localhost:8132/api/v2
实测输出：
200
验证闭环：down → 503，up → 200，维护模式进出场均以 HTTP 状态码实测确认。down/up 状态存储在应用存储目录的维护文件中，重启 Web 服务不会误解除。
8.3 route:list：路由表审计
php artisan route:list
实测输出（共 36 行，节选前 11 行）：
GET|HEAD .well-known/oauth-authorization-server/mcp/{mcpService} DreamFact…
GET|HEAD .well-known/oauth-protected-resource/mcp/{mcpService} DreamFactor…
GET|HEAD / ......................................... SplashController@index
GET|HEAD _internal/ai/mcp-access DreamFactory\Core › InternalMcpAccessCont…
GET|HEAD _internal/ai/mcp-catalog DreamFactory\Core › InternalMcpCatalogCo…
GET|HEAD _internal/ai/mcp-health DreamFactory\Core › InternalMcpHealthCont…
GET|HEAD _internal/ai/mcp-usage DreamFactory\Core › InternalMcpUsageContro…
GET|HEAD api ..................... DreamFactory\Core › RestController@index
ANY api/{service}/{resource?} DreamFactory\Core › RestController@hand…
GET|HEAD api/{version} ........... DreamFactory\Core › RestController@index
ANY api/{version}/{service}/{resource?} DreamFactory\Core › RestContr…
解读：DreamFactory 对外 API 的全部流量都汇聚在 api/{version}/{service}/{resource?} 一条通配路由上（ANY 方法），由 RestController 统一分发到各数据服务；_internal/ai/mcp-* 四条是 7.7.x 内置 MCP 服务端的内部路由。route:list 输出行尾的 … 是命令自身对超长控制器名的截断显示。验证方式：行数与实际路由数一致（本环境 36 行），核心通配路由必须在场，否则 API 不可用。
九、密钥与安全类命令
9.1 key:generate：生成应用密钥
APP_KEY 是 DreamFactory 数据加密的根密钥：系统库中所有加密存储的字段（如 lookup 的 value、SMTP 密码、OAuth 凭据）都用它做 AES 加解密。查看当前密钥（--show 只显示不修改）：
php artisan key:generate --show
实测输出：
base64:NHc+ZWag7fR+IZgyzib46OfkAwiivZhIGr+35Au0dSk=
解读：--show 是最常用的形态——只查看 .env 中已有的 APP_KEY 而不重新生成；不带 --show 执行才会写入新密钥。> ⚠️ 红线：更换 APP_KEY 后，库内既有密文字段将无法解密（详见十.3 节的加密存储实测），生产环境严禁随意执行。
9.2 jwt:secret：生成 JWT 签名密钥
php artisan jwt:secret --help
实测输出：
Description:
Set the JWTAuth secret key used to sign the tokens
Usage:
jwt:secret [options]
Options:
-s, --show Display the key instead of modifying files.
--always-no Skip generating key if it already exists.
-f, --force Skip confirmation when overwriting an existing key.
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
查看当前 JWT 密钥（--show）：
php artisan jwt:secret --show
实测输出：
EvJ9TS5eM1YLyKJGkZIAUJ7E4FS0lqRBZNbmXvRpSaKadX5lnNcdtYcsm4mokMCh
解读：该密钥用于给管理员/用户会话 JWT 令牌签名，对应 .env 的 JWT_SECRET。参数速记：--always-no 已有密钥则跳过（适合装机脚本幂等执行），--force 覆盖已有密钥时跳过确认。> ⚠️ 红线：更换 JWT_SECRET 后所有已签发令牌立即失效，用户需重新登录。
十、DreamFactory 专属 df:* 命令族
df:* 是 DreamFactory 在 Laravel 之上叠加的专属命令族，覆盖初始化（df:setup）、环境切换（df:env）、资源导入（df:import / df:import-pkg）、内部请求（df:request）与文件缓存清理（df:clear-file-cache）。
10.1 df:setup：初始化 DreamFactory
php artisan df:setup --help
实测输出：
Description:
Setup DreamFactory
Usage:
df:setup [options]
Options:
--force Force run migration and seeder
--no-app-key Skip generating APP_KEY
--admin_first_name[=ADMIN_FIRST_NAME] Admin user first name
--admin_last_name[=ADMIN_LAST_NAME] Admin user last name
--admin_email[=ADMIN_EMAIL] Admin user email
--admin_password[=ADMIN_PASSWORD] Admin user password
--admin_phone[=ADMIN_PHONE] Admin phone number
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
用途与用法：全新环境首次初始化执行 php artisan df:setup（交互式逐项询问管理员姓名/邮箱/密码），或全参数非交互执行：
php artisan df:setup --no-interaction \
--admin_first_name=Admin --admin_last_name=User \
--admin_email=admin@example.com --admin_password=q1w2e3r4
参数解读：--admin_email 即首次登录管理台的账号（本文示例统一 admin@example.com / q1w2e3r4，生产请换成强密码）；--no-app-key 跳过 APP_KEY 生成（已有密钥的迁移场景用）；--force 在已初始化的库上强制重跑迁移与种子——> ⚠️ 红线：对已有数据的环境执行 --force 可能重置系统数据，严禁在存量环境使用。本环境已初始化，故不重复执行该命令，验证方式：初始化成功后 migrate:status 无 Pending 且管理台可用 admin 账号登录（登录实测见 《DreamFactory Docker Compose 部署指南》第五章）。
10.2 df:env：一键改写环境配置
php artisan df:env --help
实测输出：
Description:
Set Environment for DreamFactory
Usage:
df:env [options]
Options:
--db_connection[=DB_CONNECTION] System database driver. [sqlite, mysql, pgsql, sqlsrv]
--db_host[=DB_HOST] Database host
--db_port[=DB_PORT] Database port
--db_database[=DB_DATABASE] Database name
--db_username[=DB_USERNAME] Database username
--db_password[=DB_PASSWORD] Database password
--cache_store[=CACHE_STORE] System cache store [file, redis, memcached]
--redis_host[=REDIS_HOST] Cache store redis host
--redis_port[=REDIS_PORT] Cache store redis port
--redis_database[=REDIS_DATABASE] Cache store redis database
--redis_password[=REDIS_PASSWORD] Cache store redis password
--memcached_host[=MEMCACHED_HOST] Cache store memcached host
--memcached_port[=MEMCACHED_PORT] Cache store memcached port
--memcached_weight[=MEMCACHED_WEIGHT] Cache store memcached weight
--df_install[=DF_INSTALL] Installation source/environment [default: "GitHub"]
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
用途：把数据库与缓存的连接参数一次性写入 .env，免去手编配置文件。典型场景：
# 切换系统库到指定 MySQL（密码值通过 --db_password 传入，注意会被明文写入 .env）
php artisan df:env --db_connection=mysql --db_host=192.168.1.10 \
--db_port=3306 --db_database=dreamfactory --db_username=df_admin
# 切换缓存到指定 Redis
php artisan df:env --cache_store=redis --redis_host=192.168.1.11 --redis_port=6379
⚠️ 注意两点：其一，
--db_password会把明文密码写进.env，执行后注意文件权限；其二，改完需php artisan optimize:clear让新配置生效（原因见七.3 节）。本环境连接参数已正确，未重复执行写操作；参数生效验证方式：php artisan config:show database查看替换后的实际连接值，方法同七.2 节。
10.3 df:import 与 df:request：资源导入与内部请求实测
这一对命令组合成"免 HTTP 的数据操作通道"：df:import 把 JSON 数据导入系统服务，df:request 在命令行直接对任意服务发起内部请求（不经过 Web 层认证）。先看两者参数：
php artisan df:import --help
实测输出：
Description:
Import resources from files.
Usage:
df:import [options] [--] <data>
Arguments:
data
Options:
--service[=SERVICE] [default: "system"]
--resource[=RESOURCE]
--format[=FORMAT] [default: "json"]
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
php artisan df:request --help
实测输出：
Description:
Perform a request on a service.
Usage:
df:request [options] [--] [<data>]
Arguments:
data
Options:
--verb[=VERB] [default: "get"]
--service[=SERVICE] [default: "system"]
--resource[=RESOURCE]
--format[=FORMAT] [default: "json"]
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
下面用系统服务里的 lookup（键值查找表）做一次完整生命周期实测。
第一步，导入一条 lookup 记录：
php artisan df:import --service=system --resource=lookup '[{"name":"d1-crypto-demo","value":"plain-abc123"}]'
实测输出：
1
Import complete!
第二步，直连 MySQL 看库内原始存储（密码为 .env 的 DB_PASSWORD，交互输入）：
mysql -u df_admin -p dreamfactory -e "select id,name,value from lookup;"
实测输出：
id name value
3 d1-crypto-demo eyJpdiI6Ind4a2wzbXhNQnpPWVZLczYrQ2FhTnc9PSIsInZhbHVlIjoidUI4WmVUcVQxVE1TRUd2bnc1ZDk1b1A3YldwRHNiYWlXZU01NEpFdktVST0iLCJtYWMiOiJiMzJkYzlhMDczYTc2MmRkMGI3MDY1YjM4OThlYjQxYjc5M2VhNDg1Nzc2MzhjNTc2YWMwN2RkYzgyMGI5MzE1IiwidGFnIjoiIn0=
第三步，用 df:request 从 API 层读同一条记录：
php artisan df:request --service=system --resource=lookup/3
实测输出（节选核心字段）：
DreamFactory\Core\Utility\ServiceResponse Object
(
[statusCode:protected] => 200
[content:protected] => Array
(
[id] => 3
[name] => d1-crypto-demo
[value] => plain-abc123
)
)
三步对照得出一个重要结论：value 字段在库内是 AES 密文（eyJpdiI6... 开头的 base64 结构），而 df:request 读回的是明文 plain-abc123——DreamFactory 用 APP_KEY 对敏感字段透明加解密（加解密根密钥见九.1 节）。这也是 lookup 等字段能安全存密码类值的原因。
第四步，删除该记录（--verb=delete）：
php artisan df:request --service=system --resource=lookup/3 --verb=delete
实测输出（节选）：
DreamFactory\Core\Utility\ServiceResponse Object
(
[statusCode:protected] => 200
[content:protected] => Array
(
[id] => 3
)
)
复核删除已生效：
mysql -u df_admin -p dreamfactory -e "select count(*) as cnt from lookup;"
实测输出：
cnt
0
错误形态实测——请求不存在的服务：
php artisan df:request --service=nosuchsvc
实测输出：
REST Exception #404 > Could not find a service for nosuchsvc
Could not find a service for nosuchsvc
REST Exception #500 > Could not find a service for nosuchsvc
In Request.php line 71:
Could not find a service for nosuchsvc
解读：df:request 输出的是 PHP 对象打印而非 JSON——实测即使显式传 --format=json，输出仍是 ServiceResponse 对象结构（该参数只影响内部数据格式，不影响打印形态），这是命令本身的展示行为，不是故障。排错信息分三层：REST 异常 404（服务不存在）→ 500（内部包装）→ PHP 异常堆栈定位到 Request.php line 71，与 Web 层调用同一服务返回的错误语义一致。
10.4 df:import-pkg：导入 DreamFactory 资源包
php artisan df:import-pkg --help
实测输出：
Description:
Import resources from a DreamFactory package (dfpkg) or zip file.
Usage:
df:import-pkg [options] [--] [<path>]
Arguments:
path Relative path to the package file/folder/url
Options:
--password[=PASSWORD] Password for encrypted package
--delete Delete package after import
-h, --help Display help for the given command. When no command is given display help for the list command
--silent Do not output any message
-q, --quiet Only errors are displayed. All other output is suppressed
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--env[=ENV] The environment the command should run under
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
用途：导入管理台导出的 .dfpkg 资源包或 zip 包（服务定义、角色、API 文档等整体迁移场景），--password 用于加密包，--delete 导入后删除包文件。错误形态实测（路径不存在）：
php artisan df:import-pkg /tmp/no-such-pkg.dfpkg
实测输出：
Invalid path /tmp/no-such-pkg.dfpkg
⚠️ 排障提示：报
Invalid path时先确认两点——文件是否真实存在、路径是否为命令接受的相对路径形态（官方约定相对应用目录）。修正路径后重新执行即可。
10.5 df:clear-file-cache：清文件缓存
php artisan df:clear-file-cache
实测输出：
Cleared DreamFactory cache for all instances!
解读：与 cache:clear 的分工——df:clear-file-cache 清 DreamFactory 自身的文件型缓存（存储服务元数据缓存等落盘缓存），cache:clear 清应用缓存（Redis 中的键）。升级版本或服务定义异常（如改了服务配置但 API 行为未变）时，两个命令连跑是标准排障组合：
php artisan df:clear-file-cache && php artisan cache:clear
10.6 df:access-usage-backfill 与 df:homestead-config
两者实测 --help 的关键信息：
df:access-usage-backfill：Seed access_usage last-used times from agent_activity_ledger history (df-agents installs)——仅在部署了 df-agents（AI 代理组件）的安装上使用，从活动台账回填 access_usage 的最近使用时间；常规安装执行无实际效果。df:homestead-config：帮助显示描述为Command description（上游未填写描述），带--dev参数（Setup workbench for all packages and configure PSR-4 autoloader for them），属开发环境（Laravel Homestead 时代遗留）的包工作台配置命令，运维场景不使用。
十一、队列与调度类命令
DreamFactory 默认队列驱动为 database（任务落 jobs 表），调度任务通过 Laravel scheduler 注册。
11.1 queue:failed：查看失败队列任务
php artisan queue:failed
实测输出：
INFO No failed jobs found.
解读：失败任务记录在 failed_jobs 表，No failed jobs found. 表示没有积压的失败任务（健康状态）。若出现失败任务，处理链路为：queue:retry <任务ID> 重试、queue:forget <任务ID> 单条删除、queue:flush 全部清空、queue:prune-failed 按时间清理。
11.2 queue:monitor：监控队列积压
php artisan queue:monitor database
实测输出：
Queue name ................................................... Size / Status
[database] database ................................................. [0] OK
Pending jobs ............................................................. 0
Delayed jobs ............................................................. 0
Reserved jobs ............................................................. 0
Oldest pending job ..................................................... N/A
解读：对 database 连接上的 database 队列给出积压画像：待处理/延迟/占用中任务均为 0，无最老积压。--max 参数可设告警阈值，超阈值时命令以非零退出码结束，可直接接入巡检脚本。
11.3 queue:restart：广播 worker 重启信号
php artisan queue:restart
实测输出：
INFO Broadcasting queue restart signal.
解读：向缓存写入一个"最后重启时间戳"信号，所有 queue:work 守护进程在处理完当前任务后自杀退出，由其守护机制拉起新进程完成"滚动重启"。修改队列相关代码或配置后执行。验证方式：信号写入后 worker 日志出现重启记录；无 worker 在跑时该命令同样成功（信号等后续 worker 启动时消费）。
11.4 schedule:list：查看调度任务（含排障实录）
php artisan schedule:list
实测输出（报错）：
In AbstractConnection.php line 155:
Connection refused [tcp://127.0.0.1:6379]
⚠️ 排障实录（错误现象 → 定位 → 解决）：
- 现象：schedule:list 报
Connection refused [tcp://127.0.0.1:6379]，但平台缓存明明使用的是另一台 Redis 主机（.env中CACHE_HOST=redis），且 cache:clear 等缓存命令全部正常。- 定位：schedule:list 读取调度任务时要通过 Laravel 原生
redis连接取调度互斥锁，该连接的主机取自REDIS_HOST，未设置时回落默认值127.0.0.1——而本环境 Redis 独立部署，127.0.0.1:6379无服务监听，连接被拒。这也是为什么只有这条命令报错：cache 相关命令走的是 DreamFactory 自定义的 cache 连接（用CACHE_HOST），不走默认连接。- 解决：以环境变量方式注入正确主机验证——
REDIS_HOST=redis php artisan schedule:list实测输出（修复后）：
0 0 * * * php artisan mcp:prune-request-logs .. Next Due: 23 hours from now 0 * * * * php artisan inspire ............... Next Due: 18 minutes from now
- 固化：把
REDIS_HOST=redis写入.env后无需前缀即可正常执行；.env修改后按七.3 节建议执行php artisan optimize:clear。- 解读：当前注册了 2 个调度任务——
mcp:prune-request-logs每日 00:00 清理 MCP 请求审计日志（保留期见 MCP 配置），inspire每小时整点运行（Laravel 自带示例任务，无业务影响）。生产环境需在 crontab 中注册* * * * * php /opt/dreamfactory/artisan schedule:run让调度真正执行。
十二、注意事项（破坏性命令红线）
下表汇总本族命令的风险等级与执行建议，红线条目均经本文实测确认（回显见对应小节）：
| 命令 | 风险 | 实测依据与建议 |
|---|---|---|
| migrate:rollback | 回滚整批迁移，将 DROP 系统表 | 5.3 节预演显示将 DROP user/role/service 等核心表；先 --pretend + 备份 |
| migrate:fresh / migrate:reset | 清空全部表重建 | 全新环境专用，生产禁用 |
| migrate:refresh | 全量回滚再重跑 | 仅开发环境 |
| db:wipe | 直接删库所有表 | 仅全新环境 |
| df:setup --force | 强制重跑迁移与种子 | 可能重置系统数据，存量环境禁用（10.1 节） |
| key:generate（不带 --show） | 覆盖 APP_KEY | 库内全部密文字段不可解（9.1 与 10.3 节实证） |
| jwt:secret --force | 覆盖 JWT_SECRET | 全部在线用户被登出（9.2 节） |
| down | 全站 API 503 | 实测 503/200 闭环（八.1/八.2 节），维护窗口提前公告 |
| optimize 后改 .env | 新配置不生效 | 必须 optimize:clear（七.3 节） |
| queue:restart | worker 滚动重启 | 处理完当前任务才退出，可安全执行（11.3 节） |
通用建议：生产执行任何迁移类命令前先 php artisan migrate:status 与数据库备份；脚本化执行统一加 --no-interaction；--force 仅在确认环境为可重建的全新库时使用。
十三、常见问题
Q1：schedule:list 报 Connection refused [tcp://127.0.0.1:6379] 怎么解决？
默认 redis 连接回落到 127.0.0.1 所致。把 .env 的 REDIS_HOST 设为实际 Redis 主机（本环境为 redis）即可，修复命令与回显见 11.4 节实测实录。
Q2：db:show / db:table 尾部报 The "intl" PHP extension is required 是不是故障？
不是。主体巡检信息已完整输出，仅尾部数字格式化环节因 PHP 缺 intl 扩展报错（六.1 节排障实录）。需要彻底消除时为 PHP 安装 intl 扩展；否则可忽略。
Q3：php artisan migrate 提示 Nothing to migrate. 是不是没执行成功？
是正常回显，表示系统库已是最新结构（5.1 节）。用 php artisan migrate:status 复核：全部 [N] Ran、无 Pending 即健康。
Q4：php artisan db 报 TTY mode requires /dev/tty to be read/writable.？
该命令需要真实交互终端，管道/cron 等非交互场景不可用（六.4 节排障实录）。自动化场景改用数据库客户端直连。
Q5：执行 down 后所有接口 503，怎么恢复？
php artisan up 即恢复，实测闭环见八.1/八.2 节（down → curl 503，up → curl 200）。
Q6：df:request 传了 --format=json 为什么输出还是 PHP 对象打印？
实测确认 --format 只影响内部数据格式，命令始终以 ServiceResponse 对象结构打印结果（10.3 节实测），属预期行为；需要 JSON 请走 Web 层 API。
十四、参考链接
- DreamFactory 官方仓库：https://github.com/dreamfactorysoftware/dreamfactory
- DreamFactory 官方文档站：https://docs.dreamfactory.com
- Laravel Artisan 官方文档：https://laravel.com/docs/artisan
- 站内系列：《DreamFactory 7.7.1 介绍与选型指南》、《DreamFactory Docker Compose 部署指南》、《DreamFactory 7.7.1 配置参数详解》