Deluge 2.2.0 常用 CLI 命令与工具详解

目标：系统讲解 Deluge 2.2.0 命令行工具链——deluged 守护进程、deluge-web 服务与 deluge-console 客户端的连接方式、全部子命令的语法与真实回显，以及 systemd 托管的服务管理方法。已在 Ubuntu 22.04（x86_64）上实测通过，deluge-console/deluged/deluge-web 均为 2.2.0。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
软件版本：Deluge 2.2.0（官方最新稳定版）、libtorrent 2.0.13.0
架构形态：deluged 守护进程承载下载核心，deluge-console 从本机经 RPC（默认端口 58846）连接管理
守护进程配置目录：/var/lib/deluge/.config/deluge/（systemd 专用用户 deluge 的家目录；root 直装时为 /root/.config/deluge/）
认证凭据：守护进程 RPC 账号文件 /var/lib/deluge/.config/deluge/auth，首启自动生成 localclient 账号（10 级管理员权限）
实测示例种子：Debian 13.7.0 官方网络安装镜像种子（已完成下载并做种）

二、工具概览

工具	角色	典型用法
`deluged`	守护进程（核心）	常驻运行，承载 BT 引擎与 RPC 服务（58846）
`deluge-web`	Web 界面服务	独立进程，浏览器经 8112 端口管理
`deluge-console`	终端客户端	交互式 curses 界面与一次性命令两种模式

三者关系：console 与 web 都是守护进程的「遥控器」，关闭它们不影响下载；守护进程才是任务引擎。命令行管理的核心是把 deluge-console 用熟，它支持全部子命令且可脚本化。

三、前置条件

守护进程已运行并监听 RPC 端口（验证方式见本篇第七章）；
已安装 deluge-console（发行版包随 deluge 一同提供）；
已知 localclient 账号口令——守护进程首次启动时随机生成，存于认证文件（实测本环境的 auth 文件内容，格式为 账号:口令:权限级别）：

localclient:e876e4ca92f9f08b3ee5cab5e590bbd84d1210ec:10

💡 说明：auth 文件中口令为首次启动随机生成的 40 位十六进制串，每台机器不同，以你自己的 auth 文件为准。下文所有命令中的 e876e4ca92f9f08b3ee5cab5e590bbd84d1210ec 均需替换为你机器上的实际值（cat /var/lib/deluge/.config/deluge/auth 查看）。

四、deluge-console 连接与基础语法

4.1 两种使用模式

交互模式：直接执行 deluge-console 进入 curses 全屏界面，底部命令行输入子命令，适合人工操作。

一次性模式：deluge-console [连接参数] "<子命令>"，执行后输出结果并退出，适合脚本与远程批量管理。连接参数通过命令行选项给出（实测确认的完整选项表，来自 deluge-console -h 回显节选）：

usage: deluge-console [-h] [-V] [-c <config>] [-l <logfile>] [-L <level>]
                      [--logrotate [<max-size>]] [-q] [--profile [<profile-file>]]
                      [-d <ip_addr>] [-p <port>] [-U <user>] [-P <pass>]
                      Command ...

选项	说明
`-d <ip_addr>`	守护进程地址
`-p <port>`	RPC 端口（默认 58846）
`-U <user>`	用户名（localclient 或其他 auth 账号）
`-P <pass>`	口令
`-q`	安静模式
`-L <level>`	日志级别

⚠️ 注意：用户名选项是大写 -U。实测误用小写 -u localclient 时被解析为未知参数，报 invalid choice: 'localclient'（把用户名当成了子命令）：

usage: deluge-console [-h] [-V] [-c <config>] [-l <logfile>] [-L <level>]
                      [--logrotate [<max-size>]] [-q] [--profile [<profile-file>]]
                      [-d <ip_addr>] [-p <port>] [-U <user>] [-P <pass>]
                      Command ...
deluge-console: error: argument Command: invalid choice: 'localclient' (choose from add, cache, config, connect, debug, del, exit, gui, halt, help, info, manage, move, pause, plugin, quit, reannounce, recheck, resume, rm, status, update_tracker)

4.2 全量子命令清单

deluge-console [连接参数] "help"（实测回显，一次性模式）：

add       - Add torrents
     usage: add [-h] [-p PATH] [-m MOVE_COMPLETED_PATH]  <torrent> [<torrent> ...]
cache     - Show information about the disk cache
     usage: cache [-h]
config    - Show and set configuration values
     usage: Usage: config [--set <key> <value>] [<key> [<key>...] ]
connect   - Connect to a new deluge server
     usage: Usage: connect <host[:port]> [<username>] [<password>]
debug     - Enable and disable debugging
     usage: debug [-h]  <on|off>
gui       - Enable interactive mode
     usage: gui [-h]
halt      - Shutdown the deluge server.
     usage: halt [-h]
help      - Displays help on other commands
     usage: help [-h]  [<command> ...]
info      - Show information about the torrents
     usage: info [-h] [-v] [-d] [-s STATE] [--sort SORT] [--sort-reverse SORT_REV]
            [<torrent-id> ...]
manage    - Show and manage per-torrent options
     usage: Usage: manage <torrent-id> [--set <key> <value>] [<key> [<key>...] ]
move      - Move torrents' storage location
     usage: move [-h]  <torrent-id> [<torrent-id> ...] <path>
pause     - Pause torrents
     usage: pause [ * | <torrent-id> [<torrent-id> ...] ]
plugin    - Manage plugins
     usage: plugin [-h] [-l] [-s] [-e ENABLE [ENABLE ...]]
              [-d DISABLE [DISABLE ...]] [-r] [-i INSTALL]
quit/exit - Exit the client
     usage: quit/exit [-h]
recheck   - Forces a recheck of the torrent data
     usage: recheck [ * | <torrent-id> [<torrent-id> ...] ]
resume    - Resume torrents
     usage: Usage: resume [ * | <torrent-id> [<torrent-id> ...] ]
rm/del    - Remove a torrent
     usage: rm/del [-h] [--remove_data] [-c]  <torrent-id> [<torrent-id> ...]
status    - Shows various status information from the daemon
     usage: status [-h] [-r] [-n]
update_tracker/reannounce - Update tracker for torrent(s)
     usage: update_tracker [ * | <torrent-id> [<torrent-id> ...] ]


For help on a specific command, use `<command> --help`

4.3 子命令详情查看

help <命令> 输出该命令的完整参数说明。以 info 为例（实测回显）：

usage: info [-h] [-v] [-d] [-s STATE] [--sort SORT] [--sort-reverse SORT_REV]
            [<torrent-id> ...]

Show information about the torrents

positional arguments:

  <torrent-id>          One or more torrent ids. If none is given, list all

options:
  -h, --help            show this help message and exit
  -v, --verbose         Show more information per torrent.
  -d, --detailed        Show more detailed information including files and
                        peers.
  -s STATE, --state STATE
                        Show torrents with state STATE: Active, Allocating,
                        Checking, Downloading, Seeding, Paused, Error, Queued,
                        Moving.
  --sort SORT           sort items. Possible keys: state, download_location,
                        tracker_host, tracker_status, next_announce, name,
                        total_size, progress, num_seeds, total_seeds,
                        num_peers, total_peers, eta, download_payload_rate,
                        upload_payload_rate, ratio, distributed_copies,
                        num_pieces, piece_length, total_done, files,
                        file_priorities, file_progress, peers, is_seed,
                        is_finished, active_time, seeding_time,
                        time_since_transfer, last_seen_complete, seed_rank,
                        all_time_download, total_uploaded,
                        total_payload_download, total_payload_upload,
                        time_added, label
  --sort-reverse SORT_REV
                        Same as --sort but items are in reverse order.

  You can give the first few characters of a torrent-id to identify the torrent.

要点：<torrent-id> 支持只给 infohash 前几位（如 7acf8fb5）即可定位任务。

五、核心子命令详解（附实测回显）

以下命令均以一次性模式执行，连接参数统一省写为 [连接参数]（即 -d 127.0.0.1 -p 58846 -U localclient -P <你的口令>）。

5.1 status：会话总览

deluge-console [连接参数] "status"

Total upload: 0.0 KiB/s
Total download: 0.0 KiB/s
DHT Nodes: 343
Total torrents: 1
 Allocating: 0
 Checking: 0
 Downloading: 0
 Seeding: 1
 Paused: 0
 Error: 0
 Queued: 0
 Moving: 0

-r（raw）输出不带 KiB/s 单位的原始速率，便于脚本解析（实测回显首行 Total upload: 0.000000）；
-n 跳过任务明细，只取会话级统计，速度更快。

5.2 info：任务列表

基础视图（实测回显，两任务场景）：

deluge-console [连接参数] "info"

[S]   100% debian-13.7.0-amd64-netinst.iso 7acf8fb590b2060dd9c3146ef770169d593433b0
    DL: 771.9 M (771.9 M) UL: 0 B (0 B) ETA: -

[D]  0.59% ubuntu-24.04.3-desktop-amd64.iso d160b8d8ea35a5b4e52837468fc8f03d55cef1f7
    DL: 34.0 M (35.7 M) @ 2.5 M/s UL: 0 B (0 B) ETA: 40m 51s

行首状态标记：[D] 下载中、[S] 做种中、[P] 已暂停、[E] 出错、[C] 校验中、[Q] 排队、[A] 分配中、[M] 迁移中。

详细视图 -v（实测回显）：

deluge-console [连接参数] "info -v 7acf8fb5"

Name: debian-13.7.0-amd64-netinst.iso
ID: 7acf8fb590b2060dd9c3146ef770169d593433b0
State: Seeding Up Speed: 0.0 K/s
Seeds: 1 (1018) Peers: 6 (4) Availability: 0.00 Seed Rank: 1342177k
Size: 756.0 M Downloaded: 771.9 M Uploaded: 0 B Share Ratio: 0.00
ETA: - Seeding: 5m 53s Active: 7m 1s
Last Transfer: 5m 53s Complete Seen: 10/30/26
Tracker: debian.org
Tracker status: Announce OK
Download Folder: /downloads

Seeds: 1 (1018) 表示已连接 1 个、全网做种 1018 个；Tracker status: Announce OK 说明 Tracker 汇报正常。

状态过滤 -s 与排序 --sort：info --sort name、info -s Seeding 等按参数过滤排序。

5.3 add：添加任务

deluge-console [连接参数] "add /downloads/debian-13.7.0-amd64-netinst.iso.torrent"

Attempting to add torrent: /downloads/debian-13.7.0-amd64-netinst.iso.torrent
Torrent added!

<torrent> 接受本地种子文件路径、URL 与磁力链（magnet:?xt=...）；-p PATH 为该任务指定下载目录，-m PATH 指定完成后迁移目录。

5.4 pause / resume：暂停与恢复

deluge-console [连接参数] "pause d160b8d8ea35a5b4e52837468fc8f03d55cef1f7"
deluge-console [连接参数] "info"

[P]   100% ubuntu-24.04.3-desktop-amd64.iso d160b8d8ea35a5b4e52837468fc8f03d55cef1f7
    DL: 5.9 G (5.9 G) UL: 0 B (0 B) ETA: -

实测要点：

一次性模式下 pause/resume 本身不打印回显，用 info 的状态标记确认生效（[P] 为已暂停）；
恢复：resume <id>（或 resume * 恢复全部），再用 info 确认标记回到 [D]/[S]；
交互模式下执行会直接在界面打印结果。

5.5 rm / del：删除任务（两步确认制）

第一步列出匹配任务（实测回显）：

deluge-console [连接参数] "rm d160b8d8ea35a5b4e52837468fc8f03d55cef1f7 --remove_data"

1 torrent match
* ubuntu-24.04.3-desktop-amd64.iso                   (d160b8d8ea35a5b4e52837468fc8f03d55cef1f7)
Confirm with -c to remove the listed torrents (Count: 1)

第二步追加 -c 确认执行（实测回显为空，用 info 验证）：

deluge-console [连接参数] "rm d160b8d8ea35a5b4e52837468fc8f03d55cef1f7 --remove_data -c"
deluge-console [连接参数] "info"

[S]   100% debian-13.7.0-amd64-netinst.iso 7acf8fb590b2060dd9c3146ef770169d593433b0
    DL: 771.9 M (771.9 M) UL: 0 B (0 B) ETA: -

实测确认：任务从列表消失，--remove_data 同时删除了已下载数据文件（5.9GB 的 ISO 从磁盘移除），但最初加入的 .torrent 源文件不受影响。不加 --remove_data 则只移除任务记录、保留数据。

5.6 config：查看与修改全局配置

查指定键（实测回显，多键可并列）：

deluge-console [连接参数] "config download_location listen_ports max_connections_global max_download_speed max_upload_slots_global dht"

dht: True
download_location: /downloads
listen_ports: (6881, 6891)
max_connections_global: 200
max_download_speed: -1.0
max_upload_slots_global: 4
max_upload_speed: -1.0

改值并回验（实测回显）：

deluge-console [连接参数] "config -s max_download_speed 2048"

Setting "max_download_speed" to: 2048.0
Configuration value successfully updated.

deluge-console [连接参数] "config max_download_speed"

max_download_speed: 2048.0

config 是脚本化改配置的首选（改内存态并由守护进程落盘），比手改 core.conf 更安全——手改文件必须先停守护进程，否则会被内存态覆盖。全部键的含义见《Deluge 2.2.0 配置参数详解》篇。

⚠️ 注意：实测发现不带任何键执行 config 会直接报参数错误，必须至少给一个键名：
usage: Usage: config [--set <key> <value>] [<key> [<key>...] ]
config: error: the following arguments are required: <value>

5.7 manage：每任务独立选项

manage <id> <键> [<键>...] 查看、manage <id> -s <键> <值> 修改（可查键与 config 类似，如 max_download_speed、auto_managed、move_completed 等）。

⚠️ 注意：2.2.0 实测一次性模式下 manage 查询长时间无输出（疑似缺陷），建议进交互模式执行：deluge-console → connect ... → manage <id> max_download_speed。

5.8 plugin：插件管理

列出可用插件（实测回显）：

deluge-console [连接参数] "plugin -l"

Available Plugins:
  AutoAdd
  Blocklist
  Execute
  Extractor
  Label
  Notifications
  Scheduler
  Stats
  Toggle
  WebUi

启用/查看/停用（实测回显）：

deluge-console [连接参数] "plugin -e Label"     # 启用 Label 插件（一次性模式无回显）
deluge-console [连接参数] "plugin -s"

Enabled Plugins:
  Label

deluge-console [连接参数] "plugin -d Label"     # 停用（同样以 plugin -s 验证）

5.9 cache：磁盘缓存统计

deluge-console [连接参数] "cache"

disk.disk_blocks_in_use: 0
disk.num_blocks_read: 48282
disk.num_blocks_written: 48612
disk.num_read_ops: 48282
disk.num_write_ops: 48612
read_hit_ratio: 0.0
write_hit_ratio: 0.0

适合在调大 cache_size 前后对比命中率（见《Deluge 2.2.0 配置参数详解》篇缓存小节）。

5.10 recheck：强制校验

deluge-console [连接参数] "recheck 7acf8fb5"

一次性模式无回显；执行期间 info 中状态短暂变为 [C]（Checking），校验通过后回到 [S] 且进度 100%（实测校验完成后回显 [S] 100% ...）。recheck * 校验全部任务。

5.11 halt：关闭守护进程

deluge-console [连接参数] "halt"

Daemon was shutdown

守护进程随即退出。若由 systemd 托管且未配置自动重启策略（官方单元为 Restart=on-failure，主动 shutdown 属正常退出不会拉起），需手动 systemctl start deluged 恢复。

5.12 其余子命令速查

命令	语法（help 回显原文）	用途
move	`move [-h] <torrent-id> [...] <path>`	迁移任务存储目录
update_tracker / reannounce	`update_tracker [ * \| <torrent-id> [...] ]`	立即向 Tracker 汇报
debug	`debug [-h] <on\|off>`	开关调试日志
gui	`gui [-h]`	进入交互模式
connect	`connect <host[:port]> [<username>] [<password>]`	交互模式内连接守护进程
quit/exit	`quit/exit [-h]`	退出客户端（不影响守护进程）

六、注意事项

一次性模式与交互模式的能力差异：2.2.0 实测确认三类差异——① connect 作为一次性首命令会触发缺陷崩溃；② info -s、info -d、manage 在一次性模式无输出或报错；③ pause/resume/plugin -e 一次性模式无回显。人工操作建议交互模式，脚本建议只用实测可靠的组合（info/status/config/add/rm/cache/help）。

connect 一次性命令缺陷实录：执行 deluge-console "connect 127.0.0.1:58846 localclient <口令>" 实测崩溃，回显（节选）：

15:11:01 [ERROR   ][deluge.component                                      :132 ] [Failure instance: Traceback: <class 'AttributeError'>: 'ConsoleUI' object has no attribute 'started_deferred'
/lsiopy/lib/python3.12/site-packages/twisted/internet/defer.py:1838:_inlineCallbacks
/lsiopy/lib/python3.12/site-packages/deluge/ui/console/main.py:367:start
]

规避方式：改用命令行选项连接（-d/-p/-U/-P），一次性命令里只放业务子命令。该缺陷源于一次性模式下连接回调先于控制台组件初始化执行。

info -s 缺陷实录：一次性模式 info -s Downloading 实测报错：

 'dict' object has no attribute 'state'
15:16:01 [ERROR   ][deluge.ui.console.cmdline.command                     :135 ] 'dict' object has no attribute 'state'

状态过滤请改用 info -v 人工辨认状态标记，或在交互模式中过滤。

启动时的 pkg_resources 告警：一次性命令执行时 stderr 会带一条 UserWarning: pkg_resources is deprecated as an API...，属 Python 3.12 下的第三方告警，不影响命令结果，脚本中可忽略或按行过滤。
两套账号体系：deluge-console 走 auth 文件的 localclient/自定义账号；deluge-web 的界面密码独立存于 web.conf（默认 deluge）。二者不通用。
改配置优先用 config -s：守护进程持有配置内存态，直接编辑 core.conf 而不停机改写会被覆盖。

七、deluged 服务管理（systemd 托管）

7.1 官方服务单元

按官方文档（deluge.readthedocs.io/en/latest/how-to/systemd-service.html，查询日期 2026-10-30）创建专用系统用户：

sudo adduser --system --gecos "Deluge Service" --disabled-password --group --home /var/lib/deluge deluge

守护进程单元 /etc/systemd/system/deluged.service（官方原文）：

[Unit]
Description=Deluge Bittorrent Client Daemon
Documentation=man:deluged
After=network-online.target

[Service]
Type=simple
UMask=007
ExecStart=/usr/bin/deluged -d
Restart=on-failure
# Time to wait before forcefully stopped.
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Web 界面单元 /etc/systemd/system/deluge-web.service（官方原文，依赖守护进程单元）：

[Unit]
Description=Deluge Bittorrent Client Web Interface
Documentation=man:deluge-web
After=deluged.service
Wants=deluged.service

[Service]
Type=simple
UMask=027
ExecStart=/usr/bin/deluge-web -d
Restart=on-failure

[Install]
WantedBy=multi-user.target

以 deluge 用户运行的覆盖配置：创建 /etc/systemd/system/deluged.service.d/user.conf（deluge-web 同理）：

[Service]
User=deluge
Group=deluge

7.2 启停与开机自启（每行仅操作一个单元）

sudo systemctl daemon-reload
sudo systemctl enable /etc/systemd/system/deluged.service
sudo systemctl start deluged
sudo systemctl status deluged
sudo systemctl enable /etc/systemd/system/deluge-web.service
sudo systemctl start deluge-web
sudo systemctl status deluge-web

验证守护进程监听（真实服务器上的预期输出形态）：

ss -ltn | grep 58846

LISTEN 0      50       0.0.0.0:58846       0.0.0.0:*

修改单元文件后按官方要求先 stop 再 start（deluged 不支持单纯 restart 生效的 umask 变更）：

sudo systemctl stop deluged
sudo systemctl start deluged

7.3 日志托管

官方做法：建日志目录并授予权限，然后在 ExecStart 追加 -l（日志文件）与 -L（级别）参数：

sudo mkdir -p /var/log/deluge
sudo chown -R deluge:deluge /var/log/deluge
sudo chmod -R 750 /var/log/deluge

ExecStart=/usr/bin/deluged -d -l /var/log/deluge/daemon.log -L warning

ExecStart=/usr/bin/deluge-web -d -l /var/log/deluge/web.log -L warning

改完 sudo systemctl daemon-reload 后按 7.2 方式重启单元；官方支持在 ExecStart 追加 --logrotate 启用内置轮转。

7.4 UMask 与下载文件权限

deluged 单元的 UMask 决定下载文件的默认权限（官方说明）：007 仅属主/属组可读写（默认）、002 其他用户只读、022 其他用户只读且属组无权、000 全开放。做种目录如需给其他服务（如 Web 服务器）读权限，改 002。

7.5 依赖挂载点的启动条件（可选）

下载盘为 USB/网络存储时，官方建议在 [Unit] 段加挂载依赖（以 media-xyz.mount 为例，单元名可用 systemctl -t mount 实查）：

[Unit]
Description=Deluge Bittorrent Client Daemon
After=network-online.target xyz.mount
Requires=xyz.mount
BindsTo=xyz.mount

BindsTo 保证挂载点断开时 deluged 一并停止，防止下载写入到未挂载目录。

八、常见问题

Q1：deluge-console 连接报 Could not connect to daemon: 127.0.0.1:58846？ 分三种：守护进程未启动（systemctl status deluged 检查）；端口不符（core.conf 的 daemon_port）；口令错误（见 Q2）。

Q2：连接报 Password does not match？ 用的是 auth 文件里 localclient 行的口令吗？注意不是 Web UI 密码。以 cat /var/lib/deluge/.config/deluge/auth 的第二段为准；实测不带 -U/-P 直接运行时 console 会用 hostlist 里存的凭据自动连接，凭据不匹配即报此错。

Q3：想给远程管理加账号？ auth 文件一行一账号（用户名:口令:级别，级别 10 为管理员、5 为普通）。改完需重启 deluged 生效；远程连接还需 core.conf 的 allow_remote 设为 True（config -s allow_remote True）并放行 58846 端口。

Q4：脚本里怎么可靠地拿到输出？ 用一次性模式的可靠组合：status -r（原始速率）、info、config <键>；输出解析按空格/冒号分列。暂停/恢复等无回显操作，执行后用 info 状态标记断言。

Q5：交互模式界面显示异常？ 终端窗口至少需约 80×24，SSH 会话建议全屏；gui 子命令可从任何状态回到交互界面。

九、参考链接

Deluge 官方文档站：https://deluge.readthedocs.io/
官方 systemd 服务指南：https://deluge.readthedocs.io/en/latest/how-to/systemd-service.html
官方 Changelog（2.2.0）：https://deluge.readthedocs.io/en/latest/changelog.html
本专栏系列：《Deluge 介绍与选型指南》（https://www.quzuo.net/document/s8y3AQ7QBBDF）、《Deluge 2.2.0 Docker Compose 部署指南》（https://www.quzuo.net/document/oJe1CN3VNd1z）、《Deluge 2.2.0 配置参数详解》（https://www.quzuo.net/document/BrkkAMDvRpiD）。