pueue从 `0.4.0` 到 `0.5.0` 版本数据迁移

pueue从 0.4.0 到 0.5.0 版本数据迁移

pueue 从 0.3.0 升级到 0.4.0	pueue 从 0.4.0 升级到 0.5.0
https://huzhenghui.blog.csdn.net/article/details/106004623	本文

关于pueue

pueue是一个命令行任务管理工具，pueue并不是类似于 ps 的管理系统所有任务的管理工具，而是用于顺序和并行安排并执行长时间运行任务的工具，pueue可以管理这些任务的执行顺序，并跟踪这些长时间运行任务的状态和输出结果。

简而言之，pueue是一个 shell 命令队列的管理工具，名字pueue即来源于 queue 队列，更重要的是，有很多便利功能和抽象管理功能。

pueue以守护进程方式运行，因此并没有绑定到任何终端，因此可以在同一台计算机上的任何终端控制任务。即使关闭所有的 ssh 会话，队列仍旧被连续处理。

pueue主要的功能包括：

• 计划要执行的命令时可以指定命令执行的工作目录。通过 pueue status 可以查看每个命令的工作目录，在 0.5.0 中也可以在回调命令中获取工作目录。
• 可以方便的查看命令的输出内容。通过 pueue log 可以以日志的形式查看。在 0.4.0 及之前的版本可以使用 pueue show 查看运行中命令的输出，在 0.5.0 版本改为 pueue follow 查看运行中命令的输出。 pueue follow 该功能的使用方式详见后面章节
• 可以和正在运行的进程交互
• 当需要释放计算机的处理能力时，可以随时暂停/恢复任务
• 可以方便的操作已安排的任务顺序
• 可以同时并行运行多个任务，还可以指定希望同时并行运行的任务数
• 自 0.5.0 开始，可以对任务分组。每个组可以视为一个独立的任务队列，并且可以并行运行多个任务。这也是本文所涉及到的必要的数据迁移之一，详细的任务分组使用方式详见后面内容
• 自 0.5.0 开始，支持回调钩子。例如，设置桌面通知。详细的任务分组使用方式详见后面内容
• 所有功能支持 Linux 和 MacOS ， Windows 上支持部分功能

pueue 0.5.0 版本说明

pueue于2020年5月16日发布 0.5.0 版本，包括：

新特性

• 分组。现在可以将任务分配到组。每个组可以视为一个独立的任务队列，并且可以并行运行多个任务。这也是本文所涉及到的必要的数据迁移之一，详细的任务分组使用方式详见后面内容

• 用户可以指定自定义回调。当任务结束时即调用该回调函数。详细的任务分组使用方式详见后面内容

变化

• 运行期间和暂停期间都可以使用 log ，而之前在运行时只能使用 show ，因此这个变化使得 log 替代了 show 的部分功能。

• 相应的， show 改为 follow 。目前 follow 只用于跟踪一个单独命令的输出。 pueue follow 该功能的使用方式详见后面章节

改进

• 捕获环境变量。任务启动时将使用调用 pueue add 时的环境变量，而不是任务启动当时的环境变量。这也是本文所涉及到的必要的数据迁移之一
• follow （即为之前的 show ）在 read_local_logs 设置为 true 时，也直接从磁盘读取。
• --all 标记用于 kill 、 start 和 pause 时影响所有组和默认组。
• status 增加 --group 标记，用于输出指定组的任务。该功能的使用方式详见后面章节
• kill 增加 --default ，使用该标记将仅影响默认队列中的任务。

pueue 0.5.0 数据迁移

虽然pueue 0.5.0 版本说明中并没有直接阐述数据迁移问题，不过从 0.4.0 升级到 0.5.0 后需要迁移数据才能正常运行。需要迁移的状态文件在

~/.local/share/pueue/state.json

先停止守护进程

先停止pueue

pueue shutdown

完整关闭后将显示如下信息

Daemon is shutting down

备份pueue状态文件

使用当前版本号备份pueue状态文件

jq '' ~/.local/share/pueue/state.json | tee ~/.local/share/pueue/state.$(pueue -V | grep -o '[0-9.]\+').json

添加守护进程的分组 groups 字段

运行pueue。

pueued -vvv

如果看到如下报错

[ERROR] Failed to deserialize previous state log: Error("missing field `groups`", line: 15, column: 5)

说明状态文件中守护进程的设置缺少分组 groups 字段。该字段用于前述分组功能。该功能的使用方式详见后面章节

数据迁移方式为

jq '.settings.daemon.groups={}' ~/.local/share/pueue/state.0.4.0.json > ~/.local/share/pueue/state.json

该功能的使用方式详见后面章节

添加每个任务的环境变量 envs 字段

运行pueue。

pueued -vvv

如果看到如下报错

[ERROR] Failed to deserialize previous state log: Error("missing field `envs`", line: 34, column: 5)

说明状态文件中每个任务缺少环境变量 envs 字段。该字段用于前述捕获环境变量功能，此处设置的环境变量为空，具体添加时可以按需设置。

在前面脚本基础上增加数据迁移方式为

jq '.settings.daemon.groups={}' ~/.local/share/pueue/state.0.4.0.json |
	jq '.|(.tasks[].envs={})' > ~/.local/share/pueue/state.json

添加状态文件中的分组 groups 字段

运行pueue。

pueued -vvv

如果看到如下报错

[ERROR] Failed to deserialize previous state log: Error("missing field `groups`", line: 9211, column: 1)

说明状态文件中缺乏分组 groups 字段。该字段用于前述分组功能。

在前面脚本基础上增加数据迁移方式为

jq '.settings.daemon.groups={}' ~/.local/share/pueue/state.0.4.0.json |
	jq '.|(.tasks[].envs={})' |
	jq '.groups={}' > ~/.local/share/pueue/state.json

该功能的使用方式详见后面章节

pueue 0.5.0 新增的回调命令功能

回调命令是 0.5.0 新增的功能，需要直接修改配置文件，不同操作系统上配置文件位置不同，MacOS 上的配置文件位于：

~"/Library/Preferences/pueue.yml"

在修改前先备份。

yq read ~"/Library/Preferences/pueue.yml" | tee ~"/Library/Preferences/pueue.$(date).yml"

设置回调命令。

yq write --inplace ~"/Library/Preferences/pueue.yml" 'daemon.callback' "export command=\$(echo {{ command }}); osascript -e 'display notification (system attribute \"command\") with title \"Pueue {{group}} : {{ id }} : {{ result }}\" subtitle \"{{ path }}\"'"

该命令为 MacOS 上显示一条通知，不同操作系统上按需设置，配置文件中回调命令的位置为 daemon.callback，命令行设置时需要对嵌套的引号转义，因此该参数应使用双引号，这样设置后查看配置文件中的内容相同。

"export command=\$(echo {{ command }}); osascript -e 'display notification (system attribute \"command\") with title \"Pueue {{group}} : {{ id }} : {{ result }}\" subtitle \"{{ path }}\"'"

去掉转义的命令为：

export command=$(echo {{ command }});
osascript -e 'display notification (system attribute "command") with title "Pueue {{group}} : {{ id }} : {{ result }}" subtitle "{{ path }}"'

其中 {{ command }} 参数并没有像其他参数一样直接用于osascript脚本，而是先保存在环境变量中。

export command=$(echo {{ command }});

这是因为 {{ command }} 中可能包含各种可能的内容，直接拼接字符串可能导致转义字符带来的语法错误的情况。

第二行 osascript 命令为执行 OSA 脚本，参数 -e 表示接下来的字符串为要执行的脚本，脚本内容拆分成多行（仅为了阅读方便，不能执行）为：

display notification (system attribute "command")
  with title "Pueue {{group}} : {{ id }} : {{ result }}"
  subtitle "{{ path }}"

其中：

• display notification表示显示通知，右侧参数为通知的内容，(system attribute "command")表示从环境变量中获取command的值，借助变量传递字符串有助于减少拼接字符串可能导致转义字符带来的语法错误的情况
• with title表示设置标题，右侧参数为通知的标题
• subtitle表示设置副标题，右侧参数为通知的副标题

内容字符串中嵌套了pueue回调命令的参数，本例使用了全部已知参数。

参数	含义
{{ id }}	任务的序号
{{ command }}	任务的命令行。在使用时需要特别注意直接拼接字符串可能出现转义字符带来的语法错误的情况
{{ path }}	任务的路径
{{ result }}	任务的结果
{{ group }}	任务所在组别

再次强调，这种拼接字符串可能在某些参数包含转义字符时拼接出不符合预期的命令，对于比较复杂的处理应当仅使用 id，然后使用 pueue status --json 查询全部状态后解析出所需要的命令。后面的例子中给出了解决常见转义冲突的方法

pueue 0.5.0 新增的分组功能

创建组：

pueue group --add youtube-download

查询创建的组：

pueue group

输出为：

Group youtube-download (1 parallel), running: true

向组中添加任务：

pueue add --immediate --group youtube-download -- youtube-dl --output "'~/Downloads/YouTube/%(title)s.%(ext)s'" --restrict-filenames "https://www.youtube.com/watch?v=Ob4Nk6gz8Ec"

查询组中的任务：

pueue status --group youtube-download

输出为：

Group "youtube-download" (1 parallel): running
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Index   Status    Exitcode   Command                                                                                                                        Path                Start   End 
═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
 30185   Running              youtube-dl --output '~/Downloads/YouTube/%(title)s.%(ext)s' --restrict-filenames https://www.youtube.com/watch?v=Ob4Nk6gz8Ec   /Users/huzhenghui   15:49       
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 

使用改名后的 follow 查看：

pueue follow 30185

可以看到输出内容，而且可以看到进度数字在变化，这和直接执行的效果相同。而某些工具可能会每个数字显示一行刷屏。

[youtube] Ob4Nk6gz8Ec: Downloading webpage
[download] Destination: /Users/huzhenghui/Downloads/YouTube/Calvin_Harris_Dua_Lipa_-_One_Kiss_Live_on_The_Graham_Norton_Show.f137.mp4
[download]  22.1% of 104.81MiB at 101.47KiB/s ETA 13:4445

运行完成后，即可收到前面使用回调命令设置的通知，通知内容中正确处理了命令中复杂的转义字符。