CQELSVR 執行清單指南
介紹如何查詢在特定邏輯伺服器（LSSN）上註冊的 CQE（Custom Query Engine）指令碼排程，以及如何強制執行、切換啟用狀態、刪除和檢視指令碼。
📋 概述
CQELSVR 執行清單 用於查詢並直接控制註冊在某一邏輯伺服器（LSSN）上的 CQE 指令碼排程（tMgmtScriptList）。選擇伺服器後會顯示其已註冊的排程清單，您可以在每一列上立即執行強制執行、切換啟用狀態、刪除或檢視指令碼正文。
🔄 整體流程 (CQE Flow)
flowchart TD
A[管理者: CQERepoPut<br/>在倉庫中註冊指令碼] --> B[tMgmtScript<br/>指令碼儲存庫]
B --> C[管理者: CQEQueuePut<br/>向目標伺服器分配排程]
C --> D[tMgmtScriptList<br/>各LSSN的排程]
D --> E[代理程式: CQEQueueGet<br/>定期輪詢]
E --> F[tMgmtQue<br/>從執行佇列接收ms_body]
F --> G[代理程式: 本地執行<br/>指令碼]
G --> H[KVSPut<br/>報告結果]
style A fill:#e1f5fe
style B fill:#b3e5fc
style C fill:#e1f5fe
style D fill:#b3e5fc
style E fill:#e8f5e9
style F fill:#c8e6c9
style G fill:#fff9c4
style H fill:#ffccbc🔍 畫面組成
1. 選擇伺服器
- 輸入 LSSN: 在頂部輸入欄中直接輸入邏輯伺服器 ID（LSSN）。
- 選擇伺服器按鈕: 點擊後會彈出目前專案（csn）下已註冊的伺服器清單，選取後自動填入 LSSN 欄位。
- 工作階段記憶: 一旦選擇過的 LSSN 會儲存在瀏覽器 sessionStorage 中，重新整理頁面後仍會保留。
2. 查詢執行清單
- Run 按鈕: 輸入或選擇 LSSN 後點擊，即可在下方載入該伺服器的排程清單。
- 翻頁: 使用 Prev / Next 按鈕逐頁移動，也可以在 Offset 輸入欄中直接輸入數字並按 Run 跳轉到指定偏移量（伺服器每次最多回傳 25 筆）。
3. 逐列操作
清單中的每一列（一筆排程 = 一個 mslsn）支援：
- 強制執行: 無論排程週期為何，立即將其加入一次性執行佇列。若該排程已有排隊中的任務，則會失敗。
- 該操作的實質是向
tMgmtQue資料表中插入一筆執行記錄。代理程式會輪詢該佇列並取走記錄。 - 對於一次性（
repeat=1）排程，強制執行時active會降為 0。這只表示「下個週期不要再自動註冊該排程」，已經進入佇列的執行記錄仍會正常執行。 請勿把active=0誤解為執行已被取消。
- 該操作的實質是向
- 切換啟用: 切換該排程的 Active 狀態（開/關）。
- 刪除: 從清單中永久移除該排程（
mslsn）——這是硬刪除而非簡單取消，如需再次使用必須重新註冊。 - 檢視指令碼: 點擊列中的執行 ID（mssn）會在下方（或彈出視窗）面板中顯示該指令碼的正文。
4. 跳轉至詳情頁面
- Machine Detail 按鈕: 跳轉至所選 LSSN 的詳情頁面（
/lsvrdetail）。 - Add Queue 按鈕: 跳轉至
/zh-TW/cqeQueuePut頁面，為該伺服器註冊新的排程。開始日期的時區約定請參閱 CQE 佇列註冊指南。
📊 欄位說明
| 欄 | 說明 |
|---|---|
| msName | 已註冊指令碼的名稱 |
| mssn | 指令碼唯一 ID。點擊可檢視指令碼正文。 |
| mslsn | 該排程（伺服器-指令碼分配）的唯一 ID，是強制執行/切換啟用/刪除的操作對象。 |
| lssn | 該排程所註冊的邏輯伺服器 ID |
| active | 週期排程是否自動重新註冊（1=開啟/0=關閉）。即使該值為 0，也與已經進入佇列的執行記錄是否執行無關。對於一次性（repeat=1）排程，強制執行時該值降為 0 屬於正常現象。 |
| repeat | 是否/如何重複執行（1=一次性） |
| interval | 重複間隔（分鐘） |
| q_flag | 執行佇列等待中標記（1=正在 tMgmtQue 中等待）。代理程式取走佇列後會恢復為 0。 也就是說 q_flag=1 表示「尚未取走」，0 表示「已取走或無等待記錄」。 |
| lastdate | 最後一次執行（加入佇列）的時間。以 UTC 為基準儲存與顯示（與本機時間相差一個時區偏移屬於正常）。 |
| regdate | 該排程的註冊時間 |
執行後的狀態轉換
無論是強制執行還是週期執行，代理程式取走佇列後，各值會依下列方式變化：
| 對象 | 變化 |
|---|---|
tMgmtQue.send_flag | 變為 1（代理程式已接收） |
q_flag | 由 1 恢復為 0（等待記錄已消除） |
lastdate | 更新為執行（加入佇列）的時間 |
active | 不會自動恢復。 |
⚠️ 若希望一次性排程在強制執行後繼續週期重複，必須在執行結束後用［切換啟用］把
active重新開啟。 系統不會自動恢復。
⚙️ 需求
- 需要登入工作階段（CSN）——沒有工作階段則無法載入伺服器清單。
- 要查詢的 LSSN 必須已註冊在目前所選專案下。
- 強制執行/切換啟用需要您是該排程的擁有者，或擁有其他權限（如市集購買）。
API 參考
有關本功能的 API 詳細規格，請參閱專門指南。
疑難排解
| 症狀 | 原因 | 解決 |
|---|---|---|
| 伺服器選擇彈出視窗清單為空 | 目前所選專案（csn）下沒有已註冊的伺服器 | 確認已在頂部選擇正確的專案。 |
| 強制執行無反應地失敗 | 該排程已有排隊中的任務（防止重複執行），或您對該排程沒有權限 | 稍後重試，或向該排程的擁有者確認。 |
| 刪除後該列看起來仍在清單中 | 刪除已成功，但畫面尚未重新整理 | 再次按 Run 重新載入最新清單。 |
| 點擊刪除沒有任何反應，或悄悄失敗（例如別人註冊的排程） | 您不是該排程的擁有者，因此沒有刪除權限（RstVal=403） | 畫面現在會顯示錯誤提示（已在 giip 3042 中修復）。請查看提示訊息，如有需要請讓該排程的擁有者或更高權限的帳號執行刪除。 |
| 開啟啟用後並未立即執行 | 啟用只是恢復該排程的排程執行，並非立即執行 | 如需立即執行，請使用 強制執行。 |
| 強制執行後 q_flag=1 但 active=0，看起來不會執行 | 一次性排程在強制執行時 active 降為 0 屬於正常 | 保持原樣即可，會在代理程式的下次輪詢中執行。若之後還希望週期重複，請用［切換啟用］重新開啟。 |
| 佇列處於等待中（q_flag=1），但過了幾分鐘仍未被取走 | 若排程的 lastdate／開始日期被儲存為未來時間，它會在取用候選排序中被永久排到最後（把本機時間原樣儲存到 UTC 資料庫時會發生） | 檢查該排程的開始日期，若被設為未來則重新註冊。若反覆出現，請提交 giip 問題單回報。 |
🔌 CQE API（自動化）
上述介面操作對應以下 CQE API 動詞（byAK/bySk 分派器）。請求傳送 text（動詞+參數名）、jsondata（值）與 token——但清單查詢（CQELsvrRunList）是例外，其參數直接包含在 text 字串中傳送（不使用 jsondata）。
- CQELsvrRunList
lssn <lssn> <offset>— 查詢該 LSSN 上註冊的排程清單。伺服端一律從指定偏移量最多回傳 25 筆（固定，呼叫端無法調整）。回應欄位與上方「欄位說明」表一致。 - LSVRList
csn— 查詢該 csn（專案）下註冊的邏輯伺服器清單（用於伺服器選擇彈出視窗）。 - CQERunForce
mslsn— 無論排程週期為何，立即加入一次性執行佇列（tMgmtQue）。一次性（repeat=1）排程此時active會降為 0，但已加入的執行記錄仍會照常執行。回應RstVal：200=成功，300=無權限，302=已在佇列中（衝突），610=權限不足或燃料餘額不足。 - CQERunActvate
mslsn— 將該排程的active值在 1 與 0 之間切換。回應RstVal與 CQERunForce 相同體系（200/300/302/610）。 - CQEQueueDel
mslsn— 永久刪除該排程（非簡單取消，需要重新註冊）。回應RstVal：200=成功，403=無權限，404=找不到目標。 - CQERepoScript
mssn— 取得該指令碼（mssn）的正文（msBody）。
認證模型: 此頁面的 API 並非使用 giip-issue 技能的 x-api-key（SK）方式，而是使用登入工作階段的權杖方式，每次請求隨附 user_id + token。
相鄰功能（指令碼註冊/批次部署至伺服器）的完整規格: CQE 儲存庫指令碼管理指南的「🔌 CQE API（自動化）」一節，以及 giipdb
docs/30_Specs/CQE_SPECIFICATION.md。
版本: 1.3
最後更新: 2026-09-25
來源檔案: giipv3/public/help/cqelsvrRunList.zh-TW.md