Spug v4.1.1 常用 CLI 命令详解

目标：把 Spug v4.1.1 服务内的命令行运维操作一次讲全——管理命令入口、账户管理（创建/重置/启用/关闭 MFA）、数据库初始化与升级、后台进程管理，以及忘记管理员密码的完整恢复流程。本文全部命令与输出均在 2026-10-25 于按《Spug v4.1.1 Docker Compose 部署指南》部署的 v4.1.1 实例上实测取得（配置体系见《Spug v4.1.1 配置参数详解》）；输出为逐字照抄，仅过滤了每条命令固定出现的两条 paramiko CryptographyDeprecationWarning 弃用提示。

一、环境信息

项目	实测值
部署形态	官方 Compose 编排（Spug 应用 + MariaDB 10.11），宿主端口 8128
Spug 版本	v4.1.1
程序目录	/data/spug（数据卷内）；后端源码目录 /data/spug/spug_api
Python	3.11.17（镜像内置）
示例账号	admin（首启随机密码，后重置为 q1w2e3r4）、root（本文实测用 user add 创建）
实测日期	2026-10-25

二、软件介绍

Spug 是面向中小企业的轻量级无 Agent 自动化运维平台。多数日常操作在 Web 界面完成，但账号恢复、密码重置、MFA 关闭、数据库结构升级、后台进程管理等运维动作需要命令行完成；此外排查任务卡顿时也离不开服务内命令。Spug 的 CLI 是标准 Django 管理命令体系（manage.py）+ supervisor 进程管理两组入口，本文逐一实测。

三、命令基础：两个执行入口

入口一：Django 管理命令（manage.py），在服务内后端源码目录执行：

docker exec spug-4.1.1-app sh -c 'cd /data/spug/spug_api && python3 manage.py <命令>'

全部可用子命令清单（python3 manage.py help 实测，按命名空间分组）：

[account]
    set
    update
    updatedb
    user

[daphne]
    runserver

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    optimizemigration
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver

[exec]
    runworker

[monitor]
    runmonitor

[schedule]
    runscheduler

其中业务命令只有 7 个：set、update、updatedb、user（账户与系统运维），runworker、runmonitor、runscheduler（三个常驻后台任务进程）；其余为 Django 内置命令（数据库检查、数据导出等辅助用途）。

入口二：进程管理（supervisorctl），全部 7 个服务进程由 supervisor 托管：

docker exec spug-4.1.1-app supervisorctl <status|restart|start|stop> <程序名>

⚠️ 不要脱离 supervisor 手动执行 runworker/runmonitor/runscheduler：它们是常驻消费进程，手动多开会重复消费同一队列（任务重复执行）。

四、核心命令详解

4.1 user：账户管理（创建 / 重置密码 / 启用）

命令帮助（python3 manage.py help user 实测）：

        账户管理命令用法：
            user add    创建账户，例如：user add -u admin -p 123 -n 管理员 -s
            user reset  重置账户密码，例如：user reset -u admin -p 123
            user enable 启用被禁用的账户，例如：user enable -u admin

参数（user add --help 实测）：action 为 add/reset/enable 之一；-u 账户名、-p 密码、-n 昵称、-s 是否超级用户（默认否）。

创建超级管理员账号（实测，2026-10-25）：

$ python3 manage.py user add -u root -p q1w2e3r4 -n 超级管理员 -s
创建用户成功

立即用接口验证（注意登录请求必须带 type 字段）：

$ curl -s -X POST -H 'Content-Type: application/json' \
    -d '{"username":"root","password":"q1w2e3r4","type":"default"}' \
    http://127.0.0.1:8128/api/account/login/
{"data": {"id": 2, "access_token": "235bea2202b24b19b8f3562a12ccead0", "nickname": "超级管理员", "is_supper": true, ……}}

重置密码（实测）：

$ python3 manage.py user reset -u root -p q1w2e3r4
账户密码已重置

启用被禁用账户（实测，对已启用账户执行返回同一提示）：

$ python3 manage.py user enable -u root
账户已启用

报错回显（实测）：重复创建与目标不存在时给出中文提示、不会误操作：

已存在登录名为【root】的用户
未找到登录名为【nobody】的账户

4.2 set：系统设置（MFA 管理）

命令帮助（python3 manage.py help set 实测）：

        系统设置命令用法：
            set mfa disable     禁用登录MFA

关闭 MFA（实测）——管理员开了 MFA 但丢失验证器的场景，这是官方恢复通道：

$ python3 manage.py set mfa disable
MFA已禁用

4.3 updatedb：初始化/更新数据库

帮助描述「初始化/更新数据库」，幂等，可重复执行。升级版本或手动补迁移后执行（实测全文）：

$ python3 manage.py updatedb
No changes detected in apps 'credential', 'notify', 'host', 'monitor', 'config', 'pipeline', 'deploy', 'home', 'schedule', 'exec', 'alarm', 'repository', 'account', 'app', 'setting'
Operations to perform:
  Apply all migrations: account, alarm, app, config, credential, deploy, exec, home, host, monitor, notify, pipeline, repository, schedule, setting
Running migrations:
  No migrations to apply.
初始化/更新成功

首次启动时由启动脚本自动调用（建全部业务表），日常无需手动执行；编排部署升级（docker compose pull && up -d）后也会自动运行。

4.4 update：在线升级命令（交互式）

帮助描述「升级Spug版本」。执行时先向 api.spug.cc 查询最新版本：

有新版本：展示版本说明并询问 发现新版本 <版本号> 是否更新[y|n]？，答 y 后自动完成前端产物下载（cdn.spug.cc tar 包）→ 后端 git checkout 对应 tag → pip 安装依赖 → updatedb。
已是最新：询问是否做修复性更新。本文实测（当前 v4.1.1 即最新版，答 n 退出）：

$ echo n | python3 manage.py update
当前已是最新版本，是否要进行修复性更新[y|n]？

💡 升级口径选择：编排部署的推荐升级路径是部署篇的 docker compose pull && docker compose up -d（换镜像 + 随启动自动迁移）；update 命令面向不换镜像、在现有运行环境内拉取新代码的场景（源码安装或老镜像手动升级）。另有一个辅助脚本 tools/migrate.py，由启动脚本在版本变更时自动调用，负责旧版本（v3.x 时代）数据目录结构到新版的迁移。

4.5 supervisorctl：服务进程管理

7 个受管程序与状态（实测）：

$ supervisorctl status
nginx                            RUNNING   pid 25, uptime 0:09:49
redis                            RUNNING   pid 26, uptime 0:09:49
spug-api                         RUNNING   pid 27, uptime 0:09:49
spug-monitor                     RUNNING   pid 32, uptime 0:09:49
spug-scheduler                   RUNNING   pid 35, uptime 0:09:49
spug-worker                      RUNNING   pid 40, uptime 0:09:49
spug-ws                          RUNNING   pid 45, uptime 0:09:49

单个进程重启（实测后恢复正常）：

$ supervisorctl restart spug-api
spug-api: stopped
spug-api: started

排障建议顺序：改完配置或服务异常时，先 status 看哪个进程异常退出（supervisor 会自动拉起，反复退出的进程 uptime 会很小），再查 /data/spug/spug_api/logs/ 下对应日志（api.log / worker.log / scheduler.log / monitor.log / ws.log）。

4.6 Django 内置命令的实用三例（实测）

shell：命令行查询业务数据（本文用它核对新账号）：

$ python3 manage.py shell -c "from apps.account.models import User; [print(u.username, u.nickname, u.is_supper, u.is_active) for u in User.objects.all()]"
root 超级管理员 True True
admin 管理员 True True

showmigrations：核对迁移状态：

$ python3 manage.py showmigrations account
account
 [X] 0001_initial

dumpdata：导出业务数据（JSON 备份）（输出含密码哈希，已截断）：

$ python3 manage.py dumpdata account.User --indent 0
[{
"model": "account.user",
"pk": 1,
"fields": {
"username": "admin",
"nickname": "管理员",
"password_hash": "pbkdf2_sha256$……",
……

⚠️ dbshell 在官方镜像内不可用——实测报 CommandError: You appear not to have the 'mysql' program installed or on your path.（镜像未带 mysql 命令行客户端）。查库请改用 shell（ORM）或在数据库服务侧执行 mariadb 客户端。

五、实战示例

场景一：忘记管理员密码的完整恢复流程

重置密码：python3 manage.py user reset -u admin -p q1w2e3r4 → 账户密码已重置
若开启了 MFA 且验证器丢失：python3 manage.py set mfa disable → MFA已禁用
浏览器以 admin + 新密码登录，验证后到个人中心改回强密码。

场景二：为运维同事开账号并交接

$ python3 manage.py user add -u root -p q1w2e3r4 -n 超级管理员 -s   # 超管账号
创建用户成功
$ python3 manage.py shell -c "from apps.account.models import User; [print(u.username, u.is_supper) for u in User.objects.all()]"
root True
admin True

日常使用建议建非超级用户（去掉 -s），权限在 Web 端按角色分配；示例中的 root/admin + q1w2e3r4 仅为文档演示口径，生产环境必须替换。

场景三：升级后的命令巡检

$ docker compose pull && docker compose up -d          # 部署篇的升级口径
$ python3 manage.py updatedb                            # 确认库结构一致（幂等）
初始化/更新成功
$ supervisorctl status                                  # 7 个进程全部 RUNNING
$ curl -sI http://127.0.0.1:8128/ | head -n 1           # Web 入口恢复
HTTP/1.1 200 OK

六、FAQ

Q1：命令必须在容器里执行吗？格式太长了。 A：本文按编排形态如实给出 docker exec 前缀；也可先 docker exec -it spug-4.1.1-app bash 进入服务内部，再 cd /data/spug/spug_api && python3 manage.py <命令>，效果一致。

Q2：每条命令都输出 TripleDES 弃用警告，要处理吗？ A：paramiko 依赖的告警（上游问题），不影响任何功能，可忽略。

Q3：user add 创建的账号能直接登录吗？ A：能。实测 user add 成功后立即用该账号调登录接口返回了有效 access_token；注意登录请求体必须带 "type":"default" 字段，否则报 (1048, "Column 'type' cannot be null")（部署篇排障实录一）。

Q4：reset 重置的密码对正在登录的用户有影响吗？ A：立即生效，旧 token 不注销但新登录必须用新密码；敏感操作后建议 supervisorctl restart spug-api 收紧会话。

Q5：任务计划/监控/批量执行不跑，CLI 怎么查？ A：supervisorctl status 确认 spug-scheduler/spug-monitor/spug-worker 是否 RUNNING，再看对应日志文件；必要时 supervisorctl restart 单个进程恢复。

七、总结与参考链接

Spug 的 CLI 面小结：业务命令集中在 [account] 命名空间的 user/set/update/updatedb 四条（覆盖账号生命周期与升级），常驻进程交给 supervisor，数据检查用 Django 内置命令。记住一个目录（/data/spug/spug_api）、一个入口（manage.py）、一个进程管理器（supervisorctl），即可完成全部命令行运维。

参考链接：

部署篇（含登录接口实测与排障）：《Spug v4.1.1 Docker Compose 部署指南》
配置篇（目录常量与进程定义）：《Spug v4.1.1 配置参数详解》
官方文档：https://spug.cc/docs/about-spug/
GitHub 仓库：https://github.com/openspug/spug