Vikunja 2.7.1 常用 CLI 命令详解
Vikunja 2.7.1 单二进制内置 CLI 全命令实测：12 顶层命令（web/doctor/dump/restore/migrate/repair/user/testmail/healthcheck 等）与 7+5 个子命令逐项用法、真实回显、社区版 set-admin 功能边界、备份恢复与应急重置密码等典型运维场景串联。
Vikunja 2.7.1 常用 CLI 命令详解
Vikunja 的单一二进制既是 API 服务器，也是完整的命令行管理工具：同一个 vikunja 命令既可以通过 web 子命令启动服务，也内置了用户管理、数据库迁移、备份恢复、数据修复、健康诊断等全部运维能力，无需额外安装管理端。本文基于 v2.7.1 真实环境实测，逐一详解 12 个顶层命令及其子命令的用法与回显。Vikunja CLI 能力覆盖完整（12 顶层命令、7 个用户子命令、5 个修复子命令），故本文按 D1（CLI 详解）而非 D5（API 详解）成文；REST API 使用已在安装篇的验证环节给出示例。
一、CLI 概述与命令总览
直接在部署主机上执行 vikunja 即可调用 CLI。所有子命令共享一个全局参数：
--config string Path to the config file to use. Bypasses the default search path.
用于指定配置文件，绕过默认查找路径（查找顺序见本专栏《Vikunja 2.7.1 配置参数详解》）。不指定时按默认规则加载，与 systemd 服务读取同一份配置。
顶层命令一览（vikunja --help 实测）：
Vikunja (/vɪˈkuːnjə/)
The to-do app to organize your life.
Also one of the two wild South American camelids which live in the high
alpine areas of the Andes and a relative of the llama.
Vikunja is a self-hosted To-Do list application with a web app and mobile apps for all platforms. It is licensed under the AGPL-3.0-or-later.
Find out more at vikunja.io.
Usage:
vikunja [flags]
vikunja [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
doctor Run diagnostic checks on your Vikunja installation
dump Dump all vikunja data into a zip file. Includes config, files and db.
healthcheck Preform a healthcheck on the Vikunja api server
help Help about any command
migrate Run all database migrations which didn't already run.
repair Repair and fix data integrity issues
restore Restores all vikunja data from a vikunja dump.
testmail Send a test mail using the configured smtp connection
user Manage users locally through the cli.
version Print the version number of Vikunja
web Starts the rest api web server
Flags:
--config string Path to the config file to use. Bypasses the default search path.
-h, --help help for vikunja
Use "vikunja [command] --help" for more information about a command.
按用途分为五组：服务运行（web / version / healthcheck）、诊断（doctor）、用户管理（user）、数据维护（migrate / dump / restore / repair）、辅助（testmail / completion / help）。
注意：除 web、version、completion、help 外，大多数子命令执行时会先加载配置、连接数据库并自动跑一遍待执行迁移（日志可见 Running migrations…），因此数据库必须可用。
二、服务运行类
2.1 vikunja web：启动 API 服务
web 是默认子命令，直接执行 vikunja 等价于 vikunja web，启动 REST API 服务器（systemd 单元的 ExecStart 即为该命令）。日常运维一般用 systemctl start vikunja 间接调用，手工调试时可前台运行观察日志：
vikunja web
2.2 vikunja version：查看版本
vikunja version
回显：
Vikunja api version v2.7.1
Built with go1.27.3
同时显示构建所用的 Go 版本，排查兼容性问题时很有用。
2.3 vikunja healthcheck：健康检查
对运行中的实例执行健康检查（校验配置加载与数据库连通性）：
vikunja healthcheck
回显：
time=2026-10-25T02:16:58.133Z level=INFO msg="Using config file: /etc/vikunja/config.yml"
time=2026-10-25T02:16:58.136Z level=INFO msg="Running migrations…"
time=2026-10-25T02:16:58.162Z level=INFO msg="Ran all migrations successfully."
time=2026-10-25T02:16:58.162Z level=WARN msg="No license key configured. Pro features have been disabled."
API server is healthy
健康时输出 API server is healthy 且退出码为 0（实测 echo $? 返回 0），可直接用于监控探活脚本。日志中 No license key configured 为社区版常态提示，不影响功能。
三、诊断类：vikunja doctor
doctor 是 v2.7 引入的一体化诊断命令，对系统、配置、数据库、文件存储做全面体检：
vikunja doctor
回显（健康实例）：
Vikunja Doctor
==============
System
✓ Version: v2.7.1
✓ Go: go1.27.3
✓ OS: linux/amd64
✓ User: root (uid=0)
✓ Working directory: /
✓ User namespace: not active
Configuration
✓ Config file: /etc/vikunja/config.yml
✓ Root path: /
✓ Public URL: http://192.168.146.131:3456/
✓ JWT secret: configured (auto-generated)
✓ CORS origins: http://127.0.0.1:*
http://localhost:*
http://192.168.146.131:3456
Database (postgres)
✓ Connection: OK
✓ Server version: PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit
✓ ParadeDB: not installed (using substring search)
Files (local)
✓ Path: /opt/vikunja/files
✓ Directory exists: yes
✓ Directory permissions: 0755
✓ Directory owner: root:root (uid=0, gid=0)
✓ Writable: yes
✓ Disk space: 226.6 GB available
✓ Stored files: 0 files, 0 B total
All checks passed
诊断覆盖四个维度：系统（版本/架构/运行用户）、配置（配置文件路径/publicurl/JWT secret/CORS 来源）、数据库（连通性与服务端版本）、文件存储（目录存在性/权限/可写性/磁盘余量）。全部通过时输出 All checks passed。
一个值得注意的细节：回显中 JWT secret: configured (auto-generated) 表示当前未显式配置 service.secret、由启动时随机生成——这种状态下每次重启服务，所有已签发的登录令牌都会失效，生产环境务必在配置文件中固定 secret（详见配置篇）。
四、用户管理类：vikunja user
user 命令组提供 7 个子命令：
Available Commands:
change-status Enable or disable a user. Will toggle the current status if no flag (--enable or --disable) is provided.
create Create a new user.
delete Delete an existing user.
list Shows a list of all users.
reset-password Reset a users password, either through mailing them a reset link or directly.
set-admin Set or remove the instance-admin flag on a user.
update Update an existing user.
所有子命令都接受用户 ID 或用户名作为参数；传用户名时会先尝试按 ID 解析，日志提示 Invalid user ID [cliuser], assuming username instead 后按用户名处理，属正常行为。
4.1 user list：列出全部用户
vikunja user list
回显：
┌────┬──────────┬────────────────────┬────────┬────────┬─────────┬───────────────────────────┬───────────────────────────┐
│ ID │ USERNAME │ EMAIL │ STATUS │ ISSUER │ SUBJECT │ CREATED │ UPDATED │
├────┼──────────┼────────────────────┼────────┼────────┼─────────┼───────────────────────────┼───────────────────────────┤
│ 1 │ admin │ admin@example.com │ Active │ local │ │ 2026-10-25T09:41:03+08:00 │ 2026-10-25T09:41:03+08:00 │
│ 2 │ demo │ demo@vikunja.local │ Active │ local │ │ 2026-10-25T09:41:47+08:00 │ 2026-10-25T09:42:11+08:00 │
└────┴──────────┴────────────────────┴────────┴────────┴─────────┴───────────────────────────┴───────────────────────────┘
STATUS 列显示 Active/Disabled，ISSUER 列标识账号来源（local 本地注册，OIDC/LDAP 账号会显示对应来源与 SUBJECT）。
4.2 user create：创建用户
参数：-u/--username、-e/--email、-p/--password（省略则交互式询问）、-a/--avatar-provider（可选头像来源）。
vikunja user create -u cliuser -e cliuser@quzuo.local -p q1w2e3r4
回显（末尾）：
User was created successfully.
关闭注册（service.enableregistration: false）的实例中，这是创建账号的唯一途径。
4.3 user change-status：启用/禁用用户
显式禁用：
vikunja user change-status --disable cliuser
回显（末尾）：
User status successfully changed, status is now "Disabled"
重新启用：
vikunja user change-status --enable cliuser
回显（末尾）：
User status successfully changed, status is now "Active"
不带标志执行则在当前状态间切换。被禁用的用户立即无法登录。
4.4 user update：修改用户资料
vikunja user update -e newmail@quzuo.local cliuser
回显（末尾）：
User updated successfully.
实测踩坑：被禁用的账号无法 update，报错 Error updating the user: Account is disabled，须先 --enable 再修改。
4.5 user reset-password：重置密码
忘记管理员密码时的应急手段。--direct 直接设新密码（不依赖 SMTP）：
vikunja user reset-password --direct -p newpass123 cliuser
回显（末尾）：
Password updated successfully.
不加 --direct 则向用户邮箱发送重置链接（需 mailer 已配置）。
4.6 user set-admin：设置实例管理员
需要 --admin 或 --no-admin 标志。实测社区版（无许可证）该命令不可用：
vikunja user set-admin --admin cliuser
回显（末尾）：
time=2026-10-25T02:17:23.158Z level=ERROR msg="The admin-panel license feature is not active; refusing to change the is_admin flag."
管理员面板属于付费功能，社区版无此能力——这是社区版与付费版的明确功能边界之一。
4.7 user delete：删除用户
vikunja user delete cliuser
删除该账号及其关联数据，不可恢复，执行前建议先 vikunja dump 备份。
五、数据库迁移类：vikunja migrate
migrate 管理数据库结构迁移，含两个子命令：list（列出全部迁移）与 rollback（回滚到指定点）。不带子命令直接执行 vikunja migrate 表示应用所有未执行的迁移（服务启动时也会自动执行）。
vikunja migrate list
回显（截取首尾）：
┌────────────────┬─────────────┐
│ ID │ DESCRIPTION │
├────────────────┼─────────────┤
│ SCHEMA_INIT │ │
│ 20190324205606 │ │
│ 20190328074430 │ │
...
│ 20261012090000 │ │
│ 20261020024804 │ │
└────────────────┴─────────────┘
迁移以时间戳 ID 标识（首个为 SCHEMA_INIT），列表可用来确认当前库结构是否已跟上二进制版本——升级 Vikunja 后若启动异常，可用此命令核对迁移是否完整执行。migrate rollback 用于回退，属于危险操作，执行前务必备份。
六、备份恢复类：dump 与 restore
6.1 vikunja dump：全量备份
将配置、数据库全部表数据与附件打包为一个 zip：
vikunja dump -p /tmp -f mydump
参数：-p/--path 指定输出目录（默认 rootpath 或二进制所在目录）；-f/--filename 指定文件名（自动补 .zip 后缀，默认 vikunja-dump_YYYY-MM-DD_HH-II-SS.zip）。
回显（末尾）：
time=2026-10-25T02:18:45.788Z level=INFO msg="Dumped files"
time=2026-10-25T02:18:45.788Z level=INFO msg="Done creating dump"
time=2026-10-25T02:18:45.788Z level=INFO msg="Dump file saved at /tmp/mydump.zip"
生成的文件（权限 0600，仅属主可读）：
-rw------- 1 root root 11K Oct 25 02:18 /tmp/mydump.zip
dump 包内部结构（截取）：
Archive: /tmp/mydump.zip
Length Date Time Name
--------- ---------- ----- ----
324 2026-10-25 01:39 config.yml
6 1980-00-00 00:00 VERSION
2 1980-00-00 00:00 database/reactions.json
2 1980-00-00 00:00 database/migration_status.json
428 1980-00-00 00:00 database/tasks.json
2200 1980-00-00 00:00 database/users.json
1071 1980-00-00 00:00 database/projects.json
...
包内为 config.yml、VERSION 与 database/ 目录下逐表的 JSON 导出（附件存储在 files/ 目录一并打包）。这种格式与数据库类型无关，因此 dump/restore 也可用于跨数据库后端迁移（如 SQLite 迁往 PostgreSQL）。
建议把 dump 纳入定时任务，例如每日凌晨备份到独立目录再同步到异地存储。
6.2 vikunja restore：从备份恢复
Usage:
vikunja restore [filename] [flags]
Flags:
-h, --help help for restore
--preserve-config Preserve existing configuration instead of restoring from dump
--preserve-config 保留现有配置不覆盖，适合迁移到新环境（域名、数据库连接已变化）的场景。恢复是覆盖性操作，执行前确认目标库数据可被丢弃。
七、数据修复类：vikunja repair
repair 用于修复数据一致性问题，共 5 个子命令：
Available Commands:
attachment-previews Remove legacy attachment previews from the keyvalue store
file-mime-types Detect and set MIME types for all files that have none
orphan-positions Remove orphaned task position records for deleted tasks or views
projects Repair orphaned projects whose parent project no longer exists
task-positions Detect and repair duplicate task positions across all views
以 task-positions（检测并修复各视图中重复的任务位置）为例，支持 --dry-run 只检测不修改：
vikunja repair task-positions --dry-run
回显（末尾）：
time=2026-10-25T02:18:46.031Z level=INFO msg=" Views scanned: 4"
time=2026-10-25T02:18:46.031Z level=INFO msg=" Views repaired: 0"
time=2026-10-25T02:18:46.031Z level=INFO msg=" Tasks affected: 0"
time=2026-10-25T02:18:46.031Z level=INFO msg="No position conflicts found - all views are healthy!"
健康实例报告 No position conflicts found。一般仅在升级后官方 changelog 提示或数据异常时按需执行，日常无需运行；先 --dry-run 确认影响面再去掉该标志执行修复，是安全姿势。
八、辅助类
8.1 vikunja testmail：测试邮件配置
配置 mailer 段后验证 SMTP 连通性：
vikunja testmail admin@quzuo.local
未配置 mailer 时的回显（末尾）：
time=2026-10-25T02:16:57.916Z level=INFO msg="Sending testmail..."
time=2026-10-25T02:16:57.916Z level=ERROR msg="Error sending test mail: mailer is not configured! Please see the config docs for more details"
配置正确时会向指定邮箱投递测试邮件，排查 SMTP 问题时配合 log.mail: stdout 观察明细。
8.2 vikunja completion：Shell 自动补全
为 bash/zsh/fish/powershell 生成补全脚本，例如 bash：
vikunja completion bash > /etc/bash_completion.d/vikunja
8.3 vikunja help
等同于 --help，vikunja help <命令> 或 vikunja <命令> --help 可查看任意子命令用法。
九、典型运维场景串联
场景 1：每日自动备份——crontab 中加入：
0 3 * * * root /usr/bin/vikunja dump -p /backup/vikunja -f daily >> /var/log/vikunja-backup.log 2>&1
场景 2：管理员密码丢失——在部署主机执行：
vikunja user list
vikunja user reset-password --direct -p '新的强口令' admin
场景 3：版本升级——完整流程为 vikunja dump 备份 → 停服务 → 替换二进制 → systemctl start vikunja（启动时自动执行迁移）→ vikunja doctor 体检 → vikunja migrate list 核对迁移。
场景 4：故障排查起点——服务异常时按 vikunja doctor（定位配置/数据库/存储问题）→ journalctl -u vikunja（运行日志）→ vikunja testmail（邮件链路）的顺序排查。
十、参考链接
- Vikunja 官方 CLI 文档：https://vikunja.io/docs/cli/
- Vikunja 备份恢复文档：https://vikunja.io/docs/backup/
- v2.7.1 发行说明：https://github.com/go-vikunja/vikunja/releases/tag/v2.7.1