ProjectSend 2.8.0 常用 CLI 命令与工具详解

ProjectSend 2.8.0 命令行运维实战：projectsend 命名空间全部 22 条 artisan 命令与 Laravel 通用维护命令的参数说明与逐条实测回显，覆盖安装引导、巡检诊断、生命周期清理与账号治理四类场景。

ProjectSendProjectSendPHP2026/11/01

ProjectSend 2.8.0 常用 CLI 命令与工具详解

目标：系统梳理 ProjectSend 2.8.0 自带的命令行工具——projectsend 命名空间全部 22 条 artisan 命令与日常运维必用的 Laravel 通用命令，逐条给出参数说明与实测回显，覆盖安装引导、巡检诊断、生命周期清理与账号治理四类场景。全部命令在 2.8.0 实测环境逐条运行取证。

一、环境信息

  • 操作系统：Ubuntu 24.04.5 LTS（x86_64）
  • ProjectSend：2.8.0（官方镜像 projectsend/projectsend:2.8.0）
  • 运行时：PHP 8.4.27 / Laravel Framework 12.69.3（php artisan about 实测）
  • 数据库：MySQL 8.4；缓存/会话/队列：Redis 7
  • 部署形态：Docker Compose 三服务，部署目录 /srv/projectsend（部署过程见《ProjectSend 2.8.0 Docker Compose 部署指南》）
  • 服务器地址：http://192.168.1.172:8135
  • 实测数据状态：1 个管理员（admin@example.com）、1 个客户、1 个文件（48 字节），病毒扫描与外发邮件未配置

二、工具概览

ProjectSend 的 CLI 入口是 Laravel 框架的 Artisan 命令行（PHP 编写，随应用分发），产品专属命令集中在 projectsend 命名空间下，另有若干 Laravel 通用命令用于数据库与队列维护。执行形态按部署方式分两种：

# Docker Compose 部署（本文实测形态）：在部署目录执行
cd /srv/projectsend
docker compose exec app php artisan <命令>

# zip 安装形态：在安装目录直接执行
cd /var/www/projectsend
sudo -u www-data php artisan <命令>

两种形态的命令本体完全一致，下文回显均以 Compose 形态采集（省略 docker compose exec app 前缀）。

php artisan list 的头部与命令命名空间全景（实测，节选保留 projectsend 命名空间全文）：

Laravel Framework 12.69.3

Usage:
  command [options] [arguments]

  ...
 projectsend
  projectsend:admin                      Create a staff administrator account
  projectsend:captcha-off                Switch off the CAPTCHA on public forms
  projectsend:captcha-test               Check the configured CAPTCHA keys against the provider
  projectsend:check-for-updates          Check for a newer ProjectSend release and notify admins (Community edition, runs daily)
  projectsend:check-missing-files        Check that every file in the database is still on disk (runs daily)
  projectsend:ensure-roles               Ensure the built-in system roles exist (idempotent; run on every boot)
  projectsend:erase-account              Permanently erase an account and anonymize its activity-log entries (GDPR erasure)
  projectsend:expire-client-accounts     Deactivate client accounts whose expiry date has passed (runs hourly)
  projectsend:fetch-news                 Fetch the ProjectSend news feed for the dashboard (both editions, runs daily)
  projectsend:purge-api-request-logs     Delete API request telemetry older than the configured retention window (runs daily)
  projectsend:purge-erasures             Permanently erase deleted accounts whose grace period has passed (runs daily)
  projectsend:purge-expired-files        Permanently delete files whose expiry grace period has passed (runs daily)
  projectsend:purge-failed-jobs          Delete failed queue jobs older than the configured retention window (runs daily)
  projectsend:purge-notifications        Delete read notifications older than the configured retention window (runs daily)
  projectsend:purge-orphan-files         Permanently delete local-disk orphan files found longer ago than the configured grace period (runs daily; never touches external storage)
  projectsend:purge-stale-uploads        Remove chunked-upload sessions (and their temp parts) older than 24 hours
  projectsend:purge-zip-downloads        Remove built zip downloads (and their files) older than 24 hours — disposable, regenerable artifacts
  projectsend:refresh-mail-oauth-tokens  Refresh connected OAuth mailbox tokens and flag connections that need to be reconnected (runs daily)
  projectsend:scan-files                 Scan files that are waiting, were missed, or were never checked (runs hourly)
  projectsend:seed-settings              Apply provisioning defaults from the environment to settings that have never been set
  projectsend:staff-passwords-on         Let staff sign in with a password again, when the provider they must use is not working
  projectsend:status                     Report this installation's version, edition, capabilities and seat usage
  projectsend:update                     Bring the database, roles and caches in line with the installed code (idempotent; run on every boot)

命令清单解读：条目描述里标注的 "runs daily/hourly" 表示该命令已由内置调度器自动执行（调度清单实测见 4.3 节），手工执行的意义是立即触发一次或在调度器异常时手工补跑；未标注的则是纯手工命令（如建号、擦除、状态查询）。

三、前置条件

  1. 一套可运行的 ProjectSend 2.8.0（核对命令与回显见下）；命令行入口可达：
php artisan projectsend:status

实测回显：

ProjectSend 2.8.0 (community)
Build:        v2.8.0
Health:       0 migrations pending, 0 failed jobs, 0 queued
  1. 权限要求：命令需以应用运行用户身份执行（zip 形态用 sudo -u www-data）；Compose 形态 docker compose exec app 默认即为容器内执行，无需额外处理。

四、projectsend 命令族详解

本节按使用场景分四组，逐条给参数与实测回显。所有命令均可独立执行。

4.1 安装引导与账号管理

projectsend:update —— 让数据库、角色与缓存对齐当前代码版本，幂等，每次启动自动执行；升级后手工补跑、或怀疑缓存状态异常时使用。无参数。

php artisan projectsend:update

实测回显：

System roles are in place.
Cleared the compiled configuration, events, routes and views.
Asked the background workers to restart.

Re-applied 2.8.0.

projectsend:ensure-roles —— 确保内置系统角色存在（幂等），update 的子步骤，偶尔需单独修复角色表时使用。实测回显：

System roles are in place.

projectsend:seed-settings —— 把环境变量中的预置值写入"从未设置过"的 settings 键，幂等、不覆盖界面已设值（与《ProjectSend 2.8.0 配置参数详解》第三章三层配置体系呼应）。实测回显（无可预置项时静默完成，无输出）。

projectsend:admin —— 创建员工管理员账号。参数：--name（姓名）、--email（登录邮箱）、--password（口令，省略时交互式询问）、--if-none（已有员工账号时不做任何事，无人值守预置用）。

php artisan projectsend:admin --help

实测回显（节选）：

Usage:
  projectsend:admin [options]

Options:
      --name[=NAME]          Full name of the administrator
      --email[=EMAIL]        Email address (used to log in)
      --password[=PASSWORD]  Password (prompted interactively when omitted)
      --if-none              Do nothing when a staff user already exists (idempotent provisioning)

实测创建示例（口令同样受 ≥12 字符 + 泄露库校验约束，见第六章注意事项）：

php artisan projectsend:admin --name=auditor --email=auditor@example.com --password=Q1w2E3r4-doc-2026

实测回显：

Administrator auditor@example.com created.

projectsend:staff-passwords-on —— 当团队被迫使用 LDAP/社交登录等外部身份源且其临时不可用时，恢复"口令登录"通道让员工能进系统。幂等，无需参数。实测回显（默认形态下口令登录本就开启）：

Staff can already sign in with a password. Nothing changed.

projectsend:erase-account —— GDPR 级账号擦除：永久删除账号并匿名化其活动日志条目。参数：位置参数 email（目标账号邮箱）、--force（跳过确认）。不可逆，正式执行前确认邮箱。

php artisan projectsend:erase-account --help

实测回显（节选）：

Usage:
  projectsend:erase-account [options] [--] <email>

Arguments:
  email                 Email address of the account to erase

Options:
      --force           Skip the confirmation prompt

实测示例（擦除上面创建的 auditor 测试账号）：

php artisan projectsend:erase-account auditor@example.com --force

实测回显：

Account erased and log entries anonymized.

4.2 巡检与诊断

projectsend:status —— 一条命令看全安装状态：版本、版本线（edition）、能力清单、席位占用、存储用量、健康度、扫描与调度器状态、近 30 天上传下载量。日常巡检首选，无参数。

php artisan projectsend:status

实测回显（完整）：

ProjectSend 2.8.0 (community)
Capabilities: users.manage, storage.configure, scanning.connect, email.transport.configure, system.updates, news.configure, scheduler.monitoring, custom_assets.manage, branding.customize, captcha.configure, ai.connector, downloads.zip
Staff seats:  1 of unlimited
Clients:      1 of unlimited
Last staff login: 2026-11-01T02:49:53+00:00
Storage:      48 bytes in 1 files
Build:        v2.8.0
Health:       0 migrations pending, 0 failed jobs, 0 queued
Scanning:     off
Scheduler:    2026-11-01T03:00:00+00:00 (0 failing)
Last 30d:     1 downloads, 1 uploads

逐行解读：Health 行三项归零即安装健康（待迁移=0、失败队列=0、排队=0）；Scheduler 行显示最近一次调度时间与失败数（never run 说明调度器尚未跑过，(0 failing) 为正常）；Scanning 行对齐病毒扫描开关。

projectsend:check-for-updates —— 检查新版本并通知管理员（社区版每日自动跑）。实测回显：

You are up to date, running version 2.8.0.

projectsend:check-missing-files —— 数据库登记的文件与磁盘实际文件比对，找出"库里有没有、盘上丢了"的记录（每日自动跑）。实测回显：

0 file(s) are missing from storage (0 newly), 0 came back.

4.3 生命周期清理与定时任务

以下命令均已由内置调度器按频次自动执行，手工执行即立即触发一次。全部幂等，且在对应功能未启用时明确说明而非误删。

命令自动频次实测回显（当前空载状态）
projectsend:purge-stale-uploads每小时Purged 0 stale upload session(s).
projectsend:purge-zip-downloads每日Purged 0 stale zip download(s) and 0 unreferenced file(s).
projectsend:purge-expired-files每日Auto-delete of expired files is disabled.
projectsend:purge-orphan-files每日Auto-delete of orphan files is disabled.
projectsend:purge-failed-jobs每日Pruned 0 failed jobs older than 30 days.
projectsend:purge-notifications每日Pruned 0 read notifications older than 90 days.
projectsend:purge-api-request-logs每日Pruned 0 API request log entries older than 30 days.
projectsend:purge-erasures每日Erased 0 account(s).
projectsend:expire-client-accounts每小时Deactivated 0 expired client account(s).

回显解读：purge-failed-jobs/purge-notifications/purge-api-request-logs 的保留窗口实测分别为 30/90/30 天；purge-expired-files 与 purge-orphan-files 默认关闭自动删除（在界面设置中开启后才执行真删除），因此只报告 disabled——这两个是"破坏性清理默认双保险"的设计。

projectsend:scan-files —— 扫描等待中、被错过或从未检查的文件（每小时自动跑）；扫描功能关闭时仅提示。实测回显：

Virus scanning is switched off.

schedule:list —— 查看内置调度器的完整任务表（Laravel 通用命令），核对各清理命令的自动频次与下次执行时间：

php artisan schedule:list

实测回显（完整）：

  0 0 * * *  php artisan mcp:prune ............... Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:purge-erasures  Next Due: 21 hours from now
  0 * * * *  php artisan projectsend:purge-stale-uploads  Next Due: 43 seconds from now
  0 * * * *  php artisan projectsend:expire-client-accounts  Next Due: 43 seconds from now
  0 0 * * *  php artisan projectsend:purge-zip-downloads  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:check-for-updates  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:fetch-news .. Next Due: 21 hours from now
  0 * * * *  php artisan projectsend:scan-files  Next Due: 43 seconds from now
  0 0 * * *  php artisan projectsend:purge-expired-files  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:purge-orphan-files  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:check-missing-files  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:purge-api-request-logs  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:purge-failed-jobs  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:purge-notifications  Next Due: 21 hours from now
  0 0 * * *  php artisan projectsend:refresh-mail-oauth-tokens  Next Due: 21 hours from now

清单解读：每小时整点跑 4 项（过期上传清理、过期客户停用、文件扫描、另含扫描），每日零点跑 11 项；mcp:prune 是 AI 连接器（MCP）授权数据的清理任务。Compose 部署形态下调度器由镜像内 supervisord 常驻拉起（scheduler 进程），zip 形态则按 INSTALL.md 配置 cron。

4.4 内容与集成维护

projectsend:captcha-off / projectsend:captcha-test —— CAPTCHA 应急开关与配置自检：忘记开 CAPTCHA 被锁定、或换了 CAPTCHA 服务商后验证密钥。实测回显：

php artisan projectsend:captcha-off

CAPTCHA is off. Your keys are still stored — switch it back on at /system/settings/captcha.

php artisan projectsend:captcha-test

No CAPTCHA is configured, so there is nothing to test.

projectsend:refresh-mail-oauth-tokens —— 刷新 OAuth 邮箱令牌、标记需要重新授权的连接（每日自动跑）。实测回显（未连接 OAuth 邮箱）：

No connected OAuth mailboxes; nothing to refresh.

projectsend:fetch-news —— 拉取仪表盘新闻源（每日自动跑，两种版本线都启用）。实测回显：

Fetched 5 news item(s).

五、通用 Laravel 维护命令精选

以下 Laravel 通用命令在 ProjectSend 运维中最常用，实测回显如下。

php artisan migrate:status

实测回显（尾部节选）：

  2026_09_25_100000_add_show_site_name_to_branding_settings .......... [1] Ran
  2026_10_02_090000_add_polling_index_to_folders_table ............... [1] Ran
  2026_10_03_090000_add_logo_crop_to_branding_settings ............... [1] Ran
  2026_10_05_090000_add_username_attribute_to_ldap_settings .......... [1] Ran
  2026_10_23_090000_add_skip_two_factor_to_social_login_providers .... [1] Ran

（全部迁移显示 [1] Ran 即数据库结构齐备；出现 Pending 行说明代码版本与数据库不一致，跑 projectsend:update 补齐。）

php artisan queue:failed

实测回显（无失败任务时）：


   INFO  No failed jobs found.

有失败任务时的处置链：queue:failed 列出 → 排查原因（多为外部服务不可达：SMTP/对象存储/扫描器）→ php artisan queue:retry <任务UUID> 单条重试或 php artisan queue:retry all 全部重试 → php artisan queue:forget <UUID> 丢弃确认无法重试的任务。zip 形态还需注意 worker 由 systemd/supervisor 托管，php artisan queue:restart 可让 worker 平滑重启（Compose 形态由镜像内进程管理器自动处理）。

六、注意事项

  1. 命令破坏性分级：read-only（status/check-missing-files/check-for-updates/captcha-test/schedule:list）可随意跑；幂等修复类（update/ensure-roles/seed-settings/staff-passwords-on）安全；删除类（erase-account、各 purge-*）执行前确认对象——erase-account 不可逆，purge 系列在自动删除未开启时只报状态不删数据。
  2. 管理员口令双校验：projectsend:admin 与首启自动建号使用同一套校验——≥12 字符、不得命中公开泄露库；省略 --password 时进入交互式询问，输入的口令同样受检。
  3. 不要手工跑 config:cache：会静默禁用 TRUSTED_PROXIES（详见《ProjectSend 2.8.0 配置参数详解》第七章 FAQ）。
  4. 版本对齐后跑 update：手工替换二进制/升级镜像后，先 projectsend:update 再对外服务，避免新旧结构混用。
  5. Compose 形态的执行身份：docker compose exec app php artisan … 在容器内执行；如需以应用用户身份（与 zip 形态一致的 www-data）运行，加 -u www-data，日常运维命令两者结果一致。

七、常见问题（FAQ）

Q1：projectsend:status 显示 Scheduler: never run 正常吗？

刚部署完尚未到第一个整点时正常（每小时/每日任务整点触发）。超过一个整点仍 never run，检查镜像内 scheduler 进程是否存活：docker compose exec app ps aux | grep scheduler；zip 形态检查 cron 条目。恢复后 status 会显示最近一次运行时间与失败计数。

Q2：projectsend:admin 建号报 The password field must be at least 12 characters.

口令长度不足 12 位。换 ≥12 位口令重试；另注意泄露库校验（见部署篇 FAQ）同样适用于此命令。

Q3：erase-account 能恢复吗？

不能。该命令的设计目标就是 GDPR 合规擦除：账号永久删除、活动日志条目匿名化。执行前务必核对邮箱；--force 会跳过交互确认立即生效。若希望留有反悔窗口，不要用本命令——改走带宽限期的路径（purge-erasures 每日任务只永久擦除"已过宽限期的已删除账号"，未到宽限期只计 0，如本文实测回显 Erased 0 account(s).）。

Q4：升级后不跑 projectsend:update 会怎样？

镜像部署形态下 entrypoint 每次启动自动执行，无需手工；但若你用 zip 形态手工替换代码，忘记跑 update 会导致数据库结构与新代码不匹配（status 的 Health 行会显示 pending migrations），页面可能 500。补救：补跑 php artisan projectsend:update 即可，幂等无副作用。

Q5：手动跑 purge 命令会重复删除或漏删吗？

不会。全部 purge 命令按"时间窗口 + 状态条件"筛选，幂等且与调度器执行同一逻辑；手动触发只是把下次整点的活提前干了。

八、参考链接