Kanboard 1.2.56 常用 CLI 命令详解

Kanboard 1.2.56 自带 CLI 全量命令实测详解：db 迁移、cronjob、四条 CSV 导出、用户密码/2FA 重置、插件管理与 CLI/API 分工，全部命令附真实回显与排障坑点。

KanboardKanboard看板自托管PHP 应用任务管理2026/10/24

Kanboard 1.2.56 常用 CLI 命令详解

目标：逐条实测讲清 Kanboard 1.2.56 自带 CLI（./cli，基于 Symfony Console）的全部常用命令——数据库运维、定时任务、CSV 导出、用户安全重置、插件管理、本地化与前端资源工具，并明确 CLI 与 JSON-RPC API 的分工边界。全部命令与回显均在 v1.2.56 环境实测。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Kanboard：v1.2.56（源码目录 /var/www/kanboard/，标准部署视角；官方 Docker 形态的 CLI 入口路径为应用根下的 /var/www/app/cli，执行方式见本站部署篇）
  • 已有测试数据：项目「运维任务看板」（id=1）含 1 条任务（供导出命令演示）
  • 实测日期：2026-10-23；CLI 版本随应用，./cli version 实测回显 Kanboard v1.2.56

二、前置条件

  • Kanboard 1.2.56 已部署可访问（部署见本站部署篇）；
  • CLI 以 Web 运行用户身份执行（tar 包部署通常为 www-data），避免产生属主混乱的缓存/日志文件：
  • 以下所有命令在应用根目录执行：
cd /var/www/kanboard
./cli version

实测回显：

Kanboard v1.2.56

三、命令清单总览

./cli list 的完整清单（25 条，实测）：

Kanboard v1.2.56

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -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
  -v|vv|vvv, --verbose  Increase the verbosity of messages

Available commands for the "kanboard" namespace:
  completion                            Dump the shell completion script
  cronjob                               Execute daily cronjob
  css                                   Minify CSS files
  db:migrate                            Run database migrations
  db:version                            Show database schema version
  export:daily-project-column-stats     Daily project column stats CSV export
  export:subtasks                       Subtasks CSV export
  export:tasks                          Tasks CSV export
  export:transitions                    Task transitions CSV export
  help                                  Display help for a command
  job                                   Execute individual job (read payload from stdin)
  js                                    Minify Javascript files
  list                                  List commands
  locale:compare                        Compare application translations
  locale:sync                           Sync application translations
  notification:overdue-tasks            Send notifications for overdue tasks
  plugin:install                        Install plugin from remote Zip archive
  plugin:uninstall                      Uninstall plugin
  plugin:upgrade                        Update all installed plugins
  projects:archive                      Disable projects not touched during one year
  projects:archive-activities           Remove activities from archived projects
  projects:daily-stats                  Calculate daily statistics for all projects
  trigger:tasks                         Trigger task event on all tasks
  user:reset-2fa                        Remove two-factor authentication of a user
  user:reset-password                   Reset user password
  version                               Show application version
  worker                                Execute queue worker

⚠️ 关键边界：CLI 覆盖的是运维型动作（迁移/导出/归档/统计/重置），不包含项目、任务、用户的增删改管理——业务对象管理请走 JSON-RPC API（见第十节）。

四、核心运维命令

本节是日常巡检与升级时最常用的六条命令。

4.1 db:version —— 查看数据库结构版本

./cli db:version

实测回显：

Current version: 128
Last version: 128

解读：Current 是库结构当前版本，Last 是代码期望的最新版本，两者相等即结构一致。升级 Kanboard 后应第一时间对比（不等则执行 db:migrate）。

4.2 db:migrate —— 执行数据库迁移

./cli db:migrate

实测回显（已到最新版时静默通过，仅回显版本号）：

Current version: 128
Last version: 128

⚠️ 注意：迁移会修改数据库结构，执行前必须备份（SQLite 形态备份 data/ 目录即可）。默认配置下应用启动会自动跑迁移（DB_RUN_MIGRATIONS=true），手工执行主要用于关闭自动迁移（DB_RUN_MIGRATIONS=false）的受控变更流程。

4.3 cronjob —— 执行每日定时任务

./cli cronjob

实测回显（无告警项时静默完成）：

（空）

这是 Kanboard 内置定时任务的统一入口，等价于 Web 侧「设置 → 定时任务」的每日动作（任务日历提醒、逾期通知、每日统计等）。生产上用系统 cron 每日驱动：

5 3 * * * cd /var/www/kanboard && ./cli cronjob >/dev/null 2>&1

4.4 notification:overdue-tasks —— 逾期任务通知

./cli notification:overdue-tasks

实测回显（无逾期任务时静默）：

（空）

扫描所有逾期未完成任务并向订阅者发送通知（依赖邮件配置 MAIL_*，邮件参数详解见本站配置篇）。可挂 cron（如每小时一次）实现逾期即时提醒。

4.5 trigger:tasks —— 重触发任务事件

./cli trigger:tasks

实测回显：

（空）

对全部任务重放事件流水，用于事件驱动相关数据（如自动动作、统计）的补偿修复。日常无需执行，排障或迁移后使用。

4.6 job 与 worker —— 队列体系

Kanboard 支持外部队列（Redis/Jitter）时可用独立 worker 消费任务（邮件发送等异步动作）；默认同步执行时这两个命令不参与日常工作流。

./cli help worker

实测回显：

Description:
  Execute queue worker

Usage:
  worker

job 从 stdin 读取单个 payload 执行，喂入无效内容时的真实回显（排障参考）：

echo 'invalid-payload' | ./cli job

实测回显：

[23-Oct-2026 16:50:00 UTC] PHP Warning:  Trying to access array offset on null in /var/www/kanboard/app/Core/Queue/JobHandler.php on line 46
Warning: Trying to access array offset on null in /var/www/kanboard/app/Core/Queue/JobHandler.php on line 46

五、项目命令

命令作用执行节奏
projects:daily-stats为所有项目计算每日统计（列任务数快照，供分析图使用）cron 每日
projects:archive归档整年未被触碰的项目（置为不可见）cron 每日/每周
projects:archive-activities清理已归档项目的活动流数据cron 每周

projects:daily-stats 实测（存在项目「运维任务看板」）：

./cli projects:daily-stats

实测回显：

Run calculation for 运维任务看板

projects:archive / projects:archive-activities 实测（当前无满足归档条件的项目，静默完成）：

（空）

⚠️ 注意：projects:archive 会真实禁用整年未动的项目（管理员可在界面重新打开）。若不希望自动归档，不要把它挂到 cron。

六、导出命令（export:*）

四条 CSV 导出命令统一格式：export:<对象> <project_id> <start_date> <end_date>（日期格式 YYYY-MM-DD），输出 CSV 到 stdout，配合重定向落文件。

6.1 export:tasks —— 任务导出

./cli export:tasks 1 2026-10-01 2026-10-23

实测回显（表头 + 数据行，供演示）：

"Task Id",Reference,Project,Status,Category,Swimlane,Column,Position,Color,"Due date",Creator,"Creator Name","Assignee Username","Assignee Name",Complexity,Title,"Creation date","Modification date","Completion date","Start date","Time estimated","Time spent",Priority,Tags
1,,运维任务看板,Open,,"Default swimlane",Ready,1,Yellow,,admin,,admin,,0,"验证 Kanboard 部署闭环","10/23/2026 16:29","10/23/2026 16:29",,,,,0,

6.2 export:daily-project-column-stats —— 每日列统计导出

./cli export:daily-project-column-stats 1 2026-10-01 2026-10-23

实测回显：

Date,Backlog,Ready,"Work in progress",Done
2026-10-23,0,1,0,0

解读：默认四列（Backlog/Ready/Work in progress/Done）的每日任务数快照——正是绘制累积流图（CFD）的数据源。

6.3 export:subtasks 与 export:transitions

./cli export:subtasks 1 2026-10-01 2026-10-23
./cli export:transitions 1 2026-10-01 2026-10-23

实测回显（无子任务/流转记录时仅返回表头）：

"Subtask Id",Title,Status,Assignee,"Time estimated","Time spent","Task Id","Task Title"

Id,"Task Title","Source column","Destination column",Executer,Date,"Time spent"

💡 技术拓展：transitions 导出记录任务每次跨列流转（源列→目标列、操作者、耗时），是计算**周期时间（Cycle Time）**的原始数据——用「任务完成时间 − 进入工作列时间」即可度量团队流动效率。

七、用户与安全命令

7.1 user:reset-password —— 重置用户密码（交互式）

./cli user:reset-password admin

实测回显（输入两次新密码）：

What is the new password for admin? (characters are not printed)

Confirmation:

Password updated successfully

口令策略实测（少于 6 位被拒）：

The minimum length is 6 characters

⚠️ 重要坑点：重置密码不会解锁被暴力防护锁定的账号——锁定状态（nb_failed_login/lock_expiration_date）独立于密码存储，锁定期间重置密码后依然登录失败（实测复现见本站配置篇 5.6 节）。需等锁定过期或手工清零这两个字段。

7.2 user:reset-2fa —— 关闭用户两步验证

./cli user:reset-2fa admin

实测回显：

Two-factor authentication disabled

用途：用户丢失验证器（TOTP）后的紧急恢复通道，属管理员兜底操作。

八、插件命令

命令作用
plugin:install <zip_url>从远程 Zip 安装插件
plugin:uninstall <plugin_name>卸载插件
plugin:upgrade升级所有已装插件

⚠️ 前提：这三条命令受配置 PLUGIN_INSTALLER 控制（默认 false），未开启时直接拒绝。实测回显（默认配置下执行 plugin:install 与 plugin:upgrade）：

In PluginInstallCommand.php line 25:

  Kanboard is not configured to install plugins itself

In PluginUpgradeCommand.php line 25:

  Kanboard is not configured to install plugins itself

💡 说明：默认关闭插件安装器是官方安全设计（插件无审核机制）。手动安装方式：下载插件 Zip 解压到 plugins/ 目录后重载服务；确认启用安装器后再用这三条 CLI 命令（配置参数见本站配置篇 5.8 节）。

九、开发与本地化命令

9.1 locale:compare —— 翻译一致性检查

./cli locale:compare

实测回显（节选，对比当前语言与英文源码的翻译差异）：

######################################################################
MISSING STRINGS
######################################################################
    'Search task title, description, and comments by default' => '',
    'This user is not allowed to be assigned to this task' => '',
######################################################################
USELESS STRINGS
######################################################################
    'number.decimals_separator' => '',
    'number.thousands_separator' => '',

用途：翻译贡献者查缺补漏；运维侧可用来快速确认当前语言包覆盖度。

9.2 locale:sync —— 同步翻译模板

./cli locale:sync 会重写应用内的翻译 PHP 文件，属开发者工具，运维环境不要执行（help 展示即可）。

9.3 js 与 css —— 前端资源压缩

./cli js
./cli css

实测回显（官方预编译形态下源资产不存在）：

assets/vendor/text-caret/index.js
assets/vendor/text-caret/index.js not found

assets/css/src/themes/light.css not found

解读：这两条命令供从源码包（GitHub clone）部署时压缩前端资产使用；官方预编译包/官方 Docker 形态不携带源资产，执行报 not found 属预期，不影响运行。

9.4 completion —— Shell 补全脚本

./cli completion bash | head -3

实测回显（完整脚本 84 行）：

# This file is part of the Symfony package.
#
# (c) Fabien Potencier <fabien@symfony.com>

按 Symfony Console 标准用法注册到当前 shell 后可对 ./cli 子命令做 Tab 补全。

十、CLI 与 JSON-RPC API 的分工

Kanboard 的 CLI 定位是运维通道，业务对象的增删改查集中在 JSON-RPC API（/jsonrpc.php）。分工对照：

需求通道说明
项目/任务/用户/评论/附件增删改JSON-RPC API官方 API 文档全量方法清单
数据库迁移/版本查询CLI db:*仅 CLI
每日任务/逾期通知CLI cronjob / notification:overdue-tasks仅 CLI
CSV 导出（任务/子任务/流转/列统计）CLI export:*仅 CLI
密码/2FA 紧急重置CLI user:reset-*仅 CLI（API 修改用户走 updateUser）
插件安装/卸载/升级CLI plugin:*受 PLUGIN_INSTALLER 控制
外部系统自动建卡API createTask/createProjectCI/工单集成标准路径

API 快速对照（v1.2.56 为 HTTP Basic 认证）：

curl -s -u admin:q1w2e3r4 -X POST http://localhost/jsonrpc.php \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"createTask","id":1,"params":{"title":"来自 API 的任务","project_id":1,"column_id":2}}'

实测回显：

{"jsonrpc":"2.0","result":2,"id":1}

⚠️ 注意：v1.2.56 的 API 认证已改为标准 HTTP Basic（旧教程的 X-RPC-Auth-Username/Password 头实测 401）；且部分方法签名与旧文档有差异（如 getTask 仅收 task_id 一个参数、任务列表方法为 getAllTasks）。权威方法清单以应用内源码为准（app/Api/Procedure/*.php）。

十一、常见问题（FAQ）

Q1：CLI 执行报权限错误（无法写 data/ 或 cache/）？

CLI 必须与 Web 运行同一系统用户执行（tar 包通常 sudo -u www-data ./cli …），否则会以 root 生成属主错误的日志/缓存，Web 侧反而写不进去。

Q2：cronjob 挂了 cron 但没有任何通知？

检查三件事：MAIL_* 是否配置为可用 SMTP（用界面「设置」发测试邮件验证）、是否真有到期/逾期数据（notification:overdue-tasks 静默说明无命中）、cron 日志确认命令真实执行。参数排查见本站配置篇 5.3 节。

Q3：升级后要不要手工跑 db:migrate？

默认 DB_RUN_MIGRATIONS=true 时启动自动迁移，无需手工执行；关闭了自动迁移的受控环境，升级流程为：备份 → 替换代码 → ./cli db:migrate → ./cli db:version 确认两个版本号一致（实测回显见 4.1/4.2）。

Q4：为什么没有 project:create / task:create 这样的命令？

Kanboard CLI 的设计边界就是运维动作，业务管理统一走 JSON-RPC API（第十节分工表）。写自动化脚本时：批量建卡用 API，批量导出用 CLI export:*，两者配合覆盖绝大多数场景。

十二、参考链接