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

運行完成後，即可收到前面使用回調命令設置的通知，通知內容中正確處理了命令中複雜的轉義字符。