IBM MQ 系統管理與 Java 開發教學手冊

文件版本:1.1 資訊確認日期:2026-10-03 IBM MQ 基準版本:IBM MQ 10.0(LTS,2026-06 GA);同時標示 9.3 / 9.4 的差異 Java 基準版本:**Java 25(LTS)**為主要範例環境,並標示 Java 17 / 21 差異 Spring Boot 基準版本:Spring Boot 4.x(Spring Framework 7.x、Jakarta EE 11)為主,並說明 3.x 差異 Java Messaging API:IBM MQ classes for Jakarta Messaging 3.0(新開發首選)、IBM MQ classes for JMS 2.0(維護既有系統)、IBM MQ classes for Java(功能凍結,僅維護) 適用對象:Java 開發人員、前後端工程師、SA、軟體架構師、IBM MQ 系統管理員、DevOps / DevSecOps、維運人員、PM / Technical PM、Legacy 維護人員、逆向工程人員、Framework 升級團隊、AI Coding Agent 使用者 文件狀態:版本資訊均對照 IBM 官方文件(IBM Documentation,IBM MQ 10.0.x)與 IBM 官方 GitHub(ibm-messaging)查證。查不到或可能隨修補版變動的資訊,一律標示「需依目前 IBM 官方文件確認」,不猜測、不補完。

版本查證摘要(2026-10-03)

以下為撰寫本手冊時,從 IBM 官方來源確認的關鍵事實。後續章節的版本相關描述皆以此為基準。

項目查證結果來源
IBM MQ 10.0.0 定位為 IBM MQ 9.4.0 之後的 LTS 版本,也是 9.4.5(9.4 最後一個 CD)之後的 CD 版本IBM Docs:What’s new and changed in IBM MQ 10.0.0
10.0 包含的功能包含 9.4.1~9.4.5 各 CD 版本累積的功能,再加上 10.0 新增功能同上
交付模型自 9.0 起採 LTS(長期穩定、只修缺陷與安全)與 CD(快速交付新功能)雙軌同上
Java API 種類三組:IBM MQ classes for Jakarta Messaging、IBM MQ classes for JMS、IBM MQ classes for JavaIBM Docs:IBM MQ Java language interfaces
IBM MQ classes for Java自 MQ 8.0 起功能凍結(Stabilized);仍完整支援,但不再新增功能同上
IBM MQ classes for JMS支援 JMS 2.0;官方建議僅用於維護與延伸既有 JMS 2.0 應用同上
IBM MQ classes for Jakarta Messaging自 MQ 9.3.0 起支援 Jakarta Messaging 3.0;官方建議為新開發首選同上
Java API 建置等級自 MQ 9.3 起三組 Java API 皆以 Java 8 建置,執行環境須為 Java 8 以上同上
10.0 安全性變更移除 SSLv3、TLS 1.0、RC4、3DES CipherSpec;RSA key exchange CipherSpec 列為 Deprecated;IBM Semeru Runtime 25 停用 TLS_RSA_*;新增最小 RSA 金鑰長度限制;User ID 驗證更嚴格並支援更長 User IDIBM Docs:What’s changed in IBM MQ 10.0.0
10.0 新增安全能力TLS 支援 FIPS 203 ML-KEM(抗量子)key share、多 certificate label、GSKit 9、dspmqcert 檢查憑證到期、HTTPS 取得 CCDT、JWKSIBM Docs:What’s new 10.0.0
10.0 HA 能力Native HA In-Region Replication(IRR)、Cross-Region Replication(CRR)、Native HA 詳細狀態檢視;Native HA 在 Linux(非容器)可用同上
Spring Boot Startercom.ibm.mq:mq-jms-spring-boot-starter v4.1.0 對應 MQ 10.0 與 Spring Boot 4.1.0;3.5.15 為 Spring Boot 3 最後一版;2.7.18 為 Spring Boot 2 最後一版GitHub:ibm-messaging/mq-jms-spring
Starter 預設行為未設定 spring.jms.listener.receiveTimeout 時,starter 會把 polling 逾時調為 30 秒;預設帳密已移除,須明確設定同上
Starter 新屬性JWT ibm.mq.tokenServer.*(由 Client 自動向 Token Server 取得 Token)、ccdtSslBundle / ccdtHttpsCertValPolicy(HTTPS CCDT)、balancing*(Uniform Cluster)、trace 屬性、additionalProperties;ibm.mq.jks.* 已標示 deprecated,改用 Spring SSL Bundle同上
IBM MQ Agent10.0 文件新增的獨立下載元件:容器化 AI Agent + MCP Server,可連最多 20 個 Queue Manager,只能查詢與推理、不能執行 MQSC;授權隨 IBM MQ Advanced 或 Cloud Pak for IntegrationIBM Docs:IBM MQ Agent
10.0 管理變更Native HA 詳細狀態檢視;可用程式(PCF)讀取 Error Log;變更 QM CCSID 可能需 force 選項;MQ Console 強化;RDQM 複寫連線可設 TLS(Advanced)IBM Docs:What’s new / changed 10.0.0
10.0 開發變更短生命週期 Java / JMS 容器的 trace;JMS Selector 可使用 MsgToken;多個 JMS 連線可視為單一應用實例;JWT endpoint;JMS keepalive 可自訂;Semeru 21 / 25 檔案編碼變更;Client 預設 TCP buffer 變更;.NET 10同上
10.0 其他變更憑證標籤含空白或逗號須跳脫;EKU 強化;MQIPT 移除 Java Security Manager 支援並調整 CipherSuite;Kafka Connect 與 Kafka Connect XML Converter(Advanced);z/OS 整合 OpenTelemetry tracing、OUTBUFF 上限提高、GB18030 最新標準同上

需依目前 IBM 官方文件確認的項目:com.ibm.mq.jakarta.client / com.ibm.mq.allclient 的確切修補版號(本手冊以 10.0.0.x 示意)、各平台詳細系統需求(OS / JDK / 容器平台版本矩陣)、Container image 的實際 tag、MQ Operator 版本對應、10.0 修補版(Fix Pack / CSU)內容。請以 System Requirements for IBM MQ 與 IBM MQ 10.0 Readme 為準。

修訂紀錄

版本日期修訂內容
1.02026-10-03初版:46 個 Part、32 個 AI Prompt、Quick Reference 與企業標準
1.12026-10-03依 IBM MQ 10.0 官方 Technical overview / Administering / Developing applications 逐章比對後補強:IBM MQ 物件全集、產品家族、官方文件對照表、MQI Client 與 CCDT、Exits 與 Installable Services、擴充元件(MFT / MQIPT / AMQP / MQTT / Multicast / Kafka Connect)、Streaming Queue、z/OS 架構與管理、Transaction 協調、Message Property 與 Selector、命令集比較、遠端管理、PCF、Administrative REST API、Console / Explorer、AMS、RACF、多語言支援、Messaging REST API、應用設計考量、10.0 Java / JMS 新能力、進階 JMS 2.0、MQ 與 Kafka 整合、IBM MQ Agent、SMF / OpenTelemetry、QSG 可用性;修正 JMS Delivery Delay 敘述;新增 P33、P34;重建目錄

關於本手冊

這份手冊要回答的問題

IBM MQ 的 API 不難學:MQCONN、MQOPEN、MQPUT、MQGET,一個下午就能寫出第一支 Producer。

真正困難的問題是:

一個同時維護十幾套 Legacy 系統、正在把 Spring Boot 3 升到 4、而且已經大量使用 GitHub Copilot 與 Claude Code 寫程式的企業 Java 團隊,要怎麼把 IBM MQ 做到「不掉訊息、不重複扣款、出事查得到、升級不翻車、AI 不亂動 Production」?

這個問題底下藏著五件事:

  1. 訊息系統的錯誤通常不會立刻爆炸。 一個沒有設 Backout Queue 的 Consumer,可能在某天凌晨遇到一筆格式錯誤的訊息,然後無限重試、塞住整條佇列,直到早上客服電話響起。
  2. MQ 的 Transaction 不是 DB 的 Transaction。 「先扣款再送 MQ」與「先送 MQ 再扣款」各有不同的失敗模式;以為兩者會自動一致,是金融系統最常見的事故根源之一。
  3. Legacy 系統的 MQ 設計通常沒有文件。 佇列名稱寫死在十年前的程式裡,Channel 設定只存在 MQ 管理員的腦袋裡,訊息格式只能從 COBOL Copybook 反推。
  4. 升級是連鎖反應。 Java 8 → 25、javax.jms → jakarta.jms、MQ Client 9.1 → 10.0、TLS 1.2 RSA CipherSpec 被淘汰——任何一環沒驗證,Production 就會出現 2393 或 2035。
  5. AI Agent 寫 MQ 程式很快,但它不知道哪個 Queue 是 Production 的。 必須有一套治理機制,讓 AI 能分析、能產生、能測試,但不能未經核准就碰 Production。

本手冊的核心主張:

IBM MQ 不是「另一個傳訊息的函式庫」,而是企業系統之間的「可靠性契約」。要把它做好,必須同時處理架構、程式、設定、安全、維運與治理六個面向,而 AI Agent 必須被納入這個契約,而不是凌駕於它之上。

手冊結構

flowchart LR
    A["第一篇<br/>基礎與架構<br/>Part 1-3"] --> B["第二篇<br/>安裝與系統管理<br/>Part 4-8"]
    B --> C["第三篇<br/>Java 開發與整合<br/>Part 9-16"]
    C --> D["第四篇<br/>逆向工程與升級<br/>Part 17-21"]
    D --> E["第五篇<br/>維運、品質與 DevOps<br/>Part 22-29"]
    E --> F["第六篇<br/>AI Agent 工程化<br/>Part 30-42"]
    F --> G["第七篇<br/>企業標準<br/>Part 43-46"]
    G --> H["附錄<br/>Quick Reference<br/>Checklist"]

依角色建議的閱讀路線

角色必讀建議可略讀
Java 開發人員Part 1-3、9-16、28、34、4322-25、30-314、26
前後端工程師Part 1、14-16、4312、154-8、26
SA / 系統分析師Part 1-3、14-17、376、3310-11
軟體架構師Part 1-3、6-8、13-17、26、37、45-46全部—
IBM MQ 系統管理員Part 2-8、21-27、3629-30、41;5.13、8.12(有主機時)10-12
z/OS MQ 系統管理員Part 1.19、2.10、5.13、8.12、24.7、26.92.6、3.12、21、3610-12、27
DevOps / DevSecOpsPart 4、8、21、27-29、3622-2610-11
維運人員Part 5、22-24、368、26;23.6 IBM MQ Agent9-13
PM / Technical PMPart 1、14、20-21、36-412610-13
Legacy 維護人員Part 3、5、17-19、2320-2112
逆向工程人員Part 17-19、33、423、234、26
Framework 升級團隊Part 9、20-21、44、IBM MQ Quick Reference28-294
AI Coding Agent 使用者Part 18-19、30-4223.6、34-354、26

版本差異標示規則

本手冊用下列標記區分版本差異:

標記意義
[MQ 10.0]IBM MQ 10.0 新增或變更的行為
[MQ 9.4 CD]9.4.1~9.4.5 CD 首次出現、10.0 LTS 首次納入的功能
[MQ 9.4]9.4.0 LTS 起可用
[MQ 9.3+]9.3 起可用
[Java 17] / [Java 21] / [Java 25]該寫法需要的最低 Java 版本
[Boot 3] / [Boot 4]Spring Boot 主版本差異
[需確認]需依目前 IBM / Spring 官方文件確認

環境分級原則

本手冊所有範例都會明確標示適用環境。Demo 做法不等於 Production 標準。

環境目的允許事項禁止事項
Development(DEV)個人開發、單元測試MQ Developer 容器、自簽憑證、寬鬆權限使用 Production 資料
Test / SIT整合測試共用 Queue Manager、測試用 CA使用 Production 憑證或帳號
UAT使用者驗收、效能測試與 Production 同等設定(TLS、CHLAUTH、OAM)直接修改設定而未經變更流程
Production(PROD)正式營運僅經核准的變更AI Agent 或個人未經核准的任何變更

不可直接抄貼原則

本手冊參考 IBM 官方文件後,以「理解 → 分析 → 重組 → 教學化 → 實務化 → AI Agent 化」的方式重新撰寫。必要的官方術語、命令名稱與參數保留原文;所有說明、案例、架構建議與檢查清單為重新組織的內容。官方命令的完整語法與所有參數,仍以 IBM Documentation 的 MQSC / Control Commands Reference 為準。


目錄


Part 1 — IBM MQ 基礎與核心概念

1.1 目的

讓讀者在動手寫程式之前,先回答三個問題:IBM MQ 解決什麼問題?什麼時候該用、什麼時候不該用?它在企業(特別是金融業)架構中扮演什麼角色?

1.2 Message Oriented Middleware(訊息導向中介軟體)

Message Oriented Middleware(MOM,訊息導向中介軟體)的核心概念只有一句話:

發送方把資料放進一個「中間的可靠容器」,接收方在自己方便的時候從容器取出。雙方不需要同時在線,也不需要知道對方在哪裡。

這個「中間容器」就是 Queue(佇列),管理容器的伺服器程式就是 Queue Manager(佇列管理器)。

用生活比喻:

通訊方式比喻特性
TCP Socket打電話雙方必須同時在線;斷線就中斷
REST API到櫃檯辦事必須等櫃員回應;櫃員不在就失敗
IBM MQ掛號郵件 + 郵局寄件人投遞後即可離開;郵局保證送達、可追蹤、可退件

1.3 IBM MQ 的定位

IBM MQ 是 IBM 的企業級訊息中介軟體產品,前身為 MQSeries、WebSphere MQ。它的設計重點是:

  1. Assured Delivery(確保送達):Persistent Message 搭配 Syncpoint,在 Queue Manager 重啟後仍不遺失。
  2. Once-and-only-once 傳遞(於 MQ 網路內):Queue Manager 之間的 Channel 以批次確認與序號機制避免重複或遺失。注意:這個保證只在 MQ 網路內部成立,應用程式端的重複處理仍需自行設計 Idempotency(見 Part 13、15)。
  3. 跨平台:Linux、Windows、AIX、IBM i、z/OS、容器、雲端,以及 MQ Appliance。
  4. 多種 API:MQI(C、COBOL 等)、Java、JMS / Jakarta Messaging、.NET、XMS、REST、AMQP、MQTT。
  5. 企業級安全與維運:TLS、CHLAUTH、CONNAUTH、OAM、事件監控、統計與帳務資料。

1.4 IBM MQ 解決什麼問題

問題沒有 MQ 時使用 MQ 後
系統暫時離線呼叫方失敗或必須自行重試、暫存訊息留在佇列,對方上線後處理
流量尖峰後端被打爆佇列吸收尖峰,Consumer 依自身能力處理(削峰填谷)
異質平台整合每對系統寫一套轉換與傳輸程式統一透過 MQ API 與 Channel
可靠性自行實作 ack、重送、去重Persistent + Syncpoint + Channel 協定
解耦呼叫方需知道對方位址只需知道佇列名稱,路由由 MQ 設定決定
稽核與追蹤散落各系統日誌Message ID / Correlation ID、事件、帳務記錄

1.5 IBM MQ 與其他技術的比較

比較原則:以下比較著重「設計取向與適用情境」,不代表某一技術絕對優於另一技術。實際選型應依需求、既有資產、團隊能力與授權成本評估。

1.5.1 IBM MQ 與 REST API

面向REST APIIBM MQ
互動模式同步 Request / Response非同步為主,也可做 Request / Reply
時間耦合雙方必須同時可用不需同時可用
可靠性由呼叫方自行重試;重試可能造成重複Persistent + Syncpoint 保證送達 MQ
流量控制需另加 Rate Limit / Circuit Breaker佇列天然緩衝
適合情境查詢、即時互動、對外開放 API交易指令、系統間可靠傳遞、批次資料、跨平台整合
不適合情境對方常離線、尖峰極高需要立即回應的使用者查詢(除非搭配 Request / Reply 與 Timeout)

1.5.2 IBM MQ 與 Apache Kafka

面向Apache KafkaIBM MQ
核心模型分散式、可重播的事件日誌(Log)佇列(取走即消失)與 Pub/Sub
訊息保留依保留政策保存,可多次重讀取走(destructive get)後即刪除;Browse 不刪除
典型用途事件串流、資料管線、大量事件分析交易指令、Request / Reply、可靠點對點
交易語意支援 Kafka transactions(主要在 Kafka 生態內)Syncpoint、XA 兩階段提交(可與 DB 協調)
個別訊息處理以 offset 為單位,單筆刪除不是設計重點以單筆訊息為單位,支援 Backout、DLQ
整合兩者可並存;IBM MQ Advanced 提供 Kafka Connect 來源與接收 connector [MQ 9.4 CD]

實務建議:交易指令(轉帳、扣款、下單)走 MQ;交易完成後產生的事件(供分析、通知)可轉發到 Kafka。兩者是互補而非替代。

1.5.3 IBM MQ 與 RabbitMQ

面向RabbitMQIBM MQ
協定AMQP 0-9-1 為主,另支援 AMQP 1.0、MQTT、STOMP 等MQ 原生協定,另支援 AMQP 1.0、MQTT
路由Exchange + Binding,彈性高Queue Alias、Remote Queue、Cluster、Topic
授權開源(另有商業支援)商業授權(有免費 Developer 版本)
企業特性依版本與外掛提供內建 XA、z/OS 整合、CHLAUTH、AMS 端到端加密(Advanced)
適合情境雲原生微服務、彈性路由大型主機整合、金融交易、需要正式原廠支援的關鍵系統

1.5.4 IBM MQ 與傳統 TCP Socket

很多 Legacy 系統(特別是金融業的電文系統)仍使用自訂 TCP Socket 協定。兩者差異:

面向TCP SocketIBM MQ
訊息邊界需自行定義(長度欄位、分隔字元)由 MQ 管理
斷線重連自行實作Channel 自動重試;Client 自動重連(可設定)
暫存自行實作佇列
加密自行處理 TLSChannel 層 TLS 設定
重複 / 遺失全部自行處理MQ 內部保證;應用層仍需 Idempotency

1.6 IBM MQ 在企業整合中的角色

flowchart TB
    subgraph Channel["通路層"]
        WEB["網路銀行 Web"]
        APP["行動 App"]
        BR["分行櫃員系統"]
    end
    subgraph Middle["整合層"]
        API["API Gateway"]
        SVC["Spring Boot 服務"]
        MQ[("IBM MQ<br/>Queue Manager")]
    end
    subgraph Core["核心層"]
        CBS["Core Banking"]
        MF["Mainframe / CICS"]
        CARD["信用卡系統"]
        BATCH["批次系統"]
    end
    WEB --> API
    APP --> API
    BR --> SVC
    API --> SVC
    SVC <--> MQ
    MQ <--> CBS
    MQ <--> MF
    MQ <--> CARD
    MQ <--> BATCH

IBM MQ 在企業整合中常扮演:

  1. 前台與核心之間的緩衝層:前台流量尖峰不會直接衝擊核心。
  2. 異質平台的共同語言:Java、.NET、COBOL、C 都能透過 MQ 溝通。
  3. 可靠的交易通道:交易指令不因網路短暫中斷而遺失。
  4. 系統邊界:佇列名稱就是系統之間的契約。

1.7 IBM MQ 在金融業的常見用途

用途說明常見模式
轉帳 / 扣款前台送交易指令到核心系統Request / Reply
跨行交易與清算機構、外部銀行介接Distributed Queuing(Sender / Receiver Channel)
帳務通知交易完成後通知簡訊、推播、稽核Pub/Sub 或多 Queue 分送
批次資料傳遞日終資料、對帳檔分段傳遞Message Group、Managed File Transfer(MFT)
主機整合透過 CICS / IMS Bridge 呼叫主機交易Request / Reply
風控 / 反洗錢交易事件送風控引擎非同步事件

1.8 實務案例

某銀行網銀轉帳原本以 REST 同步呼叫核心系統。核心系統每晚 23:30 至 00:30 進行日切,期間網銀轉帳全數失敗並顯示系統忙碌。改為「網銀 → Spring Boot → MQ → 核心」後,日切期間的轉帳指令留在 Request Queue,日切完成後依序處理,前台改為顯示「交易已受理,處理中」並提供查詢。

但這個改動帶來新問題:使用者可能因為沒有立即看到結果而重按,造成重複轉帳。解法是 Idempotency Key(見 Part 15)。MQ 解決了可用性問題,但也把一致性問題推到應用層。

1.9 注意事項

  • 不要因為「MQ 很可靠」就省略應用層的 Idempotency。
  • 不要把 MQ 當成 REST 的替代品用在需要立即回應的查詢上。
  • 導入 MQ 前,先確認誰負責 Queue Manager 的維運,避免「開發建了、沒人管」。

1.10 IBM MQ 核心元件總覽

本節起建立對 IBM MQ 物件(Objects)的完整心智模型,理解每個元件的職責與彼此關係。

Application
    ↓
MQ Client / MQI / JMS
    ↓
Queue Manager
    ↓
Queue
    ↓
Channel
    ↓
Remote Queue Manager
    ↓
Application
flowchart LR
    subgraph HostA["主機 A"]
        AppA["Producer 應用程式"]
        subgraph QMA["Queue Manager QM_A"]
            RQ["Remote Queue<br/>ORDER.REQ"]
            XQ["Transmission Queue<br/>QM_B"]
            SDR["Sender Channel<br/>QM_A.TO.QM_B"]
            LSA["Listener :1414"]
            SVR["SVRCONN Channel<br/>APP.SVRCONN"]
        end
    end
    subgraph HostB["主機 B"]
        subgraph QMB["Queue Manager QM_B"]
            RCV["Receiver Channel<br/>QM_A.TO.QM_B"]
            LQ["Local Queue<br/>ORDER.REQ"]
            DLQ["Dead Letter Queue"]
            LSB["Listener :1414"]
        end
        AppB["Consumer 應用程式"]
    end
    AppA -- "Client 連線" --> LSA --> SVR
    SVR -- "MQPUT" --> RQ --> XQ --> SDR
    SDR -- "TCP / TLS" --> LSB --> RCV
    RCV --> LQ
    RCV -. "無法投遞" .-> DLQ
    LQ -- "MQGET" --> AppB

1.11 Queue Manager(佇列管理器)

Queue Manager 是 IBM MQ 的伺服器端核心程式,負責:

  • 擁有並管理所有 MQ 物件(Queue、Channel、Topic、Listener 等)
  • 處理應用程式的 MQI 呼叫
  • 管理 Recovery Log(復原日誌),保證 Persistent Message 不遺失
  • 管理交易(Syncpoint)
  • 執行安全檢查(CHLAUTH、CONNAUTH、OAM)

命名限制:Queue Manager 名稱最長 48 字元,在整個 MQ 網路中應唯一(Cluster 中必須唯一)。

1.12 Queue(佇列)的種類

類型MQSC 物件用途是否實際存放訊息
Local QueueQLOCAL實際存放訊息的佇列是
Remote Queue(定義)QREMOTE指向另一個 Queue Manager 上的佇列否(訊息進入 Transmission Queue)
Transmission QueueQLOCAL + USAGE(XMITQ)暫存要送往遠端 Queue Manager 的訊息是
Dead Letter Queue(DLQ)QLOCAL,由 QMGR DEADQ 屬性指定存放無法投遞的訊息是
Alias QueueQALIAS為另一個 Queue 或 Topic 取別名否
Model QueueQMODEL動態建立佇列的範本(例如暫時回覆佇列)否(範本)
Cluster QueueQLOCAL + CLUSTER(...)在 Cluster 中公告、可被其他成員找到是
Backout QueueQLOCAL,由來源佇列 BOQNAME 指定存放重試超過次數的毒訊息(Poison Message)是

常見誤解:

  • Remote Queue 不是一個「遠端的佇列」,而是一個「本地的路由定義」。 對它 MQPUT 時,訊息會被放進 Transmission Queue,再由 Sender Channel 送出。你不能對 Remote Queue 做 MQGET。
  • Alias Queue 常用於「解耦應用程式與實體佇列」:應用程式寫死 Alias 名稱,實際佇列可以在不改程式的情況下切換,也可以在 Alias 層級設定不同的權限(例如只允許 GET)。

1.13 Channel(通道)的種類

Channel 分為兩大類:

  1. MQI Channel:應用程式(Client)與 Queue Manager 之間,雙向。
  2. Message Channel:Queue Manager 與 Queue Manager 之間,單向。
Channel 類型MQSC CHLTYPE類別方向說明
Server ConnectionSVRCONNMQI雙向Queue Manager 端,接受 Client 連線
Client ConnectionCLNTCONNMQI雙向Client 端定義,通常放在 CCDT 中
SenderSDRMessage送出從 Transmission Queue 取出訊息送往遠端
ReceiverRCVRMessage接收接收 Sender 送來的訊息並放入目標佇列
ServerSVRMessage送出可由遠端 Requester 觸發啟動
RequesterRQSTRMessage接收主動要求遠端 Server / Sender 開始傳送
Cluster SenderCLUSSDRMessage送出連往 Full Repository,其餘由 Cluster 自動定義
Cluster ReceiverCLUSRCVRMessage接收公告本 Queue Manager 在 Cluster 中的接收端

規則:Message Channel 兩端的名稱必須相同(例如 QM_A 上的 SDR 名為 QM_A.TO.QM_B,QM_B 上的 RCVR 也必須名為 QM_A.TO.QM_B)。

1.14 Listener(監聽器)

Listener 是 Queue Manager 上監聽 TCP 連接埠的程序,接受 Client 連線與遠端 Sender Channel 的連線。慣例連接埠為 1414。

  • 建議以 MQSC 定義 DEFINE LISTENER ... CONTROL(QMGR),讓 Listener 隨 Queue Manager 啟停。
  • 一個 Queue Manager 可有多個 Listener(例如應用程式連線與跨 QM 連線使用不同連接埠,便於防火牆分流)。

1.15 Topic 與 Subscription

物件說明
Topic String階層式字串,例如 Bank/Account/Transfer/Completed
Topic Object(TOPIC)管理物件,把屬性與權限綁到 Topic Tree 的某個節點
Subscription(SUB)訂閱關係,可為 Durable(離線期間訊息保留)或 Non-durable

Publisher 對 Topic 發佈,Queue Manager 會把訊息副本送到每個符合的 Subscription 所對應的佇列。

1.16 Message(訊息)與 MQMD

一則 MQ 訊息由三部分組成:

┌───────────────────────────────┐
│ MQMD(Message Descriptor)     │ ← 控制資訊:MsgId、CorrelId、Persistence...
├───────────────────────────────┤
│ Message Properties(選用)     │ ← 名稱/值配對;JMS 使用 RFH2 或 Message Properties
├───────────────────────────────┤
│ Application Data(Payload)    │ ← 業務資料:XML、JSON、固定長度電文...
└───────────────────────────────┘

MQMD 重要欄位

欄位說明實務重點
MsgId訊息識別碼(24 bytes)預設由 Queue Manager 產生,確保唯一
CorrelId關聯識別碼(24 bytes)Request / Reply 配對用;常見慣例為「Reply 的 CorrelId = Request 的 MsgId」
Persistence是否持久化MQPER_PERSISTENT / MQPER_NOT_PERSISTENT / MQPER_PERSISTENCE_AS_Q_DEF
Expiry存活時間,單位為 1/10 秒MQEI_UNLIMITED 為永不過期
Priority優先順序 0-9佇列 MSGDLVSQ(PRIORITY) 時生效
ReplyToQ / ReplyToQMgr回覆目的地Request / Reply 必填
Format資料格式MQSTR(字串)、MQHRF2(含 RFH2 標頭)、空白(二進位)
CodedCharSetId(CCSID)字元集UTF-8 為 1208;主機 EBCDIC 常見 37、937(繁中)
Encoding數值編碼(位元組順序)跨平台數值欄位轉換用
BackoutCount被 Backout 的次數毒訊息判斷依據
MsgType訊息類型MQMT_DATAGRAM、MQMT_REQUEST、MQMT_REPLY、MQMT_REPORT
GroupId / MsgSeqNumber訊息群組需搭配 MQMD v2 或 MQGMO / MQPMO 選項
PutApplName / PutDate / PutTime放入者與時間稽核追蹤
UserIdentifier放入者身分由 Queue Manager 設定,應用程式通常不可任意偽造(需特殊權限)

1.17 Persistence(持久性)

類型寫入 LogQueue Manager 重啟後效能適用
Persistent是保留較低(受磁碟 I/O 影響)交易指令、金額相關
Non-persistent否遺失較高查詢、可重送的通知、即時報價

重要:佇列的 DEFPSIST 只是「預設值」。若應用程式明確指定 Persistence,以應用程式為準。JMS 預設 DeliveryMode 為 PERSISTENT,而 MQI / MQ classes for Java 的 MQMD.Persistence 預設為 MQPER_PERSISTENCE_AS_Q_DEF。混用時務必確認。

1.18 元件關係總整理

classDiagram
    class QueueManager {
        +name
        +DEADQ
        +CONNAUTH
        +CHLAUTH
    }
    class LocalQueue {
        +MAXDEPTH
        +MAXMSGL
        +BOQNAME
        +BOTHRESH
        +DEFPSIST
    }
    class RemoteQueue {
        +RNAME
        +RQMNAME
        +XMITQ
    }
    class AliasQueue {
        +TARGET
    }
    class TransmissionQueue {
        +USAGE=XMITQ
    }
    class Channel {
        +CHLTYPE
        +SSLCIPH
        +MCAUSER
    }
    class Listener {
        +PORT
        +CONTROL
    }
    class Topic {
        +TOPICSTR
    }
    class Subscription {
        +DEST
        +DURABLE
    }
    QueueManager "1" o-- "*" LocalQueue
    QueueManager "1" o-- "*" RemoteQueue
    QueueManager "1" o-- "*" AliasQueue
    QueueManager "1" o-- "*" Channel
    QueueManager "1" o-- "*" Listener
    QueueManager "1" o-- "*" Topic
    RemoteQueue --> TransmissionQueue : 路由至
    TransmissionQueue <-- Channel : Sender 讀取
    AliasQueue --> LocalQueue : 指向
    Topic "1" --> "*" Subscription
    Subscription --> LocalQueue : 投遞至

1.19 IBM MQ 物件全集

前面幾節介紹的是應用開發最常碰到的物件。管理與逆向工程時,還會遇到下列物件;盤點 dmpmqcfg 輸出時,應能逐一辨識。

物件MQSC 關鍵字名稱長度上限用途常見於
Queue ManagerQMGR48擁有並管理所有物件與訊息全部
Local / Remote / Alias / Model QueueQLOCAL / QREMOTE / QALIAS / QMODEL48存放、路由、別名、動態佇列範本全部
Dynamic Queue由 QMODEL 於 MQOPEN 時建立48暫時回覆佇列(Temporary / Permanent Dynamic)Request / Reply
Topic ObjectTOPIC48(Topic String 可更長)管理 Topic 樹節點的屬性與權限Pub/Sub
SubscriptionSUB依 Subscription 名稱規則訂閱關係Pub/Sub
ChannelCHANNEL20Queue Manager 之間或 Client 與 QM 之間的通訊全部
ListenerLISTENER48監聽連接埠分散式平台
ServiceSERVICE48讓 QM 啟停時一併啟停的外部程式(例如監控代理、自訂守護程序)分散式平台
NamelistNAMELIST48名稱清單,常用於 Cluster 的 CLUSNL、TLS 的 SSLCRLNLCluster、TLS
Process DefinitionPROCESS48搭配 Trigger 指定要啟動的應用程式Legacy Trigger 設計
Authentication InformationAUTHINFO48CONNAUTH(IDPWOS / IDPWLDAP)、CRL / OCSP 檢查、JWT 設定Security
Communication InformationCOMMINFO48Multicast 傳輸參數Multicast
Channel Authentication RecordCHLAUTH—Channel 層的允許 / 封鎖 / 對應規則Security
Authority RecordAUTHREC—OAM 授權記錄Security
Storage ClassSTGCLASS8佇列對應到 Page Set(僅 z/OS)z/OS
CF StructureCFSTRUCT12Coupling Facility 中存放 Shared Queue 的結構(僅 z/OS)z/OS QSG

名稱長度上限為官方常見限制的整理;特定平台與物件的完整規則,請以 IBM MQ 10.0 Reference 的「Rules for naming IBM MQ objects」為準 [需確認]。

1.20 IBM MQ 產品家族與授權

選擇功能前,必須先確認授權等級。許多架構師在設計時預設了 Native HA 或 AMS,上線前才發現公司只買了 base 授權。

產品 / 部署形態說明典型使用情境
IBM MQ(base)核心訊息功能:Queue、Channel、Cluster、Pub/Sub、TLS、OAM、Console、REST API一般企業整合
IBM MQ Advanced在 base 之上加入 AMS、MFT、RDQM、Native HA、Kafka Connect connector 等進階能力金融核心、端到端加密、檔案傳輸、高可用
IBM MQ Advanced for Developers免費、僅限非 Production 的開發版本(含 Developer 容器映像)個人開發、CI 測試
IBM MQ for z/OS / Advanced for z/OS VUE主機平台版本;支援 QSG、Shared Queue銀行核心系統
IBM MQ Appliance預先整合的硬體設備不想自行維運 OS 的機構
IBM MQ as a Service(SaaS)IBM 代管的雲端服務雲端優先、無主機維運團隊
IBM Cloud Pak for Integration(CP4I)在 OpenShift 上以 MQ Operator 部署容器平台
IBM MQ Agent10.0 文件新增的 AI 診斷元件,授權為 Advanced / CP4I 的延伸AI 輔助維運(見 Part 23.6)

各功能對應的授權範圍、Appliance 型號、SaaS 提供的雲端平台會隨時間調整,需依目前 IBM MQ license information 與銷售文件確認 [需確認]。

1.21 官方文件主題與本手冊對照

本手冊以 IBM MQ 10.0 官方文件的三大主題為骨架,下表列出每個官方子主題在本手冊的對應位置,方便讀者回查原文,也作為本手冊完整度的驗收依據。

官方主題官方子主題本手冊對應
Technical overviewIntroduction to message queuingPart 1.2-1.4
Technical overviewIBM MQ objectsPart 1.10-1.19
Technical overviewDistributed queuing and clustersPart 2.4、Part 7
Technical overviewPublish/subscribe messagingPart 1.15、2.4.6、Part 16
Technical overviewIBM MQ MulticastPart 2.8、5.14
Technical overviewIBM MQ Telemetry(MQTT)Part 2.8、5.14
Technical overviewSecurity in IBM MQPart 8、Part 29
Technical overviewIBM MQ MQI clientsPart 2.2、2.6、9.6
Technical overviewTransaction management and supportPart 3.5、3.12、Part 13
Technical overviewExtending queue manager facilitiesPart 2.7
Technical overviewIBM MQ Java language interfacesPart 9-12
Technical overviewIBM MQ for z/OS concepts / other z/OS productsPart 2.10、5.13、8.12、24.7、26.9
Technical overviewManaged File TransferPart 2.8、5.14
Technical overviewIBM MQ Internet Pass-ThruPart 2.8、5.14
Technical overviewThe IBM MQ Console and REST APIPart 2.11、5.11、5.12、9.8
AdministeringWays of administering / Command sets comparisonPart 5.2、5.8
AdministeringControl commandsPart 4.2、5.3
AdministeringMQSC commandsPart 5.4-5.6
AdministeringPCF commandsPart 5.10
AdministeringAdministration using the REST APIPart 5.11
AdministeringIBM MQ Console / IBM MQ Explorer / TaskbarPart 5.12
AdministeringWorking with local / remote objectsPart 5.9
AdministeringMFT / Telemetry / AMQP / Multicast / MQIPTPart 5.14
AdministeringAdministering IBM MQ for z/OSPart 5.13
Developing applicationsApplication development concepts / Design considerationsPart 3、9.9
Developing applicationsJMS / Jakarta Messaging and JavaPart 9-12
Developing applicationsC++、.NET、XMS .NET、AMQP、MQI(C / COBOL)Part 9.7
Developing applicationsREST applications(Messaging REST API)Part 9.8
Developing applicationsSpecifying the application namePart 9.6、10.3、12.5
IBM MQ AgentOverview / Security / TroubleshootingPart 23.6、31.6、41.6

1.22 核心元件注意事項

  • Queue 名稱區分大小寫,最長 48 字元。MQSC 中未加單引號的名稱會被轉為大寫,含小寫字母時必須加單引號。
  • Channel 名稱最長 20 字元,命名規範需考慮此限制(見 Part 35)。
  • 不要直接使用 SYSTEM.DEF.*、SYSTEM.ADMIN.SVRCONN、SYSTEM.AUTO.* 這類系統預設物件作為應用程式連線入口。

Part 2 — IBM MQ 系統架構

2.1 目的

理解不同的 Queue Manager 部署拓撲,並能依需求選擇合適的架構。

2.2 Client / Server Architecture

應用程式連到 Queue Manager 有兩種模式:

模式說明適用
Bindings Mode(本機連線)應用程式與 Queue Manager 在同一台主機,透過 IPC 溝通同主機部署、極低延遲需求、主機上的 Adapter
Client Mode(用戶端連線)應用程式透過網路連到 Queue Manager 的 SVRCONN Channel現代 Java / Spring Boot 應用程式的標準做法
flowchart LR
    subgraph AppServer["應用伺服器(K8s Pod / VM)"]
        J["Java 應用程式<br/>+ MQ Client Library"]
    end
    subgraph MQServer["MQ Server 主機"]
        L["Listener :1414"]
        S["SVRCONN Channel"]
        QM["Queue Manager"]
        Q[("Queues")]
        LOG[("Recovery Log")]
    end
    J -- "TCP + TLS<br/>MQ Client 協定" --> L --> S --> QM
    QM --> Q
    QM --> LOG

IBM MQ Server 與 IBM MQ Client 的區別:

項目IBM MQ ServerIBM MQ Client
是否執行 Queue Manager是否
是否存放訊息是否
安裝內容Queue Manager、管理工具、Client 函式庫僅 Client 函式庫(Java 只需 jar)
授權依 IBM 授權條款計價Client 通常可自由散布 [需確認授權條款]
Java 應用取得方式—Maven Central:com.ibm.mq.jakarta.client 或 com.ibm.mq.allclient

2.3 Queue Manager 內部架構

flowchart TB
    subgraph QM["Queue Manager"]
        direction TB
        AGENT["Agent Processes<br/>處理 MQI 呼叫"]
        CHI["Channel Initiator /<br/>Channel Processes"]
        LSN["Listener"]
        CMD["Command Server<br/>處理 PCF / MQSC 遠端命令"]
        SEC["Security<br/>CHLAUTH / CONNAUTH / OAM"]
        LOGM["Log Manager"]
        QS["Queue Storage<br/>(Queue Files)"]
        PUBSUB["Pub/Sub Engine"]
    end
    LOG[("Recovery Log<br/>Circular / Linear")]
    APP["應用程式"] --> LSN --> CHI --> SEC --> AGENT
    AGENT --> QS
    AGENT --> PUBSUB
    AGENT --> LOGM --> LOG
    ADMIN["管理工具<br/>runmqsc / REST / MQ Console"] --> CMD --> AGENT

Recovery Log 是可靠性的根本:

Log 類型特性媒體復原(Media Recovery)適用
Circular日誌循環使用,管理簡單不支援大多數分散式平台 Production(搭配 HA 方案)
Linear日誌持續增加,需管理歸檔支援(rcdmqimg / rcrmqobj)需從媒體毀損中復原佇列、或使用 Backup Queue Manager 的場景

[MQ 9.4 CD] 起提供 Linear Log 的自動日誌管理選項(Automatic / Archive)。實際設定方式需依目前 IBM 官方文件確認。

2.4 架構模式比較

2.4.1 Single Queue Manager

flowchart LR
    A1["App A"] --> QM["QM1"]
    A2["App B"] --> QM
    A3["App C"] --> QM
項目說明
優點簡單、易維運、易除錯
缺點單點故障;容量受單機限制
使用情境開發 / 測試、小型系統、搭配 HA(Native HA / RDQM / Multi-instance)的中型系統
維運複雜度低
故障模式QM 停止 → 所有應用無法收發(2059 / 2538)

2.4.2 Multiple Queue Managers(Distributed Queuing)

flowchart LR
    subgraph SiteA["系統 A"]
        AppA["App A"] --> QMA["QM_A"]
    end
    subgraph SiteB["系統 B"]
        QMB["QM_B"] --> AppB["App B"]
    end
    QMA -- "SDR: QM_A.TO.QM_B" --> QMB
    QMB -- "SDR: QM_B.TO.QM_A" --> QMA
項目說明
優點系統邊界清楚、各自維運、故障隔離
缺點每對 QM 需要手動定義 Channel、XMITQ、Remote Queue;連線數 O(n²)
使用情境跨部門、跨公司(例如與清算機構)介接
維運複雜度中(Channel 數量多時高)
故障模式Channel 中斷 → 訊息堆積在 XMITQ;網路恢復後自動續傳

2.4.3 Point-to-Point

一則訊息只會被一個 Consumer 取走。可以有多個 Consumer 同時監聽同一佇列(Competing Consumers),以提高吞吐量,但會失去訊息順序保證。

2.4.4 Hub-and-Spoke

flowchart TB
    HUB["Hub QM<br/>(整合中心)"]
    S1["Spoke QM 1<br/>網銀"] <--> HUB
    S2["Spoke QM 2<br/>行動"] <--> HUB
    S3["Spoke QM 3<br/>分行"] <--> HUB
    HUB <--> CORE["Core QM<br/>核心"]
項目說明
優點集中管控、集中監控;Channel 數量 O(n)
缺點Hub 成為效能瓶頸與單點故障;Hub 需 HA
使用情境企業整合中心(ESB 時代常見架構)
維運複雜度中
故障模式Hub 故障 → 全面中斷,Hub 必須搭配 HA

2.4.5 MQ Cluster

flowchart TB
    subgraph Cluster["Cluster: BANK.CLUSTER"]
        FR1["QM_FR1<br/>Full Repository"]
        FR2["QM_FR2<br/>Full Repository"]
        P1["QM_APP1<br/>Partial Repository"]
        P2["QM_APP2<br/>Partial Repository"]
        P3["QM_CORE1<br/>擁有 PAY.REQ"]
        P4["QM_CORE2<br/>擁有 PAY.REQ"]
    end
    FR1 <--> FR2
    P1 --> FR1
    P2 --> FR2
    P3 --> FR1
    P4 --> FR2
    P1 -. "自動定義 CLUSSDR<br/>Workload Balancing" .-> P3
    P1 -. " " .-> P4
項目說明
優點自動定義 Channel 與路由;同名佇列可多實例做 Workload Balancing;擴充容易
缺點Full Repository 需妥善維運;問題排查比點對點複雜;訊息順序不保證
使用情境多個 Queue Manager 需要互通、需要水平擴充的系統
維運複雜度高
故障模式Repository 不一致導致路由錯誤(2189 / 2085);某實例停止時訊息可能卡在該實例

Uniform Cluster(9.1.2 起):一組設定相同的 Queue Manager,搭配應用程式自動重新平衡(Application Rebalancing),讓 Client 連線在成員間平均分配。Spring Boot Starter 提供 balancingApplicationType 等相關屬性。

2.4.6 Publish / Subscribe

flowchart LR
    PUB["Publisher<br/>交易服務"] -- "Publish<br/>Bank/Txn/Completed" --> T(("Topic"))
    T --> S1["SUB: 通知服務"]
    T --> S2["SUB: 稽核服務"]
    T --> S3["SUB: 風控服務"]
項目說明
優點Publisher 不需知道有多少訂閱者;新增訂閱者不影響 Publisher
缺點訊息會被複製多份;Durable Subscription 未消費會累積
使用情境事件通知、多系統需要同一事件
維運複雜度中
故障模式某訂閱者停機 → 其 Durable Subscription 佇列堆積,可能影響整個 QM 的儲存空間

2.5 架構選型決策

flowchart TD
    Start(["新整合需求"]) --> Q1{"需要多個系統<br/>收到同一訊息?"}
    Q1 -- 是 --> PS["Publish / Subscribe"]
    Q1 -- 否 --> Q2{"Producer 與 Consumer<br/>屬不同組織 / 網段?"}
    Q2 -- 是 --> DQ["Distributed Queuing<br/>Sender / Receiver"]
    Q2 -- 否 --> Q3{"需要水平擴充<br/>多個 Queue Manager?"}
    Q3 -- 是 --> CL["MQ Cluster /<br/>Uniform Cluster"]
    Q3 -- 否 --> Q4{"可用性需求?"}
    Q4 -- 高 --> HA["Single QM + HA<br/>Native HA / RDQM / Multi-instance"]
    Q4 -- 一般 --> SQ["Single Queue Manager"]

2.6 MQI Client 類型與 CCDT

Client 不是「另一個 Queue Manager」,它只是一組函式庫,透過 SVRCONN Channel 把 MQI 呼叫送到遠端 Queue Manager 執行。理解 Client 的種類與連線設定來源,是排查 2058、2059、2538 的基礎。

Client 類型內容安裝方式適用
IBM MQ C Client(MQI Client)C / C++ / COBOL 程式使用的原生函式庫OS 安裝套件或 Redistributable 壓縮檔C、COBOL、Go、Node.js(底層呼叫 C Client)
IBM MQ Java / Jakarta Client純 Java 實作,不需要安裝原生 ClientMaven artifact(com.ibm.mq.jakarta.client / com.ibm.mq.allclient)Java、Spring Boot
IBM MQ .NET Client / XMS .NET.NET 函式庫,[MQ 10.0] 以 .NET 10 建置NuGetC#、VB.NET
Redistributable Client可隨應用一起散布的 Client 檔案解壓即可,不需 root 安裝容器映像、CI 環境

Client 連線設定的來源

Client 需要知道「連哪個 QM、走哪條 Channel、用什麼 TLS」。資訊可能來自多個地方,同時存在時有優先順序,這是 Legacy 系統「改了設定卻沒生效」的常見原因。

來源說明治理建議
程式內指定(MQCD / ConnectionFactory 屬性)程式碼或設定檔直接寫入 connName、Channel允許,但值必須外部化
環境變數 MQSERVERCHANNEL/TCP/host(port),不支援 TLSProduction 禁止
CCDT(MQCHLLIB / MQCHLTAB / MQCCDTURL / ccdtUrl)Client Channel Definition Table,二進位或 JSON建議:集中管理、版本控制
mqclient.iniClient 組態檔(TCP、TLS、Channel 預設值)由平台團隊統一提供

各來源的完整優先順序依 API 與版本略有不同,請以官方「Connecting IBM MQ MQI client applications to queue managers」說明為準 [需確認]。

JSON CCDT 範例

JSON 格式 CCDT(MQ 9.1.2 起)可讀、可 diff、可放 Git,並允許同名 Channel 定義多筆以支援負載平衡與 HA。

{
  "channel": [
    {
      "name": "PAY.SVRCONN",
      "type": "clientConnection",
      "clientConnection": {
        "connection": [
          { "host": "mq-a.bank.local", "port": 1414 },
          { "host": "mq-b.bank.local", "port": 1414 }
        ],
        "queueManager": "BANKQM01"
      },
      "transmissionSecurity": {
        "cipherSpecification": "ANY_TLS13_OR_HIGHER",
        "certificateLabel": "payclient"
      },
      "connectionManagement": {
        "sharingConversations": 10,
        "heartbeatInterval": 300
      }
    }
  ]
}

欄位名稱以官方 JSON CCDT schema 為準 [需確認]。[MQ 10.0] 起 CCDT 可透過 HTTPS URL 取得,Spring Boot Starter 以 ccdtSslBundle 指定取得 CCDT 時使用的 TLS 設定。

2.7 擴充 Queue Manager 功能:Exits 與 Installable Services

IBM MQ 允許在特定時間點插入自訂程式碼。這在 Legacy 系統很常見(例如自訂加密、稽核、路由),也是升級與逆向工程時最容易被忽略的風險點。

類型插入點常見用途設定位置
Channel Exit(Security / Send / Receive / Message / Message-retry)Channel 建立連線、送出、接收、處理每則訊息時自訂認證、壓縮、加密、稽核Channel 屬性 SCYEXIT、SENDEXIT、RCVEXIT、MSGEXIT、MREXIT
Channel Auto-definition Exit自動定義 Channel 時調整自動建立的 Channel 屬性QM 屬性 CHADEXIT
Data Conversion ExitMQGET 帶 MQGMO_CONVERT 且格式為自訂格式時自訂結構的字元集轉換依 Format 名稱載入
Cluster Workload ExitCluster 選擇目的 QM 時自訂路由規則QM 屬性 CLWLEXIT
API Exit任何 MQI 呼叫(例如 MQPUT、MQGET)之前或之後稽核、訊息改寫、監控qm.ini / mqclient.ini 的 ApiExitLocal 等 stanza
Installable Service:Authorization Service授權檢查預設元件為 OAM;可替換或擴充qm.ini 的 Service / ServiceComponent stanza
Installable Service:Name Service解析佇列名稱讓遠端佇列看起來像本機佇列(預設未啟用)qm.ini
flowchart LR
    APP["應用程式"] -->|"MQPUT"| APIX["API Exit<br/>(呼叫前 / 後)"]
    APIX --> QM["Queue Manager"]
    QM --> OAM["Authorization Service<br/>OAM(可替換)"]
    QM --> XMITQ["Transmission Queue"]
    XMITQ --> MCA["Sender MCA"]
    MCA --> CHX["Channel Exits<br/>Security / Send / Message"]
    CHX -->|"網路"| RQM["遠端 Queue Manager"]

治理建議:

  • 新設計優先使用標準功能:認證用 CHLAUTH + CONNAUTH / mTLS、加密用 AMS(Part 8.11)、監控用 Activity Trace 與 Statistics(Part 24),盡量不新增自訂 Exit。
  • Exit 在 Queue Manager 或 MCA 行程內執行,程式錯誤可能導致 Channel 失敗甚至 QM 異常,必須有原始碼、建置腳本與負責人。
  • MQ 升級時,Exit 必須以新版標頭檔重新編譯並回歸測試(列入 Part 21.6 升級前必查)。
  • 逆向工程時,以 DISPLAY CHANNEL(*) SCYEXIT SENDEXIT RCVEXIT MSGEXIT 與 qm.ini 盤點所有 Exit。

2.8 擴充元件:MFT、MQIPT、AMQP、MQTT、Multicast、Kafka Connect

flowchart TB
    subgraph Core["IBM MQ Queue Manager"]
        QM["Queues / Topics / Channels"]
    end
    MFT["Managed File Transfer<br/>Agent / Coordination QM"] --> QM
    IPT["MQIPT<br/>DMZ 中繼 / 協定轉換"] --> QM
    AMQP["AMQP 1.0 Channel<br/>Qpid / MQ Light 用戶端"] --> QM
    MQTT["MQTT Channel<br/>IoT / 行動裝置"] --> QM
    MC["Multicast<br/>COMMINFO"] --> QM
    KC["Kafka Connect<br/>Source / Sink Connector"] <--> QM
    KC <--> KAFKA[("Apache Kafka")]
    ASP["Aspera faspio Gateway<br/>長距離高延遲網路"] --> QM
元件解決的問題運作方式授權何時使用注意事項
Managed File Transfer(MFT)可靠、可稽核的檔案傳輸Agent 把檔案切塊成訊息,經 MQ 傳遞,由 Coordination QM 記錄狀態Advanced取代 FTP 批次腳本、需要稽核軌跡的檔案交換[MQ 10.0] SFTP 支援 OpenSSH 格式私鑰;MFT 本身也有 REST API
MQ Internet Pass-Thru(MQIPT)跨防火牆、DMZ 的 MQ 連線作為中繼轉送 MQ 協定,可做 TLS 終止 / 轉換、HTTP 隧道base外部夥伴連入、跨網段[MQ 10.0] 移除 Java Security Manager 支援、調整支援的 CipherSuite,升級前必須檢查 mqipt.conf
AMQP Channel讓 AMQP 1.0 用戶端(Apache Qpid 等)連入DEFINE CHANNEL ... CHLTYPE(AMQP),由 AMQP Service 處理base(分散式平台)非 Java 生態系、輕量用戶端功能為 MQ 的子集,交易語意需另行評估
MQTT(Telemetry)IoT、行動裝置的輕量 Pub/SubCHLTYPE(MQTT),由 Telemetry Service 處理base(分散式平台)大量裝置、低頻寬網路裝置數量大時需評估連線數與 QoS
Multicast一對多的低延遲 Non-persistent 發佈Topic 搭配 COMMINFO 物件,用 IP Multicast 傳送base行情、即時看板不保證送達,不可用於交易訊息
Kafka Connect connectorsMQ 與 Kafka 雙向橋接Source(MQ → Kafka)、Sink(Kafka → MQ)connector;[MQ 10.0] 新增 XML ConverterAdvanced(以官方授權條款為準)事件串流分析、雙平台並存見 Part 16.6
Aspera faspio Gateway長距離、高延遲網路的 MQ 傳輸加速以 FASP 協定替代 TCP 傳送 MQ 流量Advanced跨洲 DR、海外分行[MQ 10.0] 版本升級

各元件在不同平台(z/OS、IBM i、容器)的可用性不同,需依目前官方文件與授權確認 [需確認]。

2.9 Streaming Queue

Streaming Queue(MQ 9.3.3 CD 首次提供,9.4 LTS 起納入 [MQ 9.4])讓 Queue Manager 在不修改任何應用程式的前提下,把送到某個佇列的每一則訊息自動複製一份到另一個佇列。

用途說明
稽核保留原始請求電文的副本
分析把副本送到 Kafka(透過 Kafka Connect)或資料平台
重播 / 除錯在測試環境重現 Production 流量(需去識別化)
* 副本佇列
DEFINE QLOCAL('PAY.TXN.REQ.COPY') MAXDEPTH(500000) DESCR('Audit copy of PAY.TXN.REQ')

* 原佇列開啟串流:BESTEF = 盡力複製,副本失敗不影響原訊息
ALTER QLOCAL('PAY.TXN.REQ') STREAMQ('PAY.TXN.REQ.COPY') STRMQOS(BESTEF)
STRMQOS行為適用
BESTEF(Best effort)副本無法寫入時,原訊息仍成功分析、監控
MUSTDUP(Must duplicate)副本無法寫入時,原訊息也失敗法規要求必須保留副本

注意事項:儲存與 Log 量約增加一倍;副本佇列必須有 Consumer 或容量管理,否則會塞滿;副本內含完整業務資料,權限與保存期限需納入資安治理。可串流的佇列類型與其他限制 [需確認]。

2.10 IBM MQ for z/OS 架構

許多銀行的核心帳務仍在主機上,Java 系統透過 MQ 與 CICS / IMS / Batch 交換電文。z/OS 上的 IBM MQ 與分散式平台概念相同、實作差異很大。

架構元件

flowchart TB
    subgraph LPAR1["z/OS LPAR 1"]
        MSTR1["QM 位址空間<br/>QM01MSTR"]
        CHIN1["Channel Initiator<br/>QM01CHIN"]
        PS1[("Page Sets<br/>VSAM")]
        LOG1[("Active / Archive Log<br/>BSDS")]
        MSTR1 --- PS1
        MSTR1 --- LOG1
        CHIN1 --- MSTR1
    end
    subgraph LPAR2["z/OS LPAR 2"]
        MSTR2["QM 位址空間<br/>QM02MSTR"]
        CHIN2["Channel Initiator<br/>QM02CHIN"]
    end
    subgraph Sysplex["Parallel Sysplex 共用資源"]
        CF[("Coupling Facility<br/>CF List Structures<br/>Shared Queues")]
        SMDS[("SMDS<br/>大訊息卸載")]
        DB2[("Db2<br/>共用物件定義")]
    end
    MSTR1 --- CF
    MSTR2 --- CF
    MSTR1 --- DB2
    MSTR2 --- DB2
    CF --- SMDS
    CICS["CICS / IMS / Batch"] --> MSTR1
    DIST["分散式 QM / Java Client"] -->|"TCP / TLS"| CHIN1
元件說明分散式平台對應
QM 位址空間(xxxxMSTR)處理 MQI 呼叫、管理佇列與 Logamqzxma0 等行程
Channel Initiator(xxxxCHIN)管理 Channel、Listener、MCA;分散式佇列與 Client 連線都經過它runmqchi、amqrmppa
Page SetVSAM 資料集(編號 00-99),存放佇列訊息;00 存放物件定義qmgrs/<QM>/queues 目錄
Buffer Pool記憶體緩衝區,Page Set 對應到 Buffer Pool無直接對應(OS 快取)
Storage Class(STGCLASS)佇列 → Page Set 的對應無
Active / Archive Log、BSDS交易日誌;BSDS 記錄 Log 資料集清單Linear / Circular Log
Queue Sharing Group(QSG)多個 QM 組成群組,共用物件定義(存於 Db2)無(最接近的是 Uniform Cluster)
Shared Queue訊息存於 Coupling Facility,QSG 內任一 QM 都能存取無(Native HA 解決的是另一個問題)
CF Structure(CFSTRUCT)CF 中的 List Structure;CSQ_ADMIN 為管理結構無
SMDS(Shared Message Data Set)大訊息從 CF 卸載到共用資料集無
Intra-Group Queuing(IGQ)QSG 內 QM 之間不需定義 Channel 即可傳送訊息無
Shared Channel入站:透過共用連接埠(Sysplex Distributor / VIPA)分散到任一 QM;出站:共用 Transmission Queue無
GROUP UR Disposition交易型應用以 QSG 名稱連線,交易恢復不必回到原 QM無

物件的「屬性範圍」

z/OS 物件定義有 QSGDISP 屬性,決定定義存放在哪裡、誰看得到:

QSGDISP定義存放可見範圍
QMGR本 QM 的 Page Set 00本 QM
GROUPDb2 共用儲存QSG 內每個 QM 各自產生一份 COPY
COPY本 QM(由 GROUP 定義衍生)本 QM
SHAREDDb2;訊息存於 CFQSG 內所有 QM(僅限 Local Queue)

對 Java 應用的影響

  • Java 應用通常以 Client 模式連 CHIN;若以 QSG 名稱 + 共用連接埠連線,可連到群組內任一 QM。
  • Shared Queue 讓多個 QM 上的 Consumer 共同消費同一佇列,單一 QM 停機時,CF 中的訊息仍可被其他 QM 取走,這是 z/OS 獨有的高可用能力(見 Part 26.9)。
  • 單則訊息大小、Shared Queue 對持久性訊息的效能特性,都與分散式平台不同,大訊息應評估 SMDS 設定 [需確認]。
  • 主機端字元集通常是 EBCDIC(例如 CCSID 37、937),Java 端必須搭配 MQGMO_CONVERT 或明確的 CCSID 處理(見 Part 3、P32)。

2.11 IBM MQ Console 與 REST API 架構

IBM MQ Console 與 REST API 都由 mqweb server(以 WebSphere Liberty 為基礎)提供。

flowchart LR
    BROWSER["瀏覽器"] -->|"HTTPS :9443"| WEB
    SCRIPT["自動化腳本 / Portal"] -->|"HTTPS"| WEB
    APPREST["輕量應用"] -->|"HTTPS"| WEB
    subgraph WEB["mqweb server(Liberty)"]
        CON["IBM MQ Console"]
        ADM["Administrative REST API<br/>/ibmmq/rest/v3/admin"]
        MSG["Messaging REST API<br/>/ibmmq/rest/v3/messaging"]
        MFTR["MFT REST API"]
    end
    WEB -->|"本機 bindings"| QM1["Queue Manager(同主機)"]
    WEB -.->|"遠端 QM(需設定)"| QM2["遠端 Queue Manager"]
項目說明
管理命令strmqweb、endmqweb、dspmqweb、setmqweb(調整 mqweb 屬性)
設定檔mqwebuser.xml:使用者登錄(Basic Registry / LDAP)、角色、TLS
角色MQWebAdmin(管理)、MQWebAdminRO(唯讀)、MQWebUser(以使用者身分執行,受 OAM 控管)、MFTWebAdmin / MFTWebAdminRO
認證方式HTTP Basic、Token(LTPA)、Client 憑證
預設連接埠HTTPS 9443(可調整)

詳細使用方式見 Part 5.11(Administrative REST API)、Part 5.12(Console)與 Part 9.8(Messaging REST API)。

2.12 實務案例

某銀行原本 30 套系統各自建立 Queue Manager,並兩兩定義 Channel,共 200 多條 Sender / Receiver Channel。每次新增系統,MQ 管理員要花兩週定義 Channel 與 Remote Queue。改為「2 個 Full Repository + 各系統加入 Cluster」後,新增系統只需定義 CLUSRCVR 與一條 CLUSSDR。

代價:Cluster 路由問題的排查需要更專業的 MQ 管理員,團隊額外建立了 Cluster 健康檢查腳本(DISPLAY CLUSQMGR(*))與每日巡檢。

2.13 注意事項

  • 訊息順序只在「單一 Producer、單一路徑、單一 Consumer、相同 Priority」條件下可預期。Cluster Workload Balancing、多 Consumer 都會打破順序。
  • Full Repository 至少兩個,且應分散在不同主機。
  • 不要把 Cluster 當成 HA 方案:Cluster 提供的是「可用性路由」,不是「訊息不遺失的高可用」。已在某 QM 上的訊息,在該 QM 恢復前無法被取走。

Part 3 — IBM MQ 訊息生命週期

3.1 目的

完整理解一則訊息從產生到被處理的每個步驟,以及每個步驟可能的失敗點。這是設計 Retry、DLQ、Transaction 的基礎。

3.2 本機訊息生命週期

Producer
  ↓  MQCONN(連線)
  ↓  MQOPEN(開啟佇列,MQOO_OUTPUT)
  ↓  MQPUT(放入訊息,可在 Syncpoint 內)
  ↓  MQCMIT(提交)
Queue(訊息可見)
  ↓  MQGET(取出,可在 Syncpoint 內)
  ↓  業務處理
  ↓  MQCMIT(提交 → 訊息刪除) 或 MQBACK(回滾 → 訊息回到佇列,BackoutCount + 1)
Consumer

3.3 跨 Queue Manager 的完整流程

sequenceDiagram
    autonumber
    participant P as Producer App
    participant QA as QM_A
    participant XQ as XMITQ (QM_B)
    participant CH as Sender / Receiver Channel
    participant QB as QM_B
    participant LQ as Local Queue
    participant C as Consumer App

    P->>QA: MQCONN
    P->>QA: MQOPEN Remote Queue (MQOO_OUTPUT)
    P->>QA: MQPUT (Syncpoint)
    QA->>XQ: 加上 Transmission Header (MQXQH) 放入 XMITQ
    P->>QA: MQCMIT
    Note over XQ: 訊息在 Commit 後才可被 Channel 取走
    XQ-->>CH: Trigger 啟動 Sender Channel(若未啟動)
    CH->>CH: MQGET from XMITQ(批次,Syncpoint)
    CH->>QB: 透過 TCP / TLS 傳送批次
    QB->>LQ: MQPUT 到目標佇列
    QB-->>CH: 批次確認(Confirm)
    CH->>QA: Commit XMITQ 上的批次
    C->>QB: MQGET (Wait, Syncpoint)
    QB-->>C: 訊息
    C->>C: 業務處理
    C->>QB: MQCMIT
    Note over CH,QB: 若目標佇列不存在或已滿,<br/>Receiver 將訊息放入 QM_B 的 DLQ

3.4 MQI 動詞

動詞功能注意事項
MQCONN / MQCONNX連線到 Queue Manager連線成本高,應重複使用;MQCONNX 可帶 TLS、帳密(MQCSP)等選項
MQOPEN開啟物件,取得 Object Handle開啟成本中等;長時間處理的程式應重複使用 Handle
MQPUT放入訊息到已開啟的佇列搭配 MQPMO_SYNCPOINT 或 MQPMO_NO_SYNCPOINT 明確指定
MQPUT1Open + Put + Close 一次完成適合只放一則訊息的情境(例如送 Reply);連續放多則時效能較差
MQGET從佇列取出訊息搭配 MQGMO_WAIT 與 WaitInterval 避免忙碌輪詢
MQINQ查詢物件屬性例如查詢 CURDEPTH,但不應在高頻路徑使用
MQSET修改物件部分屬性僅少數屬性可修改;一般應用程式不應使用
MQCMIT提交交易只在 Syncpoint 內的操作才需要
MQBACK回滾交易被 GET 的訊息回到佇列並增加 BackoutCount
MQCLOSE關閉物件務必在 finally 中執行
MQDISC中斷連線未 Commit 的交易:正常 MQDISC 時在分散式平台上預設會 Commit [需確認:依平台與選項而定,建議應用程式明確 Commit / Backout]

3.5 Syncpoint、Commit、Backout、Rollback

Syncpoint(同步點) 是 MQ 的「交易單位」:

  • 在 Syncpoint 內 PUT 的訊息,Commit 前對其他應用程式不可見。
  • 在 Syncpoint 內 GET 的訊息,Commit 前不會真的被刪除;若 Backout,訊息回到佇列原位。
  • Backout 是 MQ 的術語,JMS / Spring 稱為 Rollback,語意相同。
stateDiagram-v2
    [*] --> OnQueue: MQPUT + Commit
    OnQueue --> InFlight: MQGET (Syncpoint)
    InFlight --> Deleted: MQCMIT
    InFlight --> OnQueue: MQBACK<br/>BackoutCount + 1
    OnQueue --> BackoutQueue: BackoutCount >= BOTHRESH<br/>(由應用程式或 JMS 移動)
    OnQueue --> Expired: 超過 Expiry
    Expired --> [*]: 下次 GET 或掃描時清除
    Deleted --> [*]
    BackoutQueue --> [*]: 人工處理或補償

重要:IBM MQ 本身不會自動把超過 BOTHRESH 的訊息移到 BOQNAME。這個動作由應用程式執行:

  • IBM MQ classes for JMS / Jakarta Messaging:會自動處理(Backout 次數達門檻時,移到 BOQNAME;若未設定或無法放入,則嘗試放到 DLQ,視設定可能保留在原佇列)。
  • MQI / IBM MQ classes for Java:必須自行檢查 BackoutCount 並自行移動訊息(見 Part 10 範例)。

3.6 Persistent 與 Non-persistent

情境PersistentNon-persistent
Queue Manager 正常重啟保留遺失(佇列屬性 NPMCLASS(HIGH) 可在正常關閉時保留,但不保證異常時)
Queue Manager 異常終止已 Commit 的保留遺失
跨 Channel 傳遞以批次、Syncpoint 保護依 NPMSPEED(FAST) 可在 Syncpoint 外快速傳送,Channel 異常時可能遺失

3.7 Message Expiration(訊息逾期)

  • Expiry 單位為 1/10 秒。例如 30 秒 = 300。
  • 逾期訊息不會被 GET 回傳,會在下次 GET 掃描或 Queue Manager 定期掃描時清除(EXPRYINT 屬性)。
  • Request / Reply 的 Request 應設定 Expiry:若後端在 Timeout 後才處理,結果已無人接收。設定 Expiry 可讓逾時請求自動失效。
  • 可設定 MQRO_EXPIRATION Report Option 取得逾期通知。

3.8 Message Priority 與 Message Ordering

  • Priority 0(最低)至 9(最高)。
  • 佇列的 MSGDLVSQ(PRIORITY) 時依 Priority 再 FIFO;MSGDLVSQ(FIFO) 時忽略 Priority。

順序保證條件(全部成立時才能期待 FIFO):

  1. 單一 Producer 執行緒
  2. 相同 Priority
  3. 單一路徑(不經 Cluster Workload Balancing)
  4. 單一 Consumer
  5. 沒有 Backout 造成的重新排序(Backout 後的訊息回到原位,但若同時有其他 Consumer 則順序已被打亂)

需要嚴格順序時的做法:

  • 單一 Consumer(犧牲吞吐量)
  • 以業務鍵分區:同一帳號的訊息送到同一佇列 / 同一 Consumer
  • Message Group 搭配 MQGMO_LOGICAL_ORDER
  • 應用層序號檢查(最可靠)

3.9 Message Group(訊息群組)

一組邏輯上相關的訊息(例如一筆批次的 100 段資料):

  • 共用相同 GroupId
  • 各自有 MsgSeqNumber(從 1 開始)
  • 最後一則設定 MQMF_LAST_MSG_IN_GROUP

Consumer 可使用 MQGMO_ALL_MSGS_AVAILABLE(整組到齊才開始取)與 MQGMO_LOGICAL_ORDER(依序取)。

3.10 Correlation 與 Retry

  • Correlation:Reply 訊息的 CorrelId 設為 Request 的 MsgId(或由應用程式指定的業務 ID),Requester 以 MQMO_MATCH_CORREL_ID 取回對應回覆。
  • Retry 分兩層:
    • 連線層 Retry:2009、2059、2538 等連線錯誤 → 重新連線(可用 Client Auto Reconnect)。
    • 訊息層 Retry:業務處理失敗 → Backout,讓訊息回到佇列,BackoutCount 累加,超過門檻後移到 Backout Queue。

3.11 Dead Letter Queue(DLQ)

何時訊息會進 DLQ:

  • Receiver Channel 無法把訊息放到目標佇列(佇列不存在、已滿、PUT 被禁止、權限不足)
  • Trigger Monitor 無法處理觸發訊息
  • 應用程式主動放入(例如 JMS 無法放入 Backout Queue 時)

每則 DLQ 訊息前面會有一個 Dead Letter Header(MQDLH),記錄原目標佇列、原 Queue Manager、Reason Code。

DLQ 處理工具:runmqdlq(Dead-letter Queue Handler)可依規則表自動重試或轉送。

* runmqdlq 規則表範例(rules.dlq)
* 預設控制:等待新訊息、最多重試 5 次
INPUTQ('SYSTEM.DEAD.LETTER.QUEUE') INPUTQM('QM1') RETRYINT(60) WAIT(YES)
* 目標佇列已滿:最多重試 5 次後轉送到人工處理佇列
REASON(MQRC_Q_FULL) ACTION(RETRY) RETRY(5)
* 其他原因:轉送到人工處理佇列並保留 DLH
ACTION(FWD) FWDQ('BANK.OPS.DLQ.MANUAL') HEADER(YES)

規則表語法細節(關鍵字、比對順序)需依目前 IBM 官方 runmqdlq 文件確認後再上線。

3.12 Transaction 管理:誰是交易協調者

3.5 說明的是「MQ 自己的 Syncpoint」。當同一個工作單元還包含資料庫時,必須先決定誰來協調交易。IBM MQ 支援三種模式:

模式協調者涵蓋資源API適用
Local Unit of WorkQueue Manager只有 MQMQCMIT / MQBACK、JMS session.commit()大部分 MQ 應用
Global UoW(QM 為協調者)Queue ManagerMQ + 支援 XA 的資料庫MQBEGIN → 操作 → MQCMITBindings 模式的 C / COBOL 應用;需在 qm.ini 設定 XA 資源管理器
Global UoW(外部協調者)外部 Transaction Manager(Jakarta EE 應用伺服器的 JTA、CICS、Tuxedo 等)MQ + 資料庫 + 其他 XA 資源JTA UserTransaction / 容器管理交易Jakarta EE 應用伺服器、CICS
flowchart LR
    subgraph Local["Local UoW"]
        A1["應用程式"] -->|"MQPUT / MQGET + MQCMIT"| Q1["Queue Manager"]
    end
    subgraph QMCoord["QM 協調的 Global UoW"]
        A2["應用程式"] -->|"MQBEGIN / MQCMIT"| Q2["Queue Manager<br/>(協調者)"]
        Q2 -->|"XA"| D2[("資料庫")]
    end
    subgraph ExtCoord["外部 TM 協調"]
        A3["應用程式"] --> TM["Transaction Manager<br/>(JTA / CICS)"]
        TM -->|"XA"| Q3["Queue Manager"]
        TM -->|"XA"| D3[("資料庫")]
    end

實務重點:

  • Java Client 模式要參與 XA,需要支援 XA 的 Client(例如在應用伺服器中透過 IBM MQ Resource Adapter),且有額外的授權與設定要求 [需確認]。
  • XA 帶來 in-doubt 交易的處理成本:Queue Manager 重啟時以 DISPLAY CONN(*) TYPE(CONN) UOWSTATE 等方式檢查未決交易,必要時以 dspmqtrn / rsvmqtrn 處理(L4 風險操作)。
  • Spring Boot 微服務通常不採用 XA,而是用 Part 13 的 Best-Effort 1PC + Idempotency 或 Transactional Outbox。
  • z/OS 上,連到 QSG 的交易型應用可使用 GROUP UR Disposition,交易恢復時不必回到原 QM(見 Part 2.10)。

3.13 Message Property 與 Selector

除了 MQMD 的固定欄位,IBM MQ 支援任意名稱的 Message Property(名稱 / 值組),JMS 的 setStringProperty() 等方法即對應到這個機制。

主題說明
屬性儲存新應用以 Message Property 存放;舊 JMS 應用可能以 MQRFH2 標頭存放,佇列屬性 PROPCTL 決定非 JMS 應用看到的形式
PROPCTLCOMPAT(預設,相容舊行為)、NONE、ALL、FORCE、V6COMPAT;Legacy C / COBOL 讀到多出來的 MQRFH2 常是電文解析失敗的原因
SelectorJMS createConsumer(dest, selector) 或 MQI MQOPEN 的 SelectionString,以 SQL92 子集篩選訊息
效能以 JMSCorrelationID / JMSMessageID 篩選可用索引;以自訂屬性篩選會逐筆掃描,深佇列時極慢
[MQ 10.0] MsgTokenJMS Selector 可使用 MsgToken 精準取回特定訊息 [需確認語法]
屬性大小屬性總長度受 MAXPROPL 限制

設計建議:

  1. 路由與篩選需求,優先以「不同佇列」或「Topic 字串」表達,而非 Selector。
  2. 傳給 Legacy 非 JMS 系統的佇列,明確設定 PROPCTL 並搭配 targetClient=MQ(見 Part 11.4)。
  3. 不在 Message Property 放個資或敏感資料;它們會出現在監控工具與 DLQ 瀏覽畫面。

3.14 實務案例

某轉帳 Consumer 的業務邏輯呼叫外部風控 API。風控 API 停機時,每則訊息都拋例外、Backout、立刻再被取出,CPU 飆高,日誌每秒數千筆錯誤。

根因:沒有區分「暫時性錯誤」(風控 API 停機)與「永久性錯誤」(訊息格式錯誤)。

改善:

  1. 永久性錯誤 → 直接移到 Backout Queue,不重試。
  2. 暫時性錯誤 → Backout,但 Listener Container 加上退避延遲;連續失敗超過門檻時暫停 Consumer(Circuit Breaker)。
  3. 設定 BOTHRESH(5)、BOQNAME,確保最終不會無限循環。

3.15 注意事項與 Checklist

  • 所有交易性訊息都使用 Persistent + Syncpoint
  • Request 訊息設定 Expiry
  • 所有 Input Queue 都設定 BOQNAME 與 BOTHRESH
  • Queue Manager 已設定 DEADQ
  • 已區分暫時性錯誤與永久性錯誤
  • 有順序需求的流程,已明確寫出順序保證的前提
  • MQPUT1 只用在單次放入情境

Part 4 — IBM MQ 安裝

4.1 目的

說明在 Linux、Windows、Container、Kubernetes 四種環境建立 IBM MQ 的方法與企業導入時的考量。本章命令以 Linux x86-64 與 IBM MQ 10.0 為例;實際套件名稱、檔名與支援的 OS 版本,需依目前 IBM 官方文件與 System Requirements 確認。

4.2 Linux 安裝

4.2.1 安裝前準備

項目建議說明
OS依 System Requirements 支援清單(RHEL、Ubuntu、SLES 等)[需確認] 10.0 支援的確切 OS 版本
檔案系統/opt/mqm(程式)、/var/mqm(資料)、Log 目錄分開Log 與 Queue Data 建議放不同磁碟,避免 I/O 互相干擾
磁碟Log 放在低延遲儲存Persistent Message 效能主要受 Log 寫入延遲影響
Kernel 參數依 mqconfig 檢查結果調整檔案描述元、行程數、共享記憶體
使用者mqm 使用者與 mqm 群組安裝程式可自動建立;企業環境建議預先建立並固定 UID / GID(跨節點一致,HA 必要)
時間同步NTP / chrony訊息時間戳記與日誌比對、TLS 憑證效期檢查都依賴系統時間
# 預先建立 mqm 群組與使用者(UID/GID 在所有節點保持一致)
sudo groupadd -g 1001 mqm
sudo useradd -u 1001 -g mqm -d /var/mqm -s /bin/bash mqm

# 檢查檔案描述元與行程上限(以 mqm 使用者執行 mqconfig,安裝後可用)
ulimit -n
ulimit -u

4.2.2 套件安裝(RPM)

# 解壓安裝媒體後,接受授權
cd /tmp/mq10/MQServer
sudo ./mqlicense.sh -accept

# 安裝最小 Server 組合(實際套件清單依需求增減)
sudo rpm -ivh MQSeriesRuntime-*.rpm MQSeriesServer-*.rpm \
              MQSeriesJRE-*.rpm MQSeriesJava-*.rpm \
              MQSeriesGSKit-*.rpm MQSeriesSamples-*.rpm \
              MQSeriesWeb-*.rpm

# 設定為主要安裝(Primary Installation)
sudo /opt/mqm/bin/setmqinst -i -p /opt/mqm

# 確認版本
dspmqver

Ubuntu / Debian 使用 .deb 套件與 apt;套件名稱不同,請依官方文件。生產環境建議使用公司內部套件庫並記錄套件 checksum。

4.2.3 Environment Variables

# 在 mqm 使用者的 shell 載入 MQ 環境
. /opt/mqm/bin/setmqenv -s

# 常用確認
echo $PATH | tr ':' '\n' | grep mqm
dspmqver -f 2   # 只顯示版本

4.2.4 建立 Queue Manager

# 以 mqm 使用者執行
# -u:指定 DLQ 名稱;-lc:Circular Log;-lf:Log 檔大小(4KB 頁數)
# -lp / -ls:主要 / 次要 Log 檔數量;-ic:建立後自動套用的 MQSC 檔
crtmqm -u SYSTEM.DEAD.LETTER.QUEUE \
       -lc -lf 16384 -lp 10 -ls 20 \
       -ic /var/mqm/config/BANKQM01.mqsc \
       BANKQM01

strmqm BANKQM01
dspmq -m BANKQM01 -o all
參數說明建議
-uDLQ 名稱一律設定
-lc / -llCircular / Linear Log依備援與媒體復原需求(見 Part 2.3、Part 26)
-lfLog 檔大小(4KB 頁)依交易量估算
-lp / -ls主要 / 次要 Log 數長交易(Long-running UOW)多時加大
-ic啟動時自動套用 MQSC(Autoconfig)[MQ 9.2+]搭配 Configuration as Code
-ii啟動時自動套用 qm.ini 片段 [MQ 9.2+]搭配 Configuration as Code

4.2.5 Listener、Channel、Queue 基本設定

建立 /var/mqm/config/BANKQM01.mqsc:

* ===== Listener =====
DEFINE LISTENER('BANK.LSTR.1414') TRPTYPE(TCP) PORT(1414) CONTROL(QMGR) REPLACE

* ===== Application SVRCONN Channel(TLS 1.3,必須帶用戶端憑證)=====
DEFINE CHANNEL('PAY.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
       SSLCIPH('ANY_TLS13_OR_HIGHER') SSLCAUTH(REQUIRED) +
       MAXINST(200) MAXINSTC(50) SHARECNV(10) +
       DESCR('Payment service client channel') REPLACE

* ===== Application Queues =====
DEFINE QLOCAL('PAY.TXN.REQ.BOQ') DEFPSIST(YES) MAXDEPTH(100000) +
       DESCR('Payment request backout queue') REPLACE
DEFINE QLOCAL('PAY.TXN.REQ') DEFPSIST(YES) MAXDEPTH(200000) MAXMSGL(1048576) +
       BOTHRESH(5) BOQNAME('PAY.TXN.REQ.BOQ') +
       QDEPTHHI(80) QDPHIEV(ENABLED) +
       DESCR('Payment request queue') REPLACE

TLS 憑證設定(SSLKEYR / CERTLABL)與安全設定(CHLAUTH、CONNAUTH、OAM)見 Part 8。以上僅為結構示範,上線前須完成 Part 8 Security Baseline。

4.2.6 啟動 / 停止

命令功能Production 風險
strmqm QM啟動低
endmqm -c QMControlled:等待應用程式斷線可能長時間無法停止
endmqm -w QMControlled 並等待完成同上,但會回報結果
endmqm -i QMImmediate:不等待應用程式,未完成交易回滾應用程式收到 2161 / 2162 / 2009
endmqm -p QMPreemptive:強制最後手段;可能需要較長的重啟復原時間
endmqm -s QMSwitchover(Multi-instance / HA)需確認 Standby 狀態正常
dspmq -o all顯示所有 QM 狀態無

4.3 Windows 安裝

項目說明
安裝執行安裝程式(setup.exe)或以 msiexec 搭配 response file 靜默安裝
帳號安裝會建立本機 mqm 群組;網域環境需設定可查詢群組成員的服務帳號 [需確認]
ServiceQueue Manager 以 Windows Service 形式執行(「IBM MQ (Installation1)」),可設為自動啟動
MQ Explorer圖形管理工具;取得方式(隨產品或獨立下載)依版本不同 [需確認]
MQSC開啟「Command Prompt」後執行 runmqsc QM
環境使用 setmqenv -s 或安裝時設定的 Primary Installation
# 建立與啟動
crtmqm -u SYSTEM.DEAD.LETTER.QUEUE BANKQM01
strmqm BANKQM01
dspmq -o all

# 進入 MQSC
runmqsc BANKQM01

Windows 注意事項:

  • [MQ 10.0] 支援較長的 User ID,但同時加強 User ID 驗證;升級前須盤點既有 MCAUSER 與 OAM 授權的帳號格式。
  • 網域帳號授權使用 user@domain 或 domain\user 格式時,需依官方文件確認 OAM 的解析方式。

4.4 Container

4.4.1 IBM MQ Container 概念

IBM 提供官方 MQ container image:

  • IBM MQ Advanced for Developers:開發用,icr.io/ibm-messaging/mq,不可用於 Production。
  • Production image:IBM MQ Advanced / Cloud Pak for Integration 授權取得。[MQ 9.4 CD] 起 IBM MQ Advanced container image 支援在 OpenShift 以外部署。[需確認] 取得方式與授權。

4.4.2 開發環境快速啟動(Docker / Podman)

# 開發用途:以 secret 檔提供密碼,不要把密碼寫在命令列歷史
podman volume create qm1data
podman run -d --name QM1 \
  -p 1414:1414 -p 9443:9443 \
  -e LICENSE=accept \
  -e MQ_QMGR_NAME=QM1 \
  -v qm1data:/mnt/mqm \
  --secret mqAdminPassword,target=/run/secrets/mqAdminPassword \
  --secret mqAppPassword,target=/run/secrets/mqAppPassword \
  icr.io/ibm-messaging/mq:<pinned-tag>

Developer image 的預設帳號與 DEV.* 物件、密碼設定方式(環境變數或 secret 檔)依 image 版本而不同,需依 ibm-messaging/mq-container 的對應版本說明確認。mq-jms-spring 官方說明指出 Developer image 已移除預設密碼,必須明確設定。

4.4.3 Production Container 設計重點

面向設計
Persistent Volume/mnt/mqm(Queue 與 Log)必須掛載持久化儲存;Log 與 Data 可分不同 Volume
Configuration透過 /etc/mqm/*.mqsc 與 *.ini 在啟動時套用(Autoconfig),存放在 Git
Secret密碼、TLS 私鑰以 Secret 掛載;不放進 image、不放進環境變數
TLS憑證以 Secret 掛載到 image 規定的路徑 [需確認];憑證輪替流程需演練
LifecycleContainer 停止時應讓 Queue Manager 正常結束(graceful);設定足夠的 termination grace period
Image 版本固定 tag 或 digest,不使用 latest

4.5 Kubernetes

面向企業導入考量
Stateful WorkloadQueue Manager 是有狀態服務,使用 StatefulSet 或 IBM MQ Operator 的 QueueManager 自訂資源
Persistent Storage使用支援 ReadWriteOnce、低延遲的 Block Storage;Multi-instance 需 RWX 共享檔案系統(不建議新設計)
SecretTLS 金鑰、管理員密碼以 Kubernetes Secret 搭配外部 Secret Manager(Vault 等)
ConfigMapMQSC、qm.ini 片段;變更需走 GitOps 與審核
NetworkService(ClusterIP / LoadBalancer)、OpenShift Route(需 TLS SNI);Client 連線需設定 OutboundSNI [需確認]
TLS全程 TLS;Route 以 passthrough 方式讓 MQ 自行終結 TLS
MonitoringPrometheus metrics(MQ Operator 或 mq-metric-samples exporter)
High AvailabilityNative HA:3 個 Pod 複寫 Log;[MQ 10.0] 新增 In-Region Replication(IRR);[MQ 9.4 CD] Cross-Region Replication(CRR)在容器可用
flowchart TB
    subgraph K8s["Kubernetes / OpenShift Cluster"]
        subgraph NS["Namespace: mq-prod"]
            OP["IBM MQ Operator"]
            subgraph NHA["QueueManager CR: BANKQM01(Native HA)"]
                P0["Pod-0<br/>Active"]
                P1["Pod-1<br/>Replica"]
                P2["Pod-2<br/>Replica"]
            end
            PV0[("PVC-0")]
            PV1[("PVC-1")]
            PV2[("PVC-2")]
            SVC["Service :1414"]
            SEC["Secret<br/>TLS / Password"]
            CM["ConfigMap<br/>MQSC / INI"]
        end
        APP["Spring Boot Pods"]
    end
    OP --> NHA
    P0 --- PV0
    P1 --- PV1
    P2 --- PV2
    P0 <-. "Log 複寫" .-> P1
    P0 <-. "Log 複寫" .-> P2
    SEC --> NHA
    CM --> NHA
    APP -- "TLS" --> SVC --> P0

IBM MQ Operator 的版本、CRD 欄位、與 MQ 10.0 對應關係,需依目前 IBM 官方文件確認。

4.6 AI Agent 使用方式

  • 請 AI 依照公司範本產生 crtmqm 參數、MQSC 檔與 Kubernetes YAML,但只在 DEV / TEST 執行。
  • 請 AI 比對 System Requirements 與目前 OS / JDK 版本,列出不相容項目,並附上官方連結供人工確認。

4.7 常見錯誤

  • 以 root 執行 Queue Manager 管理命令(應以 mqm 群組成員執行)。
  • Log 與 Data 放在同一顆慢速磁碟,Persistent 效能低落。
  • 容器使用 latest tag,某天重新部署後版本不同。
  • 把 Developer image 帶進 Production。

4.8 Checklist

  • OS、JDK、容器平台版本已對照 IBM System Requirements
  • mqm UID / GID 在所有節點一致
  • Log 與 Data 分離,Log 位於低延遲儲存
  • crtmqm 參數(Log 類型、大小、DLQ)已記錄於設計文件
  • MQSC 設定存放於 Git,透過 -ic 或 Autoconfig 套用
  • Container image 已固定版本(tag / digest)
  • 密碼、TLS 私鑰全部透過 Secret 管理

Part 5 — IBM MQ 系統管理

5.1 目的

建立 Queue Manager 日常管理的標準做法,包含 Control Commands、MQSC 命令與 Production 操作風險分級。

5.2 管理工具總覽

工具說明適用
Control Commandscrtmqm、strmqm、endmqm、dspmq、dltmqm、setmqaut、dmpmqcfg 等 OS 命令主機上的管理員
runmqscMQSC 命令直譯器物件定義、查詢、維運
IBM MQ ConsoleWeb 管理介面(mqweb)圖形化查詢與操作
REST API(Administrative)透過 HTTPS 執行 MQSC 或查詢 [MQ 9.3+ 提供 v3]自動化、Portal 整合
PCFProgrammable Command Format,程式化管理監控工具、自動化腳本
MQ Explorer桌面圖形工具管理員日常操作

5.3 Queue Manager 管理

動作命令說明
建立crtmqm見 Part 4
啟動strmqm QM
停止endmqm -i QM見 Part 4.2.6 風險表
顯示狀態dspmq -o all、DISPLAY QMSTATUS ALL
顯示設定DISPLAY QMGR ALL
備份設定dmpmqcfg -m QM -a > QM.mqsc匯出所有物件定義與授權(含 -a 為全部),可用 runmqsc QM < QM.mqsc 重建
備份資料停機冷備份 / Linear Log 的 rcdmqimg / 儲存層快照見 Part 26
還原以 dmpmqcfg 輸出重建物件;資料以 HA/DR 方案還原
刪除dltmqm QM極高風險,Production 禁止 AI 執行
# 每日設定備份(建議排程,並納入版本控制比對差異)
dmpmqcfg -m BANKQM01 -a -o mqsc > /backup/mqcfg/BANKQM01_$(date +%Y%m%d).mqsc

# 只匯出授權記錄
dmpmqcfg -m BANKQM01 -x authrec -o setmqaut > /backup/mqcfg/BANKQM01_auth_$(date +%Y%m%d).sh

dmpmqcfg 的 -x 物件類型與輸出格式選項,請依目前官方文件確認。

5.4 MQSC 與 runmqsc

runmqsc 是 MQSC 命令的互動式 / 批次直譯器。

# 互動模式
runmqsc BANKQM01

# 批次模式(套用檔案)
runmqsc BANKQM01 < change-2026-10-001.mqsc > change-2026-10-001.out

# 只檢查語法、不實際執行(-v:verify)
runmqsc -v BANKQM01 < change-2026-10-001.mqsc

# 遠端管理(透過 Client 連線,需設定 CCDT 或 MQSERVER 與適當權限)
runmqsc -c BANKQM01

MQSC 語法要點:

  • 未加引號的名稱轉為大寫;含小寫或特殊字元必須加單引號。
  • 行尾 + 或 - 表示接續下一行(+ 去除下一行前導空白、- 保留)。
  • * 開頭為註解。
  • REPLACE 讓 DEFINE 可重複執行(冪等),但會覆蓋未指定的屬性為預設值或 LIKE 物件的值,在 Production 使用前須確認。

5.5 常用查詢命令(DISPLAY)

命令功能使用時機注意事項Production 風險
DISPLAY QMGR ALL顯示 QM 屬性盤點、比對設定輸出長,可指定屬性無
DISPLAY QMSTATUS ALLQM 執行狀態健康檢查無
DISPLAY QLOCAL(*)列出 Local Queue盤點加 WHERE(CURDEPTH GT 0) 篩選無
DISPLAY QSTATUS('Q') TYPE(QUEUE) ALL佇列即時狀態:深度、開啟數、最後 GET/PUT 時間堵塞排查MSGAGE、QTIME 需 MONQ 啟用無
DISPLAY QSTATUS('Q') TYPE(HANDLE) ALL誰開啟了佇列找出 Consumer / Producer無
DISPLAY QREMOTE(*)Remote Queue 定義路由排查無
DISPLAY QALIAS(*)Alias 定義路由排查無
DISPLAY CHANNEL(*)Channel 定義盤點無
DISPLAY CHSTATUS(*) ALLChannel 即時狀態Channel Down 排查無輸出代表 INACTIVE無
DISPLAY LISTENER(*)、DISPLAY LSSTATUS(*)Listener 定義 / 狀態連線失敗排查無
DISPLAY CONN(*) TYPE(CONN) ALL目前連線找出連線來源、Application Tag可配合 WHERE(APPLTAG EQ '...')無
DISPLAY SUB(*)、DISPLAY SBSTATUS(*)訂閱Pub/Sub 排查無
DISPLAY CHLAUTH(*)Channel 認證規則2035 / AMQ9777 排查無
DISPLAY AUTHRECOAM 授權記錄2035 排查無
DISPLAY CLUSQMGR(*)Cluster 成員Cluster 健康檢查無
* 找出所有有訊息堆積的應用佇列
DISPLAY QLOCAL('PAY.*') WHERE(CURDEPTH GT 0) CURDEPTH MAXDEPTH

* 佇列是否有 Consumer 在讀?(IPPROCS = 開啟 Input 的數量)
DISPLAY QSTATUS('PAY.TXN.REQ') TYPE(QUEUE) CURDEPTH IPPROCS OPPROCS LGETDATE LGETTIME MSGAGE

* 某應用程式的連線
DISPLAY CONN(*) TYPE(CONN) WHERE(APPLTAG EQ 'payment-service') CHANNEL CONNAME USERID

5.6 常用定義與修改命令

命令功能使用時機注意事項Production 風險
DEFINE QLOCAL(...)建立 Local Queue新服務上線搭配 BOQNAME、MAXDEPTH低(新增)
DEFINE QREMOTE(...)建立 Remote Queue跨 QM 路由RNAME、RQMNAME、XMITQ 需正確低
DEFINE CHANNEL(...)建立 Channel新連線名稱兩端一致;TLS 參數中(影響安全邊界)
DEFINE LISTENER(...)建立 Listener新連接埠防火牆規則中
ALTER QLOCAL(...)修改佇列屬性調整深度、門檻PUT(DISABLED) / GET(DISABLED) 會中斷應用中-高
ALTER CHANNEL(...)修改 ChannelTLS、MCAUSER 調整須重啟 Channel 才生效高
DELETE QLOCAL(...)刪除佇列下架有訊息時會失敗,PURGE 會連訊息一起刪除極高
CLEAR QLOCAL(...)清空佇列測試環境訊息不可恢復極高
START CHANNEL(...) / STOP CHANNEL(...)啟停 Channel維運STOP ... MODE(QUIESCE) 較安全中
RESET CHANNEL(...) SEQNUM(n)重設序號序號不一致(AMQ9526)確認無 in-doubt 後才執行高
RESOLVE CHANNEL(...) ACTION(COMMIT/BACKOUT)解決 in-doubt 批次Channel in-doubt選錯會造成訊息重複或遺失極高
REFRESH SECURITY TYPE(...)重新載入安全快取修改 OAM / CONNAUTH 後中
SET CHLAUTH(...)設定 Channel 認證規則安全調整規則錯誤會封鎖所有連線極高
SET AUTHREC(...)設定 OAM 授權權限調整避免 +all高
* 下架佇列的安全程序(Production 需經變更審核)
* 1. 先禁止 PUT,觀察是否有 Producer 失敗
ALTER QLOCAL('OLD.APP.REQ') PUT(DISABLED)
* 2. 確認深度歸零、無 Consumer 開啟
DISPLAY QSTATUS('OLD.APP.REQ') TYPE(QUEUE) CURDEPTH IPPROCS OPPROCS
* 3. 備份定義
*    (OS 層)dmpmqcfg -m BANKQM01 -n OLD.APP.REQ -t queue
* 4. 觀察期後刪除(不使用 PURGE)
DELETE QLOCAL('OLD.APP.REQ')

5.7 Production 操作風險分級

等級定義範例要求
L0 唯讀不改變任何狀態DISPLAY *、dspmq可自動化;AI 可協助產生
L1 低風險新增新增不影響既有流量的物件DEFINE QLOCAL 新佇列變更單 + 審核
L2 中風險修改修改既有物件屬性ALTER QLOCAL MAXDEPTH變更單 + 審核 + 回復步驟
L3 高風險影響連線或安全ALTER CHANNEL、SET AUTHREC、STOP CHANNEL變更單 + 雙人覆核 + 維護時段 + 回復計畫
L4 不可逆資料或安全邊界不可恢復CLEAR、DELETE ... PURGE、SET CHLAUTH、RESOLVE CHANNEL、dltmqm、endmqm -pL3 要求 + 備份驗證 + 主管核准;AI 禁止執行

5.8 管理方式全景與命令集比較

IBM MQ 提供多組管理介面,同一件事通常有三四種做法。企業必須明確規定「哪種情境用哪種介面」,否則稽核時無法說明某個設定是誰、透過什麼管道改的。

介面執行位置可否遠端可否建立 / 啟動 QM自動化友善稽核來源建議用途
Control Commands(crtmqm、strmqm…)QM 主機 OS否是中(Shell 腳本)OS 稽核、Shell 歷史QM 生命週期、安裝、備份
MQSC(runmqsc)本機或遠端是(-w、-c)否高(檔案化、可 -v 驗證)Command Event、變更單物件定義的標準管道,搭配 Git
PCF任何能連 QM 的程式是否高(程式化)Command Event監控工具、自訂管理程式
Administrative REST APImqweb(HTTPS)是否高(HTTP / JSON)mqweb 稽核日誌、Command EventPortal、Pipeline、跨平台腳本
IBM MQ Console瀏覽器是否(可管理既有本機 QM)低mqweb 日誌查詢、緊急人工操作
IBM MQ Explorer桌面程式是否(本機可建立)低Command Event管理員日常瀏覽
Taskbar 應用(Windows)Windows 工作列否否無—開發機
IBM i CL / z/OS 主控台、ISPF、CSQUTIL平台原生依平台依平台中平台稽核(SMF 等)IBM i、z/OS(見 5.13)
flowchart TD
    S(["管理需求"]) --> A{"建立 / 啟停 QM?"}
    A -- 是 --> CC["Control Commands<br/>(須登入主機或由 Agent / Operator 代執行)"]
    A -- 否 --> B{"變更物件定義?"}
    B -- 是 --> MQSC["MQSC 檔案 + Git + runmqsc -v<br/>經 Pipeline 套用"]
    B -- 否 --> C{"程式化查詢 / 監控?"}
    C -- 是 --> D{"程式語言?"}
    D -- "Java / C" --> PCF["PCF"]
    D -- "任何 HTTP 用戶端" --> REST["Administrative REST API"]
    C -- 否 --> UI["Console / Explorer<br/>(Production 預設唯讀角色)"]

企業規範建議:Production 物件變更只能透過「MQSC 檔案 + Pipeline」;Console 與 Explorer 在 Production 預設只給唯讀權限;REST 與 PCF 的寫入權限只發給受控的自動化帳號。

5.9 本機管理與遠端管理

方式原理前提限制
本機管理在 QM 所在主機執行命令OS 帳號屬於 mqm 或具備相應權限需登入主機
經由 QM 的遠端管理本機 QM 把命令訊息透過 Channel 送到遠端 QM 的 SYSTEM.ADMIN.COMMAND.QUEUE兩端 QM 之間有 Sender / Receiver Channel 與 Transmission Queue;遠端 Command Server 執行中不能建立、啟動 QM,也不能啟動 Command Server
Client 模式遠端管理runmqsc -c 以 MQI Client 連到遠端 QM有可用的 SVRCONN、CCDT 或 MQSERVER、適當權限同上
# 檢查 / 啟動 Command Server(QM 屬性 SCMDSERV(QMGR) 時會隨 QM 自動啟動)
dspmqcsv BANKQM01
strmqcsv BANKQM01

# 經由本機 QM(-m)把命令送到遠端 QM,-w 為等待回覆秒數
runmqsc -w 30 -m ADMINQM01 BANKQM02

# 以 Client 模式直接連遠端 QM(使用 CCDT)
export MQCCDTURL=file:///etc/mq/admin-ccdt.json
runmqsc -c BANKQM02

安全要求:

  • 遠端管理使用專用的管理 SVRCONN(例如 ADM.SVRCONN),強制 TLS + 用戶端憑證,以 CHLAUTH 限制來源 IP 與憑證 DN。
  • 以 CHLAUTH 封鎖 SYSTEM.ADMIN.SVRCONN、SYSTEM.DEF.SVRCONN 等預設 Channel 的外部存取。
  • 啟用 Command Event(ALTER QMGR CMDEV(ENABLED))與 Configuration Event(CONFIGEV(ENABLED)),讓所有遠端變更都留下紀錄。

5.10 PCF 與 MQAI 自動化

PCF(Programmable Command Format) 是 MQSC 的程式化版本:程式把一則帶有 MQCFH 標頭與參數結構的訊息放到 SYSTEM.ADMIN.COMMAND.QUEUE,Command Server 執行後把結果放回 Reply Queue。監控工具(例如 mq-metric-samples)、IBM MQ Explorer 與許多商業工具都是透過 PCF 運作。

項目說明
命令代碼MQCMD_INQUIRE_Q、MQCMD_INQUIRE_Q_STATUS、MQCMD_INQUIRE_CHANNEL_STATUS 等
Java 支援com.ibm.mq.headers.pcf 套件(PCFMessageAgent、PCFMessage)
C 支援直接組 PCF 結構,或使用 MQAI(MQ Administration Interface,mqExecute 等,以「資料袋」抽象化 PCF)
權限需要 SYSTEM.ADMIN.COMMAND.QUEUE 的 put、Reply Queue 的 get,以及目標物件的 dsp(查詢)或 chg 等權限
[MQ 10.0]新增以程式化方式讀取 Error Log 的能力 [需確認 PCF 命令名稱]

以下範例為 L0 唯讀的佇列深度巡檢,可作為監控與 AI Agent 工具的基礎:

package com.tutorial.mq.admin;

import com.ibm.mq.MQException;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.constants.CMQC;
import com.ibm.mq.constants.CMQCFC;
import com.ibm.mq.headers.MQDataException;
import com.ibm.mq.headers.pcf.PCFMessage;
import com.ibm.mq.headers.pcf.PCFMessageAgent;

import java.io.IOException;
import java.util.LinkedHashMap;
import java.util.Map;

/**
 * 以 PCF 查詢 Local Queue 深度(唯讀巡檢,Production 風險等級 L0)。
 */
public final class QueueDepthInspector {

    private QueueDepthInspector() {
    }

    /**
     * 查詢符合名稱樣式的 Local Queue 目前深度。
     *
     * @param queueManager 已連線的 Queue Manager(呼叫端負責中斷連線)
     * @param namePattern  佇列名稱樣式,例如 {@code PAY.*}
     * @return 佇列名稱與目前深度
     * @throws MQDataException PCF 回應格式錯誤或命令失敗
     * @throws MQException     MQ 呼叫失敗
     * @throws IOException     讀取回應失敗
     */
    public static Map<String, Integer> inquireDepth(MQQueueManager queueManager, String namePattern)
            throws MQDataException, MQException, IOException {
        PCFMessageAgent agent = new PCFMessageAgent(queueManager);
        try {
            PCFMessage request = new PCFMessage(CMQCFC.MQCMD_INQUIRE_Q);
            request.addParameter(CMQC.MQCA_Q_NAME, namePattern);
            request.addParameter(CMQC.MQIA_Q_TYPE, CMQC.MQQT_LOCAL);
            request.addParameter(CMQCFC.MQIACF_Q_ATTRS,
                    new int[] {CMQC.MQCA_Q_NAME, CMQC.MQIA_CURRENT_Q_DEPTH, CMQC.MQIA_MAX_Q_DEPTH});

            Map<String, Integer> depths = new LinkedHashMap<>();
            for (PCFMessage response : agent.send(request)) {
                depths.put(response.getStringParameterValue(CMQC.MQCA_Q_NAME).trim(),
                        response.getIntParameterValue(CMQC.MQIA_CURRENT_Q_DEPTH));
            }
            return depths;
        } finally {
            agent.disconnect();
        }
    }
}

PCFMessageAgent 位於 IBM MQ classes for Java 的 com.ibm.mq.headers.pcf 套件;所需 artifact 與 Jakarta 環境下的可用性,請依使用版本確認 [需確認]。PCF 帳號只授予 dsp 權限即可完成巡檢,不要用管理員帳號跑監控。

5.11 Administrative REST API

Administrative REST API 由 mqweb server 提供(見 Part 2.11),讓任何能發 HTTPS 請求的工具都能管理 MQ。v3 起建議使用 MQSC 端點,以 JSON 傳送 MQSC 命令。

項目說明
基礎路徑https://<host>:9443/ibmmq/rest/v3/admin/...
查詢 QMGET /ibmmq/rest/v3/admin/qmgr/{qmgr}
執行 MQSCPOST /ibmmq/rest/v3/admin/action/qmgr/{qmgr}/mqsc,Body 為 runCommand(純文字命令)或 runCommandJSON(結構化)
CSRF 保護POST、PATCH、DELETE 須帶 ibm-mq-rest-csrf-token 標頭(值不限)
認證HTTP Basic、登入取得 LTPA Token(/ibmmq/rest/v3/login)、Client 憑證
授權mqweb 角色(MQWebAdmin / MQWebAdminRO / MQWebUser)+ MQWebUser 情境下的 OAM
# 帳密放在權限 600 的 netrc 檔,避免出現在命令列歷史與行程清單
# ~/.mq-rest.netrc:machine mqweb.bank.local login ops-ro password ********

# 唯讀:查詢 Queue Manager(MQWebAdminRO 即可)
curl -sS --cacert /etc/mq/ca.pem --netrc-file ~/.mq-rest.netrc \
  "https://mqweb.bank.local:9443/ibmmq/rest/v3/admin/qmgr/BANKQM01"

# 唯讀:以 runCommandJSON 查詢佇列深度(POST 必須帶 CSRF 標頭)
curl -sS --cacert /etc/mq/ca.pem --netrc-file ~/.mq-rest.netrc \
  -H "Content-Type: application/json" \
  -H "ibm-mq-rest-csrf-token: ops" \
  -X POST "https://mqweb.bank.local:9443/ibmmq/rest/v3/admin/action/qmgr/BANKQM01/mqsc" \
  -d '{"type":"runCommandJSON","command":"display","qualifier":"qlocal","name":"PAY.*","responseParameters":["curdepth","maxdepth"]}'

治理重點:

  • REST 寫入命令與 MQSC 一樣屬於 L1-L4,必須經變更流程;Pipeline 帳號與人員帳號分開。
  • 不要使用 -k(略過憑證驗證);mqweb 憑證要納入憑證到期監控。
  • mqweb 的 HTTP 連接埠預設應關閉,只開 HTTPS。
  • REST 回應中的 overallCompletionCode / overallReasonCode 要檢查,HTTP 200 不代表每個 MQSC 都成功。
  • JSON 欄位與端點細節以 IBM MQ 10.0 REST API Reference 為準 [需確認]。

5.12 IBM MQ Console 與 IBM MQ Explorer

項目IBM MQ ConsoleIBM MQ Explorer
形態瀏覽器(mqweb)Eclipse 架構的桌面程式(Windows / Linux)
取得方式隨 Server 安裝獨立下載 [需確認 10.0 取得方式]
管理範圍同主機 QM;可設定遠端 QM 連線本機與遠端 QM(透過 Client 連線)
認證mqweb 使用者登錄(LDAP 建議)依連線使用的 Channel 與 CONNAUTH
[MQ 10.0]Console 功能強化 [需確認細節]支援 FIPS 合規模式
適合營運查詢、儀表板、跨團隊共用管理員日常瀏覽與除錯

Production 使用原則:

  1. 依角色給權限:維運人員 MQWebAdminRO,只有 MQ 管理員群組有 MQWebAdmin。
  2. Explorer 連 Production 必須走 TLS 管理 Channel(5.9),不可使用 SYSTEM.ADMIN.SVRCONN 的預設設定。
  3. Console 與 Explorer 的變更不應成為常態;若緊急人工變更,事後必須以 dmpmqcfg 回寫到 Git 中的 MQSC,避免設定漂移。

5.13 IBM MQ for z/OS 系統管理

本節延續 Part 2.10 的架構,整理 z/OS 管理員的日常命令。z/OS 上的命令以「命令前綴字串(CPF)」區分 Queue Manager,例如 -QM01。

命令入口

入口說明使用時機
z/OS 主控台 + CPF-QM01 DISPLAY QLOCAL(*)啟停、緊急操作
ISPF Operations and Control 面板互動式選單管理員日常操作
CSQUTIL COMMAND 功能以 Batch Job 執行 MQSC大量定義、排程巡檢
初始化輸入資料集CSQINP1(啟動早期參數)、CSQINP2(物件定義)、CSQINPX(CHIN 啟動時執行)QM / CHIN 啟動
MQSC 遠端 / PCF / REST / Console與分散式平台相同概念自動化、跨平台管理

常用命令

命令功能Production 風險
-QM01 START QMGR / STOP QMGR MODE(QUIESCE)啟停 Queue ManagerL3
-QM01 START CHINIT / STOP CHINIT啟停 Channel InitiatorL3
DISPLAY SYSTEM、DISPLAY QMGR系統參數與 QM 屬性L0
DISPLAY USAGE TYPE(ALL)Page Set、Buffer Pool、Log 使用量L0
DISPLAY LOG、DISPLAY ARCHIVELog 狀態L0
ARCHIVE LOG強制切換並歸檔 Active LogL2
DISPLAY GROUPQSG 成員L0
DISPLAY CFSTRUCT(*)、DISPLAY CFSTATUS(*) TYPE(SUMMARY)CF Structure 定義與狀態L0
BACKUP CFSTRUCT(APP1)備份 CF Structure 中的持久性訊息L1(需排程)
RECOVER CFSTRUCT(APP1)從備份與 Log 復原 CF StructureL4
ALTER BUFFPOOL(n) BUFFERS(...)調整 Buffer PoolL3
DEFINE PSID(n) BUFFPOOL(m)新增 Page Set 對應L2
任一命令加 CMDSCOPE(*)在 QSG 所有成員執行風險隨命令放大,寫入命令禁止 AI 產生 CMDSCOPE(*) 而未經審核
//MQDISP   JOB (ACCT),'MQ DAILY CHECK',CLASS=A,MSGCLASS=X
//* L0 唯讀巡檢:以 CSQUTIL 對 QSG 所有成員查詢應用佇列深度
//CSQUTIL  EXEC PGM=CSQUTIL,PARM='QM01'
//STEPLIB  DD DISP=SHR,DSN=thlqual.SCSQANLE
//         DD DISP=SHR,DSN=thlqual.SCSQAUTH
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
COMMAND DDNAME(CMDINP)
/*
//CMDINP   DD *
DISPLAY QLOCAL('PAY.*') CURDEPTH MAXDEPTH CMDSCOPE(*)
DISPLAY CFSTATUS(*) TYPE(SUMMARY)
DISPLAY USAGE TYPE(PAGESET)
/*

thlqual 為安裝時的高階限定詞;JCL 與資料集名稱依各機構標準調整。

公用程式

程式用途
CSQUTIL執行命令、匯出物件定義(SDEFS)、Page Set 複製 / 載入 / 清空 / 格式化
CSQ5PQSG在 Db2 中新增或移除 QSG 與成員 QM
CSQJU003 / CSQJU004修改 / 列印 BSDS(Log 資料集清單)
CSQ4INSG 等範例預設物件與系統物件定義範本

SMF 與監控資料

紀錄內容啟用
SMF 115Queue Manager 統計(Log、Buffer Pool、Page Set、CF 使用量等)START TRACE(STAT) CLASS(...)
SMF 116Accounting(每個連線 / 每個佇列的 MQI 用量、Channel Accounting)START TRACE(ACCTG) CLASS(...)
[MQ 10.0] 變更SMF 115 / 116 的 Release 欄位變更;Channel Accounting 新欄位;整合 OpenTelemetry tracing;新的驗證失敗訊息依官方說明調整報表程式 [需確認]

Trace class 編號、STATIME 間隔與 SMF 報表工具(例如 MQSMF 範例程式)請依 IBM MQ for z/OS 文件確認後再啟用;SMF 116 Class 3 資料量大,需先評估。

z/OS 管理的 Production 風險

  • RECOVER CFSTRUCT、Page Set 復原、BSDS 修改屬 L4,必須由主機系統程式師與 MQ 管理員雙人執行。
  • CF Structure 容量不足會導致 Shared Queue 上的 MQPUT 失敗(2192 等),應監控 CF 使用率並排程 BACKUP CFSTRUCT。
  • Db2 是 QSG 物件定義的共用儲存,Db2 不可用會影響 QSG 物件的定義與變更。

5.14 擴充元件管理

元件常用管理命令 / 設定重點
MFTfteSetupCoordination、fteCreateAgent、fteStartAgent、fteStopAgent、ftePingAgent、fteListAgents、fteCreateTransfer、fteCreateMonitor、fteCreateLoggerCoordination QM 與 Agent QM 規劃;傳輸紀錄(Logger)寫入資料庫或檔案以供稽核
MQIPTmqipt <設定目錄> 啟動、mqiptAdmin 管理;mqipt.conf 定義 Route(ListenerPort、Destination、DestinationPort、TLS)放 DMZ;[MQ 10.0] 升級前檢查 CipherSuite 與 Java Security Manager 相關設定
AMQPDEFINE CHANNEL('APP.AMQP') CHLTYPE(AMQP) PORT(5672);START SERVICE(SYSTEM.AMQP.SERVICE);START CHANNEL('APP.AMQP')一樣要用 CHLAUTH、MCAUSER、TLS 保護
MQTTDEFINE CHANNEL('IOT.MQTT') CHLTYPE(MQTT) TRPTYPE(TCP) PORT(8883) SSLCIPH(...);Telemetry Service SYSTEM.MQXR.SERVICE正式環境只開 TLS 連接埠
MulticastDEFINE COMMINFO('MC.INFO') GRPADDR('239.1.1.1') PORT(1414);Topic 設 MCAST(ENABLED) COMMINFO('MC.INFO')網路需支援 IP Multicast
Kafka ConnectConnector 設定 mq.queue.manager、mq.connection.name.list、mq.channel.name、mq.queue、topic 等Connector 使用專用 MQ 帳號與最小權限

上表命令只列出關鍵字與常用參數,完整語法以 IBM MQ 10.0 文件為準 [需確認]。

5.15 IBM MQ 10.0 新增的管理能力

能力管理意義標記
Native HA 詳細狀態可看到各實例的複寫狀態與落後程度,故障排查不必猜 [需確認命令選項][MQ 10.0]
程式化讀取 Error Log監控工具不必登入主機讀 AMQERR01.LOG[MQ 10.0]
dspmqcert檢查 QM 憑證到期日,可納入每日巡檢[MQ 10.0]
多 Certificate Label憑證輪替時可同時掛新舊憑證[MQ 10.0]
變更 QM CCSID 可能需 force避免無意間改壞既有資料轉換[MQ 10.0]
延伸 Authority Event(正向驗證)稽核成功登入[MQ 9.4 CD]
Console 強化營運查詢更完整[MQ 9.4 CD]
AMQ7366W 可列入 Exclude / Suppress 清單減少 Error Log 雜訊[MQ 10.0]
隨產品附帶的 Java runtime 變更影響 MFT、MQ Console、AMQP、MQTT 等 Java 元件[MQ 10.0]

5.16 AI Agent 使用方式

  • 可以:請 AI 依需求產生 MQSC 變更檔、runmqsc -v 驗證腳本、回復(Rollback)MQSC 檔、DISPLAY 巡檢腳本。
  • 可以:把 dmpmqcfg 輸出交給 AI 做差異分析、找出過度授權與不一致設定。
  • 不可以:讓 AI 直接連 Production 執行 L1 以上的命令。

5.17 常見錯誤

  • 在 Production 用 DEFINE ... REPLACE 覆寫既有佇列,導致 BOQNAME 等屬性被重設。
  • 忘記 ALTER CHANNEL 後需要重啟 Channel 才生效。
  • CLEAR QLOCAL 誤清 Production 佇列。
  • 沒有定期 dmpmqcfg,災難時無法重建物件。

5.18 Checklist

  • 每日 dmpmqcfg 備份並納入版本比對
  • 所有變更 MQSC 先以 runmqsc -v 驗證語法
  • 每個變更檔都有對應 Rollback MQSC
  • L3 / L4 操作有雙人覆核
  • 巡檢腳本只使用 DISPLAY 類命令
  • 已明定各管理介面的使用情境;Production 物件變更只走 MQSC + Pipeline
  • 遠端管理使用專用 TLS 管理 Channel,預設 SYSTEM.*.SVRCONN 已封鎖
  • Command Event 與 Configuration Event 已啟用
  • PCF / REST 監控帳號只有唯讀(dsp、MQWebAdminRO)權限
  • mqweb 只開 HTTPS,憑證納入到期監控
  • z/OS:CF Structure 已排程 BACKUP CFSTRUCT,SMF 115 / 116 已依需求啟用

Part 6 — Queue 設計

6.1 目的

建立企業級 Queue 設計原則:命名、容量、錯誤處理佇列(Backout / DLQ / Retry)與 Request / Response 佇列配置。

6.2 Queue Naming Convention

建議格式:

<system>.<domain>.<function>.<direction>[.<suffix>]
區段說明範例
system擁有者系統代碼(3-6 字元)PAY、CBS、CARD、NBK
domain業務領域TXN、ACCT、CUST
function功能TRANSFER、INQUIRY、NOTIFY
direction方向 / 角色REQ、RSP、EVT、CMD
suffix特殊用途BOQ(Backout)、RETRY、DLQ、ALIAS

規則:

  1. 全大寫、以 . 分隔,避免底線與小寫(MQSC 引號問題)。
  2. 總長度 ≤ 48 字元。
  3. 不使用 SYSTEM. 開頭。
  4. 佇列名稱不含環境名稱(DEV、PROD),環境以 Queue Manager 區分,讓程式設定在各環境一致。
  5. 一個佇列只屬於一個擁有者系統。

6.3 金融系統命名範例

佇列類型用途
NBK.TXN.TRANSFER.REQQREMOTE / QALIAS網銀發送轉帳請求(Producer 端看到的名稱)
CBS.TXN.TRANSFER.REQQLOCAL核心系統接收轉帳請求
CBS.TXN.TRANSFER.REQ.BOQQLOCAL轉帳請求的 Backout Queue
NBK.TXN.TRANSFER.RSPQLOCAL網銀接收轉帳回覆
NBK.TXN.TRANSFER.RSP.BOQQLOCAL回覆佇列的 Backout Queue
CBS.ACCT.BALANCE.EVTTopic String Bank/Account/Balance/Changed餘額異動事件
PAY.TXN.SETTLE.RETRYQLOCAL延遲重試佇列

6.4 Queue Capacity:MAXDEPTH 與 MAXMSGL

屬性說明預設 [需確認]設計建議
MAXDEPTH佇列最多訊息數5000依「峰值 TPS × 可容忍的 Consumer 停機秒數 × 安全係數」估算
MAXMSGL單則訊息最大長度(bytes)4 MB(4194304)依實際訊息上限設定,不要盲目設到最大值
QMGR MAXMSGLQM 層級上限4 MB必須 ≥ 佇列與 Channel 的 MAXMSGL
Channel MAXMSGLChannel 層級上限4 MB兩端協商取較小值

MAXDEPTH 估算範例:

峰值 TPS                 = 500 msg/s
可容忍 Consumer 停機時間  = 30 分鐘 = 1800 秒
安全係數                 = 1.5
MAXDEPTH ≈ 500 × 1800 × 1.5 = 1,350,000

同時檢查:1,350,000 × 平均訊息大小 2KB ≈ 2.7GB
→ 確認 Queue 檔案系統空間足夠,並設定 QDEPTHHI 告警(例如 60%)

佇列滿時 Producer 會收到 2053 MQRC_Q_FULL;跨 QM 傳遞時訊息會進 DLQ。MAXDEPTH 是保護機制,不是容量規劃的替代品。

6.5 Backout Queue、Dead Letter Queue、Retry Queue

flowchart LR
    P["Producer"] --> REQ["CBS.TXN.TRANSFER.REQ<br/>BOTHRESH(5)"]
    REQ --> C["Consumer"]
    C -- "成功" --> OK(["Commit"])
    C -- "暫時錯誤<br/>Backout" --> REQ
    C -- "BackoutCount ≥ 5<br/>或永久錯誤" --> BOQ["CBS.TXN.TRANSFER.REQ.BOQ"]
    C -- "需延遲重試" --> RETRY["PAY.TXN.SETTLE.RETRY"]
    RETRY -- "排程 / 延遲處理器<br/>放回原佇列" --> REQ
    CH["Receiver Channel"] -- "目標不存在 / 已滿" --> DLQ["SYSTEM.DEAD.LETTER.QUEUE"]
    BOQ --> OPS["維運處理 / 補償"]
    DLQ --> DLQH["runmqdlq / 維運處理"]
佇列誰放入用途處理方式
Backout Queue(BOQ)應用程式(JMS 自動;MQI 自行)處理失敗超過門檻的毒訊息人工檢視、修正後重送或補償
Dead Letter Queue(DLQ)Queue Manager / ChannelMQ 層級無法投遞runmqdlq 規則或人工
Retry Queue應用程式需延遲一段時間再重試排程程式依時間放回原佇列

延遲投遞的選擇:MQI 層級沒有「指定時間後才可被取出」的訊息屬性,但 IBM MQ classes for JMS / Jakarta Messaging 支援 JMS 2.0 的 Delivery Delay:Producer 設定 setDeliveryDelay() 後,訊息會先放到 Queue Manager 的暫存佇列 SYSTEM.DDELAY.LOCAL.QUEUE,時間到才移到目標佇列。使用時需注意:

  • 需要 Queue Manager 端支援並允許使用暫存佇列;暫存佇列的容量與權限要納入管理。
  • 延遲期間訊息不在目標佇列上,監控目標佇列深度時看不到它們。
  • 與部分功能(例如特定 Cluster 或 z/OS Shared Queue 情境)的相容性有限制 [需確認]。

延遲重試的常見做法:

  1. JMS Delivery Delay(Java 應用、延遲時間短、訊息量可控)
  2. Retry Queue + 排程程式(訊息帶下次處理時間屬性)
  3. Consumer 端 Backout 後由 Listener Container 退避(Backoff)
  4. 外部排程(例如資料庫記錄重試時間)

6.6 Request Queue 與 Response Queue

設計選項說明優點缺點
共用 Response Queue + CorrelId 篩選所有 Requester 實例共用一個回覆佇列佇列數少、易管理需以 CorrelId 篩選;多實例時要確保回覆被正確實例取走
每實例一個 Response Queue每個服務實例專屬回覆佇列不需跨實例篩選佇列數量隨實例數增加;K8s 動態擴縮困難
Temporary Dynamic Queue由 Model Queue 動態建立自動清理連線斷開即消失、回覆遺失;Persistent 不適用

金融系統建議:共用 Response Queue + CorrelId 篩選,搭配 Expiry 與 Timeout(見 Part 15)。

6.7 MQSC 範例:一組完整的 Request / Reply 佇列

* ===== 核心系統 QM (CBSQM01) =====
DEFINE QLOCAL('CBS.TXN.TRANSFER.REQ.BOQ') DEFPSIST(YES) MAXDEPTH(100000) +
       DESCR('Transfer request backout') REPLACE
DEFINE QLOCAL('CBS.TXN.TRANSFER.REQ') DEFPSIST(YES) +
       MAXDEPTH(500000) MAXMSGL(65536) +
       BOTHRESH(5) BOQNAME('CBS.TXN.TRANSFER.REQ.BOQ') HARDENBO +
       QDEPTHHI(60) QDPHIEV(ENABLED) +
       MONQ(MEDIUM) +
       DESCR('Transfer request from NBK') REPLACE

* ===== 網銀 QM (NBKQM01) =====
DEFINE QLOCAL('NBK.TXN.TRANSFER.RSP.BOQ') DEFPSIST(YES) MAXDEPTH(100000) REPLACE
DEFINE QLOCAL('NBK.TXN.TRANSFER.RSP') DEFPSIST(YES) MAXDEPTH(500000) +
       BOTHRESH(3) BOQNAME('NBK.TXN.TRANSFER.RSP.BOQ') HARDENBO +
       QDEPTHHI(60) QDPHIEV(ENABLED) MONQ(MEDIUM) REPLACE
* 網銀程式只認得 NBK.TXN.TRANSFER.REQ,實際路由到核心
DEFINE QREMOTE('NBK.TXN.TRANSFER.REQ') RNAME('CBS.TXN.TRANSFER.REQ') +
       RQMNAME('CBSQM01') XMITQ('CBSQM01') REPLACE

HARDENBO 讓 BackoutCount 在 QM 重啟後仍正確,對毒訊息判斷很重要(有些許效能代價)。

6.8 常見錯誤

  • Input Queue 沒有 BOQNAME,毒訊息無限循環。
  • Backout Queue 本身又設定 BOQNAME 指回原佇列(循環)。
  • MAXMSGL 設成 100MB,結果有人把大檔案塞進 MQ 拖垮效能。
  • 佇列名稱含環境代碼,導致程式設定在各環境不同。

6.9 Checklist

  • 命名符合 <system>.<domain>.<function>.<direction>
  • 每個 Input Queue 都有 BOQNAME + BOTHRESH + HARDENBO
  • MAXDEPTH 有估算依據並記錄
  • MAXMSGL 依實際需求設定
  • 設定 QDEPTHHI 事件或監控告警
  • Request 與 Response 佇列分離
  • Backout Queue 有處理流程與負責人

Part 7 — Channel 設計

7.1 目的

說明 Channel 的類型選擇、設定參數、安全設計與狀態管理。

7.2 Channel 架構

Application
    |
    | Client Connection(SVRCONN)
    ↓
Queue Manager A
    |
    | Sender / Receiver
    ↓
Queue Manager B
flowchart LR
    subgraph App["Spring Boot(Client)"]
        CCDT["CCDT / connName<br/>CLNTCONN: PAY.SVRCONN"]
    end
    subgraph QMA["NBKQM01"]
        SVR["SVRCONN<br/>PAY.SVRCONN"]
        XQ["XMITQ: CBSQM01"]
        SDR["SDR: NBKQM01.CBSQM01"]
        RCV2["RCVR: CBSQM01.NBKQM01"]
    end
    subgraph QMB["CBSQM01"]
        RCV["RCVR: NBKQM01.CBSQM01"]
        XQ2["XMITQ: NBKQM01"]
        SDR2["SDR: CBSQM01.NBKQM01"]
    end
    CCDT -- "TLS 1.3 + 用戶端憑證" --> SVR
    XQ --> SDR -- "TLS(QM 憑證)" --> RCV
    XQ2 --> SDR2 -- "TLS(QM 憑證)" --> RCV2

7.3 Channel 類型選擇

需求選擇
Java / Spring Boot 應用連到 QMSVRCONN(QM 端)+ connName 或 CCDT(Client 端)
QM 單向送訊息到另一個 QMSDR → RCVR
遠端由對方主動要求才傳送RQSTR ↔ SVR(或 RQSTR ↔ SDR 回撥模式)
Cluster 內互通CLUSSDR + CLUSRCVR

Message Channel 是單向的:雙向通訊需要兩組 SDR/RCVR。

7.4 Sender Channel 關鍵參數

參數說明建議
CONNAME目標主機與連接埠,可用逗號列出多個位址(HA)'host1(1414),host2(1414)'
XMITQ讀取的 Transmission Queue慣例與目標 QM 同名
BATCHSZ每批次最大訊息數預設 50;高吞吐可調大,但 in-doubt 時影響範圍變大
DISCINT閒置多久自動斷線(秒)搭配 Trigger 啟動
SHORTRTY / SHORTTMR短重試次數 / 間隔網路短暫中斷
LONGRTY / LONGTMR長重試次數 / 間隔長時間中斷
HBINTHeartbeat 間隔偵測斷線
NPMSPEEDNon-persistent 傳送速度FAST 時 Non-persistent 可能在 Channel 故障時遺失
SSLCIPHCipherSpec兩端必須一致(或使用 ANY_TLS* 別名)

7.5 Transmission Queue 與 Trigger

DEFINE QLOCAL('CBSQM01') USAGE(XMITQ) DEFPSIST(YES) MAXDEPTH(500000) +
       TRIGGER TRIGTYPE(FIRST) TRIGDATA('NBKQM01.CBSQM01') +
       INITQ('SYSTEM.CHANNEL.INITQ') REPLACE

DEFINE CHANNEL('NBKQM01.CBSQM01') CHLTYPE(SDR) TRPTYPE(TCP) +
       CONNAME('cbs-mq-a.bank.local(1414),cbs-mq-b.bank.local(1414)') +
       XMITQ('CBSQM01') SSLCIPH('ANY_TLS13_OR_HIGHER') +
       DISCINT(6000) SHORTRTY(10) SHORTTMR(60) LONGRTY(999999999) LONGTMR(300) +
       DESCR('NBK to CBS') REPLACE

對方 QM:

DEFINE CHANNEL('NBKQM01.CBSQM01') CHLTYPE(RCVR) TRPTYPE(TCP) +
       SSLCIPH('ANY_TLS13_OR_HIGHER') SSLCAUTH(REQUIRED) +
       MCAUSER('nbkmca') +
       DESCR('From NBK') REPLACE

Receiver 的 MCAUSER 決定「以誰的身分把訊息放進目標佇列」。不可留空(留空會以 MCA 程序身分執行,通常是 mqm,等同管理員權限)。應設定為低權限帳號,並以 CHLAUTH SSLPEERMAP 綁定對方憑證(見 Part 8)。

7.6 Server Connection Channel 關鍵參數

參數說明建議
SSLCIPHTLS CipherSpecANY_TLS13_OR_HIGHER 或指定 TLS 1.3 / 1.2 ECDHE 套件
SSLCAUTH是否要求用戶端憑證REQUIRED(雙向 TLS)
MAXINST此 Channel 最大實例數防止單一應用耗盡連線
MAXINSTC單一 Client IP 最大實例數防止單一主機失控
SHARECNV每個 Channel 實例共用的對話數預設 10;設 0 會停用許多 Client 功能,不建議
HBINTHeartbeat偵測斷線
MCAUSER預設身分搭配 CHLAUTH 映射;不要依賴 Client 傳入的 User ID
DISCINT閒置斷線依需求

7.7 Channel Status 與 Retry

stateDiagram-v2
    [*] --> INACTIVE
    INACTIVE --> STARTING: START / Trigger
    STARTING --> BINDING: 協商(含 TLS 握手)
    BINDING --> RUNNING: 成功
    BINDING --> RETRYING: 失敗
    RUNNING --> RETRYING: 網路中斷
    RETRYING --> BINDING: 重試間隔到
    RETRYING --> STOPPED: 重試次數用盡
    RUNNING --> INACTIVE: DISCINT 閒置
    RUNNING --> STOPPED: STOP CHANNEL
    STOPPED --> STARTING: START CHANNEL
    RUNNING --> INDOUBT: 批次確認中斷
    INDOUBT --> RUNNING: 重新連線自動解決
狀態意義動作
RUNNING正常—
RETRYING正在重試檢查網路、對方 Listener、TLS
STOPPED停止(手動或重試用盡)查明原因後 START CHANNEL
BINDING 長時間協商卡住檢查 TLS、防火牆、對方狀態
INACTIVE(無 CHSTATUS 輸出)未啟動或閒置斷線Trigger 設定是否正確
In-doubt批次確認中斷通常重新連線後自動解決;手動 RESOLVE 前必須與對方管理員確認

7.8 Channel Authentication、MCA User、TLS、Certificate

摘要如下,細節於 Part 8:

  • CHLAUTH:依來源 IP、TLS DN、Client User ID、遠端 QM 名稱,決定「允許 / 封鎖 / 映射成哪個 MCAUSER」。
  • MCA User:Channel 實際執行 MQ 操作所使用的身分,OAM 依此檢查權限。
  • TLS:SSLCIPH 啟用;SSLCAUTH(REQUIRED) 要求對方憑證;SSLPEER 或 CHLAUTH SSLPEERMAP 驗證對方 DN。
  • Certificate:QM 憑證預設 label 為 ibmwebspheremq<qmname小寫>,或以 QM / Channel 的 CERTLABL 指定。[MQ 10.0] 支援多個 certificate label。

7.9 常見錯誤

  • SDR / RCVR 名稱兩端不一致 → AMQ9520E(Channel 未在遠端定義)。
  • Receiver MCAUSER 空白 → 對方可放訊息到任何佇列,包括 SYSTEM.ADMIN.COMMAND.QUEUE。
  • 兩端 SSLCIPH 不一致 → AMQ9631E 類錯誤。
  • XMITQ 沒有設定 Trigger → 訊息堆積在 XMITQ,Channel 不會自動啟動。

7.10 Checklist

  • SDR / RCVR 名稱兩端一致並記錄於 Channel Map
  • 所有 Channel 啟用 TLS
  • RCVR / SVRCONN 的 MCAUSER 為低權限帳號,不為空白
  • SVRCONN 設定 MAXINST / MAXINSTC
  • XMITQ 設定 Trigger
  • CONNAME 列出 HA 所有位址
  • Channel 狀態納入監控

Part 8 — IBM MQ Security

8.1 目的

建立金融等級的 IBM MQ 安全基準(Production Security Baseline),涵蓋身分驗證、授權、傳輸加密、稽核與機敏資訊管理。

8.2 安全架構

flowchart LR
    C["Client 應用程式"] -->|"1 TCP 連線"| L["Listener"]
    L -->|"2 TLS 握手<br/>驗證雙方憑證"| TLS{"TLS / SSLCAUTH"}
    TLS -->|"3 CHLAUTH 規則<br/>IP / DN / User / QM"| CA{"CHLAUTH"}
    CA -->|"封鎖"| X1["拒絕 AMQ9777E 等"]
    CA -->|"4 CONNAUTH<br/>帳號密碼 / JWT"| AU{"CONNAUTH"}
    AU -->|"失敗"| X2["拒絕 2035"]
    AU -->|"5 決定 MCAUSER"| ID["有效身分"]
    ID -->|"6 OAM 授權檢查<br/>connect / put / get"| OAM{"OAM"}
    OAM -->|"無權限"| X3["2035 NOT_AUTHORIZED"]
    OAM -->|"允許"| Q[("Queue")]
    AUD["稽核:Authority Event<br/>Channel Event / Error Log"] -.-> CA
    AUD -.-> AU
    AUD -.-> OAM

8.3 Authentication(身分驗證)

IBM MQ 有多層身分驗證機制:

機制驗證什麼說明
TLS 雙向認證連線端的憑證SSLCAUTH(REQUIRED),以憑證 DN 作為身分依據(金融系統建議主要方式)
CONNAUTH帳號 / 密碼驗證 OS 帳號(IDPWOS)或 LDAP(IDPWLDAP)
JWT TokenToken[MQ 9.3.4+ / 9.4 CD] 支援 JWT 驗證;[MQ 10.0] 新增 JWKS 支援 [需確認細節]
CHLAUTH連線來源特徵不是驗證本身,而是依特徵允許 / 封鎖 / 映射
* CONNAUTH:要求 Client 連線必須提供有效帳密
DEFINE AUTHINFO('BANK.IDPW.OS') AUTHTYPE(IDPWOS) +
       CHCKCLNT(REQUIRED) CHCKLOCL(OPTIONAL) ADOPTCTX(YES) +
       FAILDLAY(1) REPLACE
ALTER QMGR CONNAUTH('BANK.IDPW.OS')
REFRESH SECURITY TYPE(CONNAUTH)
屬性說明
CHCKCLNT(REQUIRED)Client 連線必須提供帳密
CHCKLOCL(OPTIONAL)本機(Bindings)連線可不提供,但若提供則驗證
ADOPTCTX(YES)驗證成功後以該帳號作為後續授權身分
FAILDLAY驗證失敗延遲秒數,減緩暴力破解

Java 端注意:使用 MQ classes for Java / JMS 傳送帳密時,應啟用 MQCSP 驗證模式(USE_MQCSP_AUTHENTICATION_PROPERTY / USER_AUTHENTICATION_MQCSP=true),否則可能使用相容模式並有密碼長度等限制。Spring Boot Starter 的 userAuthenticationMQCSP 預設為 true。

8.4 CHLAUTH(Channel Authentication Records)

Queue Manager 預設有三條 CHLAUTH 規則:

* 預設 1:封鎖所有 SYSTEM.* Channel 的外部存取(ADDRESSMAP * → NOACCESS)
SET CHLAUTH('SYSTEM.*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(NOACCESS)
* 預設 2:SYSTEM.ADMIN.SVRCONN 例外(允許,但仍受其他規則限制)
SET CHLAUTH('SYSTEM.ADMIN.SVRCONN') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(CHANNEL)
* 預設 3:封鎖所有具管理權限的使用者(*MQADMIN)經由 Client Channel 連線
SET CHLAUTH('*') TYPE(BLOCKUSER) USERLIST('*MQADMIN')

以上為預設規則的內容說明,不要在 Production 重新執行這些命令;應以 DISPLAY CHLAUTH(*) 確認其存在。

*MQADMIN 代表什麼:任何具有管理權限的身分(例如 mqm 群組成員、Windows 的管理員)。預設 BLOCKUSER 規則讓「以管理員身分從遠端連線」被拒絕。常見的錯誤做法是為了解決 2035 而移除這條規則——這等於讓任何能偽造 User ID 的 Client 取得管理員權限。

Production 建議規則(白名單模式):

* 1. 封鎖所有 Channel 的所有來源(Back-stop 規則)
SET CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(NOACCESS) +
    DESCR('Back-stop: deny all by default') ACTION(REPLACE)

* 2. 付款服務:只允許指定網段 + 指定憑證 DN,並映射到低權限帳號
SET CHLAUTH('PAY.SVRCONN') TYPE(SSLPEERMAP) +
    SSLPEER('CN=payment-service,OU=Payments,O=Example Bank,C=TW') +
    ADDRESS('10.20.30.*') USERSRC(MAP) MCAUSER('paysvc') +
    DESCR('Payment service mTLS') ACTION(REPLACE)

* 3. QM 對 QM:只允許對方 QM 憑證
SET CHLAUTH('NBKQM01.CBSQM01') TYPE(SSLPEERMAP) +
    SSLPEER('CN=NBKQM01,OU=MQ,O=Example Bank,C=TW') +
    USERSRC(MAP) MCAUSER('nbkmca') ACTION(REPLACE)

上述規則若順序或內容錯誤,會封鎖所有連線。 Production 套用前務必:(1) 在 UAT 完整驗證;(2) 準備回復命令;(3) 保留一條緊急管理途徑(例如本機 runmqsc)。

CHLAUTH 規則類型:

TYPE用途
ADDRESSMAP依來源 IP 映射或封鎖
SSLPEERMAP依對方憑證 DN 映射或封鎖
USERMAP依 Client 宣告的 User ID 映射(不建議單獨依賴,Client User ID 可被偽造)
QMGRMAP依遠端 QM 名稱映射
BLOCKUSER封鎖特定 User ID
BLOCKADDR在 Listener 層封鎖 IP(連線即拒)

驗證規則行為(不實際連線):

DISPLAY CHLAUTH('PAY.SVRCONN') MATCH(RUNCHECK) ADDRESS('10.20.30.15') +
        SSLPEER('CN=payment-service,OU=Payments,O=Example Bank,C=TW')

8.5 Authorization:OAM(Object Authority Manager)

OAM 控制「某身分(以群組為主)對某物件可以做什麼」。

權限說明典型授予對象
connect連線 QM所有應用帳號
inq查詢屬性所有應用帳號(JMS 常需要)
put放入訊息Producer
get取出訊息Consumer
browse瀏覽不刪除Consumer(JMS 某些功能需要)、監控
setid / setall設定 MQMD 身分 / 來源欄位極少數系統(例如轉送程式)
passid / passall傳遞身分欄位轉送程式
dsp顯示物件(管理)監控帳號
chg / crt / dlt / clr管理權限僅 MQ 管理員
+all / +alladm全部 / 全部管理應用帳號禁止
# 以群組授權(OS 層),不要對個人帳號授權
# 付款服務(Producer + Reply Consumer)
setmqaut -m NBKQM01 -t qmgr -g paysvc_grp +connect +inq
setmqaut -m NBKQM01 -t queue -n 'NBK.TXN.TRANSFER.REQ' -g paysvc_grp +put +inq
setmqaut -m NBKQM01 -t queue -n 'NBK.TXN.TRANSFER.RSP' -g paysvc_grp +get +browse +inq
# JMS 應用若會把毒訊息移到 BOQ,需要 BOQ 的 put 權限
setmqaut -m NBKQM01 -t queue -n 'NBK.TXN.TRANSFER.RSP.BOQ' -g paysvc_grp +put +inq

# 查詢某群組的權限
dspmqaut -m NBKQM01 -t queue -n 'NBK.TXN.TRANSFER.REQ' -g paysvc_grp
dmpmqaut -m NBKQM01 -g paysvc_grp

MQSC 等效寫法:

SET AUTHREC OBJTYPE(QMGR) GROUP('paysvc_grp') AUTHADD(CONNECT,INQ)
SET AUTHREC PROFILE('NBK.TXN.TRANSFER.REQ') OBJTYPE(QUEUE) GROUP('paysvc_grp') AUTHADD(PUT,INQ)
SET AUTHREC PROFILE('NBK.TXN.TRANSFER.RSP') OBJTYPE(QUEUE) GROUP('paysvc_grp') AUTHADD(GET,BROWSE,INQ)

Generic Profile:可用 PAY.** 一次授權一組佇列。優點是省事,缺點是未來新增的同前綴佇列會自動被授權,需評估是否符合最小權限原則。

8.6 避免 *MQADMIN 與 +all 過度授權

反模式風險正確做法
應用帳號加入 mqm 群組應用帳號 = MQ 管理員應用帳號只屬於應用群組
setmqaut ... +all可刪除、清空、修改佇列只授予 put / get / inq / browse
移除 BLOCKUSER('*MQADMIN') 規則遠端管理員連線保留規則;管理員使用專用管理 Channel + mTLS
MCAUSER('mqm')所有連線以管理員身分執行低權限 MCAUSER + CHLAUTH 映射
CHCKCLNT(NONE) + USERSRC(CHANNEL)信任 Client 宣告的任意身分CHCKCLNT(REQUIRED) 或 mTLS + SSLPEERMAP
使用 SYSTEM.DEF.SVRCONN / SYSTEM.ADMIN.SVRCONN 給應用程式共用、難以控管每個應用一條專屬 SVRCONN

8.7 TLS、Certificate 與 CipherSpec

[MQ 10.0] 重要變更(升級時必須檢查):

變更影響
移除 SSLv3、TLS 1.0、RC4、3DES CipherSpec使用這些 CipherSpec 的 Channel 在 10.0 無法連線
RSA key exchange CipherSpec 列為 Deprecated規劃遷移到 ECDHE 套件或 TLS 1.3
IBM Semeru Runtime 25 停用 TLS_RSA_*Java 25(Semeru)Client 使用 TLS_RSA_* 會失敗
最小 RSA 金鑰長度限制過短的 RSA 金鑰憑證無法使用([需確認] 確切門檻)
憑證 label 含空白或逗號須跳脫既有 CERTLABL 設定需檢查
新建 keystore 預設使用安全演算法舊工具建立的 keystore 需評估
支援 FIPS 203 ML-KEM key share抗量子金鑰交換,依政策評估導入

CipherSpec 建議:

場景建議 SSLCIPH
一般新建ANY_TLS13_OR_HIGHER(雙方皆支援 TLS 1.3)
需相容 TLS 1.2 的舊 ClientANY_TLS12_OR_HIGHER,並在 QM 層限制允許的 CipherSpec [需確認設定方式]
指定單一套件TLS 1.3:TLS_AES_256_GCM_SHA384;TLS 1.2:ECDHE + GCM 系列

Java Client 注意事項:

  • 使用非 IBM JRE(例如 Eclipse Temurin、Oracle JDK)時,需設定 -Dcom.ibm.mq.cfg.useIBMCipherMappings=false,並以 JSSE 名稱指定 Cipher Suite。
  • 金鑰庫建議使用 PKCS#12。
  • [MQ 10.0] 起 TLS 1.0 已移除;Java 端若仍限制在 TLS 1.0 / 1.1 將無法連線。

憑證管理工具:

# 建立 QM 金鑰庫(PKCS#12 / CMS 依工具版本,需確認)
runmqakm -keydb -create -db /var/mqm/qmgrs/BANKQM01/ssl/key.kdb -pw "$KDB_PW" -type cms -stash

# 檢視憑證
runmqakm -cert -list -db /var/mqm/qmgrs/BANKQM01/ssl/key.kdb -stashed

# [MQ 10.0] 檢查憑證到期日(新工具)
dspmqcert -m BANKQM01    # 參數需依官方文件確認

# 修改憑證後重新載入
# MQSC: REFRESH SECURITY TYPE(SSL)

REFRESH SECURITY TYPE(SSL) 會重設正在執行的 TLS Channel,屬 L3 操作,應在維護時段執行。

8.8 Audit 與 Log

項目設定用途
Authority EventALTER QMGR AUTHOREV(ENABLED)2035 發生時產生事件到 SYSTEM.ADMIN.QMGR.EVENT
Channel EventALTER QMGR CHLEV(ENABLED) SSLEV(ENABLED)Channel 啟停、TLS 事件
Command EventALTER QMGR CMDEV(ENABLED)記錄誰執行了哪些管理命令(稽核必要)
Configuration EventALTER QMGR CONFIGEV(ENABLED)物件建立、修改、刪除
Error Log/var/mqm/qmgrs/<QM>/errors/AMQERR0*.LOG安全拒絕訊息
[MQ 9.4 CD] 延伸 Authority Event正向驗證成功事件稽核成功登入
ALTER QMGR AUTHOREV(ENABLED) CHLEV(ENABLED) SSLEV(ENABLED) +
           CMDEV(ENABLED) CONFIGEV(ENABLED)

事件訊息會累積在 SYSTEM.ADMIN.*.EVENT 佇列,必須有工具持續消費並轉送到 SIEM,否則佇列會被塞滿。

8.9 Secret Management 與 Credential Rotation

機敏資訊存放方式輪替
應用帳號密碼Vault / Kubernetes Secret / 雲端 Secret Manager依公司政策(例如 90 天);支援新舊密碼並存的切換流程
TLS 私鑰Secret,權限最小化憑證到期前(建議 30 天)換發;[MQ 10.0] 可用 dspmqcert 監控
Keystore 密碼Stash 檔權限 600,或 Secret隨 Keystore 更換
管理員密碼PAM / 特權帳號管理系統每次使用後輪替

輪替流程(無停機):

sequenceDiagram
    participant Ops as 維運
    participant CA as 憑證機構
    participant QM as Queue Manager
    participant App as 應用程式
    Ops->>CA: 申請新憑證(到期前 30 天)
    Ops->>QM: 新 CA 鏈加入 QM 信任庫
    Ops->>App: 新 CA 鏈加入 App 信任庫(滾動部署)
    Ops->>App: 換用新用戶端憑證(滾動部署)
    Ops->>QM: 換用新 QM 憑證 + REFRESH SECURITY TYPE(SSL)(維護時段)
    Ops->>QM: 更新 CHLAUTH SSLPEERMAP(若 DN 改變)
    Ops->>QM: 驗證所有 Channel RUNNING
    Ops->>QM: 移除舊 CA / 舊憑證

8.10 IBM MQ Production Security Baseline

#類別基準要求
S1身分驗證所有 Client Channel 採 mTLS(SSLCAUTH(REQUIRED))或 CHCKCLNT(REQUIRED);金融核心系統建議兩者並用
S2身分映射以 CHLAUTH SSLPEERMAP / ADDRESSMAP 映射到固定 MCAUSER;不信任 Client 宣告的 User ID
S3預設封鎖保留 BLOCKUSER('*MQADMIN');新增 Back-stop ADDRESSMAP('*') NOACCESS
S4權限控管以群組授權;應用只授予 connect、inq、put / get / browse;禁止 +all、mqm 群組
S5Channel每個應用專屬 SVRCONN;設定 MAXINST / MAXINSTC;停用或封鎖未使用的 SYSTEM.* Channel
S6TLSTLS 1.3 優先;禁止已移除與 Deprecated 的 CipherSpec;憑證金鑰長度符合政策
S7Queue Security管理佇列(SYSTEM.ADMIN.COMMAND.QUEUE 等)僅管理群組可存取
S8Audit啟用 Authority / Command / Configuration / Channel / SSL 事件,轉送 SIEM
S9LogError Log 集中收集並保存(保存期限依公司政策與適用法規確認)
S10Secret密碼與私鑰不得出現在程式碼、Git、映像檔、命令列歷史
S11Rotation憑證到期監控與輪替演練;帳密定期輪替
S12管理途徑管理員使用專用管理 Channel + mTLS + 跳板機;所有操作留存紀錄
S13弱點定期套用 IBM 安全修補(CSU / Fix Pack)並追蹤 IBM Security Bulletin
S14AMS(選用)需端到端訊息加密 / 簽章時評估 Advanced Message Security(需 Advanced 授權)

8.11 Advanced Message Security(AMS)

TLS 只保護「傳輸中」的資料。訊息一旦落在佇列、Log、DLQ 或備份中,就是明文,MQ 管理員或取得備份的人都看得到。AMS 在應用端對訊息本體簽章或加密,讓訊息在整條路徑上都受到保護(需 IBM MQ Advanced 授權)。

保護等級效果適用
Integrity數位簽章:可驗證來源與內容未被竄改,但內容仍可讀需要不可否認性的指令訊息
Privacy簽章 + 加密:只有指定收件者能解密含個資、帳戶資料的交易電文
Confidentiality只加密(可重複使用對稱金鑰,效能較佳)高流量且只需保密的資料
sequenceDiagram
    participant P as Producer(payment-service)
    participant QM as Queue Manager / Log / DLQ
    participant C as Consumer(core-banking)
    P->>P: 依 Policy 以自己的私鑰簽章、以收件者公鑰加密
    P->>QM: MQPUT(佇列與 Log 中為密文)
    Note over QM: MQ 管理員瀏覽佇列只看到密文
    C->>QM: MQGET
    C->>C: 以自己的私鑰解密並驗證簽章者 DN
* 為佇列設定 AMS Policy:SHA256 簽章 + AES256 加密,指定簽章者與收件者
SET POLICY('CBS.TXN.TRANSFER.REQ') SIGNALG(SHA256) ENCALG(AES256) +
    SIGNER('CN=payment-service,OU=Payments,O=Example Bank,C=TW') +
    RECIP('CN=core-banking,OU=CBS,O=Example Bank,C=TW') +
    ACTION(REPLACE)

DISPLAY POLICY('CBS.TXN.TRANSFER.REQ')
# 應用端 keystore.conf(Java 範例;鍵名與支援的 keystore 類型需依官方文件確認)
jks.keystore = /etc/payment/ams/payment-keystore
jks.certificate = payment-service
jks.encrypted = yes

導入注意事項:

  • Policy 以佇列名稱為單位,Producer 與 Consumer 兩端都必須能存取對應的金鑰與憑證;收件者憑證更新時要同步更新 Policy。
  • 沒有金鑰的工具(含部分監控工具、runmqdlq)只能看到密文;DLQ 處理流程要事先設計。
  • 加解密會增加 CPU 與訊息大小,需在 UAT 做效能測試。
  • 也可使用 setmqspl / dspmqspl 控制命令管理 Policy;[MQ 10.0] AMS 支援 FIPS 模式。
  • 金鑰庫密碼與私鑰比照 8.9 Secret Management 處理。

8.12 IBM MQ for z/OS 安全(RACF)

z/OS 上的 IBM MQ 不使用 OAM,而是透過 ESM(External Security Manager,通常是 RACF) 進行授權。

安全面向RACF Class(大寫 / 混合大小寫)Profile 範例說明
啟用 / 停用各類檢查MQADMIN / MXADMINQM01.NO.QUEUE.CHECKSSwitch Profile:存在即「關閉」該類檢查,Production 必須審核
連線MQCONNQM01.BATCH、QM01.CICS、QM01.CHIN誰可以連到 QM
佇列MQQUEUE / MXQUEUEQM01.PAY.TXN.REQ對應分散式的 put / get 權限
命令MQCMDSQM01.ALTER.QLOCAL誰可以執行哪些 MQSC
命令資源MQADMIN / MXADMINQM01.QUEUE.PAY.TXN.REQ誰可以對哪個物件下命令
Topic / Process / NamelistMXTOPIC、MQPROC、MQNLIST 等依物件名稱其他物件
/* 定義佇列 Profile:預設無權限,只授權付款群組 */
RDEFINE MQQUEUE QM01.PAY.** UACC(NONE) OWNER(MQADMGRP)
PERMIT QM01.PAY.** CLASS(MQQUEUE) ID(PAYGRP) ACCESS(UPDATE)
SETROPTS RACLIST(MQQUEUE) REFRESH
* 通知 Queue Manager 重新載入 RACF 快取(L3)
-QM01 REFRESH SECURITY(MQQUEUE)

重點:

  • QSG 環境可使用以 QSG 名稱為前綴的 Profile,一次套用到群組內所有 QM。
  • Channel 的 TLS 可使用 RACF Key Ring,或由 AT-TLS 處理;CHLAUTH 在 z/OS 上同樣適用。
  • Switch Profile 是「關閉檢查」的開關,稽核時應列出所有存在的 *.NO.* Profile 並逐一說明理由。
  • Profile 命名、Class 清單與存取等級對應,請依 IBM MQ for z/OS 安全文件確認 [需確認]。

8.13 IBM MQ 10.0 憑證與身分管理細節

項目內容建議行動
多 Certificate Label [MQ 10.0]QM 可同時設定多個憑證標籤用於無停機憑證輪替與演算法遷移(RSA → ECDSA)
Keystore 選擇邏輯改善 [MQ 10.0]QM 選擇 TLS keystore 的方式更明確升級後驗證 SSLKEYR 與實際使用的 keystore
憑證標籤跳脫 [MQ 10.0]含空白或逗號的標籤必須跳脫盤點 CERTLABL
EKU 強化 [MQ 10.0]對 Extended Key Usage 的檢查更完整確認伺服器憑證含 serverAuth、用戶端憑證含 clientAuth
最小 RSA 金鑰長度 [MQ 10.0]過短金鑰被拒絕盤點所有憑證金鑰長度 [需確認門檻]
JWKS [MQ 10.0]QM 端自動取得驗證 JWT 所需的公鑰與 IdP(例如 Keycloak)整合時減少手動換鑰
JWT typ 參數改為選用相容更多 IdP—
JWT endpoint(JMS / Jakarta)Client 可自動向 Token Server 取得 TokenSpring Boot 以 ibm.mq.tokenServer.* 設定
HTTPS CCDT / JWT 可自訂 SSLSocketFactory取 CCDT 或 Token 時使用自訂 TLS 設定搭配企業內部 CA
三個新的 TLS 1.2 CipherSpec擴充 TLS 1.2 選項仍以 TLS 1.3 為優先
FIPS 140-3(Semeru)、AMS / JWT / JWKS / HTTPS CCDT 支援 FIPS符合政府與金融法規要求有 FIPS 需求時於 UAT 驗證
ML-KEM(FIPS 203)key share抗量子金鑰交換依組織 PQC 遷移政策評估

8.14 常見錯誤

  • 為了快速解決 2035,把應用帳號加入 mqm 群組。
  • CHCKCLNT(OPTIONAL) 搭配 ADOPTCTX(NO):帳密驗證通過但沒採用該身分。
  • CHLAUTH 規則只用 USERMAP,Client 改個環境變數就能變成另一個人。
  • 憑證過期導致半夜 Channel 全斷(2393 / AMQ9633E 類錯誤)。

8.15 Checklist

  • Security Baseline S1-S13 全部符合,S14 已評估
  • DISPLAY CHLAUTH(*) 結果已審核並記錄
  • dmpmqaut 結果中沒有應用帳號具 +all / 管理權限
  • 所有 CipherSpec 符合 MQ 10.0 支援清單
  • 憑證到期日已納入監控
  • 稽核事件已轉送 SIEM 並有人負責檢視
  • 含敏感資料的佇列已評估 AMS,DLQ 處理流程已考慮密文
  • z/OS:RACF Switch Profile 已逐一審核,佇列與命令 Profile 預設 UACC(NONE)
  • 憑證 EKU、金鑰長度、標籤跳脫已依 10.0 規則盤點

Part 9 — Java 開發:API 選擇

9.1 目的

釐清 Java 存取 IBM MQ 的各種 API,並依情境做出正確選擇。這是 Framework 升級與逆向工程最常混淆的地方。

9.2 API 家族全貌

flowchart TB
    subgraph Std["標準 API(可攜)"]
        JMS["JMS 2.0<br/>javax.jms.*"]
        JAK["Jakarta Messaging 3.0<br/>jakarta.jms.*"]
    end
    subgraph IBM["IBM MQ 提供的 Java 實作"]
        CJ["IBM MQ classes for Java<br/>com.ibm.mq.*<br/>(Stabilized since MQ 8.0)"]
        CJMS["IBM MQ classes for JMS<br/>com.ibm.mq.jms.* / com.ibm.msg.client.*"]
        CJAK["IBM MQ classes for Jakarta Messaging<br/>com.ibm.mq.jakarta.jms.*<br/>(MQ 9.3+,新開發首選)"]
    end
    subgraph Spring["Spring"]
        SJMS["Spring JMS<br/>JmsTemplate / @JmsListener / JmsClient"]
        STARTER["mq-jms-spring-boot-starter"]
    end
    MQI["MQI(C / COBOL 原生介面)"]
    JMS -.實作.-> CJMS
    JAK -.實作.-> CJAK
    SJMS --> JAK
    STARTER --> CJAK
    CJ -. "概念對應" .-> MQI
    CJMS --> QM[("Queue Manager")]
    CJAK --> QM
    CJ --> QM
    MQI --> QM

9.3 比較表

技術套件標準化官方狀態適合場景不適合場景
MQIC / COBOL 標頭IBM 專有持續支援C / COBOL / 主機程式、需要完整 MQ 控制Java 應用
IBM MQ classes for Javacom.ibm.mq.*IBM 專有自 MQ 8.0 功能凍結(Stabilized),仍完整支援維護既有程式;需要直接操作 MQMD 全部欄位的特殊工具新開發不建議
IBM MQ classes for JMSjavax.jms.* + com.ibm.mq.jms.*JMS 2.0僅建議維護既有 JMS 2.0 應用Java EE 8 / Spring Boot 2 舊系統新開發
IBM MQ classes for Jakarta Messagingjakarta.jms.* + com.ibm.mq.jakarta.jms.*Jakarta Messaging 3.0新開發首選(MQ 9.3+)Jakarta EE 9+、Spring Boot 3 / 4Java EE 8 以下
Spring JMSorg.springframework.jms.*SpringSpring 生態Spring Boot 應用(底層用 Jakarta Messaging)非 Spring 專案

官方說明(重新以自己的話整理):JMS 2.0 已被 Jakarta Messaging 取代,未來的 Java 訊息功能只會出現在 Jakarta Messaging 版本中;IBM MQ classes for Java 雖功能凍結,但缺陷修正與因應系統需求的變更仍會提供。

9.4 Maven 依賴

<properties>
    <!-- 實際修補版號需依 Maven Central 與 IBM 官方 Readme 確認 -->
    <ibm.mq.version>10.0.0.0</ibm.mq.version>
</properties>

<dependencies>
    <!-- 新開發:Jakarta Messaging -->
    <dependency>
        <groupId>com.ibm.mq</groupId>
        <artifactId>com.ibm.mq.jakarta.client</artifactId>
        <version>${ibm.mq.version}</version>
    </dependency>

    <!-- 舊系統維護:JMS 2.0(javax)與 MQ classes for Java -->
    <!--
    <dependency>
        <groupId>com.ibm.mq</groupId>
        <artifactId>com.ibm.mq.allclient</artifactId>
        <version>${ibm.mq.version}</version>
    </dependency>
    -->
</dependencies>

不要在同一個應用同時引入 com.ibm.mq.allclient 與 com.ibm.mq.jakarta.client,兩者都內含 IBM MQ classes for Java(com.ibm.mq.MQQueueManager、com.ibm.mq.headers.pcf.* 等)的類別,同時引入會造成重複類別與版本衝突。依官方 Java 介面說明:allclient = classes for Java + classes for JMS(javax);jakarta.client = classes for Java + classes for Jakarta Messaging。實際打包內容仍以使用版本的 Readme 確認 [需確認]。

9.5 Java 版本對照

Java狀態MQ Client 相關注意
Java 8MQ Java API 的建置基準(9.3+ 以 Java 8 建置)可執行;但 Spring Boot 3 / 4 不支援
Java 17 [Java 17]Spring Boot 3 最低要求主流 LTS
Java 21 [Java 21]LTS;Virtual Threads 正式版Virtual Thread 與 MQ Client 的相容性與效益需實測 [需確認]
Java 25 [Java 25]最新 LTS;本手冊基準Semeru 25 停用 TLS_RSA_*;檔案編碼預設 UTF-8 的影響需評估 [MQ 10.0]

MQ 10.0 支援的 JDK 清單請以 System Requirements 為準 [需確認]。

9.6 Client 連線關鍵概念

概念說明
Connection ModeClient(WMQ_CM_CLIENT)或 Bindings(WMQ_CM_BINDINGS)
connNamehost(port),可逗號分隔多個(HA)
CCDTClient Channel Definition Table,JSON 或二進位格式;可透過 URL 取得,[MQ 10.0] 支援 HTTPS 取得 CCDT
Auto ReconnectClient 自動重連(WMQ_CLIENT_RECONNECT / WMQ_CLIENT_RECONNECT_Q_MGR),重連期間 API 呼叫會被阻塞直到成功或逾時
Application Name在 DISPLAY CONN 中顯示為 APPLTAG,對維運排查極重要,一律設定
SHARECNV多個 JMS Session 共用一條 TCP 連線

9.7 多語言支援全貌

企業的 MQ 生態系很少只有 Java。Java 團隊在逆向工程或整合時,必須知道對端可能用哪種 API,以及它的支援等級。

語言 / 協定API提供方式支援等級典型場景
CMQI產品內附IBM 正式支援高效能服務、系統工具
COBOLMQI產品內附IBM 正式支援主機 CICS / Batch、Legacy
PL/I、AssemblerMQI產品內附IBM 正式支援(僅 z/OS)主機系統
RPGMQI產品內附IBM 正式支援(僅 IBM i)IBM i 系統
Visual BasicMQI產品內附IBM 正式支援(僅 Windows)舊式桌面程式
C++IBM MQ C++ classes(物件模型)產品內附IBM 正式支援C++ 應用
JavaIBM MQ classes for Java / JMS / Jakarta MessagingMaven CentralIBM 正式支援本手冊主軸(Part 9-12)
.NET(C#、VB.NET)IBM MQ classes for .NET、XMS .NETNuGet;[MQ 10.0] 以 .NET 10 建置IBM 正式支援Windows / Linux .NET 服務
Gomq-golangGitHub ibm-messagingas-is(非正式支援),底層呼叫 C Client雲原生工具、Exporter
Node.jsmq-mqi-nodejsnpm / GitHubas-is,底層呼叫 C ClientBFF、工具
PythonIBM 提供的 Python MQI 套件PyPI / GitHubas-is [需確認套件名稱與支援狀態]腳本、測試工具
AMQP 1.0Apache Qpid Proton、Qpid JMS 等第三方協定由 IBM MQ 支援;用戶端依第三方非 IBM 生態系
MQTTEclipse Paho 等第三方協定由 IBM MQ Telemetry 支援IoT
HTTPMessaging REST API產品內附(mqweb)IBM 正式支援輕量整合(見 9.8)

選型原則:

  1. 交易性、高可靠的業務流程,使用 IBM 正式支援的 API(MQI、Java / Jakarta、.NET)。
  2. as-is 的語言綁定適合工具與非關鍵服務;採用前確認團隊有能力自行維護。
  3. 所有語言都應設定 Application Name(MQ 9.1.2 起多數語言可設定),讓 DISPLAY CONN 能辨識來源。

9.8 Messaging REST API

Messaging REST API 讓任何能發 HTTPS 請求的程式送收訊息,不需要安裝 MQ Client。它與 Part 5.11 的 Administrative REST API 共用 mqweb server。

操作HTTP路徑(v3)說明
放入訊息POST/ibmmq/rest/v3/messaging/qmgr/{qmgr}/queue/{queue}/messageBody 即訊息內容
取出訊息(破壞性讀取)DELETE同上回應 Body 為訊息內容
瀏覽訊息GET同上不刪除
發佈到 TopicPOST/ibmmq/rest/v3/messaging/qmgr/{qmgr}/topic/{topicString}/messagePub/Sub
# 放入一則訊息(需 MQWebUser 角色,並受 OAM 權限控管)
curl -sS --cacert /etc/mq/ca.pem --netrc-file ~/.mq-msg.netrc \
  -H "ibm-mq-rest-csrf-token: app" \
  -H "Content-Type: text/plain;charset=utf-8" \
  -H "ibm-mq-md-expiry: 300000" \
  -X POST "https://mqweb.bank.local:9443/ibmmq/rest/v3/messaging/qmgr/BANKQM01/queue/NOTIFY.EVENT/message" \
  -d '{"eventType":"STATEMENT_READY","customerRef":"C-001"}'

# 取出一則訊息(-i 顯示回應標頭,可取得 ibm-mq-md-messageId 等 MQMD 資訊)
curl -sS -i --cacert /etc/mq/ca.pem --netrc-file ~/.mq-msg.netrc \
  -H "ibm-mq-rest-csrf-token: app" \
  -X DELETE "https://mqweb.bank.local:9443/ibmmq/rest/v3/messaging/qmgr/BANKQM01/queue/NOTIFY.EVENT/message?wait=5000"

MQMD 對應標頭(ibm-mq-md-*)、Expiry 的單位、是否預設啟用 Messaging API,以及支援的訊息格式,請依 IBM MQ 10.0 REST API Reference 確認 [需確認]。

面向評估
優點不需 MQ Client;任何語言都能使用;防火牆只需開 HTTPS
交易性每個 HTTP 請求各自獨立,無法把多個操作放在同一個 Syncpoint
可靠性風險DELETE 取出後若 HTTP 回應在網路上遺失,訊息已從佇列移除但用戶端沒收到
效能每則訊息一次 HTTPS 往返,吞吐量遠低於原生 Client
結論適合通知、監控、測試工具、IoT 閘道;不適合金融主交易流程

9.9 應用設計考量

官方「Design considerations for IBM MQ applications」討論的主題,整理成企業 Java 團隊可直接執行的設計規則:

主題設計規則違反時的典型症狀參考
連線與 Handle連線與開啟的物件要重複使用;用 Connection Pool / CachingConnectionFactoryQM 連線數暴增、2537、CPU 偏高Part 10、12
訊息大小交易電文控制在 KB 級;大檔用 MFT 或 Claim Check2010 / 2030、Log 壓力Part 6.4、25
持久性交易性訊息一律 Persistent;Non-persistent 只用於可遺失資料QM 異常後訊息消失Part 3.6
交易範圍交易要小、時間要短,避免一個交易包含大量訊息或長時間等待Log 空間被長交易佔住、恢復時間變長Part 3.5、13
等待方式用 MQGMO_WAIT / Listener,不要忙碌輪詢CPU 浪費、QM 負載Part 10.5
錯誤分類依 Reason Code 區分連線、權限、容量、資料錯誤無限重試、毒訊息塞住佇列Part 23.4
字元集明確設定 CCSID 與 Encoding;跨平台使用 MQGMO_CONVERT 或應用層轉換中文亂碼、數字欄位錯誤Part 3、P32
訊息屬性與 Legacy 互通時控制 PROPCTL / targetClient對端解析到多餘 MQRFH2Part 3.13、11.4
可辨識性一律設定 Application Name出事時找不到是哪個應用Part 9.6
高可用友善不依賴特定 QM 的狀態;支援自動重連;Uniform Cluster 下設定 balancing 參數切換後應用卡住Part 26.8
安全帳密與憑證外部化;最小權限憑證外洩、2035Part 8
可移植性物件名稱以設定提供;不寫死平台路徑換環境需改程式Part 34

9.10 IBM MQ 10.0 對 Java / JMS 開發者的新能力

能力說明對開發者的意義
短生命週期容器的 trace為短暫執行的 Java / JMS 容器提供可收集的 trace 方式K8s Job、Serverless 類工作負載也能除錯 [需確認設定方式]
JMS Selector 使用 MsgToken以 MsgToken 精準取回特定訊息減少以自訂屬性 Selector 的掃描成本
多個 JMS 連線視為單一應用實例Uniform Cluster 平衡時,把同一行程的多個連線一起移動搭配 Spring Boot Starter balancingInstanceMode=JVM
JWT endpointClient 自動向 Token Server 取得 JWT不需在應用程式中自己管理 Token;Starter 以 ibm.mq.tokenServer.* 設定
JMS 連線 keepalive 可自訂調整 Client 端 TCP keepalive 行為解決防火牆閒置斷線造成的 2009
Client 預設 TCP buffer 變更預設值調整升級後重新做效能基準測試
HTTPS CCDT 與自訂 SSLSocketFactory安全取得集中管理的 CCDT配合企業內部 CA
Semeru 21 / 25 檔案編碼變更預設檔案編碼改變未指定 Charset 的 String.getBytes()、new String(byte[]) 行為可能改變,電文組裝一律明確指定 Charset
Jakarta Messaging Resource Adapter 支援 GlassFish應用伺服器部署選項增加Jakarta EE 應用可評估

9.11 AI Agent 使用方式

  • 請 AI 掃描專案的 import,產出「使用中的 MQ API 清單」(com.ibm.mq.*、javax.jms.*、jakarta.jms.*、com.ibm.msg.client.*)。
  • 請 AI 依本章比較表,對每個模組建議「保留 / 遷移到 Jakarta Messaging」,並列出理由。

9.12 Checklist

  • 新開發使用 IBM MQ classes for Jakarta Messaging
  • 不同時引入 javax 與 jakarta 兩套 MQ Client
  • MQ Client 版號由 BOM 或 property 集中管理
  • 所有連線設定 Application Name
  • 非 Java 對端的 API 與支援等級已列入介面文件
  • Messaging REST API 只用於非交易性情境
  • 電文組裝與解析一律明確指定 Charset 與 CCSID

Part 10 — Java MQ 基礎程式(IBM MQ classes for Java)

10.1 目的

以 IBM MQ classes for Java 示範完整的 Producer 與 Consumer。此 API 已功能凍結,本章主要用途是:理解 MQI 概念、維護既有系統、逆向工程時能讀懂舊程式。新開發請使用 Part 11、12。

10.2 設計重點

面向做法
Connection長連線,重複使用;可恢復錯誤時重連
ResourceMQQueue.close()、MQQueueManager.disconnect() 放在 finally
Message明確設定 Persistence、Expiry、Format、CCSID
TransactionMQPMO_SYNCPOINT / MQGMO_SYNCPOINT + commit() / backout()
TimeoutMQGMO_WAIT + waitInterval
Retry只對可恢復的 Reason Code 重試,指數退避 + 上限
Poison自行檢查 backoutCount,超過門檻移到 BOQ
LoggingLog4j2;記錄 MsgId / CorrelId(十六進位)、Reason Code;不記錄訊息內容中的個資
Security帳密由環境 / Secret 注入;TLS Cipher Suite;MQCSP

10.3 共用:連線設定與工具

package com.example.mq.classic;

import com.ibm.mq.MQException;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.constants.MQConstants;

import java.util.HexFormat;
import java.util.Hashtable;
import java.util.Set;

/**
 * IBM MQ classes for Java 連線設定。
 * 敏感資訊(password)必須由 Secret 注入,禁止寫死在程式或設定檔中。
 */
public record MqClientConfig(
        String host,
        int port,
        String channel,
        String queueManager,
        String user,
        String password,
        String cipherSuite,
        String applicationName) {

    /** 可透過重新連線恢復的 Reason Code。 */
    public static final Set<Integer> RECONNECTABLE_REASONS = Set.of(
            MQConstants.MQRC_CONNECTION_BROKEN,     // 2009
            MQConstants.MQRC_Q_MGR_NOT_AVAILABLE,   // 2059
            MQConstants.MQRC_Q_MGR_QUIESCING,       // 2161
            MQConstants.MQRC_Q_MGR_STOPPING,        // 2162
            MQConstants.MQRC_HOST_NOT_AVAILABLE,    // 2538
            MQConstants.MQRC_RECONNECT_FAILED);     // 2548

    /**
     * 建立 Queue Manager 連線。
     *
     * @return 已連線的 MQQueueManager
     * @throws MQException 連線失敗
     */
    public MQQueueManager connect() throws MQException {
        Hashtable<String, Object> props = new Hashtable<>();
        props.put(MQConstants.TRANSPORT_PROPERTY, MQConstants.TRANSPORT_MQSERIES_CLIENT);
        props.put(MQConstants.HOST_NAME_PROPERTY, host);
        props.put(MQConstants.PORT_PROPERTY, port);
        props.put(MQConstants.CHANNEL_PROPERTY, channel);
        props.put(MQConstants.APPNAME_PROPERTY, applicationName);
        props.put(MQConstants.USER_ID_PROPERTY, user);
        props.put(MQConstants.PASSWORD_PROPERTY, password);
        props.put(MQConstants.USE_MQCSP_AUTHENTICATION_PROPERTY, Boolean.TRUE);
        if (cipherSuite != null && !cipherSuite.isBlank()) {
            // 非 IBM JRE 需另設 -Dcom.ibm.mq.cfg.useIBMCipherMappings=false
            props.put(MQConstants.SSL_CIPHER_SUITE_PROPERTY, cipherSuite);
        }
        return new MQQueueManager(queueManager, props);
    }

    /** 以十六進位輸出 MsgId / CorrelId,方便與 MQ 工具比對。 */
    public static String hex(byte[] id) {
        return id == null ? "" : HexFormat.of().formatHex(id);
    }

    @Override
    public String toString() {
        // 避免密碼被意外寫入日誌
        return "MqClientConfig[host=%s, port=%d, channel=%s, qmgr=%s, user=%s, app=%s]"
                .formatted(host, port, channel, queueManager, user, applicationName);
    }
}

注意:record 預設的 toString() 會輸出所有欄位,包括密碼,因此必須覆寫。[Java 17] 起可用 record;HexFormat 需 [Java 17]。

10.4 Producer(MQPUT)

package com.example.mq.classic;

import com.ibm.mq.MQException;
import com.ibm.mq.MQMessage;
import com.ibm.mq.MQPutMessageOptions;
import com.ibm.mq.MQQueue;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.constants.MQConstants;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.io.IOException;
import java.nio.charset.StandardCharsets;

/**
 * 轉帳請求 Producer。非執行緒安全:每個執行緒使用自己的實例。
 */
public final class TransferRequestProducer implements AutoCloseable {

    private static final Logger LOG = LogManager.getLogger(TransferRequestProducer.class);
    private static final int MAX_ATTEMPTS = 5;
    private static final long BASE_BACKOFF_MS = 500L;
    private static final long MAX_BACKOFF_MS = 10_000L;
    private static final int CCSID_UTF8 = 1208;

    private final MqClientConfig config;
    private final String requestQueueName;
    private final String replyQueueName;
    private MQQueueManager qmgr;
    private MQQueue requestQueue;

    public TransferRequestProducer(MqClientConfig config, String requestQueueName, String replyQueueName) {
        this.config = config;
        this.requestQueueName = requestQueueName;
        this.replyQueueName = replyQueueName;
    }

    /**
     * 送出一筆轉帳請求。
     *
     * @param businessKey 業務唯一鍵(作為 CorrelId 來源與冪等依據)
     * @param payload     JSON 內容
     * @param expirySec   請求存活秒數(逾時後自動失效)
     * @return Queue Manager 產生的 MsgId
     * @throws MQException 不可恢復的 MQ 錯誤,或重試次數用盡
     */
    public byte[] send(String businessKey, String payload, int expirySec) throws MQException {
        for (int attempt = 1; ; attempt++) {
            try {
                ensureOpen();
                MQMessage msg = new MQMessage();
                msg.format = MQConstants.MQFMT_STRING;
                msg.characterSet = CCSID_UTF8;
                msg.persistence = MQConstants.MQPER_PERSISTENT;
                msg.expiry = expirySec * 10;                       // 單位:1/10 秒
                msg.messageType = MQConstants.MQMT_REQUEST;
                msg.replyToQueueName = replyQueueName;
                msg.correlationId = CorrelationIds.fromBusinessKey(businessKey);
                msg.write(payload.getBytes(StandardCharsets.UTF_8));

                MQPutMessageOptions pmo = new MQPutMessageOptions();
                pmo.options = MQConstants.MQPMO_SYNCPOINT
                        | MQConstants.MQPMO_NEW_MSG_ID
                        | MQConstants.MQPMO_FAIL_IF_QUIESCING;

                requestQueue.put(msg, pmo);
                qmgr.commit();
                LOG.info("MQPUT ok queue={} msgId={} correlId={}",
                        requestQueueName, MqClientConfig.hex(msg.messageId), MqClientConfig.hex(msg.correlationId));
                return msg.messageId;

            } catch (MQException e) {
                backoutQuietly();
                boolean reconnectable = MqClientConfig.RECONNECTABLE_REASONS.contains(e.reasonCode);
                boolean queueFull = e.reasonCode == MQConstants.MQRC_Q_FULL;
                LOG.warn("MQPUT failed attempt={} queue={} reason={} cc={}",
                        attempt, requestQueueName, e.reasonCode, e.completionCode);
                if ((!reconnectable && !queueFull) || attempt >= MAX_ATTEMPTS) {
                    throw e;
                }
                if (reconnectable) {
                    // 若錯誤發生在 commit 期間,結果未知:下游必須以 businessKey 做冪等
                    closeQuietly();
                }
                sleep(backoff(attempt));
            } catch (IOException e) {
                backoutQuietly();
                throw new IllegalStateException("Failed to write message body", e);
            }
        }
    }

    private void ensureOpen() throws MQException {
        if (qmgr == null || !qmgr.isConnected()) {
            qmgr = config.connect();
            requestQueue = null;
        }
        if (requestQueue == null || !requestQueue.isOpen()) {
            int openOptions = MQConstants.MQOO_OUTPUT | MQConstants.MQOO_FAIL_IF_QUIESCING;
            requestQueue = qmgr.accessQueue(requestQueueName, openOptions);
        }
    }

    private static long backoff(int attempt) {
        long exp = BASE_BACKOFF_MS * (1L << Math.min(attempt - 1, 10));
        long jitter = (long) (Math.random() * BASE_BACKOFF_MS);
        return Math.min(exp + jitter, MAX_BACKOFF_MS);
    }

    private static void sleep(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException ie) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Interrupted during MQ retry backoff", ie);
        }
    }

    private void backoutQuietly() {
        try {
            if (qmgr != null && qmgr.isConnected()) {
                qmgr.backout();
            }
        } catch (MQException e) {
            LOG.debug("backout failed reason={}", e.reasonCode);
        }
    }

    private void closeQuietly() {
        try {
            if (requestQueue != null && requestQueue.isOpen()) {
                requestQueue.close();
            }
        } catch (MQException e) {
            LOG.debug("close queue failed reason={}", e.reasonCode);
        } finally {
            requestQueue = null;
        }
        try {
            if (qmgr != null && qmgr.isConnected()) {
                qmgr.disconnect();
            }
        } catch (MQException e) {
            LOG.debug("disconnect failed reason={}", e.reasonCode);
        } finally {
            qmgr = null;
        }
    }

    @Override
    public void close() {
        closeQuietly();
    }
}

CorrelationIds 工具(將業務鍵轉為固定 24 bytes 的 CorrelId):

package com.example.mq.classic;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Arrays;

/** 將業務鍵轉為 24 bytes CorrelId(SHA-256 前 24 bytes),確保相同業務鍵得到相同 CorrelId。 */
public final class CorrelationIds {

    private static final int MQ_ID_LENGTH = 24;

    private CorrelationIds() {
    }

    public static byte[] fromBusinessKey(String businessKey) {
        try {
            byte[] digest = MessageDigest.getInstance("SHA-256")
                    .digest(businessKey.getBytes(StandardCharsets.UTF_8));
            return Arrays.copyOf(digest, MQ_ID_LENGTH);
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("SHA-256 not available", e);
        }
    }
}

10.5 Consumer(MQGET)

package com.example.mq.classic;

import com.ibm.mq.MQException;
import com.ibm.mq.MQGetMessageOptions;
import com.ibm.mq.MQMessage;
import com.ibm.mq.MQPutMessageOptions;
import com.ibm.mq.MQQueue;
import com.ibm.mq.MQQueueManager;
import com.ibm.mq.constants.MQConstants;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * 轉帳請求 Consumer。以 Syncpoint 取訊息,處理成功才 Commit;
 * 超過 Backout 門檻或永久性錯誤時移到 Backout Queue。
 */
public final class TransferRequestConsumer implements Runnable, AutoCloseable {

    private static final Logger LOG = LogManager.getLogger(TransferRequestConsumer.class);
    private static final int WAIT_INTERVAL_MS = 5_000;
    private static final long RECONNECT_DELAY_MS = 5_000L;

    /** 業務處理介面;以例外型別區分暫時性與永久性錯誤。 */
    public interface Handler {
        void handle(String correlIdHex, String body) throws TransientException, PermanentException;
    }

    public static final class TransientException extends Exception {
        public TransientException(String m, Throwable c) { super(m, c); }
    }

    public static final class PermanentException extends Exception {
        public PermanentException(String m, Throwable c) { super(m, c); }
    }

    private final MqClientConfig config;
    private final String inputQueueName;
    private final String backoutQueueName;
    private final int backoutThreshold;
    private final Handler handler;
    private final AtomicBoolean running = new AtomicBoolean(true);

    private MQQueueManager qmgr;
    private MQQueue inputQueue;

    public TransferRequestConsumer(MqClientConfig config, String inputQueueName,
                                   String backoutQueueName, int backoutThreshold, Handler handler) {
        this.config = config;
        this.inputQueueName = inputQueueName;
        this.backoutQueueName = backoutQueueName;
        this.backoutThreshold = backoutThreshold;
        this.handler = handler;
    }

    @Override
    public void run() {
        while (running.get()) {
            try {
                ensureOpen();
                consumeOne();
            } catch (MQException e) {
                if (e.reasonCode == MQConstants.MQRC_NO_MSG_AVAILABLE) {
                    continue;                                        // 2033:等待逾時,正常
                }
                LOG.error("MQGET loop error queue={} reason={}", inputQueueName, e.reasonCode);
                closeQuietly();
                if (!MqClientConfig.RECONNECTABLE_REASONS.contains(e.reasonCode)) {
                    // 2035、2085 等設定錯誤:停止並告警,避免無限重試
                    running.set(false);
                    break;
                }
                pause(RECONNECT_DELAY_MS);
            }
        }
        closeQuietly();
        LOG.info("Consumer stopped queue={}", inputQueueName);
    }

    private void consumeOne() throws MQException {
        MQMessage msg = new MQMessage();
        MQGetMessageOptions gmo = new MQGetMessageOptions();
        gmo.options = MQConstants.MQGMO_WAIT
                | MQConstants.MQGMO_SYNCPOINT
                | MQConstants.MQGMO_CONVERT
                | MQConstants.MQGMO_FAIL_IF_QUIESCING;
        gmo.waitInterval = WAIT_INTERVAL_MS;

        inputQueue.get(msg, gmo);

        String msgId = MqClientConfig.hex(msg.messageId);
        String correlId = MqClientConfig.hex(msg.correlationId);

        if (msg.backoutCount >= backoutThreshold) {
            LOG.warn("Poison message msgId={} backoutCount={} -> {}", msgId, msg.backoutCount, backoutQueueName);
            moveToBackoutQueue(msg);
            return;
        }

        try {
            String body = readBody(msg);
            handler.handle(correlId, body);
            qmgr.commit();
            LOG.info("Processed msgId={} correlId={}", msgId, correlId);
        } catch (PermanentException e) {
            LOG.error("Permanent failure msgId={} -> {} cause={}", msgId, backoutQueueName, e.getMessage());
            moveToBackoutQueue(msg);
        } catch (TransientException e) {
            LOG.warn("Transient failure msgId={} backoutCount={} cause={}", msgId, msg.backoutCount, e.getMessage());
            qmgr.backout();
            pause(1_000L * (msg.backoutCount + 1));            // 簡易退避,避免熱循環
        } catch (RuntimeException e) {
            LOG.error("Unexpected failure msgId={}", msgId, e);
            qmgr.backout();
        }
    }

    /** 在同一個 Syncpoint 內:PUT 到 BOQ + 原訊息 GET 一起 Commit。 */
    private void moveToBackoutQueue(MQMessage original) throws MQException {
        MQPutMessageOptions pmo = new MQPutMessageOptions();
        pmo.options = MQConstants.MQPMO_SYNCPOINT
                | MQConstants.MQPMO_PASS_ALL_CONTEXT
                | MQConstants.MQPMO_FAIL_IF_QUIESCING;
        pmo.contextReference = inputQueue;
        try {
            qmgr.put(backoutQueueName, original, pmo);
            qmgr.commit();
        } catch (MQException e) {
            LOG.error("Move to BOQ failed reason={} — backing out", e.reasonCode);
            qmgr.backout();
            throw e;
        }
    }

    private static String readBody(MQMessage msg) {
        try {
            byte[] data = new byte[msg.getDataLength()];
            msg.readFully(data);
            return new String(data, StandardCharsets.UTF_8);
        } catch (IOException e) {
            throw new IllegalStateException("Failed to read message body", e);
        }
    }

    private void ensureOpen() throws MQException {
        if (qmgr == null || !qmgr.isConnected()) {
            qmgr = config.connect();
            inputQueue = null;
        }
        if (inputQueue == null || !inputQueue.isOpen()) {
            int openOptions = MQConstants.MQOO_INPUT_AS_Q_DEF
                    | MQConstants.MQOO_SAVE_ALL_CONTEXT
                    | MQConstants.MQOO_FAIL_IF_QUIESCING;
            inputQueue = qmgr.accessQueue(inputQueueName, openOptions);
        }
    }

    private void pause(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException ie) {
            Thread.currentThread().interrupt();
            running.set(false);
        }
    }

    private void closeQuietly() {
        try {
            if (inputQueue != null && inputQueue.isOpen()) inputQueue.close();
        } catch (MQException e) {
            LOG.debug("close failed reason={}", e.reasonCode);
        } finally {
            inputQueue = null;
        }
        try {
            if (qmgr != null && qmgr.isConnected()) qmgr.disconnect();
        } catch (MQException e) {
            LOG.debug("disconnect failed reason={}", e.reasonCode);
        } finally {
            qmgr = null;
        }
    }

    /** 由 shutdown hook 或容器生命週期呼叫;最長等待一個 waitInterval 後結束。 */
    @Override
    public void close() {
        running.set(false);
    }
}

重點說明:

項目說明
MQGMO_WAIT + waitInterval避免忙碌輪詢;2033 表示等待逾時、不是錯誤
MQGMO_SYNCPOINT處理成功才 commit();失敗 backout() 讓訊息回到佇列
backoutCount 檢查MQ classes for Java 不會自動移到 BOQ,必須自行處理
MQOO_SAVE_ALL_CONTEXT + MQPMO_PASS_ALL_CONTEXT移到 BOQ 時保留原始身分與來源資訊(需 passall 權限)
不可恢復錯誤停止2035、2085 屬設定問題,重試無意義,應停止並告警
Graceful shutdownclose() 設定旗標,迴圈最晚在 waitInterval 後結束

10.6 Transaction 說明

  • Producer:MQPMO_SYNCPOINT + commit(),若 commit() 期間連線中斷(2009),送出結果未知。重送可能造成重複 → 下游以 CorrelId / 業務鍵做冪等。
  • Consumer:GET 與「移到 BOQ」在同一 Syncpoint,確保不會「原訊息已刪除、BOQ 卻沒有」。
  • DB 操作不在 MQ Syncpoint 內(除非使用 XA),見 Part 13。

10.7 Security 注意事項

  • password 從 Secret 注入;toString() 不得輸出密碼。
  • 使用 TLS Cipher Suite;非 IBM JRE 設定 useIBMCipherMappings=false。
  • MQPMO_PASS_ALL_CONTEXT 需要 passall 權限,只授予確實需要搬移訊息的帳號。
  • 日誌只記錄 MsgId / CorrelId,不記錄 body(可能含帳號、身分證字號)。

10.8 常見錯誤

  • 每送一則訊息就 connect() / disconnect():連線成本高,吞吐量下降數十倍。
  • MQGMO_NO_WAIT 搭配 while(true):CPU 100%。
  • 忘記 commit():訊息一直在 in-flight 狀態,其他 Consumer 看不到;連線結束時的行為依平台而定。
  • 多執行緒共用同一個 MQQueueManager 與 MQQueue 而未同步。

10.9 Checklist

  • 連線重複使用,錯誤時才重建
  • finally / close() 釋放 Queue 與連線
  • Producer 與 Consumer 都使用 Syncpoint
  • MQGMO_WAIT + 合理 waitInterval
  • 只對可恢復 Reason Code 重試,有上限與退避
  • 自行處理 BackoutCount
  • 日誌記錄 MsgId / CorrelId 十六進位,不記錄敏感內容

Part 11 — Java JMS / Jakarta Messaging

11.1 目的

以 IBM MQ classes for Jakarta Messaging(新開發首選)示範 ConnectionFactory、Destination、JMSContext、Producer、Consumer 與 MessageListener。

11.2 JMS 2.0 / Jakarta Messaging 物件模型

classDiagram
    class ConnectionFactory {
        +createContext(user, pwd, sessionMode)
    }
    class JMSContext {
        +createProducer()
        +createConsumer(Destination, selector)
        +createQueue(name)
        +createTextMessage(text)
        +commit()
        +rollback()
        +close()
    }
    class JMSProducer {
        +setDeliveryMode()
        +setTimeToLive()
        +setJMSCorrelationID()
        +setJMSReplyTo()
        +send(Destination, Message)
    }
    class JMSConsumer {
        +receive(timeout)
        +setMessageListener()
        +close()
    }
    class Destination
    class Queue
    class Topic
    class Message {
        +getJMSMessageID()
        +getJMSCorrelationID()
        +getStringProperty()
    }
    ConnectionFactory --> JMSContext
    JMSContext --> JMSProducer
    JMSContext --> JMSConsumer
    Destination <|-- Queue
    Destination <|-- Topic
    JMSProducer --> Message
    JMSConsumer --> Message

11.3 JMS 與 MQMD 對應

JMS / Jakarta 欄位MQMD / MQ 對應說明
JMSMessageIDMsgId格式 ID: + 48 位十六進位
JMSCorrelationIDCorrelId以 ID: + 48 位十六進位設定時,直接對應 24 bytes CorrelId
JMSDeliveryModePersistenceJMS 預設 PERSISTENT
JMSExpiration / TimeToLiveExpiryJMS 以毫秒設定,MQ 內部換算為 1/10 秒
JMSPriorityPriority0-9
JMSReplyToReplyToQ / ReplyToQMgr
JMSXDeliveryCountBackoutCount + 1判斷重送次數
Message PropertiesRFH2 標頭或 MQ Message Properties非 JMS 的 Legacy 接收端可能看不懂 RFH2

11.4 與 Legacy(非 JMS)系統互通:targetClient

當接收端是 COBOL / C / MQ classes for Java 程式時,必須讓 JMS 送出不含 RFH2 標頭的純 MQ 訊息:

// 方法 1:URI 參數(targetClient=1 表示非 JMS 接收端)
Queue legacyQueue = context.createQueue("queue:///CBS.TXN.TRANSFER.REQ?targetClient=1");

// 方法 2:程式設定(需轉型為 IBM 實作類別)
// ((com.ibm.mq.jakarta.jms.MQDestination) legacyQueue)
//         .setTargetClient(com.ibm.msg.client.jakarta.wmq.WMQConstants.WMQ_CLIENT_NONJMS_MQ);

逆向工程常見坑:Legacy 收到的訊息前面多了一段以 RFH 加一個空白開頭的二進位資料,導致解析失敗。原因就是 JMS 端沒有設定 targetClient。

11.5 ConnectionFactory

package com.example.mq.jakarta;

import com.ibm.mq.jakarta.jms.MQConnectionFactory;
import com.ibm.msg.client.jakarta.wmq.WMQConstants;
import jakarta.jms.JMSException;

/** 建立 IBM MQ Jakarta Messaging ConnectionFactory。 */
public final class MqConnectionFactories {

    private MqConnectionFactories() {
    }

    /**
     * @param connNameList 例如 "mq-a.bank.local(1414),mq-b.bank.local(1414)"
     */
    public static MQConnectionFactory create(String queueManager, String channel, String connNameList,
                                             String applicationName, String cipherSuite) throws JMSException {
        MQConnectionFactory cf = new MQConnectionFactory();
        cf.setTransportType(WMQConstants.WMQ_CM_CLIENT);
        cf.setQueueManager(queueManager);
        cf.setChannel(channel);
        cf.setConnectionNameList(connNameList);
        cf.setAppName(applicationName);
        cf.setSSLCipherSuite(cipherSuite);
        // 同名 QM 的 HA(Multi-instance / Native HA)使用 QMGR 重連
        cf.setClientReconnectOptions(WMQConstants.WMQ_CLIENT_RECONNECT_Q_MGR);
        cf.setClientReconnectTimeout(300);
        cf.setBooleanProperty(WMQConstants.USER_AUTHENTICATION_MQCSP, true);
        return cf;
    }
}

setConnectionNameList、setClientReconnectOptions 等 setter 與常數名稱,請以使用版本的 IBM MQ Jakarta Messaging API 文件確認。

11.6 Producer(JMSContext + JMSProducer)

package com.example.mq.jakarta;

import jakarta.jms.DeliveryMode;
import jakarta.jms.JMSContext;
import jakarta.jms.JMSException;
import jakarta.jms.JMSProducer;
import jakarta.jms.JMSRuntimeException;
import jakarta.jms.Queue;
import jakarta.jms.TextMessage;
import com.ibm.mq.jakarta.jms.MQConnectionFactory;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

/** 以 Jakarta Messaging 送出轉帳請求(交易式 Session)。 */
public final class JakartaTransferProducer implements AutoCloseable {

    private static final Logger LOG = LogManager.getLogger(JakartaTransferProducer.class);

    private final JMSContext context;
    private final Queue requestQueue;
    private final Queue replyQueue;

    public JakartaTransferProducer(MQConnectionFactory cf, String user, String password) {
        this.context = cf.createContext(user, password, JMSContext.SESSION_TRANSACTED);
        this.context.setExceptionListener(ex ->
                LOG.error("JMS connection exception errorCode={}", ex.getErrorCode(), ex));
        this.requestQueue = context.createQueue("queue:///NBK.TXN.TRANSFER.REQ?targetClient=1");
        this.replyQueue = context.createQueue("queue:///NBK.TXN.TRANSFER.RSP");
    }

    /**
     * @return JMSMessageID(ID: + 48 hex)
     */
    public String send(String correlationIdHex48, String json, long ttlMillis) {
        try {
            TextMessage msg = context.createTextMessage(json);
            msg.setJMSCorrelationID("ID:" + correlationIdHex48);
            msg.setStringProperty("traceId", TraceContext.currentTraceId());

            JMSProducer producer = context.createProducer()
                    .setDeliveryMode(DeliveryMode.PERSISTENT)
                    .setTimeToLive(ttlMillis)
                    .setJMSReplyTo(replyQueue);
            producer.send(requestQueue, msg);
            context.commit();

            LOG.info("JMS send ok msgId={} correlId={}", msg.getJMSMessageID(), msg.getJMSCorrelationID());
            return msg.getJMSMessageID();
        } catch (JMSException | JMSRuntimeException e) {
            safeRollback();
            throw new MqSendException("Failed to send transfer request", e);
        }
    }

    private void safeRollback() {
        try {
            context.rollback();
        } catch (JMSRuntimeException ex) {
            LOG.debug("rollback failed", ex);
        }
    }

    @Override
    public void close() {
        context.close();
    }

    public static final class MqSendException extends RuntimeException {
        public MqSendException(String m, Throwable c) { super(m, c); }
    }
}

TraceContext 代表專案自己的追蹤 ID 來源(例如 OpenTelemetry),此處省略。JMSContext 不是執行緒安全的,每個執行緒使用自己的 Context。

11.7 Consumer(同步 receive)

package com.example.mq.jakarta;

import jakarta.jms.JMSConsumer;
import jakarta.jms.JMSContext;
import jakarta.jms.JMSException;
import jakarta.jms.JMSRuntimeException;
import jakarta.jms.Message;
import jakarta.jms.Queue;
import jakarta.jms.TextMessage;
import com.ibm.mq.jakarta.jms.MQConnectionFactory;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.function.Consumer;

/** 交易式同步 Consumer:處理成功 commit,失敗 rollback;毒訊息由 MQ JMS 依 BOTHRESH 移至 BOQNAME。 */
public final class JakartaTransferConsumer implements Runnable, AutoCloseable {

    private static final Logger LOG = LogManager.getLogger(JakartaTransferConsumer.class);
    private static final long RECEIVE_TIMEOUT_MS = 5_000L;

    private final JMSContext context;
    private final Queue inputQueue;
    private final Consumer<String> businessHandler;
    private volatile boolean running = true;

    public JakartaTransferConsumer(MQConnectionFactory cf, String user, String password,
                                   String queueName, Consumer<String> businessHandler) {
        this.context = cf.createContext(user, password, JMSContext.SESSION_TRANSACTED);
        this.inputQueue = context.createQueue("queue:///" + queueName);
        this.businessHandler = businessHandler;
    }

    @Override
    public void run() {
        try (JMSConsumer consumer = context.createConsumer(inputQueue)) {
            while (running) {
                Message message = consumer.receive(RECEIVE_TIMEOUT_MS);
                if (message == null) {
                    continue;
                }
                handle(message);
            }
        } catch (JMSRuntimeException e) {
            LOG.error("Consumer loop terminated", e);
        }
    }

    private void handle(Message message) {
        String msgId = "";
        try {
            msgId = message.getJMSMessageID();
            int deliveryCount = message.getIntProperty("JMSXDeliveryCount");
            if (!(message instanceof TextMessage text)) {               // [Java 17] pattern matching
                LOG.error("Unexpected message type msgId={} type={}", msgId, message.getClass().getSimpleName());
                context.rollback();                                     // 交由 BOTHRESH 機制移到 BOQ
                return;
            }
            businessHandler.accept(text.getText());
            context.commit();
            LOG.info("Processed msgId={} deliveryCount={}", msgId, deliveryCount);
        } catch (JMSException | RuntimeException e) {
            LOG.warn("Processing failed msgId={} -> rollback", msgId, e);
            context.rollback();
        }
    }

    @Override
    public void close() {
        running = false;
        context.close();
    }
}

11.8 MessageListener(非同步)

JMSContext ctx = cf.createContext(user, password, JMSContext.SESSION_TRANSACTED);
JMSConsumer consumer = ctx.createConsumer(ctx.createQueue("queue:///CBS.ACCT.NOTIFY"));
consumer.setMessageListener(message -> {
    try {
        process(message);
        ctx.commit();
    } catch (Exception e) {
        LOG.warn("listener failed -> rollback", e);
        ctx.rollback();
    }
});
ctx.start();

Java SE 中的 MessageListener 每個 JMSContext 只有一條派送執行緒。需要並行時建立多個 Context,或改用 Spring 的 Listener Container(Part 12)。

11.9 Message 類型

類型用途建議
TextMessageJSON、XML、文字電文最常用;搭配 CCSID 1208
BytesMessage二進位、固定長度主機電文Legacy / Mainframe 整合常用
MapMessage名稱/值僅 JMS 雙方使用
StreamMessage序列化基本型別少用
ObjectMessageJava 序列化物件禁止使用:反序列化弱點風險,且無法跨語言

11.10 Message Properties、Correlation ID、Message ID

// 自訂屬性:名稱須符合 Java 識別字規則
msg.setStringProperty("traceId", traceId);
msg.setStringProperty("sourceSystem", "NBK");
msg.setIntProperty("schemaVersion", 2);

// 以 CorrelId 選取(MQ 會最佳化為 MQMO_MATCH_CORREL_ID,效能良好)
String selector = "JMSCorrelationID = 'ID:" + correlationIdHex48 + "'";
try (JMSConsumer replyConsumer = ctx.createConsumer(replyQueue, selector)) {
    Message reply = replyConsumer.receive(30_000);
}

以任意自訂屬性做 Selector 會造成 Queue Manager 逐筆掃描,深佇列時效能極差。Selector 應盡量只用 JMSCorrelationID / JMSMessageID。

11.11 進階 JMS 2.0 / Jakarta Messaging 功能

功能APIIBM MQ 上的實作適用注意
Delivery DelayJMSProducer.setDeliveryDelay()訊息先放到 SYSTEM.DDELAY.LOCAL.QUEUE,時間到才移到目標延遲重試、排程通知延遲期間不在目標佇列;暫存佇列需容量與權限管理
非同步送出JMSProducer.setAsync(CompletionListener)對應 MQ 非同步 Put高吞吐量事件、可容忍事後補救錯誤延後回報;交易性金融電文不使用
Shared SubscriptioncreateSharedConsumer() / createSharedDurableConsumer()多個 Consumer 分攤同一訂閱事件訂閱方水平擴充訂閱名稱即治理單位,需納入命名規範
投遞次數JMSXDeliveryCount 屬性對應 MQMD BackoutCount + 1判斷是否為重送與 BOTHRESH 一起設計
JMSContext 簡化 APIcreateContext()一個 Context = Connection + Session新程式碼不可跨執行緒共用
// Delivery Delay:5 分鐘後才可被取出
ctx.createProducer()
        .setDeliveryMode(DeliveryMode.PERSISTENT)
        .setDeliveryDelay(Duration.ofMinutes(5).toMillis())
        .send(retryQueue, body);

// 非同步送出:送出後立即返回,結果由 CompletionListener 回報
ctx.createProducer()
        .setAsync(new CompletionListener() {
            @Override
            public void onCompletion(Message message) {
                LOG.debug("Async send completed");
            }

            @Override
            public void onException(Message message, Exception exception) {
                LOG.error("Async send failed", exception);
            }
        })
        .send(eventTopic, body);

// Shared Durable Subscription:多個服務實例共同消費同一個持久訂閱
JMSConsumer auditConsumer = ctx.createSharedDurableConsumer(txnTopic, "AUDIT.TXN.SUB");

非同步送出在 IBM MQ 上的錯誤回報時機、與 Syncpoint 的互動,請依 IBM MQ classes for Jakarta Messaging 文件確認 [需確認]。

11.12 Checklist

  • 新開發使用 jakarta.jms 與 com.ibm.mq.jakarta.client
  • 送往 Legacy 非 JMS 系統時設定 targetClient=1
  • 使用 SESSION_TRANSACTED
  • JMSContext 不跨執行緒共用
  • 不使用 ObjectMessage
  • Selector 只用 CorrelationID / MessageID

Part 12 — Spring Boot + IBM MQ

12.1 目的

以 Spring Boot 4.x 示範企業級 IBM MQ 整合:連線設定、Producer、Listener、交易、錯誤處理、Retry 與 DLQ。

12.2 架構

Vue / Angular
       ↓
Spring Boot
       ↓
Service
       ↓
IBM MQ
       ↓
Legacy System
flowchart LR
    UI["Vue / Angular"] -->|"HTTPS / JSON"| CTRL["TransferController"]
    subgraph SB["Spring Boot 4.x"]
        CTRL --> SVC["TransferService<br/>(Idempotency / 驗證)"]
        SVC --> DB[("交易狀態 DB")]
        SVC --> GW["TransferMqGateway<br/>JmsTemplate"]
        LSN["TransferReplyListener<br/>@JmsListener"] --> SVC
        CF["MQConnectionFactory<br/>(mq-jms-spring-boot-starter)"]
        GW --> CF
        LSN --> CF
    end
    CF -->|"TLS"| MQ[("IBM MQ")]
    MQ --> LEG["Legacy / Core"]
    LEG --> MQ

12.3 版本對應

Spring BootStarter 版本MQ Client說明
4.x [Boot 4]mq-jms-spring-boot-starter 4.1.0(對應 MQ 10.0、Spring Boot 4.1.0)Jakarta Messaging本手冊基準;後續更新只沿 Boot 4 路線
3.x [Boot 3]3.5.15(Boot 3 最後一版)Jakarta MessagingSpring Boot 3 已結束非商業支援
2.x2.7.18(Boot 2 最後一版)JMS 2.0(javax)僅維護

來源:GitHub ibm-messaging/mq-jms-spring README 與 Release。Starter 屬 IBM 以 as-is 提供的開源元件,不在 IBM 正式支援案件範圍內;底層 MQ Client 函式庫則依其原本的支援條款。

12.4 Maven 設定

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.0</version> <!-- 依公司基準版本,需確認最新修補版 -->
</parent>

<properties>
    <java.version>25</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <!-- Boot 4 起 Web MVC starter 改名為 webmvc;Boot 3 使用 spring-boot-starter-web -->
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>com.ibm.mq</groupId>
        <artifactId>mq-jms-spring-boot-starter</artifactId>
        <version>4.1.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

12.5 application.yml

ibm:
  mq:
    queue-manager: NBKQM01
    channel: PAY.SVRCONN
    conn-name: nbk-mq-a.bank.local(1414),nbk-mq-b.bank.local(1414)
    application-name: payment-service          # DISPLAY CONN 的 APPLTAG
    user: ${MQ_USER:}                          # 由 Secret 注入
    password: ${MQ_PASSWORD:}                  # 由 Secret 注入,禁止寫在 Git
    userAuthenticationMQCSP: true              # 預設即為 true;縮寫字屬性直接用 camelCase
    ssl-bundle: mq-client                      # Spring SSL Bundle(Boot 3.1+)
    ssl-cipher-suite: TLS_AES_256_GCM_SHA384
    useIBMCipherMappings: false                # 非 IBM JRE 必須為 false
    reconnect: QMGR                            # 同名 QM 的 HA 重連
    reconnect-timeout: 300
    pool:
      enabled: false                           # 使用 Spring CachingConnectionFactory(starter 建議)

spring:
  ssl:
    bundle:
      jks:
        mq-client:
          keystore:
            location: file:/etc/secrets/mq/client.p12
            password: ${MQ_KEYSTORE_PASSWORD}
            type: PKCS12
          truststore:
            location: file:/etc/secrets/mq/truststore.p12
            password: ${MQ_TRUSTSTORE_PASSWORD}
            type: PKCS12
  jms:
    cache:
      enabled: true
      session-cache-size: 10

logging:
  level:
    com.ibm.mq.spring.boot: INFO

Starter 屬性原文為 camelCase(如 queueManager、connName、userAuthenticationMQCSP、useIBMCipherMappings)。Spring Boot relaxed binding 支援 kebab-case,縮寫字(MQCSP、IBM)轉 kebab-case 的寫法容易出錯,建議對這類屬性直接使用 camelCase 原名並以整合測試驗證。

Boot 4 的 starter 模組化調整(例如 spring-boot-starter-web 改為 spring-boot-starter-webmvc)請以 Spring Boot 4 Release Notes 確認 [需確認]。

Starter 進階屬性(依 mq-jms-spring README 整理):

屬性用途建議
ibm.mq.ccdtUrl以 CCDT 取代 channel / connName(優先於兩者)多 QM 或 HA 環境建議使用
ibm.mq.ccdtSslBundle、ibm.mq.ccdtHttpsCertValPolicy以 HTTPS 取得 CCDT 時的 TLS 設定;驗證策略 HOSTNAMECN(預設)/ ANY / NONEProduction 保持 HOSTNAMECN
ibm.mq.tokenServer.endpoint / clientId / clientSecretClient 自動向 Token Server(例如 Keycloak)取得 JWTclientSecret 由 Secret 注入
ibm.mq.token直接提供 JWT不建議;改用 tokenServer
ibm.mq.balancingApplicationTypeUniform Cluster 平衡提示:SIMPLE / REQREPRequest / Reply 應用設 REQREP
ibm.mq.balancingTimeout、balancingOptions、balancingInstanceMode平衡時機、是否忽略交易中連線、JVM 模式將同行程連線視為一個實例搭配 [MQ 10.0] 多連線單一實例功能
ibm.mq.outboundSNI設定 HOSTNAME 以連線 OpenShift Route容器平台連線時使用
ibm.mq.trace.*以 Spring 屬性控制 MQ JMS trace、FFDC 路徑只在除錯時開啟
ibm.mq.additionalProperties.<CONSTANT>設定尚未封裝的 ConnectionFactory 屬性無錯誤檢查,需以整合測試驗證
ibm.mq.jks.*舊式 keystore 設定已 deprecated,改用 sslBundle
spring.jms.listener.receiveTimeoutListener polling 逾時未設定時 starter 調為 30 秒

12.6 Listener Container 設定

package com.example.payment.mq;

import jakarta.jms.ConnectionFactory;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jms.annotation.EnableJms;
import org.springframework.jms.config.DefaultJmsListenerContainerFactory;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.util.backoff.ExponentialBackOff;

@Configuration
@EnableJms
class MqJmsConfig {

    private static final Logger LOG = LogManager.getLogger(MqJmsConfig.class);

    /** 交易式 Listener:例外 → rollback → MQ JMS 依 BOTHRESH / BOQNAME 處理毒訊息。 */
    @Bean
    DefaultJmsListenerContainerFactory mqListenerFactory(ConnectionFactory connectionFactory) {
        var factory = new DefaultJmsListenerContainerFactory();
        factory.setConnectionFactory(connectionFactory);
        factory.setSessionTransacted(true);
        factory.setConcurrency("2-8");
        factory.setReceiveTimeout(5_000L);
        factory.setErrorHandler(t -> LOG.error("JMS listener error", t));

        // 連線中斷時的重連退避(不是訊息重試)
        var backOff = new ExponentialBackOff(1_000L, 2.0);
        backOff.setMaxInterval(30_000L);
        factory.setBackOff(backOff);
        return factory;
    }

    @Bean
    JmsTemplate mqJmsTemplate(ConnectionFactory connectionFactory) {
        var template = new JmsTemplate(connectionFactory);
        template.setSessionTransacted(true);
        template.setExplicitQosEnabled(true);
        template.setDeliveryPersistent(true);
        template.setTimeToLive(30_000L);
        template.setReceiveTimeout(30_000L);
        return template;
    }
}

[Boot 4] Spring Boot 4 進行了 auto-configuration 模組化,DefaultJmsListenerContainerFactoryConfigurer 等類別的套件路徑可能與 Boot 3 不同 [需確認]。本範例不依賴 configurer,直接設定 factory,以降低升級時的耦合。

12.7 Producer(Gateway)

package com.example.payment.mq;

import jakarta.jms.JMSException;
import jakarta.jms.TextMessage;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.springframework.jms.JmsException;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.stereotype.Component;

@Component
public class TransferMqGateway {

    private static final Logger LOG = LogManager.getLogger(TransferMqGateway.class);
    private static final String REQUEST_QUEUE = "queue:///NBK.TXN.TRANSFER.REQ?targetClient=1";
    private static final String REPLY_QUEUE = "NBK.TXN.TRANSFER.RSP";
    private static final int MAX_ATTEMPTS = 3;

    private final JmsTemplate jmsTemplate;

    public TransferMqGateway(JmsTemplate mqJmsTemplate) {
        this.jmsTemplate = mqJmsTemplate;
    }

    /**
     * 送出轉帳請求。
     *
     * @param correlationHex48 由 Idempotency Key 產生的 48 位十六進位字串
     */
    public void sendTransferRequest(String correlationHex48, String json) {
        JmsException last = null;
        for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
            try {
                jmsTemplate.send(REQUEST_QUEUE, session -> {
                    TextMessage msg = session.createTextMessage(json);
                    msg.setJMSCorrelationID("ID:" + correlationHex48);
                    msg.setJMSReplyTo(session.createQueue(REPLY_QUEUE));
                    return msg;
                });
                LOG.info("Transfer request sent correlId={} attempt={}", correlationHex48, attempt);
                return;
            } catch (JmsException e) {
                last = e;
                LOG.warn("Send failed attempt={} correlId={} cause={}", attempt, correlationHex48, e.getMessage());
                sleep(500L * attempt);
            }
        }
        throw new MqUnavailableException("IBM MQ unavailable after retries", last);
    }

    private static void sleep(long ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException ie) {
            Thread.currentThread().interrupt();
            throw new MqUnavailableException("Interrupted", ie);
        }
    }

    public static final class MqUnavailableException extends RuntimeException {
        public MqUnavailableException(String m, Throwable c) { super(m, c); }
    }
}

JmsTemplate.send 不回傳 MsgId。需要取得 MsgId 時,可在 jmsTemplate.execute(SessionCallback) 內自行建立 Producer 並送出後讀取 getJMSMessageID()。[Spring Framework 7] 新增 JmsClient 流暢式 API 與核心 Retry / Resilience 支援,可取代上方的手寫重試迴圈 [需確認 API 細節]。

12.8 Listener(Consumer)

package com.example.payment.mq;

import jakarta.jms.JMSException;
import jakarta.jms.TextMessage;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.springframework.jms.annotation.JmsListener;
import org.springframework.stereotype.Component;

@Component
class TransferReplyListener {

    private static final Logger LOG = LogManager.getLogger(TransferReplyListener.class);

    private final TransferResultService resultService;

    TransferReplyListener(TransferResultService resultService) {
        this.resultService = resultService;
    }

    @JmsListener(destination = "NBK.TXN.TRANSFER.RSP", containerFactory = "mqListenerFactory")
    void onReply(TextMessage message) throws JMSException {
        String correlId = message.getJMSCorrelationID();
        int deliveryCount = message.getIntProperty("JMSXDeliveryCount");
        LOG.info("Reply received correlId={} deliveryCount={}", correlId, deliveryCount);

        try {
            resultService.applyReply(correlId, message.getText());   // 內部需冪等
        } catch (InvalidReplyException e) {
            // 永久性錯誤:記錄後吞掉例外 → commit,並寫入人工處理表;不要讓它無限重試
            LOG.error("Invalid reply correlId={} -> manual queue", correlId, e);
            resultService.recordInvalidReply(correlId, e.getMessage());
        }
        // 其他 RuntimeException 往外拋 → rollback → 達 BOTHRESH 後由 MQ JMS 移到 BOQ
    }
}

TransferResultService、InvalidReplyException 為業務服務與自訂例外,此處省略。

12.9 Error Handling、Retry 與 DLQ 策略

flowchart TD
    M["收到訊息"] --> P{"處理"}
    P -- 成功 --> C["commit"]
    P -- "永久性錯誤<br/>(格式、業務規則)" --> R1["記錄人工處理表<br/>commit(不重試)"]
    P -- "暫時性錯誤<br/>(DB / 外部 API)" --> RB["拋出例外 → rollback"]
    RB --> D{"JMSXDeliveryCount<br/>> BOTHRESH?"}
    D -- 否 --> M
    D -- 是 --> BOQ["MQ JMS 移至 BOQNAME"]
    BOQ --> ALERT["監控 BOQ 深度 → 告警"]
錯誤類型範例處理
永久性JSON 解析失敗、必填欄位缺漏、未知交易代碼不重試;轉人工 / BOQ
暫時性DB 連線逾時、下游 API 503rollback 重試;有上限
連線層2009、2538Listener Container BackOff 重連
設定層2035、2085告警;人工處理(重試無效)

12.10 Spring Boot 3.x 與 4.x 差異重點

項目Boot 3.xBoot 4.x
Starter3.5.15(最後版)4.1.0+
Spring Framework6.x7.x
Jakarta EE 基準1011 [需確認 Messaging 版本對應]
Auto-config 套件單一 spring-boot-autoconfigure模組化拆分 [需確認]
Retry常用 spring-retry框架核心內建 Retry / Resilience [需確認]
Java 最低版本1717 [需確認]

12.11 Production 注意事項

  • concurrency 上限 × Pod 數 ≤ SVRCONN MAXINST,否則擴容時出現連線被拒。
  • Actuator 健康檢查若包含 JMS 健康指標,MQ 短暫中斷可能導致 Pod 被重啟;需評估是否將 JMS 健康從 liveness 移除,只放 readiness。
  • Graceful shutdown:設定 server.shutdown=graceful 與合理的 spring.lifecycle.timeout-per-shutdown-phase,讓 Listener 處理完當前訊息。

12.12 Checklist

  • Starter 版本與 Spring Boot 主版本對應
  • 帳密、Keystore 密碼由 Secret 注入
  • 使用 SSL Bundle 設定 TLS
  • application-name 已設定
  • Listener sessionTransacted=true
  • 每個 Input Queue 設定 BOQNAME / BOTHRESH,且應用帳號有 BOQ put 權限
  • 永久性錯誤不進入無限重試
  • concurrency × Pod 數 已對照 MAXINST

Part 13 — Java Transaction

13.1 目的

釐清 DB Transaction 與 MQ Transaction 的關係,說明 Local Transaction、JMS Transaction、XA、Outbox 等做法的取捨,以及金融交易系統的實務風險。

13.2 核心概念:兩個資源、兩個交易

DB Transaction
+
MQ Transaction
≠
一個交易

除非使用 XA 兩階段提交,DB 與 MQ 是兩個獨立的交易。任何一方 commit 之後、另一方 commit 之前,程式當掉或網路中斷,都會造成不一致。

13.3 失敗情境分析

以「Consumer 收到轉帳指令 → 更新 DB 餘額 → commit」為例:

順序失敗點結果風險
先 DB commit,再 MQ commitDB commit 後、MQ commit 前當機訊息回到佇列被重新處理重複扣款(若無冪等)
先 MQ commit,再 DB commitMQ commit 後、DB commit 前當機訊息已刪除,DB 未更新交易遺失

結論:金融系統應選擇「先 DB 後 MQ」(寧可重複、不可遺失),並用冪等機制消除重複。

13.4 做法比較

做法一致性複雜度效能適用
MQ Local Transaction(僅 MQ)MQ 內一致低高純轉送、不涉及 DB
Best-Effort 1PC(DB 先 commit + 冪等)最終一致(at-least-once + 去重)中高多數 Spring Boot 服務的建議做法
Transactional Outbox最終一致中-高高Producer 端「DB 更新 + 發送訊息」需一致
XA / JTA 兩階段提交強一致(in-doubt 時需人工介入)高較低法規或業務要求原子性、且基礎設施支援

13.5 Best-Effort 1PC + Idempotency(Consumer 端)

sequenceDiagram
    autonumber
    participant MQ as IBM MQ
    participant L as Listener (JMS tx)
    participant DB as Database (JDBC tx)
    MQ->>L: receive(JMS Session 交易中)
    L->>DB: BEGIN
    L->>DB: INSERT processed_message(correl_id) — 唯一鍵
    alt 唯一鍵衝突(已處理過)
        L->>DB: ROLLBACK
        L->>MQ: JMS commit(丟棄重複訊息)
    else 首次處理
        L->>DB: UPDATE account SET balance = ...
        L->>DB: COMMIT
        L->>MQ: JMS commit
        Note over L,MQ: 若此處當機 → 訊息重送 → 第 3 步唯一鍵衝突 → 安全丟棄
    end
@JmsListener(destination = "CBS.TXN.TRANSFER.REQ", containerFactory = "mqListenerFactory")
void onTransfer(TextMessage message) throws JMSException {
    String correlId = message.getJMSCorrelationID();
    // DB 交易由 TransactionTemplate 控制,先於 JMS commit 完成
    transactionTemplate.executeWithoutResult(status -> {
        if (!idempotencyRepository.tryInsert(correlId)) {     // INSERT ... 唯一鍵衝突回傳 false
            LOG.info("Duplicate message ignored correlId={}", correlId);
            return;
        }
        transferService.execute(parse(message.getText()));
    });
    // 方法正常結束 → Listener Container 執行 JMS commit
}

Spring 的 DefaultMessageListenerContainer 在 sessionTransacted=true 且未設定外部交易管理器時,會在 Listener 方法返回後 commit JMS Session。DB 交易需在 Listener 方法內完成並 commit,才符合「先 DB 後 MQ」。

13.6 Transactional Outbox(Producer 端)

flowchart LR
    API["API 請求"] --> TX{"單一 DB 交易"}
    TX --> BIZ[("業務資料表")]
    TX --> OUT[("outbox 表<br/>status=NEW")]
    RELAY["Outbox Relay<br/>(排程 / CDC)"] --> OUT
    RELAY -->|"MQPUT + commit"| MQ[("IBM MQ")]
    RELAY -->|"更新 status=SENT"| OUT
  • 業務資料與待發送訊息寫在同一個 DB 交易 → 不會「DB 有、訊息沒送」。
  • Relay 送出後才標記 SENT;Relay 在兩步之間當機會重送 → 下游冪等。
  • Outbox 表需要清理機制與監控(未送出筆數即「積壓」指標)。

13.7 XA / Distributed Transaction

項目說明
原理Transaction Manager 協調 DB 與 MQ 進行兩階段提交(prepare → commit)
MQ 支援IBM MQ 可作為 XA 資源(JMS 的 XAConnectionFactory);Client 連線下的 XA 支援條件需依官方文件確認 [需確認]
Java EE / Jakarta EE應用伺服器(如 WebSphere Liberty)內建 JTA 與 MQ Resource Adapter
Spring BootBoot 3 起不再內建 Atomikos / Bitronix 自動設定,需使用第三方提供的 JTA starter [需確認]
風險Transaction Manager 在 prepare 後當機 → in-doubt 交易,資源被鎖定,需要復原日誌與人工處理
效能額外的 prepare 往返與 log 寫入

13.8 Exactly-once 的實務限制

端到端的 Exactly-once 在分散式系統中無法單靠 MQ 達成。

  • MQ 保證的是「MQ 網路內的 once-and-only-once 傳遞」,以及在 Syncpoint 下的原子性。
  • 應用程式「處理」這則訊息的副作用(扣款、寄信、呼叫外部 API)不在 MQ 的控制範圍內。
  • 實務目標是 Effectively-once = At-least-once 傳遞 + 冪等處理。

13.9 金融交易系統的實務風險

風險情境對策
重複扣款重送、使用者重按、Producer 重試冪等鍵(業務鍵 / CorrelId)+ 唯一約束
交易遺失先 MQ commit 後 DB 失敗先 DB 後 MQ;Outbox
狀態不明Request 送出後 Timeout,不知道後端是否處理查詢交易(Inquiry)+ 對帳;不要盲目重送
in-doubt 鎖定XA 協調者故障監控 in-doubt、建立人工處理 SOP
部分成功多筆訊息中部分處理交易邊界設計;補償交易(Saga)
順序錯亂先收到「沖正」再收到「原交易」業務序號檢查;暫存等待

13.10 Checklist

  • 每個 Consumer 有冪等機制(唯一鍵表或業務狀態檢查)
  • Consumer 交易順序為「先 DB 後 MQ」
  • Producer 端若需「DB 更新 + 發訊息」一致,已採用 Outbox
  • 若使用 XA,已建立 in-doubt 監控與處理 SOP
  • Request / Reply Timeout 後有查詢與對帳機制
  • 文件中明確寫出「本流程不保證 Exactly-once」的處理方式

Part 14 — IBM MQ 與 Web Application 整合

14.1 目的

說明 Web Application 如何正確地透過分層架構使用 IBM MQ,以及為什麼瀏覽器端或前端框架不應直接連 MQ。

14.2 企業架構

Browser
   ↓
Vue / Angular
   ↓
API Gateway
   ↓
Spring Boot
   ↓
Application Service
   ↓
IBM MQ
   ↓
Legacy / Mainframe / Core Banking
flowchart TB
    subgraph Client["使用者端"]
        BR["Browser"] --> FE["Vue / Angular SPA"]
    end
    subgraph Edge["邊界層"]
        GW["API Gateway<br/>認證 / 限流 / WAF"]
    end
    subgraph App["應用層(Spring Boot)"]
        API["API Layer<br/>Controller / DTO / 驗證"]
        SVC["Service Layer<br/>業務邏輯 / Idempotency / 狀態"]
        MSG["Messaging Layer<br/>Gateway / Listener"]
        ADP["Adapter Layer<br/>電文轉換(JSON ↔ 固定長度 / XML)"]
    end
    subgraph Int["整合層"]
        MQ[("IBM MQ")]
    end
    subgraph Legacy["Legacy 層"]
        CORE["Core Banking"]
        MF["Mainframe CICS"]
    end
    FE -->|"HTTPS"| GW --> API --> SVC --> ADP --> MSG --> MQ
    MQ --> CORE
    MQ --> MF

14.3 為什麼 Web Application 不應直接連 IBM MQ

原因說明
安全MQ 帳密與憑證會暴露在使用者端;MQ 連接埠需對外開放
協定瀏覽器無法使用 MQ 原生協定;即使透過 MQ REST Messaging API,也等於把內部佇列對外暴露
治理無法在 MQ 層做使用者層級的授權、輸入驗證、限流
耦合前端直接依賴佇列名稱與電文格式,後端無法演進
冪等使用者重按、網路重送無法在 MQ 層去重
稽核無法把「哪個使用者做了什麼」與訊息關聯

14.4 各層職責

層職責不應做的事
API Layer認證資訊解析、輸入驗證、DTO、HTTP 狀態碼直接呼叫 JmsTemplate
Service Layer業務規則、Idempotency Key 檢查、交易狀態機拼裝電文位元組
Adapter LayerJSON ↔ Legacy 電文格式轉換、CCSID 處理業務判斷
Messaging Layer送出 / 接收、CorrelId、Timeout、錯誤分類業務判斷
Legacy Integration Layer由 MQ 與 Legacy 系統負責;Adapter 層包住其介面—

14.5 同步 API 與非同步處理的對應

API 設計說明適用
同步等待(Request / Reply + Timeout)API 送出 MQ 請求後等待回覆,逾時回 504 或「處理中」後端通常秒級回應的交易
非同步受理(202 Accepted)API 寫入 DB 並送出 MQ 後立即回 202 + 查詢 URL處理時間長或不確定
事件推送回覆到達後透過 WebSocket / SSE 推送前端需要即時顯示結果

14.6 實務案例

某網銀把「轉帳」API 設計為同步等待 30 秒。尖峰時核心處理變慢,大量 API 執行緒卡在等待回覆,Tomcat 執行緒耗盡,連查詢餘額都失敗。

改善:

  1. 轉帳 API 改為 202 Accepted + 查詢;同步等待上限降為 5 秒,超過即回「處理中」。
  2. Request 設定 Expiry = 等待上限 + 緩衝,避免核心處理已無人等待的請求。
  3. [Java 21] 評估 Virtual Threads 降低等待中執行緒的資源成本(MQ Client 相容性需實測)。

14.7 Checklist

  • 前端只透過 API Gateway 存取後端
  • Messaging 與 Adapter 層獨立,業務層不依賴電文格式
  • 同步等待有上限,逾時有明確的使用者回應
  • 每筆請求有 Idempotency Key 並記錄於 DB

Part 15 — Request / Reply Pattern

15.1 目的

完整說明 Request / Reply 的設計:Message ID、Correlation ID、Timeout、Retry、Duplicate Request、Idempotency 與 DLQ。

15.2 流程

Web Application
      ↓
Request Queue
      ↓
IBM MQ
      ↓
Legacy System
      ↓
Response Queue
      ↓
Spring Boot
      ↓
Web Application
sequenceDiagram
    autonumber
    participant U as Web / API
    participant S as Spring Boot
    participant DB as 交易狀態 DB
    participant RQ as Request Queue
    participant L as Legacy
    participant RS as Response Queue

    U->>S: POST /transfers, Idempotency-Key = K1
    S->>DB: INSERT txn(K1, PENDING) — 唯一鍵
    alt K1 已存在
        S-->>U: 回傳既有結果 / 處理中
    else 新請求
        S->>RQ: MQPUT Request<br/>CorrelId = f(K1), ReplyToQ, Expiry = 35s
        S->>RS: receive by CorrelId, timeout = 30s
        RQ->>L: MQGET
        L->>L: 處理(以 CorrelId / 業務鍵冪等)
        L->>RS: MQPUT1 Reply<br/>CorrelId = Request.CorrelId
        alt 30 秒內收到
            RS-->>S: Reply
            S->>DB: UPDATE txn(K1, SUCCESS / FAIL)
            S-->>U: 200 結果
        else Timeout
            S->>DB: UPDATE txn(K1, UNKNOWN)
            S-->>U: 202 處理中(請查詢)
            Note over S,RS: 遲到的 Reply 由背景 Listener 更新狀態
        end
    end

15.3 Message ID 與 Correlation ID 慣例

慣例說明優點缺點
A:Reply.CorrelId = Request.MsgIdMQ 傳統慣例(MQRO_COPY_MSG_ID_TO_CORREL_ID,預設)Legacy 程式普遍支援Request 的 MsgId 由 QM 產生,重送時改變,無法冪等
B:Reply.CorrelId = Request.CorrelIdRequest 帶入應用程式指定的 CorrelId(MQRO_PASS_CORREL_ID)可由業務鍵產生、重送時不變,利於冪等需與 Legacy 端約定

逆向工程時必須確認 Legacy 端採用哪一種慣例,否則 Requester 永遠等不到回覆。

15.4 Timeout 設計

API Timeout(例如 30s)
  ≥ Reply 等待時間(例如 28s)
  < Request Expiry(例如 35s)  ← 讓後端不處理「已無人等待」的請求
  < 使用者端 Timeout(例如 40s)
參數說明
Request Expiry後端在逾時後不應處理;金融交易需確認後端是否會檢查 Expiry 以外的時間欄位
Reply Expiry避免遲到的 Reply 永久堆積
receive timeout等待回覆上限

15.5 Retry 與 Duplicate Request

情境正確做法錯誤做法
MQPUT 失敗(連線錯誤)以相同 CorrelId 重送產生新 CorrelId 重送
等待 Reply 逾時標記 UNKNOWN,背景查詢 / 對帳直接重送 Request(可能重複扣款)
使用者重按以 Idempotency-Key 回傳既有狀態視為新請求
後端收到重複 Request以 CorrelId / 業務鍵查詢已處理結果並回覆相同結果再處理一次

15.6 Idempotency 設計

-- Requester 端:交易狀態表
CREATE TABLE transfer_request (
    idempotency_key   VARCHAR(64)  PRIMARY KEY,
    correl_id_hex     CHAR(48)     NOT NULL UNIQUE,
    status            VARCHAR(16)  NOT NULL,     -- PENDING / SUCCESS / FAIL / UNKNOWN
    request_hash      CHAR(64)     NOT NULL,     -- 防止相同 Key 不同內容
    created_at        TIMESTAMP    NOT NULL,
    updated_at        TIMESTAMP    NOT NULL
);

-- Responder 端(Legacy 或其 Adapter):已處理訊息表
CREATE TABLE processed_request (
    correl_id_hex     CHAR(48)     PRIMARY KEY,
    result_code       VARCHAR(8)   NOT NULL,
    reply_payload     CLOB,
    processed_at      TIMESTAMP    NOT NULL
);
  • request_hash 防止「相同 Idempotency-Key 但內容不同」的請求被誤判為重複。
  • Responder 收到重複 CorrelId 時,回覆相同的 reply_payload,讓 Requester 得到一致結果。

15.7 Spring Boot Request / Reply 範例

package com.example.payment.mq;

import jakarta.jms.Message;
import jakarta.jms.TextMessage;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class TransferRequestReplyClient {

    private static final String REQUEST_QUEUE = "queue:///NBK.TXN.TRANSFER.REQ?targetClient=1";
    private static final String REPLY_QUEUE = "NBK.TXN.TRANSFER.RSP";

    private final JmsTemplate jmsTemplate;

    public TransferRequestReplyClient(JmsTemplate mqJmsTemplate) {
        this.jmsTemplate = mqJmsTemplate;
    }

    /**
     * 送出請求並在 replyTimeoutMs 內等待回覆。
     *
     * @return 回覆內容;逾時回傳 Optional.empty()(呼叫端應標記 UNKNOWN,不可直接重送)
     */
    public Optional<String> call(String correlHex48, String json, long replyTimeoutMs) throws Exception {
        String correlId = "ID:" + correlHex48;
        jmsTemplate.send(REQUEST_QUEUE, session -> {
            TextMessage msg = session.createTextMessage(json);
            msg.setJMSCorrelationID(correlId);
            msg.setJMSReplyTo(session.createQueue(REPLY_QUEUE));
            return msg;
        });

        // 以 JmsTemplate 的副本設定本次等待時間,避免修改共用 Bean 的狀態
        JmsTemplate receiver = new JmsTemplate(jmsTemplate.getConnectionFactory());
        receiver.setReceiveTimeout(replyTimeoutMs);
        receiver.setSessionTransacted(true);
        Message reply = receiver.receiveSelected(REPLY_QUEUE, "JMSCorrelationID = '" + correlId + "'");
        if (reply instanceof TextMessage text) {
            return Optional.of(text.getText());
        }
        return Optional.empty();
    }
}

若 Reply 由背景 @JmsListener 統一接收(所有實例共用 Response Queue),同步等待的實例可能收不到自己的回覆(被其他實例的 Listener 取走)。兩種模式不要在同一個 Response Queue 上混用。常見做法:同步等待用 receiveSelected;未在時限內被取走的遲到 Reply,由另一個「只處理逾時回覆」的 Response Queue 或延遲掃描程式處理 [依架構決定]。

15.8 Legacy 回覆端(MQPUT1)

Legacy / Adapter 回覆時使用 MQPUT1(單次放入),依 Request 的 Report Options 設定 CorrelId:

// Request 端已取得 request(MQMessage),回覆使用 MQPUT1
MQMessage reply = new MQMessage();
reply.messageType = MQConstants.MQMT_REPLY;
reply.format = MQConstants.MQFMT_STRING;
reply.characterSet = 1208;
reply.persistence = request.persistence;               // 依請求的持久性
reply.expiry = 300;
// 慣例 B:沿用 Request 的 CorrelId;慣例 A:改用 request.messageId
reply.correlationId = request.correlationId;
reply.write(replyBytes);

MQPutMessageOptions pmo = new MQPutMessageOptions();
pmo.options = MQConstants.MQPMO_SYNCPOINT | MQConstants.MQPMO_NEW_MSG_ID | MQConstants.MQPMO_FAIL_IF_QUIESCING;
qmgr.put(request.replyToQueueName, request.replyToQueueManagerName, reply, pmo);
qmgr.commit();                                         // 與 Request 的 GET 同一 Syncpoint

15.9 DLQ 情境

情境結果對策
ReplyToQ 不存在跨 QM 時 Reply 進入 Requester QM 的 DLQ驗證 ReplyToQ 設定;DLQ 監控
Response Queue 已滿Reply 進 DLQ 或 PUT 失敗監控深度;Reply 設 Expiry
Requester 長時間停機Reply 堆積Reply 設 Expiry;容量規劃

15.10 Checklist

  • 已確認 CorrelId 慣例(A 或 B)並記錄於介面規格
  • Request 與 Reply 都設定 Expiry
  • Timeout 關係符合 15.4 公式
  • Timeout 後不直接重送,有查詢 / 對帳機制
  • Requester 與 Responder 皆有冪等表
  • 同一 Response Queue 不混用同步等待與 Listener

Part 16 — Asynchronous Event Pattern

16.1 目的

說明以 IBM MQ 實作事件驅動架構(Event-driven Architecture):Pub/Sub、Topic、Subscription 的設計與限制。

16.2 架構

Application
    ↓
Event
    ↓
IBM MQ
    ↓
Multiple Consumers
flowchart LR
    TX["交易服務"] -->|"Publish<br/>Bank/Txn/Transfer/Completed"| TOP(("Topic Tree"))
    TOP --> S1["Durable SUB<br/>NOTIFY.TXN.SUB → 通知服務"]
    TOP --> S2["Durable SUB<br/>AUDIT.TXN.SUB → 稽核服務"]
    TOP --> S3["Durable SUB<br/>RISK.TXN.SUB → 風控服務"]
    TOP --> S4["Non-durable SUB<br/>即時儀表板"]

16.3 Topic 設計

Bank/<Domain>/<Entity>/<Event>
Bank/Txn/Transfer/Completed
Bank/Txn/Transfer/Reversed
Bank/Account/Balance/Changed
* 管理節點:在 Bank/Txn 設定屬性與權限
DEFINE TOPIC('BANK.TXN') TOPICSTR('Bank/Txn') DEFPSIST(YES) REPLACE

* 管理式 Durable Subscription:訊息送到指定佇列,由管理員控管
DEFINE QLOCAL('NOTIFY.TXN.EVT') DEFPSIST(YES) MAXDEPTH(500000) +
       BOTHRESH(5) BOQNAME('NOTIFY.TXN.EVT.BOQ') REPLACE
DEFINE SUB('NOTIFY.TXN.SUB') TOPICSTR('Bank/Txn/Transfer/#') +
       DEST('NOTIFY.TXN.EVT') REPLACE
選項說明
Administrative Subscription(管理式)由 MQSC 定義,訂閱者只需讀佇列;企業建議:可控、可審核
Application Subscription應用程式自行建立 Durable Subscription;需 sub 權限與 clientId
Shared Subscription(JMS 2.0+)多個 Consumer 分攤同一訂閱的訊息,用於水平擴充

16.4 Event 與 Command 的區別

Command(指令)Event(事件)
語意「請你做這件事」「某件事已經發生」
接收者一個零到多個
模式Point-to-Point / Request-ReplyPub/Sub
失敗影響發送方需知道結果發送方不關心誰處理
範例「轉帳 1000 元」「轉帳 1000 元已完成」

16.5 事件訊息設計

{
  "eventId": "6f1c2d4e-...",
  "eventType": "Bank.Txn.Transfer.Completed",
  "schemaVersion": 2,
  "occurredAt": "2026-10-03T10:15:30+08:00",
  "source": "CBS",
  "correlationId": "c0ffee...",
  "data": {
    "transferId": "T202610030001",
    "amount": "1000.00",
    "currency": "TWD"
  }
}
  • eventId 供訂閱者冪等。
  • schemaVersion 供演進;新增欄位向後相容,刪除欄位需版本升級。
  • 金額使用字串或定點數,避免浮點誤差。
  • 事件中避免放入完整個資;需要時由訂閱者以 ID 查詢。

16.6 IBM MQ 與 Apache Kafka 整合

許多企業同時有 IBM MQ(交易)與 Kafka(事件串流、分析)。兩者不是互相取代,而是以 Kafka Connect connector 橋接:交易仍走 MQ,事件副本送到 Kafka 供分析與下游使用。

flowchart LR
    CBS["核心系統"] -->|"MQPUT"| Q1["TXN.EVT.TO.KAFKA"]
    Q1 --> SRC["MQ Source Connector"]
    SRC --> KT[("Kafka Topic<br/>bank.txn.events")]
    KT --> ANA["分析 / 風控 / 資料湖"]
    KT2[("Kafka Topic<br/>bank.notify.cmd")] --> SNK["MQ Sink Connector"]
    SNK -->|"MQPUT"| Q2["NOTIFY.CMD.FROM.KAFKA"]
    Q2 --> LEG["Legacy 通知系統"]
面向Source(MQ → Kafka)Sink(Kafka → MQ)
用途交易事件送到串流平台串流平台的指令送進 Legacy
傳遞語意依 connector 版本與設定,可設定為 exactly-once 或 at-least-once [需確認]at-least-once,MQ 端 Consumer 必須冪等
訊息格式可選擇以 JMS 格式或原始 bytes 讀取;[MQ 10.0] 新增 XML Converter需決定 MQMD 欄位(Persistence、CCSID、ReplyTo)如何對應
部署Kafka Connect Cluster(含 IBM Event Streams);[MQ 10.0] IBM MQ Advanced 提供 Kafka Connect 支援同左
# MQ Source Connector 範例(帳密以 Kafka Connect 的 ConfigProvider 從 Secret 讀取)
name=mq-source-txn-events
connector.class=com.ibm.eventstreams.connect.mqsource.MQSourceConnector
tasks.max=1
mq.queue.manager=NBKQM01
mq.connection.name.list=nbk-mq-a.bank.local(1414),nbk-mq-b.bank.local(1414)
mq.channel.name=KAFKA.SVRCONN
mq.queue=TXN.EVT.TO.KAFKA
mq.user.name=${file:/opt/kafka/secrets/mq.properties:user}
mq.password=${file:/opt/kafka/secrets/mq.properties:password}
mq.ssl.cipher.suite=TLS_AES_256_GCM_SHA384
mq.message.body.jms=true
topic=bank.txn.events
value.converter=org.apache.kafka.connect.storage.StringConverter

設計規則:

  • Connector 使用專用的 SVRCONN 與帳號,只授予該佇列的 get(Source)或 put(Sink)。
  • 不要讓 Connector 直接讀業務主佇列;以 Streaming Queue(Part 2.9)或 Pub/Sub 訂閱產生副本佇列。
  • 監控 Connector lag 與 MQ 佇列深度;Connector 停止時副本佇列會累積。
  • Connector 屬性名稱以 GitHub ibm-messaging/kafka-connect-mq-source、kafka-connect-mq-sink 的版本說明為準 [需確認]。

16.7 常見錯誤

  • Durable Subscription 的訂閱者已下線但未刪除訂閱 → 佇列持續累積,最終影響整個 QM。
  • 以 Pub/Sub 傳遞需要回應的指令。
  • 事件順序被假設為全域有序。
  • Kafka Connector 直接讀業務主佇列,與正式 Consumer 搶訊息。

16.8 Checklist

  • Topic 命名遵循階層規範
  • 正式訂閱使用管理式 Subscription
  • 每個訂閱佇列有 BOQ 與深度監控
  • 事件含 eventId 與 schemaVersion
  • 有訂閱者下線的清理流程
  • MQ 與 Kafka 的橋接使用副本佇列與專用帳號

Part 17 — IBM MQ 與 Legacy System 逆向工程

17.1 目的

在缺乏文件的情況下,從程式碼、設定、日誌與訊息樣本重建 Legacy 系統的 MQ 整合全貌。這是本手冊的核心章節之一。

17.2 現況假設

手上只有:

資料可能透露的資訊
Java CodeMQ API 呼叫、佇列名稱、CorrelId 慣例、交易邊界
C# CodeIBM MQ .NET / XMS .NET 呼叫
VB / VB.NET Code舊版 MQ ActiveX / .NET 呼叫
COBOLCALL 'MQPUT'、Copybook(電文格式)
Stored Procedure資料庫觸發送 MQ、或 MQ 資料落地的表
MQ Configuration / MQSC佇列、Channel、路由、權限
XML / properties / yml連線設定、JNDI、Spring 設定
Log實際訊息流量、錯誤、Reason Code
Message Sample電文格式、CCSID、RFH2
DB Schema交易狀態、冪等表、Outbox

17.3 目標產出

Legacy Application
        ↓
MQPUT
        ↓
Queue
        ↓
MQ Channel
        ↓
Remote Queue
        ↓
Legacy System
產出內容
MQ Flow每個業務流程經過的 Queue / Channel / QM
Message Flow訊息在系統之間的流向與轉換
Queue Map所有佇列、類型、擁有者、Producer、Consumer
Channel Map所有 Channel、兩端 QM、TLS、MCAUSER
System Context系統與外部系統的邊界圖
Integration Context整合點清單與協定
Sequence Diagram每個主要交易的時序
Message Specification電文欄位、長度、型別、CCSID
Error Flow錯誤時訊息去向(BOQ、DLQ、補償)
Retry Flow重試機制與上限
Dependency Map系統之間的相依與啟動順序

17.4 逆向工程架構

flowchart TB
    subgraph Inputs["輸入來源"]
        SRC["原始碼<br/>Java / C# / VB / COBOL"]
        CFG["設定檔<br/>MQSC / XML / yml / properties"]
        DBS["DB Schema / SP"]
        LOGS["Application Log / AMQERR / FDC"]
        SAMP["Message Samples"]
    end
    subgraph Analysis["分析"]
        A1["MQ API 偵測"]
        A2["Queue / Channel 偵測"]
        A3["訊息結構偵測"]
        A4["交易 / 錯誤處理偵測"]
        A5["Runtime 驗證<br/>(DISPLAY / 日誌比對)"]
    end
    subgraph Outputs["產出"]
        O1["MQ Inventory"]
        O2["Queue Map / Channel Map"]
        O3["Message Specification"]
        O4["Sequence / Flow Diagram"]
        O5["Architecture Specification"]
    end
    SRC --> A1 --> A2
    CFG --> A2
    SAMP --> A3
    SRC --> A3
    SRC --> A4
    DBS --> A4
    LOGS --> A5
    A2 --> A5
    A1 --> O1
    A2 --> O2
    A3 --> O3
    A4 --> O4
    A5 --> O4
    O1 --> O5
    O2 --> O5
    O3 --> O5
    O4 --> O5

17.5 方法:從靜態到動態

階段方法工具
1. 靜態盤點搜尋 MQ API、佇列名稱字串、設定檔grep / IDE 搜尋 / AI Agent
2. 設定比對dmpmqcfg 輸出與程式中的名稱交叉比對腳本 / AI Agent
3. 路由解析從 QREMOTE / QALIAS / Cluster 解析實際目的地MQSC / 人工
4. 訊息結構從 Copybook / DTO / 樣本推導AI Agent + 人工確認
5. 動態驗證DISPLAY QSTATUS TYPE(HANDLE)、DISPLAY CONN 找出實際讀寫者MQSC
6. 流量驗證日誌時間序列比對、訊息計數Log 平台
7. 文件化產出 17.3 所列文件AI Agent + Review

17.6 IBM MQ Reverse Engineering Input Checklist

AI 可以分析的檔案類型:

*.java
*.xml
*.properties
*.yml
*.yaml
pom.xml
build.gradle
MQSC
Shell Script
PowerShell
C#
VB.NET
COBOL
Stored Procedure
SQL
Application Log
MQ Error Log
MQ Configuration
Message Sample
#輸入必要性取得方式注意事項
1*.java必要Git包含測試程式(常見真實佇列名稱)
2*.xml(Spring XML、JNDI、ejb-jar.xml、ra.xml)必要Git / 部署包Java EE 的 MQ 設定常在 XML
3*.properties / *.yml / *.yaml必要Git / 設定中心先遮蔽密碼再交給 AI
4pom.xml / build.gradle必要GitMQ Client 版本、JMS / Jakarta
5MQSC(dmpmqcfg 輸出)必要MQ 管理員各環境分別取得以比對差異
6Shell Script / PowerShell建議主機 / Git啟停、監控、批次送檔
7C# / VB.NET視情況GitIBM MQ .NET(IBM.WMQ)、XMS
8COBOL + Copybook視情況主機電文格式的唯一真相來源
9Stored Procedure / SQL建議DBA交易狀態、Outbox、冪等表
10Application Log建議Log 平台實際流量、CorrelId 慣例
11MQ Error Log(AMQERR*.LOG)建議MQ 管理員Channel 錯誤、安全拒絕
12MQ Configuration(qm.ini、mqs.ini、CCDT)建議MQ 管理員
13Message Sample必要(電文格式)測試環境 Browse(amqsbcg 等範例程式)只用測試環境或已遮罩樣本
14架構圖、交接文件、變更單參考各單位可能過時,需與程式比對

安全提醒:交給 AI Agent 的任何資料,必須先移除密碼、私鑰、正式個資。Production 訊息樣本需經遮罩並取得資料擁有者同意。

17.7 分析產出鏈

MQ Inventory
     ↓
Queue Map
     ↓
Channel Map
     ↓
Message Map
     ↓
Application Map
     ↓
Dependency Map
     ↓
Sequence Diagram
     ↓
Architecture Specification

17.8 Queue Map 範本

QueueTypeQM實際目的地ProducerConsumerPersistenceBOQ來源證據
NBK.TXN.TRANSFER.REQQREMOTENBKQM01CBSQM01 / CBS.TXN.TRANSFER.REQpayment-service—PERSISTENT(程式)—TransferMqGateway.java:L42、NBKQM01.mqsc:L310
CBS.TXN.TRANSFER.REQQLOCALCBSQM01—Channel NBKQM01.CBSQM01CBS COBOL TRF001DEFPSIST(YES)CBS.TXN.TRANSFER.REQ.BOQCBSQM01.mqsc:L88、TRF001.cbl:L120

每一列都要有「來源證據」(檔案 + 行號或命令輸出)。沒有證據的推論必須標記為「推測」。

17.9 Legacy MQ Flow 範例

sequenceDiagram
    autonumber
    participant NB as 網銀 Java(payment-service)
    participant Q1 as NBKQM01
    participant CH as Channel NBKQM01.CBSQM01
    participant Q2 as CBSQM01
    participant CB as COBOL TRF001(CICS)
    NB->>Q1: MQPUT NBK.TXN.TRANSFER.REQ(QREMOTE)
    Q1->>CH: XMITQ CBSQM01
    CH->>Q2: CBS.TXN.TRANSFER.REQ
    Q2->>CB: Trigger / MQGET
    CB->>Q2: MQPUT1 ReplyToQ=NBK.TXN.TRANSFER.RSP<br/>ReplyToQMgr=NBKQM01
    Q2->>Q1: Channel CBSQM01.NBKQM01
    Q1->>NB: MQGET(CorrelId 篩選)

17.10 常見發現與風險

發現風險
佇列名稱寫死在程式中(非設定檔)搬遷 / 改名需改程式
程式使用 SYSTEM.DEF.SVRCONN 連線安全基準不符
沒有 BOQ,例外時 while(true) 重試毒訊息堵塞
JMS 送往 COBOL 但未設定 targetClient電文前多出 RFH2
CCSID 不一致(Big5 / 950 vs 937 vs UTF-8)中文亂碼
CorrelId 慣例 A / B 混用等不到回覆
Production 與 UAT 的 MQSC 不一致測試無法代表正式環境

17.11 Checklist

  • 已依 Input Checklist 收集資料並完成遮罩
  • Queue Map 每列都有來源證據
  • Channel Map 已含兩端 QM、TLS、MCAUSER
  • 已以 DISPLAY QSTATUS TYPE(HANDLE) 驗證 Producer / Consumer
  • CorrelId 慣例與 CCSID 已確認
  • 所有推測項目已標記並排入人工驗證

Part 18 — AI Agent 協助 IBM MQ 逆向工程

18.1 目的

建立以 AI Agent 進行 MQ 逆向工程的標準 Workflow,並定義 AI 必須辨識的 API 樣式。

18.2 Workflow

Source Code
     ↓
AI Agent
     ↓
MQ API Detection
     ↓
Queue Detection
     ↓
Channel Detection
     ↓
Message Structure Detection
     ↓
Flow Reconstruction
     ↓
Sequence Diagram
     ↓
Architecture Specification
flowchart TB
    S0["0. 準備<br/>遮罩敏感資料 / 定義範圍"] --> S1["1. MQ API Detection<br/>MQI / classes for Java / JMS / Jakarta / Spring / .NET / COBOL"]
    S1 --> S2["2. Queue Detection<br/>字串常數 / 設定檔 / JNDI / MQSC"]
    S2 --> S3["3. Channel Detection<br/>connName / CCDT / MQSC Channel"]
    S3 --> S4["4. Message Structure Detection<br/>DTO / Copybook / 樣本 / CCSID"]
    S4 --> S5["5. Flow Reconstruction<br/>Producer → Queue → 路由 → Consumer"]
    S5 --> S6["6. Sequence Diagram<br/>Mermaid"]
    S6 --> S7["7. Architecture Specification"]
    S7 --> H["Human Review<br/>以 DISPLAY / Log 驗證"]
    H -->|"發現差異"| S2

18.3 MQI 動詞辨識

AI 必須辨識:

MQCONN
MQOPEN
MQPUT
MQGET
MQPUT1
MQCLOSE
MQDISC
MQIC / COBOLMQ classes for Java.NET(IBM.WMQ)
MQCONN / MQCONNXMQCONN(...) / CALL 'MQCONN'new MQQueueManager(...)new MQQueueManager(...)
MQOPENMQOPEN(...)qmgr.accessQueue(...)qmgr.AccessQueue(...)
MQPUTMQPUT(...)queue.put(msg, pmo)queue.Put(msg, pmo)
MQPUT1MQPUT1(...)qmgr.put(qName, msg, pmo)qmgr.Put(...)
MQGETMQGET(...)queue.get(msg, gmo)queue.Get(msg, gmo)
MQCMIT / MQBACKMQCMIT / MQBACKqmgr.commit() / backout()qmgr.Commit() / Backout()
MQCLOSEMQCLOSE(...)queue.close()queue.Close()
MQDISCMQDISC(...)qmgr.disconnect()qmgr.Disconnect()

18.4 JMS / Jakarta Messaging 辨識

ConnectionFactory
JMSContext
JMSProducer
JMSConsumer
MessageListener
樣式說明
ConnectionFactory / MQConnectionFactory / MQQueueConnectionFactory連線設定所在
JMSContext(JMS 2.0 / Jakarta)簡化 API
QueueConnection / QueueSession / QueueSender / QueueReceiverJMS 1.1 舊式 API
JMSProducer.send / MessageProducer.sendProducer
JMSConsumer.receive / MessageConsumer.receive同步 Consumer
MessageListener.onMessage非同步 Consumer
@JmsListener、JmsTemplate、DefaultMessageListenerContainerSpring
@MessageDriven(MDB)Java EE / Jakarta EE
InitialContext.lookup("jms/...")JNDI:佇列名稱在應用伺服器設定中

18.5 Queue / Channel 偵測規則

來源搜尋樣式
程式字串全大寫且含 . 的字串(如 "CBS.TXN.TRANSFER.REQ")、queue:/// URI
Spring 設定ibm.mq.*、destination =、spring.jms.*
JNDI.bindings 檔、應用伺服器設定(server.xml 的 jmsQueue、jmsConnectionFactory)
環境變數MQSERVER、MQCHLLIB、MQCHLTAB、MQCCDTURL
MQSCDEFINE QLOCAL / QREMOTE / QALIAS / CHANNEL / LISTENER / SUB / TOPIC

18.6 AI 輸出的品質要求

要求說明
證據每個結論附檔案路徑 + 行號,或 MQSC 物件名稱
信心度標示「確認 / 推測 / 不明」
不臆測找不到 Consumer 時寫「程式碼中未找到」,不得自行假設
範圍明確說明分析了哪些目錄、哪些檔案類型、哪些未分析
驗證步驟提供人工驗證用的 DISPLAY 命令

18.7 Human-in-the-loop 驗證

sequenceDiagram
    participant AI as AI Agent
    participant ENG as 工程師
    participant ADM as MQ 管理員
    participant MQ as Queue Manager(TEST / 唯讀)
    AI->>ENG: Queue Map(含推測項目)+ 驗證用 DISPLAY 命令
    ENG->>ADM: 申請執行唯讀命令
    ADM->>MQ: DISPLAY QSTATUS TYPE(HANDLE) / DISPLAY CONN
    MQ-->>ADM: 結果
    ADM-->>ENG: 結果(已遮罩)
    ENG->>AI: 回饋結果
    AI->>ENG: 更新 Queue Map,推測 → 確認 / 推翻

18.8 Checklist

  • AI 分析範圍與排除項已明確定義
  • 所有 MQI / JMS / Spring 樣式皆已掃描
  • 每個結論有證據與信心度
  • 推測項目已經人工以 DISPLAY / Log 驗證
  • AI 未直接連線 Production MQ

Part 19 — AI Agent 逆向工程 Prompt

19.1 目的

提供可直接複製使用的 MQ 逆向工程 Prompt,並要求 AI 產生標準化的 MQ Reverse Engineering Report。

19.2 主 Prompt:Java 專案 MQ 全面分析

你是一位 IBM MQ 與 Java 逆向工程專家。請分析這個 Java 專案所有 IBM MQ 相關程式。

【分析範圍】
- 目錄:<填入,例如 src/main/java、src/main/resources、config/>
- 排除:target/、node_modules/、*.class

【請找出】
1. MQ Connection(ConnectionFactory、MQQueueManager、connName、CCDT、Channel)
2. Queue Manager 名稱
3. Queue(含 queue:/// URI、JNDI 名稱、設定檔中的名稱)
4. Channel
5. MQPUT(含 MQPUT1、JmsTemplate.send、JMSProducer.send)
6. MQGET(含 receive、@JmsListener、MessageListener、MDB)
7. JMS Producer
8. JMS Consumer
9. Transaction(Syncpoint、SESSION_TRANSACTED、@Transactional、XA)
10. Retry(迴圈重試、Spring Retry、Listener BackOff)
11. Exception Handling(捕捉哪些例外、Reason Code 處理)
12. DLQ / Backout Queue 處理
13. Correlation ID 設定與比對方式
14. Message ID 使用方式

【請建立】
- MQ Inventory(表格:類型 / 名稱 / 檔案:行號 / 信心度)
- MQ Flow(Mermaid flowchart)
- Sequence Diagram(Mermaid sequenceDiagram,每個主要交易一張)
- Dependency Map(系統與 Queue Manager 的相依)
- Error Flow(例外時訊息去向)
- Message Specification(欄位、型別、來源 DTO / Copybook)

【限制】
- 每個結論必須附「檔案路徑:行號」證據
- 找不到的資訊寫「未找到」,不得推測為事實;推測請標記「推測」
- 不要輸出任何密碼、金鑰、Token;遇到時以 *** 遮蔽並列入安全發現
- 不要修改任何檔案

【輸出】
請產出一份 Markdown:MQ Reverse Engineering Report,格式依下方範本。

19.3 MQ Reverse Engineering Report 範本

# MQ Reverse Engineering Report — <系統名稱>

## 1. 摘要
- 分析日期 / 分析範圍 / 排除範圍
- MQ API 類型:MQ classes for Java / JMS 2.0 / Jakarta / Spring JMS
- MQ Client 版本(pom.xml / build.gradle)
- 主要發現(前 5 項)

## 2. MQ Inventory
| 類型 | 名稱 | 檔案:行號 | 用途 | 信心度 |

## 3. Queue Map
| Queue | 推定類型 | Producer | Consumer | Persistence | Expiry | BOQ | 證據 |

## 4. Channel / Connection Map
| QM | Channel | connName / CCDT | TLS | 認證方式 | 證據 |

## 5. Message Specification
| 訊息 | 欄位 | 型別 / 長度 | 必填 | 來源 | 備註 |

## 6. MQ Flow(Mermaid)

## 7. Sequence Diagrams(Mermaid)

## 8. Transaction 與 Error Flow
- 交易邊界、Commit / Rollback 時機
- 例外處理、Retry、BOQ / DLQ

## 9. Dependency Map(Mermaid)

## 10. 安全發現
- 寫死的帳密 / 過度權限 / 未啟用 TLS 的跡象

## 11. 風險與技術債

## 12. 未確認項目與建議的驗證命令
| 項目 | 驗證方式(DISPLAY 命令 / Log 查詢) | 負責人 |

19.4 補充 Prompt:MQSC 與程式交叉比對

以下提供兩份資料:
(A) Queue Manager <QM 名稱> 的 dmpmqcfg 輸出(已遮罩)
(B) 前一步產生的 MQ Inventory

請:
1. 找出程式使用但 MQSC 中不存在的佇列(可能為 Cluster 佇列、別名或設定錯誤)
2. 找出 MQSC 存在但程式中未使用的佇列(可能為其他系統使用或已廢棄)
3. 解析每個 QREMOTE / QALIAS 的最終目的地
4. 檢查每個 Input Queue 是否有 BOQNAME / BOTHRESH
5. 檢查每個 SVRCONN / RCVR 的 SSLCIPH、SSLCAUTH、MCAUSER
輸出:差異表 + 風險清單。每項附 MQSC 物件名稱作為證據。
不得建議直接在 Production 執行任何 ALTER / DEFINE / DELETE。

19.5 補充 Prompt:COBOL Copybook 轉 Message Specification

以下是 COBOL Copybook(電文格式)。請轉為 Message Specification 表格:
欄位名稱 / 層級 / PIC / 位元組長度 / 起始位置 / 型別(文字、數字、COMP-3)/ 說明。

要求:
- 計算每個欄位的起始位置與總長度
- COMP-3(Packed Decimal)標示實際位元組長度
- 標示可能的 CCSID 相關風險(中文欄位、EBCDIC)
- 產出對應的 Java record 定義(只產生,不寫入檔案)
- 對無法確定的 REDEFINES / OCCURS DEPENDING ON 明確標示

19.6 驗證方式

驗證方法
完整性以 grep 搜尋 com.ibm.mq、jakarta.jms、javax.jms、JmsTemplate、@JmsListener,數量與 Inventory 比對
正確性隨機抽 10 個證據行號人工確認
一致性Queue Map 與 dmpmqcfg 比對
動態DISPLAY QSTATUS TYPE(HANDLE) 確認 Producer / Consumer

Part 20 — AI Agent 協助 Framework 升級

20.1 目的

以 AI Agent 協助完成 Legacy Java 到現代 Java / Spring / Jakarta 的升級,並同步升級 IBM MQ Client。

20.2 升級路徑

Legacy Java
      ↓
Java Upgrade
      ↓
Spring Upgrade
      ↓
IBM MQ Client Upgrade
      ↓
Jakarta Migration
flowchart LR
    A["Java 8<br/>Spring 4/5<br/>Boot 1.x/2.x<br/>javax.jms<br/>MQ Client 8/9.1"] --> B["Java 17<br/>(LTS 跳板)"]
    B --> C["Spring Boot 2.7<br/>(javax 最後版)"]
    C --> D["Spring Boot 3.x<br/>jakarta.jms<br/>MQ jakarta.client"]
    D --> E["Java 25<br/>Spring Boot 4.x<br/>MQ Client 10.0"]
    style A fill:#fdd
    style E fill:#dfd

20.3 版本與 API 對照

元件舊新主要變化
Java817 → 21 → 25模組封裝、移除 Java EE 模組、TLS 預設、SecurityManager 停用
Spring Framework4.x / 5.x6.x → 7.xJakarta 命名空間、Java 17 基準
Spring Boot1.x / 2.x3.x → 4.xJakarta、屬性改名、auto-config 模組化(Boot 4)
JMS APIjavax.jms(JMS 1.1 / 2.0)jakarta.jms(Jakarta Messaging 3.x)套件名稱變更
IBM MQ Clientcom.ibm.mq.allclient(javax)com.ibm.mq.jakarta.clientJakarta 版需 MQ 9.3+
IBM MQ JMS Provider 類別com.ibm.mq.jms.MQConnectionFactorycom.ibm.mq.jakarta.jms.MQConnectionFactory套件名稱變更
WMQConstantscom.ibm.msg.client.wmq.WMQConstantscom.ibm.msg.client.jakarta.wmq.WMQConstants套件名稱變更
Startermq-jms-spring-boot-starter 2.x3.x → 4.x對應 Boot 主版本

20.4 AI 必須產出的文件

文件內容
Dependency Inventory所有直接 / 傳遞依賴與版本,標示 javax / jakarta
Compatibility MatrixJava × Spring Boot × MQ Client × 應用伺服器 × OS
Breaking Change List每項變更、影響檔案、修改方式
Migration Plan分階段步驟、每階段可獨立測試與回復
Risk List風險、影響、機率、對策
Test Plan單元、整合(MQ 容器)、回歸、效能、安全
Rollback Plan每階段回復方式(版本、設定、資料)

20.5 常見 Breaking Changes(MQ 相關)

變更症狀修正
javax.jms → jakarta.jms編譯錯誤套件替換(OpenRewrite 等工具可協助)
同時存在 javax 與 jakarta MQ ClientClassCastException、NoSuchMethodError移除舊 artifact
Spring Boot 屬性改名設定未生效、使用預設值對照官方 migration guide;啟用 spring-boot-properties-migrator
TLS CipherSpec 被淘汰 [MQ 10.0]2393、2397、AMQ9631E 類錯誤改用 TLS 1.3 / ECDHE 套件
TLS_RSA_* 在 Semeru 25 停用Java 25 Client TLS 握手失敗改用 ECDHE / TLS 1.3
非 IBM JRE Cipher 名稱2400 UNSUPPORTED_CIPHER_SUITEuseIBMCipherMappings=false
預設檔案編碼 UTF-8(Java 18+;[MQ 10.0] 提及 Semeru 21 / 25 編碼變更)非 UTF-8 電文亂碼明確指定 Charset 與 CCSID
Starter 預設帳密移除2035明確設定 user / password

20.6 Upgrade Risk Matrix

風險機率影響等級對策
TLS 握手失敗導致 Production 無法連線中高高UAT 以相同 QM 設定驗證;保留舊 CipherSpec 過渡期(若 QM 仍支援)
javax / jakarta 混用高中高mvn dependency:tree 檢查;ArchUnit / Enforcer 規則
電文編碼變更中高高以真實樣本做位元組比對測試
屬性改名未發現中中中properties-migrator;啟動時列印有效設定
效能退化低中中效能基準測試比對
Listener 行為改變(concurrency、receiveTimeout)中中中整合測試覆蓋;比較 DISPLAY CONN 連線數

20.7 IBM MQ + Java Framework Upgrade Playbook

Inventory
 ↓
Dependency Analysis
 ↓
API Analysis
 ↓
Compatibility Analysis
 ↓
MQ Client Analysis
 ↓
JMS Analysis
 ↓
Java Upgrade
 ↓
Spring Upgrade
 ↓
Testing
 ↓
Performance
 ↓
Security
 ↓
UAT
 ↓
Production
步驟動作AI 協助人工確認完成條件
1 Inventory列出所有模組、依賴、MQ 使用點掃描 pom / import範圍確認Inventory 文件
2 Dependency Analysisdependency:tree 分析傳遞依賴標示 javax / jakarta 衝突—衝突清單
3 API Analysis找出已淘汰 / 移除 API掃描並列出抽查Breaking Change List
4 Compatibility Analysis對照官方相容矩陣整理表格 + 官方連結以官方文件確認Compatibility Matrix
5 MQ Client AnalysisClient 版本、Cipher、CCDT、重連設定掃描設定MQ 管理員確認 QM 端MQ Client 變更清單
6 JMS Analysisjavax → jakarta、Provider 類別產生替換清單ReviewJMS 變更清單
7 Java Upgrade8 → 17 → 25修改建議 / PRCode Review編譯與單元測試通過
8 Spring UpgradeBoot 2.7 → 3.x → 4.x修改建議 / PRCode Review整合測試通過
9 TestingMQ 整合測試、回歸產生測試Review測試通過
10 Performance對照基準分析結果確認無顯著退化
11 SecuritySAST / SCA / TLS 掃描分析報告Security 簽核無高風險
12 UAT使用者驗收—業務簽核UAT 通過
13 Production分批上線、監控產生上線檢查表變更核准監控穩定

20.8 Checklist

  • 七份 AI 產出文件齊全且經人工審閱
  • Compatibility Matrix 每一格有官方來源
  • 每階段可獨立回復
  • TLS / CipherSpec 已在 UAT 以 Production 等同設定驗證
  • 電文編碼以真實樣本驗證

Part 21 — IBM MQ 升級

21.1 目的

說明 IBM MQ Server、Client、Java Client、JMS、TLS、OS、Container Image 升級的方法與流程。

21.2 升級類型

類型內容主要風險
MQ Version Upgrade9.3 / 9.4 LTS → 10.0 LTS行為變更、CipherSpec 移除、不可降版
Maintenance(Fix Pack / CSU)同版本修補低;仍需測試
MQ Client Upgrade應用端 Client 函式庫TLS、預設值改變(例如 [MQ 10.0] Client 預設 TCP buffer 變更)
Queue Manager UpgradeQM 資料遷移到新版QM 以新版啟動後通常無法回到舊版 [需確認各版本規則]
Java Client Upgradejakarta.client 版號API 行為、JDK 支援
JMS Upgradejavax → jakarta見 Part 20
TLS / CipherSpec Upgrade移除舊套件、更換憑證連線中斷
OS UpgradeRHEL 主版本等支援矩陣、核心參數
Container Image UpgradeImage tag設定與 Secret 路徑、Operator 版本

21.3 相容性基本原則

  • MQ Client 與 Server 版本可以不同:一般而言較新與較舊的 Client / Server 可以互通,但新功能需雙方都支援 [需確認官方相容性聲明]。
  • 建議先升級 Server,再升級 Client(Server 通常向下相容舊 Client)。
  • LTS 與 CD 不要混用於同一套升級規劃:LTS 系統升級目標應為下一個 LTS(例如 9.4.0 LTS → 10.0 LTS)。
  • 10.0 移除的 CipherSpec 必須在升級前完成替換。

21.4 升級流程

Current
   ↓
Assessment
   ↓
Compatibility Check
   ↓
POC
   ↓
Test
   ↓
Performance Test
   ↓
Security Test
   ↓
UAT
   ↓
Production
   ↓
Monitoring
flowchart TB
    C["Current<br/>盤點版本 / 設定 / CipherSpec"] --> A["Assessment<br/>What's changed / Deprecated 清單"]
    A --> CC["Compatibility Check<br/>OS / JDK / Client / 應用伺服器"]
    CC --> POC["POC<br/>單一 QM + 代表性應用"]
    POC --> T["Test<br/>功能 / 回歸"]
    T --> PT["Performance Test"]
    PT --> ST["Security Test<br/>TLS / CHLAUTH / OAM"]
    ST --> U["UAT"]
    U --> GO{"Go / No-Go"}
    GO -- Go --> P["Production<br/>分批升級"]
    GO -- No-Go --> A
    P --> M["Monitoring<br/>錯誤率 / Channel / 效能"]
    M -->|"異常"| RB["Rollback / Fallback<br/>(依事前規劃)"]

21.5 Queue Manager 升級方式

方式說明停機回復
In-place 升級停 QM → 升級安裝 → 以新版啟動有困難(需備份還原)
Side-by-side(多版本並存)新版另行安裝(setmqinst),QM 以 setmqm 切換到新安裝短切換前可回退;啟動後同 In-place
Rolling(HA / Multi-instance / Native HA)先升 Standby,再切換極短依 HA 方式
新建遷移建新 QM,以 dmpmqcfg 重建物件,應用切換規劃切換舊 QM 保留可回切
# Side-by-side 範例(Linux):新版安裝在 /opt/mqm10
dspmqinst                          # 列出安裝
endmqm -w BANKQM01
setmqm -m BANKQM01 -n Installation2
. /opt/mqm10/bin/setmqenv -s
strmqm BANKQM01                    # 以新版啟動,資料將遷移
dspmq -o installation

setmqm、setmqinst 的確切語法與升級前置條件,需依目前 IBM 官方 Migration 文件確認。啟動新版後,舊版通常無法再啟動該 QM,升級前必須完成完整備份。

21.6 10.0 升級前必查

項目檢查方式
已移除的 CipherSpec(SSLv3、TLS 1.0、RC4、3DES)DISPLAY CHANNEL(*) SSLCIPH
RSA key exchange CipherSpec(Deprecated)同上
憑證 RSA 金鑰長度runmqakm -cert -details
憑證 label 是否含空白或逗號DISPLAY QMGR CERTLABL、Channel CERTLABL
User ID 格式(更嚴格驗證)dmpmqaut、MCAUSER、CHLAUTH
Java Client 的 JDK(Semeru 25 停用 TLS_RSA_*)應用 JDK 盤點
隨產品附帶的 Java runtime 變更依 IBM Docs「Changes to the Java runtime environment shipped with IBM MQ」
Deprecated / Removed 功能IBM Docs「Deprecated, stabilized, and removed features in IBM MQ 10.0.0」

21.7 Container Image 升級

  • 先升級 MQ Operator(若使用),再升級 QueueManager CR 的版本欄位 [需確認 Operator 版本對應]。
  • Native HA:Operator 會以滾動方式升級各 Pod。
  • 升級前備份 PV 或確認 DR 副本狀態。

21.8 Checklist

  • 已閱讀 10.0 What’s new / What’s changed / Deprecated 清單
  • 已替換所有被移除與 Deprecated 的 CipherSpec
  • 已確認 OS / JDK 在 System Requirements 支援清單
  • 已完成完整備份(設定 + 資料)並驗證可還原
  • Rollback / Fallback 方式已演練
  • 分批升級順序與監控指標已定義

Part 22 — IBM MQ 維運

22.1 目的

建立 Production Operation Guide:每日巡檢、關鍵指標、告警門檻與維運流程。

22.2 維運範圍

項目觀察重點工具 / 命令
Queue Monitoring深度、開啟數、訊息年齡DISPLAY QSTATUS
Queue Depth是否持續上升CURDEPTH、QDEPTHHI 事件
Channel StatusRUNNING / RETRYING / STOPPEDDISPLAY CHSTATUS(*)
Connection Status連線數、來源、應用名稱DISPLAY CONN(*)
Message RatePUT / GET 速率Statistics、amqsrua、Prometheus exporter
Backlog深度 ÷ 消費速率 = 預估清空時間計算指標
DLQ深度 > 0 即需處理DISPLAY QLOCAL(SYSTEM.DEAD.LETTER.QUEUE) CURDEPTH
Error LogAMQ 錯誤、FDCAMQERR01.LOG、/var/mqm/errors/*.FDC
Performance延遲、吞吐Statistics、應用端指標
CPU / MemoryQM 程序資源OS 監控
DiskLog 與 Queue 檔案系統使用率OS 監控;Log 空間耗盡會造成嚴重問題
LogRecovery Log 使用量、長交易DISPLAY QMSTATUS LOG(欄位依版本)
Alert告警規則監控平台

22.3 每日巡檢腳本(唯讀)

#!/usr/bin/env bash
# MQ 每日巡檢(唯讀):僅使用 DISPLAY 類命令
set -euo pipefail
QM="${1:?usage: $0 <QMGR>}"
TS=$(date +%Y%m%d_%H%M%S)
OUT="/var/log/mq-healthcheck/${QM}_${TS}.txt"
mkdir -p "$(dirname "$OUT")"

{
  echo "=== dspmq ==="
  dspmq -m "$QM" -o all
  echo "=== MQSC ==="
  runmqsc "$QM" <<'EOF'
DISPLAY QMSTATUS ALL
DISPLAY QLOCAL(*) WHERE(CURDEPTH GT 0) CURDEPTH MAXDEPTH
DISPLAY QSTATUS(SYSTEM.DEAD.LETTER.QUEUE) TYPE(QUEUE) CURDEPTH
DISPLAY QLOCAL(*.BOQ) WHERE(CURDEPTH GT 0) CURDEPTH
DISPLAY CHSTATUS(*) WHERE(STATUS NE RUNNING) STATUS SUBSTATE
DISPLAY LSSTATUS(*) STATUS PORT
EOF
  echo "=== Error log tail ==="
  tail -n 200 "/var/mqm/qmgrs/${QM}/errors/AMQERR01.LOG"
  echo "=== FDC (last 24h) ==="
  find /var/mqm/errors -name '*.FDC' -mtime -1 -print
} > "$OUT" 2>&1

echo "Health check written to $OUT"

實際部署時以監控平台取代人工看報表;本腳本適合作為最低限度與事後追查的紀錄。/var/mqm/qmgrs/<QM> 目錄名稱在 QM 名稱含特殊字元時會轉換,需依實際路徑調整。

22.4 告警門檻建議

指標WarningCritical說明
Queue Depth(% MAXDEPTH)60%80%對應 QDEPTHHI
最舊訊息年齡(MSGAGE)> SLA × 0.5> SLA需 MONQ 啟用
IPPROCS = 0(Input Queue 無 Consumer)1 分鐘5 分鐘Consumer 全部停止
DLQ 深度> 0> 100任何 DLQ 訊息都應被看見
BOQ 深度> 0> 10毒訊息
Channel 非 RUNNINGRETRYING 1 分鐘STOPPED
Log 檔案系統70%85%
憑證剩餘天數30 天7 天[MQ 10.0] dspmqcert
連線數(% MAXINST)70%90%
FDC 產生任何同類重複需開 IBM Case 評估

22.5 維運流程

flowchart LR
    A["告警"] --> B{"分類"}
    B -->|"深度上升"| C["檢查 Consumer<br/>IPPROCS / 應用日誌"]
    B -->|"Channel 異常"| D["檢查網路 / 對方 QM / TLS"]
    B -->|"DLQ / BOQ"| E["分析 DLH / 原因<br/>修正後重送"]
    B -->|"資源"| F["磁碟 / Log / CPU"]
    C --> G["處置 + 記錄"]
    D --> G
    E --> G
    F --> G
    G --> H["事後檢討(RCA)"]

22.6 Checklist

  • 每日巡檢自動化並保存紀錄
  • 22.4 告警門檻已設定於監控平台
  • DLQ / BOQ 有明確負責人與處理 SLA
  • Log 檔案系統有容量告警
  • 憑證到期監控已啟用

Part 23 — IBM MQ 故障排除

23.1 目的

建立 Troubleshooting Matrix 與常見 Reason Code 對照,讓開發與維運人員能快速定位問題。

23.2 排查方法論

flowchart TD
    S["症狀"] --> R{"有 Reason Code?"}
    R -- 是 --> RC["查 23.4 Reason Code 表"]
    R -- 否 --> L["查應用日誌 / AMQERR / FDC"]
    RC --> W{"哪一層?"}
    L --> W
    W -->|"連線"| N["Listener / 網路 / TLS / CHLAUTH"]
    W -->|"授權"| A["CONNAUTH / OAM / MCAUSER"]
    W -->|"物件"| O["佇列存在?名稱大小寫?路由?"]
    W -->|"容量"| C["MAXDEPTH / MAXMSGL / 磁碟"]
    W -->|"處理"| P["Consumer 狀態 / 毒訊息"]
    N --> F["修正 → 驗證 → 記錄"]
    A --> F
    O --> F
    C --> F
    P --> F

23.3 Troubleshooting Matrix

問題可能原因檢查方式處理方式
MQPUT 失敗 2085Queue 不存在、名稱大小寫錯誤、未在 Cluster 中公告DISPLAY QLOCAL / QREMOTE / QALIAS('名稱')、DISPLAY QCLUSTER檢查設定與名稱
MQPUT 失敗 2053佇列已滿DISPLAY QSTATUS CURDEPTH、MAXDEPTH檢查 Consumer;短期可調高 MAXDEPTH(L2 變更)
MQPUT 失敗 2030 / 2031訊息超過佇列 / QM MAXMSGLDISPLAY QLOCAL MAXMSGL、DISPLAY QMGR MAXMSGL調整訊息大小或屬性
MQPUT 失敗 2051佇列 PUT(DISABLED)DISPLAY QLOCAL PUT確認是否為刻意停用
MQGET Timeout 2033佇列無訊息(正常)、CorrelId 不符CURDEPTH、比對 CorrelId 慣例檢查 Producer、Reply 慣例
Channel Down網路、對方 Listener、TLSDISPLAY CHSTATUS、AMQERR檢查網路、防火牆、對方 QM
2035授權不足、CHLAUTH 封鎖、CONNAUTH 失敗AMQERR(AMQ5534E、AMQ9777E 等)、DISPLAY CHLAUTH MATCH(RUNCHECK)、dspmqaut依最小權限補授權;不要加入 mqm
2059QM 未啟動、Listener 未啟動、名稱錯誤dspmq、DISPLAY LSSTATUS啟動 QM / Listener
2538主機無法連線(DNS、Port、防火牆)nc -vz host 1414檢查網路
2539 / 2540Channel 名稱錯誤或 Channel 未定義 / 類型錯誤DISPLAY CHANNEL修正 Channel 名稱
2009連線中斷(網路、QM 停止、防火牆閒置斷線)AMQERR、網路設備日誌設定 Heartbeat / Keepalive;Client 重連
TLS Error 2393 / 2397 / 2400憑證、Cipher 不符、信任鏈、JRE Cipher 對應AMQERR(AMQ9631E、AMQ9633E、AMQ9637E 等)、Java -Djavax.net.debug檢查憑證、CipherSpec、useIBMCipherMappings
Message 堵塞Consumer 異常、毒訊息、處理變慢CURDEPTH、IPPROCS、MSGAGE、BOQ檢查 Consumer、移除毒訊息
訊息進 DLQ目標佇列不存在 / 已滿 / 權限讀 DLQ 的 MQDLH Reason修正後以 runmqdlq 重送
中文亂碼CCSID 不一致、未使用 MQGMO_CONVERT、RFH2訊息樣本 hex、MQMD CCSID統一 CCSID;設定轉換
Legacy 收到 RFH 開頭的資料JMS 未設 targetClient樣本前 4 bytes設定 targetClient=1
Channel 序號錯誤 AMQ9526E一端重建或還原AMQERR雙方管理員確認後 RESET CHANNEL
Channel in-doubt批次確認中斷DISPLAY CHSTATUS INDOUBT通常自動解決;手動 RESOLVE 需雙方確認
連線數爆增應用未重用連線、Pod 擴容DISPLAY CONN(*) 依 APPLTAG 統計修正連線管理;調整 MAXINST

23.4 常用 Reason Code

Code常數意義常見處理
2003MQRC_BACKED_OUT交易已被回滾重試交易
2009MQRC_CONNECTION_BROKEN連線中斷重連;檢查網路
2012MQRC_ENVIRONMENT_ERROR環境不允許此呼叫檢查交易環境 / 呼叫方式
2016MQRC_GET_INHIBITED佇列禁止 GETGET(ENABLED)
2018MQRC_HCONN_ERROR連線 Handle 無效重新連線;檢查多執行緒共用
2019MQRC_HOBJ_ERROR物件 Handle 無效重新開啟佇列
2024MQRC_SYNCPOINT_LIMIT_REACHED單一交易訊息數超過上限縮小交易;調整 MAXUMSGS
2030MQRC_MSG_TOO_BIG_FOR_Q超過佇列 MAXMSGL調整
2031MQRC_MSG_TOO_BIG_FOR_Q_MGR超過 QM MAXMSGL調整
2033MQRC_NO_MSG_AVAILABLE無訊息(等待逾時)正常情況
2035MQRC_NOT_AUTHORIZED未授權見 Part 8
2042MQRC_OBJECT_IN_USE物件被獨佔開啟檢查 MQOO_INPUT_EXCLUSIVE
2051MQRC_PUT_INHIBITED佇列禁止 PUTPUT(ENABLED)
2053MQRC_Q_FULL佇列已滿見 Part 6
2058MQRC_Q_MGR_NAME_ERRORQM 名稱錯誤檢查名稱 / CCDT
2059MQRC_Q_MGR_NOT_AVAILABLEQM 不可用啟動 QM / Listener
2063MQRC_SECURITY_ERROR安全錯誤檢查安全設定
2080MQRC_TRUNCATED_MSG_FAILEDBuffer 太小加大 buffer 或用 MQGMO_ACCEPT_TRUNCATED_MSG
2082MQRC_UNKNOWN_ALIAS_BASE_QAlias 目標不存在修正 TARGET
2085MQRC_UNKNOWN_OBJECT_NAME物件不存在檢查名稱
2087MQRC_UNKNOWN_REMOTE_Q_MGR遠端 QM 無法解析檢查 XMITQ / QM Alias / Cluster
2092MQRC_XMIT_Q_USAGE_ERRORXMITQ 用途設定錯誤USAGE(XMITQ)
2102MQRC_RESOURCE_PROBLEM系統資源不足檢查磁碟 / 記憶體 / Log
2110MQRC_FORMAT_ERROR訊息格式無法轉換檢查 Format / CCSID
2119MQRC_NOT_CONVERTED資料轉換失敗檢查 CCSID
2161MQRC_Q_MGR_QUIESCINGQM 正在停止中止並重連
2162MQRC_Q_MGR_STOPPINGQM 停止中中止並重連
2189MQRC_CLUSTER_RESOLUTION_ERRORCluster 解析失敗檢查 Repository
2195MQRC_UNEXPECTED_ERROR非預期錯誤查 FDC,必要時開 IBM Case
2393MQRC_SSL_INITIALIZATION_ERRORTLS 初始化失敗金鑰庫、憑證、Cipher
2397MQRC_JSSE_ERRORJava JSSE 錯誤看 linked exception
2400MQRC_UNSUPPORTED_CIPHER_SUITECipher Suite 不支援名稱對應、JRE 支援
2537MQRC_CHANNEL_NOT_AVAILABLEChannel 不可用(停止 / 達上限)MAXINST、Channel 狀態
2538MQRC_HOST_NOT_AVAILABLE主機無法連線網路 / Listener
2539MQRC_CHANNEL_CONFIG_ERRORChannel 設定錯誤檢查 Channel 定義
2540MQRC_UNKNOWN_CHANNEL_NAMEChannel 不存在檢查名稱
2548MQRC_RECONNECT_FAILED自動重連失敗檢查 HA 狀態

Reason Code 完整清單與說明以 IBM Documentation「Reason codes」為準;AMQ 錯誤訊息編號以實際日誌內容為準。

23.5 Java 端除錯技巧

// JMSException 的根因通常在 linked exception
catch (JMSException e) {
    Throwable cause = e.getLinkedException() != null ? e.getLinkedException() : e.getCause();
    if (cause instanceof com.ibm.mq.MQException mqe) {
        LOG.error("MQ reason={} cc={}", mqe.getReason(), mqe.getCompCode(), e);
    } else {
        LOG.error("JMS error code={}", e.getErrorCode(), e);
    }
}
工具用途
-Djavax.net.debug=ssl,handshakeTLS 握手除錯(只在非 Production 使用,輸出含敏感資訊)
MQ Java Client Trace以 mqclient.ini / 系統屬性或 starter 的 ibm.mq.trace.* 啟用
[MQ 10.0] 短生命週期 Java / JMS 容器的 trace 支援依官方文件設定

23.6 IBM MQ Agent:官方 AI 診斷助理

IBM MQ Agent 是 IBM 在 MQ 10.0 文件中推出的獨立下載元件,以生成式 AI 協助理解設定、查詢物件狀態與診斷問題。它和本手冊 Part 30-42 討論的 Coding Agent 定位不同:MQ Agent 面向「執行中的 Queue Manager」,Coding Agent 面向「程式碼與設定檔」。

flowchart LR
    U["維運 / MQ 管理員"] -->|"自然語言提問"| CHAT["Chat Assistant"]
    CHAT --> RT["Agent Runtime<br/>(使用 AI 基礎模型)"]
    RT --> MCP["MCP Server<br/>MQ 查詢工具組"]
    MCP -->|"唯讀查詢"| QM1["QM1"]
    MCP -->|"唯讀查詢"| QM2["QM2"]
    MCP -->|"唯讀查詢"| QMN["…最多 20 個 QM"]
    RT --> DOC["IBM MQ 文件搜尋"]
項目說明
型態容器化元件:連線設定 + MCP(Model Context Protocol)Server + Agent Runtime
連線範圍最多 20 個 Queue Manager,可位於任何平台
能力QM 設定與狀態、Channel / Queue / Listener / Cluster 診斷、應用連線狀態、訊息堆積分析、文件搜尋與下一步規劃
限制只能查詢與推理,不能執行 MQSC 等命令
授權IBM MQ Advanced 或 Cloud Pak for Integration 授權的延伸
輸出責任產品聲明 AI 輸出可能不準確,使用風險由使用者承擔

典型問題與對應的手動排查:

向 MQ Agent 提問它可能採用的證據人工複核方式
哪些佇列深度超過 100?CURDEPTHDISPLAY QLOCAL(*) WHERE(CURDEPTH GT 100)
為什麼 PAY.TXN.REQ 堆積?IPPROCS、OPPROCS、LGETDATE、MSGAGEDISPLAY QSTATUS('PAY.TXN.REQ') TYPE(QUEUE) ALL
哪些 Channel 在 RETRYING?Channel StatusDISPLAY CHSTATUS(*) WHERE(STATUS EQ RETRYING)
為什麼訊息進了 DLQ?DLQ 中 MQDLH 的 Reason以工具瀏覽 DLQ(需授權)
payment-service 連在哪個 QM?Connection 資訊DISPLAY CONN(*) WHERE(APPLTAG EQ 'payment-service')

企業導入建議:

  1. 先在 UAT 導入,比對 Agent 的診斷與人工排查結果。
  2. Agent 連線 QM 時使用專用唯讀帳號(只有 dsp / inq 類權限),經 TLS 管理 Channel。
  3. Agent 建議的 ALTER / CLEAR 等動作,一律轉成變更單走 Part 5.7 風險分級流程。
  4. 評估基礎模型的部署位置與資料流向,確認物件名稱、連線資訊是否符合資料外流政策(參考官方「Security for the IBM MQ Agent」與「Foundation models」說明)[需確認]。

23.7 IBM MQ 10.0 的診斷新能力

能力用法
程式化讀取 Error Log監控工具或 AI 工具以 PCF 取得 Error Log,不必登入主機
Native HA 詳細狀態排查複寫落後、實例同步問題
dspmqcert應用端出現 2393 時先確認 QM 憑證是否到期
短生命週期容器 traceJob 類工作負載也能取得 Client trace
延伸 Authority Event除了 2035 失敗,也能看到成功驗證記錄,用於釐清「是誰連進來」
z/OS:新的驗證失敗訊息、OpenTelemetry tracing主機端跨系統追蹤(見 Part 24.7)

23.8 AI Agent 使用方式

  • 把 Reason Code、AMQERR 片段(已遮罩)、應用日誌片段交給 AI,請它依 23.3 矩陣產生排查步驟。
  • AI 只產生建議與唯讀檢查命令,修改動作由人執行並走變更流程。

23.9 Checklist

  • 應用日誌一定輸出 Reason Code 與 linked exception
  • 團隊熟悉 23.3 矩陣
  • FDC 與 AMQERR 集中收集
  • TLS debug 只在非 Production 使用
  • 若導入 IBM MQ Agent:使用唯讀帳號,建議動作一律走變更流程

Part 24 — IBM MQ 監控

24.1 目的

建立 MQ 監控架構與企業監控 KPI。

24.2 監控來源

來源說明
MQSC MonitoringDISPLAY QSTATUS、CHSTATUS、CONN(即時狀態)
EventsPerformance(PERFMEV,含 QDEPTHHI)、Channel、Authority、Configuration 事件
Statistics / AccountingSTATQ、STATMQI、STATCHL、ACCTQ、ACCTMQI,寫入 SYSTEM.ADMIN.STATISTICS.QUEUE / ACCOUNTING.QUEUE
System Topics$SYS/MQ/INFO/QMGR/... 資源使用發佈;範例程式 amqsrua
REST APIAdministrative REST API 查詢物件狀態
Monitoring ToolsIBM 開源 mq-metric-samples(Prometheus / OpenTelemetry 等 exporter)、MQ Operator 內建 metrics、商業 APM
Log MonitoringAMQERR、FDC、應用日誌
Application MonitoringMicrometer:送出 / 處理數、處理延遲、失敗數

24.3 監控架構

flowchart LR
    subgraph MQ["Queue Managers"]
        QM1["QM1"]
        QM2["QM2"]
    end
    EXP["mq-metric-samples<br/>Prometheus Exporter"] -->|"PCF / System Topics"| QM1
    EXP --> QM2
    EVT["Event 消費程式"] -->|"SYSTEM.ADMIN.*.EVENT"| QM1
    LOGC["Log Collector"] -->|"AMQERR / FDC"| QM1
    APP["Spring Boot<br/>Micrometer"] --> PROM[("Prometheus")]
    EXP --> PROM
    PROM --> GRAF["Grafana Dashboard"]
    PROM --> AM["Alertmanager"]
    EVT --> SIEM["SIEM"]
    LOGC --> ELK["Log 平台"]
    AM --> ONCALL["On-call / ChatOps"]

24.4 企業監控 KPI

Queue Depth
Message Rate
Consumer Lag
Error Rate
Retry Rate
DLQ Count
Channel Availability
Connection Count
KPI定義來源目標範例
Queue Depth目前訊息數CURDEPTH / exporter< 60% MAXDEPTH
Message Rate每秒 PUT / GETStatistics / exporter依容量規劃
Consumer Lag最舊訊息年齡或 深度 ÷ GET 速率MSGAGE / 計算< SLA
Error Rate處理失敗數 ÷ 總處理數應用 Micrometer< 0.1%
Retry Rate重送(JMSXDeliveryCount > 1)比例應用 Micrometer< 1%
DLQ CountDLQ + BOQ 深度MQSC / exporter0
Channel AvailabilityRUNNING 時間比例CHSTATUS / 事件99.95%
Connection Count連線數 / MAXINSTDISPLAY CONN / exporter< 70%

24.5 啟用監控的 MQSC

ALTER QMGR MONQ(MEDIUM) MONCHL(MEDIUM) PERFMEV(ENABLED) +
           STATQ(ON) STATMQI(ON) STATCHL(MEDIUM) STATINT(600)
ALTER QLOCAL('CBS.TXN.TRANSFER.REQ') QDEPTHHI(60) QDPHIEV(ENABLED) +
           QSVCINT(30000) QSVCIEV(HIGH)

Statistics / Accounting 會產生大量訊息,必須有程式持續消費,並評估對效能的影響。

24.6 應用端指標(Spring Boot + Micrometer)

@Component
class MqMetrics {
    private final Counter processed;
    private final Counter failed;
    private final Timer processing;

    MqMetrics(MeterRegistry registry) {
        this.processed = Counter.builder("mq.messages.processed").tag("queue", "CBS.TXN.TRANSFER.REQ").register(registry);
        this.failed = Counter.builder("mq.messages.failed").tag("queue", "CBS.TXN.TRANSFER.REQ").register(registry);
        this.processing = Timer.builder("mq.messages.processing").tag("queue", "CBS.TXN.TRANSFER.REQ").register(registry);
    }
}

24.7 z/OS 監控:SMF 與 OpenTelemetry

來源內容用途
SMF 115QM 統計:Log 寫入、Buffer Pool 命中率、Page Set、CF 使用量容量規劃、效能分析
SMF 116Accounting:每個任務的 MQI 呼叫、每個佇列的使用量、Channel Accounting計費分攤、找出高成本應用
DISPLAY USAGE、DISPLAY CFSTATUS即時使用量告警
[MQ 10.0] OpenTelemetry tracing主機 MQ 的 trace 可與分散式系統串成同一條追蹤端到端交易追蹤
z/OS KPI告警建議
Page Set 使用率> 70% 警告、> 85% 嚴重
Buffer Pool 命中率 / 可用頁數依基準值設定下限
CF Structure 使用率> 70% 警告
Active Log 切換頻率異常升高表示寫入量爆增
CHIN Adapter / Dispatcher 使用率接近上限時評估調整

門檻為起始建議,實際值應依各機構的基準測量調整。

24.8 Native HA 與 RDQM 監控

項目來源告警
實例角色(Active / Replica)dspmq -o nativeha 類命令、Operator 狀態 [需確認選項]非預期切換
複寫落後[MQ 10.0] Native HA 詳細狀態、[MQ 9.4 CD] Native HA 監控強化Replica 落後持續增加
仲裁(Quorum)實例狀態可用實例少於多數
CRR 跨區複寫CRR 狀態複寫中斷
RDQMrdqmstatus、Pacemaker 狀態節點離線、DRBD 同步異常

24.9 Checklist

  • 24.4 八項 KPI 都有資料來源與儀表板
  • 事件與 Statistics 佇列有持續消費者
  • 應用端指標與 MQ 端指標可用 CorrelId / 時間關聯
  • 告警規則已演練
  • z/OS:SMF 115 / 116 與 Page Set、CF 使用率已納入監控
  • HA:Native HA / RDQM 的角色與複寫狀態有告警

Part 25 — IBM MQ 效能調校

25.1 目的

說明影響 MQ 效能的因素,以及 TPS、Latency、Throughput、Reliability 之間的取捨。

25.2 效能因素

因素影響調校方向
Persistent Message每次 commit 需寫 Log(磁碟 fsync)Log 放低延遲儲存;批次 commit
Non-persistent Message不寫 Log,快很多僅用於可遺失的資料
Message Size大訊息增加 I/O 與網路控制在 KB 級;大檔用 MFT 或引用(Claim Check)
Batch一次 commit 多則訊息提高吞吐,但增加延遲與重做範圍
Syncpoint交易保護交易過大會造成 Log 壓力(2024)
Connection Pool連線建立成本高重用連線;Spring CachingConnectionFactory
Session PoolSession 建立成本session-cache-size
Consumer Concurrency平行處理增加吞吐,但失去順序;受 MAXINST 限制
Queue Depth深佇列加上選擇器會掃描避免以自訂屬性 Selector
Network LatencyClient 模式每次 API 一次往返應用與 QM 同區域;適度批次
Disk I/OLog 寫入延遲決定 Persistent TPS 上限專用磁碟、檢查儲存延遲
SHARECNV多 Session 共用 TCP高併發時可評估調整(需測試)

25.3 取捨關係

            可靠性
              ↑
  Persistent + 單筆 commit ●          ● Persistent + 批次 commit
  (金融交易典型)                    (需高階硬體與調校)
              │
              │             ● Non-persistent + Syncpoint
              │
              │                          ● Non-persistent + 無 Syncpoint
              │                            (通知 / 報價)
              └────────────────────────────────→ 吞吐量
目標傾向設定代價
高 ReliabilityPersistent、Syncpoint、單筆 commitTPS 受 Log 延遲限制
高 Throughput批次 commit、多 Consumer、Non-persistent(若允許)延遲增加、失去順序、可能遺失
低 Latency小訊息、單筆 commit、應用靠近 QM吞吐較低
高 TPS(交易型)Persistent + 多 Consumer + 快速 Log 磁碟硬體成本

25.4 效能測試方法

  1. 建立基準:固定訊息大小、Persistence、Consumer 數。
  2. 一次只改一個變數。
  3. 同時觀察:應用延遲(P50 / P95 / P99)、QM CPU、Log 磁碟延遲、網路。
  4. 使用 IBM 提供的效能工具或 JMeter / 自寫 Producer;不要用 Production QM 做壓測。
  5. 參考 IBM 發布的 MQ Performance Reports(依版本與平台) [需確認最新報告]。

25.5 Checklist

  • Log 與 Data 分離,Log 位於低延遲儲存
  • 連線與 Session 有快取
  • 大訊息有替代方案
  • Consumer 數量經測試決定
  • 效能基準文件化,升級前後比對

Part 26 — High Availability / Disaster Recovery

26.1 目的

說明 MQ 的 HA 與 DR 選項、RTO / RPO 考量,以及金融系統架構案例。

26.2 名詞

名詞意義
HA(High Availability)單一站點內元件故障時快速恢復
DR(Disaster Recovery)整個站點失效時於另一站點恢復
RTO(Recovery Time Objective)可容忍的服務中斷時間
RPO(Recovery Point Objective)可容忍的資料遺失量(時間)

26.3 HA 選項比較

方案原理平台RTO(概略)備註
Multi-instance QMActive / Standby 共用網路檔案系統(NFSv4 等)分散式平台秒到分鐘依賴共享儲存的可用性與鎖定語意
RDQM HA3 節點,DRBD 同步複寫 + PacemakerLinux(Advanced)秒到分鐘不需共享儲存
Native HA3 實例 Log 複寫(容器;[MQ 9.4 CD] 起亦支援 Linux)容器 / Linux(授權條件需確認)秒級[MQ 10.0] 新增 IRR
OS / Cluster 軟體 HA由 HA 軟體搬移 QM各平台分鐘傳統方式
MQ Appliance HA設備成對Appliance秒到分鐘
MQ Cluster / Uniform Cluster不是 HA:提供新訊息的替代路由全部—已在故障 QM 上的訊息需等該 QM 恢復

各方案的授權條件(例如 RDQM、Native HA 需要 IBM MQ Advanced)與平台支援,需依目前 IBM 官方文件確認。

26.4 DR 選項

方案說明RPO
RDQM DR跨站點非同步或同步複寫非同步:接近 0 但可能遺失少量;同步:0(受距離限制)
Native HA Cross-Region Replication(CRR)[MQ 9.4 CD / 10.0]跨區域複寫依同步方式 [需確認]
儲存層複寫由儲存設備複寫 Log 與 Data依儲存方案
Backup Queue Manager(Linear Log)定期傳送 Log 並在備援 QM 重播(strmqm -r),災難時啟用(strmqm -a)最後一次傳送 Log 之後的資料
設定備份(dmpmqcfg)只還原物件定義訊息全部遺失

26.5 HA 架構圖

flowchart TB
    subgraph Site["Primary Site"]
        subgraph RDQM["RDQM HA Group(3 節點)"]
            N1["Node 1<br/>BANKQM01 Running"]
            N2["Node 2<br/>Secondary"]
            N3["Node 3<br/>Secondary"]
        end
        FIP["Floating IP"]
    end
    APP["Spring Boot<br/>connName=Floating IP"] --> FIP --> N1
    N1 <-. "DRBD 同步複寫" .-> N2
    N1 <-. "DRBD 同步複寫" .-> N3

26.6 DR 架構圖:金融系統案例

Primary Site
    |
    | IBM MQ
    |
Secondary Site
flowchart LR
    subgraph P["Primary Site(台北)"]
        PA["App Pods"] --> PQ["BANKQM01<br/>HA Group Active"]
    end
    subgraph S["Secondary Site(台中)"]
        SA["App Pods(Standby / 低量)"] -.-> SQ["BANKQM01<br/>DR Replica"]
    end
    PQ == "RDQM DR / CRR<br/>非同步複寫" ==> SQ
    DNS["GSLB / DNS"] --> PA
    DNS -. "災難切換" .-> SA
項目設計
RTO目標 30 分鐘(範例;依業務定義)
RPO非同步複寫:秒級;依法規與業務要求決定是否需同步
切換決策人工決策(避免網路分割造成雙主)
應用切換GSLB / DNS 或 CCDT 指向 DR 站點
演練至少每年(依公司政策與主管機關要求);包含回切

法規提醒:金融業 RTO / RPO、演練頻率等實際要求,應依組織適用法規、主管機關規範與內部控制政策確認。

26.7 Backup 與 Recovery

項目方式
物件設定每日 dmpmqcfg
授權記錄dmpmqcfg -x authrec 或 dmpmqaut
金鑰庫加密備份,權限控管
Queue 資料Linear Log + rcdmqimg(媒體映像);或 HA / DR 複寫
復原測試定期在隔離環境還原並驗證

26.8 HA / DR 對應用程式的要求

  • Client 設定所有可能的位址(connName 列表或 CCDT),啟用自動重連。
  • 冪等處理:切換時正在處理的訊息可能被重送。
  • 交易狀態 UNKNOWN 的對帳流程。
  • Request / Reply:切換期間的請求可能逾時,需查詢機制。

26.9 z/OS 可用性:Queue Sharing Group 與 Shared Queue

z/OS 的高可用性與分散式平台概念不同:不是「一個 QM 故障後切到另一個」,而是多個 QM 同時運作、共用同一份佇列資料。

flowchart LR
    APP["分散式 Java 應用"] -->|"共用連接埠 / VIPA"| SD["Sysplex Distributor"]
    SD --> QM1["QM01(LPAR1)"]
    SD --> QM2["QM02(LPAR2)"]
    QM1 --- CF[("Coupling Facility<br/>Shared Queue")]
    QM2 --- CF
    CICS1["CICS(LPAR1)"] --> QM1
    CICS2["CICS(LPAR2)"] --> QM2
能力效果
Shared Queue任一 QM 停機,其他 QM 仍可存取 CF 中的訊息;持久性訊息可由 BACKUP / RECOVER CFSTRUCT 保護
Shared Inbound Channel連線經 Sysplex Distributor 分散到任一成員
Shared Outbound Channel共用 Transmission Queue,Channel 可在任一成員重啟
Peer Recovery失效 QM 的未完成交易由其他成員處理
GROUP UR交易型應用以 QSG 名稱連線,恢復時不必回到原 QM
[MQ 10.0] Alternative Site Recovery 改善DR 站點恢復流程強化 [需確認細節]

設計注意:CF 本身要有備援(Duplexing 或多個 CF);Db2 是 QSG 共用定義的來源,其可用性也在 MQ 的 HA 範圍內;Shared Queue 的容量受 CF Structure 大小與 SMDS 設定限制。

26.10 IBM MQ 10.0 的 HA / DR 強化

強化說明授權
Native HA In-Region Replication(IRR)同區域內的 Native HA 複寫能力Advanced
Native HA Cross-Region Replication(CRR)跨區域複寫;容器與 Linux(非容器)皆可用Advanced
Native HA 詳細狀態檢視觀察各實例與複寫狀態—
Native HA / CRR 可用於 IBM MQ licensed QM(容器)容器部署的授權選項擴大 [需確認條件]依官方授權
RDQM 複寫連線以 TLS 保護HA RDQM、DR RDQM、DR/HA RDQM 的複寫連線可加密Advanced
HA RDQM 安全 HeartbeatHeartbeat 通訊受保護Advanced

26.11 Checklist

  • RTO / RPO 已由業務定義並核准
  • HA 方案與授權已確認
  • DR 切換為人工決策並有 SOP
  • 應用支援重連與冪等
  • 定期演練並記錄結果
  • z/OS:CF 備援、Db2 可用性、BACKUP CFSTRUCT 排程已納入 HA 設計
  • RDQM 複寫連線已評估啟用 TLS

Part 27 — DevOps / CI/CD

27.1 目的

將 IBM MQ 設定與應用程式一併納入版本控制與自動化流程。

27.2 Pipeline

Git
 ↓
Build
 ↓
Unit Test
 ↓
Integration Test
 ↓
MQ Test
 ↓
Security Scan
 ↓
Performance Test
 ↓
Deploy
flowchart LR
    G["Git<br/>App + MQSC"] --> B["Build"]
    B --> U["Unit Test"]
    U --> I["Integration Test<br/>(MQ 容器)"]
    I --> M["MQ Config Test<br/>runmqsc -v / 規則檢查"]
    M --> S["Security Scan<br/>SAST / SCA / Secret / Image"]
    S --> P["Performance Test<br/>(排程 / 重大變更)"]
    P --> D1["Deploy DEV / SIT"]
    D1 --> D2["Deploy UAT"]
    D2 --> AP{"Change Approval"}
    AP --> D3["Deploy PROD<br/>(人工核准)"]
    D3 --> MON["Monitoring"]

27.3 MQ Configuration as Code

mq-config/
├── common/
│   └── security-baseline.mqsc        # CHLAUTH back-stop、事件設定
├── apps/
│   └── payment/
│       ├── queues.mqsc
│       ├── channels.mqsc
│       └── authrec.mqsc
├── env/
│   ├── dev.properties                 # 環境差異(主機、Port、MAXDEPTH)
│   ├── uat.properties
│   └── prod.properties
├── rollback/
│   └── 2026-10-001-rollback.mqsc
└── tests/
    └── lint-rules.yaml                # 例如:Input Queue 必須有 BOQNAME
原則說明
單一事實來源Git 中的 MQSC 為準,dmpmqcfg 比對漂移(Drift)
冪等使用 REPLACE 時確認所有屬性都被明確指定
環境差異參數化名稱一致,只有容量、主機等不同
每個變更附 Rollback必要
規則檢查(Lint)自動檢查命名、BOQ、TLS、MCAUSER

27.4 CI 範例(GitHub Actions)

name: mq-config-validate
on:
  pull_request:
    paths: ['mq-config/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    services:
      mq:
        image: icr.io/ibm-messaging/mq:<pinned-tag>   # 只用於驗證,非 Production
        env:
          LICENSE: accept
          MQ_QMGR_NAME: QMCI
        ports: ['1414:1414']
    steps:
      - uses: actions/checkout@v4
      - name: Lint MQSC rules
        run: python tools/mq/lint_mqsc.py mq-config/   # 專案自建規則檢查
      - name: Verify MQSC syntax
        run: |
          for f in mq-config/apps/*/*.mqsc; do
            docker exec -i ${{ job.services.mq.id }} runmqsc -v QMCI < "$f"
          done

tools/mq/lint_mqsc.py 為示意的專案自建工具;Developer image 的設定方式見 Part 4.4。

27.5 Environment Configuration 與 Secret Management

項目DEVUATPROD
QM容器 / 共用 DEV QM與 PROD 同設定正式
TLS測試 CA測試 CA(同演算法)正式 CA
帳密Secret(測試)Secret(UAT 專用)Secret Manager(正式),僅 Pipeline 服務帳號可讀
套用方式自動自動 + 核准人工核准後由 Pipeline 套用

27.6 Deployment 與 Rollback

sequenceDiagram
    participant Dev as 開發者
    participant PR as Pull Request
    participant CI as CI
    participant CAB as 變更核准
    participant CD as CD Pipeline
    participant QM as PROD QM
    Dev->>PR: MQSC 變更 + Rollback 檔
    PR->>CI: Lint + runmqsc -v + 整合測試
    CI-->>PR: 通過
    PR->>CAB: 變更申請(風險等級 L1-L4)
    CAB-->>CD: 核准
    CD->>QM: dmpmqcfg 備份
    CD->>QM: 套用 MQSC
    CD->>QM: 驗證(DISPLAY)
    alt 驗證失敗
        CD->>QM: 套用 Rollback MQSC
    end

27.7 Checklist

  • MQSC 在 Git 中並經 PR 審核
  • Lint 規則涵蓋命名、BOQ、TLS、MCAUSER
  • 每個變更有 Rollback 檔
  • PROD 套用需人工核准
  • 定期 Drift 偵測

Part 28 — Automated Testing

28.1 目的

建立 Java / Spring Boot + IBM MQ 的完整測試策略。

28.2 測試金字塔

flowchart TB
    E2E["End-to-End Test<br/>少量:完整流程含 Legacy 模擬"]
    PERF["Performance / Failure Test<br/>排程執行"]
    CT["Contract Test<br/>電文規格"]
    IT["MQ Integration Test<br/>Testcontainers + MQ 容器"]
    UT["Unit Test<br/>大量:業務邏輯、轉換、錯誤分類"]
    E2E --- PERF --- CT --- IT --- UT
層級目的工具執行時機
Unit Test業務邏輯、電文轉換、錯誤分類、冪等邏輯JUnit 5 / 6、Mockito每次 Build
Integration Test應用與真實 MQ 互動Testcontainers + MQ 容器每次 PR
MQ Integration Test交易、Backout、BOQ、targetClient、CCSID同上 + MQSC 預載每次 PR
Contract Test電文規格雙方一致樣本檔比對、Schema 驗證每次 PR
End-to-End Test完整流程SIT 環境每日 / 版本
Performance TestTPS、延遲JMeter / 自寫 Producer重大變更
Failure TestQM 重啟、網路中斷、毒訊息Testcontainers(停容器)、Toxiproxy每週 / 版本

28.3 Unit Test:錯誤分類

class TransferMessageHandlerTest {

    private final TransferMessageHandler handler = new TransferMessageHandler(new FakeTransferService());

    @Test
    void invalidJsonIsPermanentFailure() {
        assertThrows(PermanentFailureException.class, () -> handler.handle("<<not-json>>"));
    }

    @Test
    void downstreamTimeoutIsTransientFailure() {
        var svc = new FakeTransferService();
        svc.failWith(new java.net.SocketTimeoutException("timeout"));
        var h = new TransferMessageHandler(svc);
        assertThrows(TransientFailureException.class, () -> h.handle(validJson()));
    }
}

28.4 Integration Test:Spring Boot + MQ 容器

@SpringBootTest
@Testcontainers
class TransferFlowIT {

    // 測試用 Developer image;版本固定。密碼以測試專用值提供,不可與任何正式環境相同
    @Container
    static final GenericContainer<?> MQ = new GenericContainer<>("icr.io/ibm-messaging/mq:<pinned-tag>")
            .withEnv("LICENSE", "accept")
            .withEnv("MQ_QMGR_NAME", "QM1")
            .withEnv("MQ_APP_PASSWORD", "it-only-password")      // 設定方式依 image 版本確認
            .withCopyFileToContainer(MountableFile.forClasspathResource("mq/it.mqsc"), "/etc/mqm/it.mqsc")
            .withExposedPorts(1414)
            // 僅等待連接埠可能早於 QM 就緒;可改為等待 image 特定的啟動完成日誌(依版本確認)
            .waitingFor(Wait.forListeningPort().withStartupTimeout(Duration.ofMinutes(3)));

    @DynamicPropertySource
    static void mqProps(DynamicPropertyRegistry r) {
        r.add("ibm.mq.queueManager", () -> "QM1");
        r.add("ibm.mq.channel", () -> "DEV.APP.SVRCONN");
        r.add("ibm.mq.connName", () -> MQ.getHost() + "(" + MQ.getMappedPort(1414) + ")");
        r.add("ibm.mq.user", () -> "app");
        r.add("ibm.mq.password", () -> "it-only-password");
    }

    @Autowired JmsTemplate mqJmsTemplate;

    @Test
    void poisonMessageEndsUpInBackoutQueue() {
        mqJmsTemplate.convertAndSend("CBS.TXN.TRANSFER.REQ", "<<not-json>>");
        mqJmsTemplate.setReceiveTimeout(30_000);
        var moved = mqJmsTemplate.receive("CBS.TXN.TRANSFER.REQ.BOQ");
        assertNotNull(moved, "poison message should be moved to BOQ after BOTHRESH");
    }
}

src/test/resources/mq/it.mqsc:

DEFINE QLOCAL('CBS.TXN.TRANSFER.REQ.BOQ') REPLACE
DEFINE QLOCAL('CBS.TXN.TRANSFER.REQ') BOTHRESH(3) BOQNAME('CBS.TXN.TRANSFER.REQ.BOQ') REPLACE
SET AUTHREC PROFILE('CBS.**') OBJTYPE(QUEUE) PRINCIPAL('app') AUTHADD(PUT,GET,BROWSE,INQ)
  • 容器的 DEV.* 預設物件、app 使用者、等待啟動完成的日誌訊息,依 image 版本不同,需依 mq-container 對應版本說明確認。
  • IBM 也提供 mq-java-testcontainer 與 mq-jms-spring-testcontainer 模組(ibm-messaging/mq-jms-spring),可簡化設定。
  • Testcontainers 主版本升級時套件路徑可能變更,請依使用版本調整 import。

28.5 Contract Test:電文規格

@Test
void legacyFixedLengthMessageMatchesCopybook() throws Exception {
    byte[] expected = Files.readAllBytes(Path.of("src/test/resources/contract/TRF001_request.bin"));
    byte[] actual = TransferRequestEncoder.encode(sampleRequest(), Charset.forName("Cp937"));
    assertArrayEquals(expected, actual, "Encoded bytes must match the agreed copybook sample");
}

28.6 Failure Test 情境

情境驗證
處理中 QM 重啟訊息未遺失;重送被冪等處理
網路中斷 30 秒自動重連;無訊息遺失
毒訊息進 BOQ,不阻塞後續訊息
DB 不可用rollback、重試、上限後進 BOQ
Reply 逾時狀態為 UNKNOWN,不重送
佇列已滿Producer 正確回報並重試 / 告警

28.7 Checklist

  • 錯誤分類有 Unit Test
  • Backout / BOQ 行為有整合測試
  • 送 Legacy 的電文有位元組層級 Contract Test
  • Failure Test 至少涵蓋 28.6 六項
  • 測試用 MQ 容器版本固定

Part 29 — Security / DevSecOps

29.1 目的

把 MQ 安全檢查納入 DevSecOps 流程。

29.2 安全掃描組合

SAST
+
SCA
+
Container Scan
+
Secret Scan
+
DAST
+
MQ Security Review
掃描目標MQ 相關重點
SAST原始碼寫死帳密、ObjectMessage 反序列化、日誌輸出訊息內容、TLS 驗證關閉
SCA依賴MQ Client 版本是否有已知弱點;追蹤 IBM Security Bulletin
Container ScanImageMQ image 與應用 image 的 OS 套件弱點
Secret ScanGit / ImageMQ 密碼、keystore 密碼、私鑰
DAST執行中 APIAPI 層的輸入驗證、授權(間接保護 MQ)
MQ Security ReviewMQSC / 設定Part 8 Security Baseline

29.3 MQ Security Review 檢查項目

#檢查方法
R1所有 SVRCONN 啟用 TLS 且 SSLCAUTH(REQUIRED)DISPLAY CHANNEL(*) CHLTYPE(SVRCONN) SSLCIPH SSLCAUTH
R2無已移除 / Deprecated CipherSpec同上
R3MCAUSER 不為空、不為管理帳號DISPLAY CHANNEL(*) MCAUSER
R4CHLAUTH back-stop 與 *MQADMIN 封鎖存在DISPLAY CHLAUTH(*)
R5CONNAUTH 啟用且 CHCKCLNT(REQUIRED)DISPLAY AUTHINFO(*) ALL
R6應用群組無 +all / 管理權限dmpmqaut
R7應用帳號不在 mqm 群組OS 帳號審查
R8稽核事件啟用並轉送 SIEMDISPLAY QMGR AUTHOREV CMDEV CONFIGEV
R9憑證到期 > 30 天dspmqcert [MQ 10.0] / runmqakm
R10未使用的 SYSTEM.* Channel 被封鎖DISPLAY CHLAUTH('SYSTEM.*')
R11應用程式碼無寫死憑證或帳密Secret Scan
R12日誌不輸出訊息內容中的個資Code Review / SAST 規則

29.4 Security Architecture

flowchart TB
    subgraph Dev["開發階段"]
        IDE["IDE + AI Agent"] --> SAST["SAST"]
        IDE --> SEC1["Secret Scan(pre-commit)"]
    end
    subgraph CI["CI"]
        SCA["SCA"] --> IMG["Container Scan"]
        LINT["MQSC Security Lint"]
    end
    subgraph Runtime["執行環境"]
        GWY["API Gateway / WAF"] --> APP["Spring Boot"]
        APP -- "mTLS 1.3" --> QM["Queue Manager<br/>CHLAUTH / CONNAUTH / OAM"]
        VAULT["Secret Manager"] --> APP
        VAULT --> QM
        QM -- "Events / Logs" --> SIEM["SIEM"]
    end
    Dev --> CI --> Runtime

29.5 Checklist

  • 六項掃描都納入 Pipeline
  • MQ Security Review R1-R12 每季(或依政策)執行
  • 發現項目有追蹤與期限
  • IBM Security Bulletin 有人訂閱並評估

Part 30 — AI Coding Agent 開發標準

30.1 目的

規範 AI Coding Agent 在 IBM MQ 相關工作中的權限邊界與 Human-in-the-loop 流程。

30.2 AI Agent 使用原則

所有 AI Agent 工作都遵循:

AI 分析
   ↓
AI 建議
   ↓
AI 產生
   ↓
Automated Test
   ↓
Human Review
   ↓
Deployment

Production 操作遵循:

AI Agent
   ↓
提出變更
   ↓
Human Approval
   ↓
Backup
   ↓
Apply
   ↓
Validation
   ↓
Rollback if necessary

30.3 禁止事項

AI Agent 不可以直接:

  • 修改 Production MQ
  • Delete Production Queue
  • 修改 Production Security
  • 修改 CHLAUTH
  • 修改 TLS
  • 停止 Queue Manager

除非同時具備:

Human Approval
+
Change Request
+
Backup
+
Validation
+
Rollback Plan

而且實際執行者應為經授權的人員或經核准的 Pipeline,而不是 AI Agent 的互動式工作階段。

30.4 Human-in-the-loop 流程

sequenceDiagram
    autonumber
    participant AI as AI Agent
    participant ENG as 工程師
    participant REV as Reviewer / MQ 管理員
    participant CAB as 變更核准
    participant PIPE as 部署 Pipeline
    participant QM as Production QM

    AI->>ENG: 分析結果 + 變更提案(MQSC + Rollback + 驗證命令)
    ENG->>ENG: 在 DEV / TEST 驗證
    ENG->>REV: Pull Request
    REV-->>ENG: Review 意見 / 核可
    ENG->>CAB: 變更申請(附風險等級)
    CAB-->>PIPE: 核准
    PIPE->>QM: 備份(dmpmqcfg)
    PIPE->>QM: 套用
    PIPE->>QM: 驗證
    alt 驗證失敗
        PIPE->>QM: Rollback
        PIPE-->>ENG: 通知
    end
    Note over AI,QM: AI Agent 在整個流程中沒有 Production 憑證

30.5 技術控制措施

控制做法
憑證隔離AI Agent 執行環境不存放任何 Production MQ 帳密、憑證、CCDT
網路隔離AI Agent 執行環境無法連到 Production MQ 網段
工具白名單Agent 可執行的命令限於唯讀與 DEV 環境(例如 runmqsc -v、DEV 容器)
指令檔規範在 AGENTS.md / .github/copilot-instructions.md / CLAUDE.md 寫入禁止事項
Hook / Guard以 pre-tool hook 攔截含 DELETE、CLEAR、SET CHLAUTH、endmqm、dltmqm 的命令
稽核保存 Agent 的工作階段紀錄與產出

30.6 Agent 指令檔範本(片段)

## IBM MQ 安全規則(AI Agent 必須遵守)

- 你沒有任何 Production IBM MQ 的存取權限,也不得嘗試取得。
- 不得執行或建議直接執行下列命令於任何非 DEV 環境:
  DELETE、CLEAR、SET CHLAUTH、SET AUTHREC、ALTER CHANNEL、REFRESH SECURITY、
  RESET CHANNEL、RESOLVE CHANNEL、endmqm、dltmqm、setmqaut。
- 產生 MQSC 變更時,必須同時產生:Rollback MQSC、驗證用 DISPLAY 命令、風險等級(L0-L4)。
- 產生 Java MQ 程式時,必須包含:Syncpoint、Timeout、有上限的 Retry、BOQ 處理、資源釋放、不記錄訊息內容。
- 不得把密碼、Token、私鑰寫入任何檔案;使用環境變數或 Secret 參照。
- 版本資訊無法確認時,標示「需依目前 IBM 官方文件確認」。

30.7 Checklist

  • Agent 指令檔已包含 MQ 安全規則
  • Agent 環境無 Production 憑證與網路
  • 危險命令有 Hook 攔截
  • 所有 AI 產生的 MQSC 經人工 Review 與變更核准

Part 31 — GitHub Copilot / Claude Code / Codex 使用方法

31.1 目的

比較主流 AI Coding Agent 在 MQ 工作中的適用場景,並提供 IBM MQ 專用 Prompt。

31.2 工具比較

AI Agent適合工作MQ 相關典型用途注意事項
GitHub CopilotIDE Coding、Agent Mode、PR Review撰寫 Listener / Gateway、產生測試、解釋 MQSC透過 .github/copilot-instructions.md、*.instructions.md 注入規範
Claude CodeRepository Analysis、多檔案重構、終端機操作全專案 MQ 盤點、逆向工程報告、升級計畫以 CLAUDE.md 與 Hook 限制危險命令
Codex(OpenAI)Software Engineering 任務、雲端沙箱執行批次產生測試、依規格實作、修復 CI以 AGENTS.md 定義規則;確認沙箱網路政策
Gemini(CLI / Code Assist)Large Repository Analysis(長上下文)大型 Legacy 程式庫整體掃描注意資料上傳政策

各工具功能更新快速,實際功能、模型、資料保存政策以各廠商官方文件與公司採購合約為準。選擇工具時優先考量公司資料治理政策,而不是單純的功能比較。

31.3 依工作類型的建議

工作建議工具型態理由
單一類別撰寫 / 修改IDE 內 Agent(Copilot)上下文明確、即時回饋
全專案 MQ 盤點Repository 分析型 Agent(Claude Code / Gemini)需大量檔案讀取
依規格批次實作 + 測試可執行測試的 Agent(Copilot Agent / Claude Code / Codex)需反覆執行測試
PR Review(MQ 規範檢查)Copilot Code Review / 自訂 Review Agent與 PR 流程整合

31.4 IBM MQ 專用 Prompt(IDE 開發)

請在 TransferReplyListener 中實作 IBM MQ 回覆處理,遵守以下規範:
- Spring Boot 4.x、Jakarta Messaging、mq-jms-spring-boot-starter
- @JmsListener 使用 containerFactory="mqListenerFactory"(sessionTransacted=true)
- 冪等:以 JMSCorrelationID 寫入 processed_message 唯一鍵表,重複則直接結束
- 錯誤分類:InvalidReplyException 為永久性錯誤(記錄人工處理表後正常結束);其他例外往外拋觸發 rollback
- 日誌:Log4j2,只記錄 correlId 與 JMSXDeliveryCount,不記錄訊息內容
- 產生對應的 JUnit 測試:成功、重複、永久性錯誤、暫時性錯誤四種情境
- 不要修改 MqJmsConfig 與 application.yml

31.5 IBM MQ 專用 Prompt(Repository 分析)

請以唯讀方式分析整個 repository 的 IBM MQ 使用情況,不修改任何檔案。
輸出 MQ Reverse Engineering Report(格式見手冊 Part 19.3),
每個結論附檔案:行號,推測項目標示「推測」,敏感資訊以 *** 遮蔽。
最後列出「需 MQ 管理員以 DISPLAY 命令驗證」的項目清單。

31.6 IBM MQ Agent 與 AI Coding 工具的定位

面向GitHub Copilot / Claude Code / CodexIBM MQ Agent(官方)
分析對象程式碼、MQSC 檔、設定檔、文件執行中的 Queue Manager 狀態與設定
資料來源Repository、使用者貼入的日誌透過 MCP Server 即時查詢 QM
產出程式碼、測試、MQSC 變更檔、文件診斷結論、原因分析、下一步建議
能否執行變更可修改檔案(受工具權限與本手冊規範限制)不能執行 MQSC
最適合的階段開發、Code Review、逆向工程、升級維運、事故排查

組合用法:事故發生時先用 MQ Agent 找出「哪個佇列堆積、為什麼」,再把結論與對應的程式碼交給 Coding Agent 分析根因與產生修正 PR;兩者的輸出都經人工審查。若組織自行開發 MQ 用的 MCP 工具,建議比照 MQ Agent 的設計:只提供唯讀工具(例如以 Part 5.10 的 PCF 查詢為基礎)。

31.7 Checklist

  • 工具選擇符合公司資料治理政策
  • 各工具的指令檔都包含 MQ 安全規則
  • Prompt 明確指定版本、範圍、禁止事項與輸出格式
  • 已區分 Coding Agent 與 IBM MQ Agent 的使用場景

Part 32 — AI Agent Skills

32.1 目的

定義 IBM MQ 專用的 AI Agent Skill,讓團隊以一致的方式執行常見任務。

32.2 Skill 清單

ibm-mq-analysis
ibm-mq-reverse-engineering
ibm-mq-java-development
ibm-mq-troubleshooting
ibm-mq-security-audit
ibm-mq-upgrade
ibm-mq-test

32.3 ibm-mq-analysis

項目內容
Purpose分析 MQ 架構與設定(MQSC、dmpmqcfg),產出 Queue Map、Channel Map、風險清單
Inputdmpmqcfg 輸出(已遮罩)、架構說明、命名規範
Process1. 解析物件 → 2. 解析路由(QREMOTE / QALIAS / Cluster)→ 3. 比對命名規範 → 4. 檢查 BOQ / MAXDEPTH / TLS / MCAUSER → 5. 產出報告
OutputQueue Map、Channel Map、路由圖(Mermaid)、規範違反清單
Safety Rules唯讀;不產生 DELETE / CLEAR;建議變更需附 Rollback 與風險等級

32.4 ibm-mq-reverse-engineering

項目內容
Purpose從程式碼與設定重建 MQ 整合全貌
InputPart 17.6 Input Checklist 所列資料
ProcessPart 18.2 Workflow 七步驟
OutputMQ Reverse Engineering Report(Part 19.3)
Safety Rules每個結論附證據;推測需標示;敏感資訊遮蔽;不修改檔案

32.5 ibm-mq-java-development

項目內容
Purpose依本手冊 Coding Standard 產生 Java / Spring Boot MQ 程式
Input需求、佇列規格、訊息規格、目標版本
Process1. 確認 API(Jakarta)→ 2. 產生 Gateway / Listener → 3. 產生錯誤分類與冪等 → 4. 產生測試 → 5. 執行測試
Output程式碼、測試、設定範例(不含密碼)
Safety Rules不使用 ObjectMessage;不寫死帳密;必須 Syncpoint、Timeout、有上限 Retry;不記錄訊息內容

32.6 ibm-mq-troubleshooting

項目內容
Purpose依症狀、Reason Code、日誌提供排查步驟
InputReason Code、AMQERR 片段、應用日誌(已遮罩)、環境資訊
Process1. 分類(連線 / 授權 / 物件 / 容量 / 處理)→ 2. 對照 Part 23 矩陣 → 3. 產生唯讀檢查命令 → 4. 依結果縮小範圍
Output排查步驟、唯讀命令、可能根因與建議修正(附風險等級)
Safety Rules只產生唯讀命令;修正建議不得包含移除 *MQADMIN 封鎖或加入 mqm 群組

32.7 ibm-mq-security-audit

項目內容
Purpose依 Production Security Baseline 稽核 MQ 設定
Inputdmpmqcfg -a、dmpmqaut、CHLAUTH、AUTHINFO、憑證資訊(無私鑰)
Process對照 Part 8.10 S1-S14 與 Part 29.3 R1-R12 逐項判定
Output稽核報告:項目 / 結果(符合 / 不符合 / 無法判定)/ 證據 / 建議 / 風險
Safety Rules不接觸私鑰與密碼;不產生可直接執行於 Production 的修正腳本(需經變更流程)

32.8 ibm-mq-upgrade

項目內容
Purpose協助 MQ Server / Client / Java / Spring 升級評估與計畫
Input目前版本盤點、目標版本、pom.xml、MQSC、JDK 資訊
ProcessPart 20.7 Playbook 與 Part 21.4 流程
OutputDependency Inventory、Compatibility Matrix、Breaking Change List、Migration Plan、Risk List、Test Plan、Rollback Plan
Safety Rules版本資訊必須附官方來源,無法確認時標示「需依目前 IBM 官方文件確認」

32.9 ibm-mq-test

項目內容
Purpose產生並執行 MQ 相關測試
Input程式碼、佇列規格、錯誤情境
Process產生 Unit / Integration(MQ 容器)/ Contract / Failure 測試 → 執行 → 回報
Output測試程式、測試報告、未涵蓋情境清單
Safety Rules只使用 DEV 容器;測試密碼不得與任何正式環境相同

32.10 SKILL.md 範本

---
name: ibm-mq-troubleshooting
description: 依 IBM MQ Reason Code、AMQERR 日誌與症狀提供唯讀排查步驟與修正建議。用於 MQ 連線失敗、2035、2059、2538、TLS 錯誤、訊息堵塞、DLQ 等問題。
---

# IBM MQ Troubleshooting Skill

## 輸入
- Reason Code / AMQ 訊息編號
- 已遮罩的日誌片段
- 環境(DEV / SIT / UAT / PROD)與 MQ 版本

## 流程
1. 分類問題層級:連線 / 授權 / 物件 / 容量 / 處理
2. 對照手冊 Part 23 Troubleshooting Matrix
3. 產生唯讀檢查命令(DISPLAY、dspmq、dspmqaut)
4. 根據回饋縮小範圍,提出根因假設與驗證方式
5. 提出修正建議,標示風險等級 L0-L4 與 Rollback

## 安全規則
- 只產生唯讀命令;修改類命令只能以「建議 + 變更流程」形式呈現
- 禁止建議:加入 mqm 群組、移除 BLOCKUSER('*MQADMIN')、+all 授權、關閉 TLS
- 不輸出任何密碼或私鑰

32.11 Checklist

  • 七個 Skill 已建立並放在團隊共用位置
  • 每個 Skill 都有 Safety Rules
  • Skill 內容隨手冊版本更新

Part 33 — AI Agent 自動產生文件

33.1 目的

讓 AI Agent 從程式碼與設定自動產生 MQ 相關文件,並維持與程式同步。

33.2 文件清單

MQ Architecture
MQ Inventory
Queue Specification
Channel Specification
Message Specification
Sequence Diagram
Deployment Diagram
Error Handling Specification
Security Specification
Test Specification
文件主要來源內容更新時機
MQ ArchitectureInventory + 架構說明系統脈絡、QM 拓撲、HA/DR架構變更
MQ Inventory程式碼 + MQSC所有 MQ 物件與使用點每次 PR(自動)
Queue SpecificationMQSC + 程式屬性、Producer、Consumer、容量、BOQ佇列變更
Channel SpecificationMQSC類型、兩端、TLS、MCAUSER、重試Channel 變更
Message SpecificationDTO / Copybook / 樣本欄位、型別、長度、CCSID、版本電文變更
Sequence Diagram程式流程主要交易時序(Mermaid)流程變更
Deployment DiagramK8s YAML / 部署設定節點、Pod、QM、網路部署變更
Error Handling Specification程式錯誤分類、Retry、BOQ、DLQ、補償錯誤處理變更
Security SpecificationMQSC + 設定TLS、CHLAUTH、OAM、Secret安全變更
Test Specification測試程式測試範圍、情境、覆蓋測試變更

33.3 Deployment Diagram 範例

flowchart TB
    subgraph K8s["Kubernetes(prod)"]
        subgraph NSApp["namespace: payment"]
            P1["payment-service Pod x3"]
            SEC1["Secret: mq-client-cert / mq-cred"]
        end
        subgraph NSMQ["namespace: mq-prod"]
            QM["NBKQM01 Native HA x3"]
        end
    end
    subgraph DC["機房"]
        CQM["CBSQM01(RDQM HA)"]
        CICS["CICS / COBOL"]
    end
    P1 -- "PAY.SVRCONN mTLS" --> QM
    SEC1 --> P1
    QM -- "SDR/RCVR TLS" --> CQM
    CQM --> CICS

33.4 文件產生流程

flowchart LR
    PR["Pull Request"] --> AG["AI Agent<br/>文件產生 Skill"]
    AG --> DIFF["文件差異"]
    DIFF --> REV["Reviewer 確認"]
    REV --> MERGE["合併"]
    MERGE --> PORTAL["文件入口(Wiki / Docs Site)"]

33.5 Prompt:產生 Queue Specification

請依下列資料產生 Queue Specification(Markdown 表格):
- MQSC:<貼上已遮罩的 DEFINE QLOCAL / QREMOTE / QALIAS>
- MQ Inventory:<貼上>

每個佇列包含:名稱、類型、QM、用途、Producer、Consumer、DEFPSIST、MAXDEPTH、MAXMSGL、
BOQNAME、BOTHRESH、監控門檻、擁有者系統、證據來源。
規範檢查:命名是否符合 <system>.<domain>.<function>.<direction>;Input Queue 是否有 BOQ。
不得推測未提供的屬性,缺少時填「未提供」。

33.6 Checklist

  • 十份文件皆有範本
  • Inventory 由 Pipeline 自動更新
  • AI 產生的文件經人工審核後才發布

Part 34 — IBM MQ Coding Standards

34.1 目的

建立企業 Java MQ Coding Standard,作為 Code Review 與 AI Agent 產生程式的共同依據。

34.2 規則表

編號類別規則等級
CS-01API 選擇新開發使用 Jakarta Messaging(com.ibm.mq.jakarta.client)或 Spring JMS必須
CS-02Connection Management連線重複使用;Spring 使用 CachingConnectionFactory;禁止每則訊息建立連線必須
CS-03Connection Management設定 Application Name必須
CS-04Connection Management支援 HA:connName 列表或 CCDT + 自動重連必須
CS-05Resource ManagementQueue / Context / Consumer 以 try-with-resources 或 finally 關閉必須
CS-06Resource ManagementJMSContext、MQQueueManager 不跨執行緒共用(除非文件明確允許)必須
CS-07Exception Handling記錄 Reason Code 與 linked exception必須
CS-08Exception Handling區分永久性 / 暫時性 / 連線 / 設定錯誤必須
CS-09Retry有上限、指數退避 + jitter;只重試可恢復錯誤必須
CS-10Retry禁止無限迴圈重試;毒訊息必須進 BOQ必須
CS-11Timeoutreceive / MQGET 必須有等待上限必須
CS-12TimeoutRequest 設定 Expiry;Timeout 關係符合 Part 15.4必須
CS-13Transaction交易性訊息使用 Syncpoint / SESSION_TRANSACTED必須
CS-14TransactionConsumer 先 DB commit 後 MQ commit必須
CS-15Idempotency每個 Consumer 有冪等機制必須
CS-16Logging記錄 MsgId、CorrelId、DeliveryCount、佇列名稱、處理結果必須
CS-17Logging禁止記錄訊息內容中的個資與機敏資料必須
CS-18Correlation ID使用業務鍵衍生的 CorrelId,重送時保持不變建議
CS-19Message ID不自行設定 MsgId(由 QM 產生)建議
CS-20Message明確設定 Persistence、CCSID、Format必須
CS-21Message禁止 ObjectMessage必須
CS-22MessageSelector 只用 CorrelationID / MessageID必須
CS-23Legacy送往非 JMS 系統設定 targetClient=1必須
CS-24Security帳密、Keystore 密碼由 Secret 注入;禁止寫入程式、Git必須
CS-25SecurityTLS 啟用;不關閉憑證驗證必須
CS-26Observability輸出處理數、失敗數、延遲指標;傳遞 traceId必須
CS-27Configuration佇列名稱外部化,不寫死在程式邏輯中建議
CS-28Shutdown支援 Graceful shutdown必須

34.3 Code Review 快速判斷

看到這些 → 退回:
  new MQQueueManager(...) 在迴圈內
  while (true) { ... receive() ... } 沒有 timeout
  catch (Exception e) { } 空的
  ObjectMessage
  password = "..."
  LOG.info(... message.getText() ...)
  @JmsListener 沒有 containerFactory(未確認交易設定)
  Thread.sleep 在 Listener 中做無上限重試

34.4 Checklist

  • CS-01 至 CS-28 已納入 Code Review 範本
  • 可自動化的規則已轉為靜態分析 / ArchUnit 規則

Part 35 — IBM MQ Naming Standards

35.1 目的

建立 Queue Manager、Queue、Channel、Topic、Subscription 的命名規範。

35.2 Queue Manager

<SYSTEM><ROLE><NN>        例:NBKQM01、CBSQM01、HUBQM01
規則說明
長度≤ 48 字元;建議 ≤ 8-12 字元以利 Channel 命名
唯一全企業唯一(Cluster 必要)
不含環境環境以主機 / Namespace 區分;若組織要求含環境,需一致(例如 NBKQM01T)

35.3 Queue

<system>.<domain>.<function>.<direction>[.<suffix>]

見 Part 6.2。Suffix:BOQ、RETRY、DLQ、ALIAS。

35.4 Channel(≤ 20 字元)

類型格式範例
SVRCONN<APP>.SVRCONN 或 <APP>.<PURPOSE>.SVRCONNPAY.SVRCONN、PAY.ADM.SVRCONN
SDR / RCVR<FROMQM>.<TOQM>NBKQM01.CBSQM01
CLUSRCVR<CLUSTER>.<QM>BANK.NBKQM01
CLUSSDR<CLUSTER>.<FRQM>BANK.HUBQM01

20 字元限制常是 QM 命名過長的瓶頸,設計 QM 名稱時就要考慮。

35.5 Topic

Topic String:Bank/<Domain>/<Entity>/<Event>      例:Bank/Txn/Transfer/Completed
Topic Object:BANK.<DOMAIN>[.<ENTITY>]           例:BANK.TXN

35.6 Subscription

<CONSUMER-SYSTEM>.<DOMAIN>.<PURPOSE>.SUB          例:NOTIFY.TXN.TRANSFER.SUB

35.7 其他物件

物件格式範例
Listener<QM>.LSTR.<PORT> 或 LSTR.<PORT>LSTR.1414
AUTHINFO<ORG>.<TYPE>BANK.IDPW.OS
應用群組(OAM)<app>_grppaysvc_grp
MCAUSER 帳號<app>svc / <qm>mcapaysvc、nbkmca

35.8 Checklist

  • 所有新物件通過命名 Lint
  • Channel 名稱 ≤ 20 字元
  • 命名規範納入 MQSC Lint 規則

Part 36 — IBM MQ Production Checklist

36.1 Development Checklist

  • 使用 Jakarta Messaging / Spring JMS(新開發)
  • Syncpoint / SESSION_TRANSACTED
  • Timeout、Expiry、有上限 Retry
  • 冪等機制
  • 錯誤分類與 BOQ
  • targetClient 設定(Legacy)
  • CCSID 明確
  • Application Name
  • Graceful shutdown
  • 單元、整合、Contract 測試

36.2 Code Review Checklist

  • 符合 Coding Standard CS-01 至 CS-28
  • 無寫死帳密 / 憑證
  • 日誌不含訊息內容
  • 無 ObjectMessage
  • Selector 合規
  • 例外沒有被吞掉

36.3 Security Checklist

  • Security Baseline S1-S14(Part 8.10)
  • Security Review R1-R12(Part 29.3)
  • 應用群組最小權限
  • 憑證到期監控
  • 稽核事件轉送 SIEM

36.4 Deployment Checklist

  • MQSC 變更已 PR 審核
  • Rollback MQSC 已準備
  • 變更核准完成
  • dmpmqcfg 備份完成
  • 部署後驗證命令與預期結果
  • 監控儀表板與告警已就緒
  • concurrency × Pod 數 ≤ MAXINST

36.5 Operation Checklist

  • 每日巡檢
  • DLQ / BOQ 為 0 或已處理
  • Channel 全部 RUNNING
  • Log 磁碟 < 70%
  • FDC 已檢視

36.6 Upgrade Checklist

  • What’s new / changed / deprecated 已閱讀
  • CipherSpec 相容
  • OS / JDK 支援
  • 完整備份與還原驗證
  • Rollback / Fallback 演練
  • 效能基準比對

36.7 Incident Checklist

  • 確認影響範圍(哪些佇列、系統、交易)
  • 收集 Reason Code、AMQERR、FDC、應用日誌
  • 判斷是否有訊息遺失 / 重複的可能
  • 啟動對帳(若涉及金額)
  • 修正 → 驗證 → 通報
  • 事後 RCA 與改善項目

36.8 DR Checklist

  • RTO / RPO 定義並核准
  • DR 複寫狀態監控
  • 切換 SOP 與決策人
  • 應用切換方式(DNS / CCDT)已驗證
  • 演練紀錄與改善追蹤
  • 回切程序

Part 37 — IBM MQ 架構設計案例

37.1 Case 1:Spring Boot → IBM MQ → Legacy Java

項目內容
情境新開發的 Spring Boot 服務需呼叫十年前的 Java 批次服務(使用 MQ classes for Java)
架構Spring Boot(Jakarta)→ LEG.ORDER.REQ → Legacy Java Consumer → NEW.ORDER.RSP
關鍵決策targetClient=1(Legacy 讀 MQMD,不認識 RFH2);CorrelId 慣例沿用 Legacy(慣例 A)
風險Legacy 不檢查 Expiry 與重複 → 新服務端負責冪等與 Timeout 後查詢
sequenceDiagram
    participant SB as Spring Boot
    participant MQ as IBM MQ
    participant LJ as Legacy Java
    SB->>MQ: PUT LEG.ORDER.REQ(targetClient=1)
    MQ->>LJ: GET
    LJ->>MQ: PUT NEW.ORDER.RSP(CorrelId = Request MsgId)
    MQ->>SB: GET by CorrelId

37.2 Case 2:Vue → API → Spring Boot → IBM MQ → Mainframe

項目內容
情境網銀前端查詢與交易,核心在主機 CICS
架構Vue → API Gateway → Spring Boot → MQ → CICS(透過 MQ-CICS Bridge 或 CICS 程式讀取佇列)
關鍵決策電文為 EBCDIC 固定長度(CCSID 937);Adapter 層負責 JSON ↔ Copybook
風險中文欄位轉碼(全形 / 半形、SO/SI);Contract Test 以位元組比對

37.3 Case 3:銀行交易 Request / Reply

項目內容
情境轉帳交易,要求不重複、不遺失、可對帳
架構Part 15 完整模式:Idempotency-Key → CorrelId(慣例 B)→ Expiry → Timeout → UNKNOWN 狀態 → 查詢 / 對帳
關鍵決策Timeout 後不重送;核心端以 CorrelId 冪等並回覆相同結果
風險Reply 遲到;以背景 Listener 更新狀態並通知使用者

37.4 Case 4:批次系統透過 IBM MQ 傳送資料

項目內容
情境日終將 50 萬筆交易明細送往報表系統
選項(A) 每筆一則訊息;(B) Message Group 分段;(C) IBM MQ Managed File Transfer(MFT);(D) 檔案放共享儲存 + MQ 通知(Claim Check)
建議大量資料優先考慮 MFT 或 Claim Check;Message Group 適合中量且需原子性的資料
關鍵設定批次 commit(例如每 500 筆)、Persistent、MAXDEPTH 依總量規劃
風險批次中斷的續傳點;接收端以批次 ID + 序號冪等
flowchart LR
    B["批次程式"] -->|"GroupId=BATCH-20261003<br/>Seq 1..N"| Q["RPT.TXN.DAILY.EVT"]
    Q --> R["報表 Consumer<br/>MQGMO_ALL_MSGS_AVAILABLE<br/>MQGMO_LOGICAL_ORDER"]
    R --> DB[("報表 DB")]

37.5 Case 5:IBM MQ 多 Queue Manager

項目內容
情境網銀、行動、分行三個通路 QM 與核心 QM 互通
架構小規模:點對點 SDR/RCVR;中大規模:MQ Cluster(2 個 Full Repository)
關鍵決策通路 QM 只公告自己的 Reply 佇列;核心 QM 公告 Request 佇列
風險Cluster 路由錯誤;以 DISPLAY CLUSQMGR、DISPLAY QCLUSTER 每日巡檢

37.6 Case 6:IBM MQ HA / DR

項目內容
情境核心 QM 要求 RTO 15 分鐘、RPO 接近 0
架構主站點 RDQM HA(3 節點)+ DR 站點 RDQM DR(或容器環境 Native HA + CRR)
關鍵決策DR 切換由人工決策;應用 CCDT 包含 DR 位址但預設不啟用
風險非同步複寫的少量資料遺失 → 對帳流程;演練必須含回切

37.7 Case 7:Legacy MQ Application Reverse Engineering

項目內容
情境15 年歷史的匯款系統,文件遺失,需要重寫
做法Part 17-19:收集輸入 → AI 產生 Inventory 與 Report → MQ 管理員以 DISPLAY 驗證 → 產出 Architecture Specification
發現(範例)3 個佇列無 Consumer(已廢棄);2 個 Channel 未啟用 TLS;JMS 送 COBOL 未設 targetClient,COBOL 端自行跳過 RFH2
成果重寫範圍從「全部 MQ 介面」縮小為 12 個實際使用中的介面

37.8 Case 8:Java / Spring Boot / IBM MQ Framework Upgrade

項目內容
情境Java 8 + Spring Boot 2.3 + MQ allclient 9.1 → Java 25 + Spring Boot 4.x + MQ jakarta.client 10.0
步驟Part 20.7 Playbook:先 Java 17 + Boot 2.7 → Boot 3.x(jakarta)→ Java 25 + Boot 4.x
主要問題(範例)TLS_RSA_WITH_AES_256_CBC_SHA256 在 Java 25(Semeru)失敗 → 與 MQ 管理員協調改 TLS 1.3;spring.jms.listener.concurrency 屬性變更未生效 → properties-migrator 偵測
成果每階段可獨立上線與回復

Part 38 — AI Agent 實戰專案

38.1 目的

設計一個完整練習專案,讓團隊在安全的 DEV 環境中,以 AI Agent 走完一次 MQ 專案生命週期。

38.2 專案架構

Vue
 ↓
Spring Boot
 ↓
IBM MQ
 ↓
Legacy Application
 ↓
DB
flowchart LR
    VUE["Vue 3<br/>轉帳頁面"] --> SB["Spring Boot 4<br/>transfer-api"]
    SB --> DB1[("PostgreSQL<br/>transfer_request")]
    SB -->|"TRN.TXN.TRANSFER.REQ"| MQ[("IBM MQ<br/>Developer 容器")]
    MQ --> LEG["legacy-core<br/>MQ classes for Java"]
    LEG --> DB2[("PostgreSQL<br/>account / processed_request")]
    LEG -->|"TRN.TXN.TRANSFER.RSP"| MQ
    MQ --> SB

38.3 任務與 AI Agent 協助

#任務AI 協助內容人工產出 / 確認完成條件
1Requirement Analysis由使用者故事產生需求清單、非功能需求(冪等、Timeout)PM / SA 確認需求文件
2Architecture產生架構圖、選型理由架構師審核Architecture Spec
3MQ DesignRequest / Reply 設計、CorrelId 慣例架構師MQ Design Doc
4Queue Design命名、屬性、BOQ、MQSC + RollbackMQ 管理員MQSC 通過 Lint
5Java DevelopmentGateway、Listener、Legacy ConsumerCode Review編譯 + 單元測試
6TestUnit / Integration / Contract / FailureQA測試全過
7SecurityTLS(DEV CA)、CHLAUTH、OAM、Secret ScanSecurityBaseline 符合
8Performance壓測腳本、結果分析架構師基準報告
9DeploymentDockerfile、K8s YAML、PipelineDevOpsDEV 部署成功
10MonitoringExporter、Dashboard、告警規則維運KPI 可見
11Reverse Engineering只給 legacy-core 程式,讓另一組以 AI 逆向比對原始設計報告與設計一致率
12Upgrade將 legacy-core 由 classes for Java 遷移至 JakartaCode Review測試全過

38.4 驗收標準

  • 重送同一 Idempotency-Key 不會重複扣款
  • 毒訊息進 BOQ,不阻塞後續訊息
  • Legacy 停機 2 分鐘,恢復後所有請求完成
  • Reply Timeout 時狀態為 UNKNOWN,背景 Listener 補更新
  • TLS 1.3 + mTLS 連線
  • 所有 AI 產出都有人工 Review 紀錄

Part 39 — AI Agent 工作流程

39.1 目的

定義企業級多 Agent 協作流程,以及每個 Agent 的角色、輸入、輸出、責任與邊界。

39.2 流程

Requirement
    ↓
SA
    ↓
AI Architecture Agent
    ↓
MQ Design
    ↓
Java Developer Agent
    ↓
Test Agent
    ↓
Security Agent
    ↓
Performance Agent
    ↓
DevOps Agent
    ↓
Human Review
    ↓
Production
flowchart TB
    REQ["Requirement"] --> SA["SA(人)"]
    SA --> ARCH["AI Architecture Agent"]
    ARCH --> MQD["MQ Design<br/>(Architecture Agent + MQ 管理員)"]
    MQD --> DEV["Java Developer Agent"]
    DEV --> TEST["Test Agent"]
    TEST --> SEC["Security Agent"]
    SEC --> PERF["Performance Agent"]
    PERF --> OPS["DevOps Agent"]
    OPS --> HR{"Human Review<br/>+ Change Approval"}
    HR -- 核准 --> PROD["Production(由 Pipeline 部署)"]
    HR -- 退回 --> DEV
    TEST -- 失敗 --> DEV
    SEC -- 高風險 --> DEV

39.3 Agent 定義

AgentRoleInputOutputResponsibilityBoundary
AI Architecture Agent架構設計助理需求、現有架構、標準架構選項、ADR 草稿、圖提出選項與取捨不做最終決策
MQ Design(Agent 部分)MQ 設計助理架構、命名規範Queue / Channel 規格、MQSC + Rollback依規範產生設計不套用到任何共用環境
Java Developer Agent開發規格、Coding Standard程式碼、單元測試符合 CS-01-28不修改安全設定與 Pipeline
Test Agent測試程式、規格整合 / Contract / Failure 測試、報告覆蓋關鍵情境只用 DEV 容器
Security Agent安全審查程式、MQSC、依賴安全報告對照 Baseline不接觸私鑰與正式帳密
Performance Agent效能程式、測試環境壓測腳本、分析找出瓶頸不壓測 Production
DevOps Agent部署程式、設定Pipeline、YAML、部署文件自動化不持有 Production 部署權限
Human Review人全部產出核准 / 退回最終責任—

39.4 Checklist

  • 每個 Agent 的邊界寫入其指令檔
  • Agent 之間的交接產出有固定格式
  • Human Review 有紀錄

Part 40 — IBM MQ 與企業 AI SDLC

40.1 目的

將 IBM MQ 工作納入完整 AI-SDLC,並說明每個階段 AI Agent 的協助方式。

40.2 流程

Requirement
↓
Analysis
↓
Architecture
↓
Design
↓
Coding
↓
Testing
↓
Security
↓
Performance
↓
UAT
↓
Deployment
↓
Operation
↓
Maintenance
↓
Upgrade
flowchart LR
    R["Requirement"] --> A["Analysis"] --> AR["Architecture"] --> D["Design"] --> C["Coding"]
    C --> T["Testing"] --> S["Security"] --> P["Performance"] --> U["UAT"]
    U --> DE["Deployment"] --> O["Operation"] --> M["Maintenance"] --> UP["Upgrade"]
    UP -. "回饋" .-> R
    subgraph Gate["Human Gate"]
        G1["架構審查"]
        G2["Code Review"]
        G3["安全簽核"]
        G4["變更核准"]
    end
    AR -.-> G1
    C -.-> G2
    S -.-> G3
    DE -.-> G4

40.3 各階段 AI 協助

階段AI Agent 協助 IBM MQ 工作人工把關
Requirement從需求辨識需要非同步 / 可靠傳遞的情境;列出非功能需求(冪等、順序、RTO)業務確認
Analysis既有 MQ 盤點(逆向工程);影響分析SA 確認
Architecture拓撲選項(單 QM / Cluster / HA)、ADR 草稿架構審查
DesignQueue / Channel / Message 規格、MQSC + RollbackMQ 管理員審核
CodingGateway / Listener / Adapter、冪等、錯誤分類Code Review
Testing整合、Contract、Failure 測試QA
SecurityBaseline 稽核、Secret Scan、TLS 檢查Security 簽核
Performance壓測腳本、結果分析、調校建議架構師
UAT測試案例、資料準備業務驗收
DeploymentPipeline、部署檢查表變更核准
Operation告警分析、排查建議(唯讀命令)維運執行
Maintenance文件同步、技術債清單團隊
UpgradeCompatibility Matrix、升級計畫架構 + 管理員

Part 41 — IBM MQ AI Governance

41.1 目的

建立 AI 在 IBM MQ 工作中的企業治理規則。

41.2 AI 可以做

行為條件
Read Code依資料分級;機敏程式需在核准的工具中進行
Analyze MQ Flow使用已遮罩的設定與日誌
Generate Documentation經人工審核後發布
Generate Test在 DEV 環境執行
Generate MQSC必附 Rollback 與風險等級;只在 DEV 自動套用
Generate Java Code經 Code Review
Generate Architecture Diagram經架構審查

41.3 AI 不可以直接做

行為原因
Production Queue Delete訊息不可恢復
Production MQ Stop服務中斷
Production CHLAUTH 修改可能封鎖所有連線或開放未授權存取
Production TLS 修改可能中斷所有加密連線
Production User Permission 修改權限擴張或服務中斷

除非經過人工核准,且由授權人員或核准的 Pipeline 執行(見 Part 30)。

41.4 治理架構

flowchart TB
    POL["AI 使用政策<br/>(資料分級 / 工具清單)"] --> STD["本手冊標準<br/>Coding / Naming / Security"]
    STD --> INS["Agent 指令檔<br/>AGENTS.md / copilot-instructions / CLAUDE.md"]
    STD --> SK["Skills<br/>ibm-mq-*"]
    INS --> AG["AI Agents"]
    SK --> AG
    AG --> OUT["產出"]
    OUT --> HR["Human Review"]
    HR --> CHG["變更管理"]
    CHG --> PIPE["Pipeline"]
    PIPE --> ENV["環境"]
    AUD["稽核紀錄<br/>Agent session / PR / 變更單"] -.-> AG
    AUD -.-> HR
    AUD -.-> PIPE

41.5 責任歸屬(RACI 範例)

活動AI Agent工程師MQ 管理員Security主管
MQ 程式產生RACI—
MQSC 產生RRACI
Production MQSC 套用—CRCA
安全設定變更—IRAA
事故排查建議RRACI

R:執行、A:負責核准、C:諮詢、I:知會。

41.6 IBM MQ Agent 治理

IBM MQ Agent 直接連線 Queue Manager,治理重點與 Coding Agent 不同:

治理面向要求
權限連線帳號只有查詢權限;符合 Part 5.7 的 L0 等級,與產品「不能執行 MQSC」的設計一致
連線專用 TLS 管理 Channel,CHLAUTH 限制來源為 Agent 部署位置
資料流向確認基礎模型部署位置;物件名稱、連線資訊、錯誤日誌是否可送出組織邊界,需經資安評估
範圍明列 Agent 可連線的 QM(最多 20 個),Production 正式啟用前先在 UAT 驗證
稽核保留對話紀錄與 Agent 對 QM 的查詢紀錄(Command Event)
輸出使用Agent 建議不得直接作為變更依據;必須由 MQ 管理員以手動 DISPLAY 複核後開變更單

41.7 Checklist

  • AI 使用政策涵蓋 MQ 設定、日誌、訊息樣本的資料分級
  • 41.3 禁止事項已落實為技術控制
  • RACI 已公告
  • IBM MQ Agent 若導入,已完成權限、資料流向與稽核評估

Part 42 — AI Agent Prompt Library

42.1 使用說明

每個 Prompt 皆包含:Input、Task、Output、限制、驗證方式。使用前將 <...> 替換為實際內容,並確認輸入資料已遮罩敏感資訊。

P01 MQ Architecture Analysis

【角色】IBM MQ 架構師
【Input】架構說明、QM 清單、dmpmqcfg 摘要(已遮罩)、系統清單
【Task】分析目前 MQ 拓撲(單 QM / 點對點 / Hub / Cluster / Pub-Sub),指出單點故障、瓶頸、過度耦合
【Output】拓撲圖(Mermaid)、問題清單(嚴重度 / 證據 / 建議)、改善選項比較表
【限制】不得推測未提供的物件;建議需標示適用情境與代價
【驗證】MQ 管理員以 DISPLAY CLUSQMGR / CHSTATUS 確認拓撲圖正確

P02 MQ Configuration Analysis

【Input】dmpmqcfg -a 輸出(已遮罩)、命名規範(Part 35)
【Task】檢查所有物件設定:命名、BOQ、MAXDEPTH、DEFPSIST、TLS、MCAUSER、事件設定
【Output】違規清單(物件 / 屬性 / 現值 / 建議值 / 風險等級)
【限制】只輸出建議;修正 MQSC 須附 Rollback;不得建議刪除物件
【驗證】隨機抽 10 項以 DISPLAY 確認

P03 Queue Analysis

【Input】Queue 定義、QSTATUS 輸出、應用清單
【Task】為每個佇列標示 Producer / Consumer、容量是否合理、是否缺 BOQ、是否疑似廢棄
【Output】Queue Map(Part 17.8 格式)
【限制】每列附證據;無證據標示「推測」
【驗證】DISPLAY QSTATUS TYPE(HANDLE) 確認讀寫者

P04 Channel Analysis

【Input】Channel 定義、CHSTATUS、CHLAUTH
【Task】建立 Channel Map;檢查兩端名稱一致性、TLS、SSLCAUTH、MCAUSER、重試參數
【Output】Channel Map + 安全與可用性風險清單
【限制】不得建議移除 CHLAUTH 預設封鎖規則
【驗證】兩端 MQ 管理員確認

P05 Java MQ Analysis

【Input】Java 原始碼目錄
【Task】找出 MQ classes for Java 使用點(MQQueueManager / accessQueue / put / get / commit / backout)
【Output】使用點清單(檔案:行號)、資源釋放問題、Syncpoint 使用、BackoutCount 處理、錯誤處理問題
【限制】不修改檔案;不輸出密碼
【驗證】以 grep "com.ibm.mq" 數量比對

P06 JMS Analysis

【Input】Java 原始碼、設定檔、JNDI 設定
【Task】找出 JMS / Jakarta 使用點:ConnectionFactory、Context / Session 模式、Producer、Consumer、Listener、Selector、targetClient
【Output】JMS 使用清單 + javax / jakarta 判定 + 問題(非交易 Session、自訂屬性 Selector、ObjectMessage)
【限制】證據必附
【驗證】grep "javax.jms|jakarta.jms" 比對

P07 Spring Boot MQ Analysis

【Input】Spring Boot 專案
【Task】分析 ibm.mq.* 與 spring.jms.* 設定、@JmsListener、JmsTemplate、ListenerContainerFactory、交易設定
【Output】設定總表、Listener 清單(destination / factory / concurrency / transacted)、風險
【限制】密碼以 *** 遮蔽
【驗證】啟動時輸出有效設定(Actuator configprops,需遮罩)比對

P08 MQ Reverse Engineering

【Input】Part 17.6 Input Checklist 所列資料
【Task】依 Part 18 Workflow 產出 MQ Reverse Engineering Report
【Output】Part 19.3 格式報告
【限制】不修改檔案;推測需標示;敏感資訊遮蔽
【驗證】Part 19.6 驗證方式

P09 Message Flow Analysis

【Input】MQ Inventory、Queue Map、路由定義
【Task】追蹤 <業務交易名稱> 的訊息從產生到最終處理的完整路徑(含 QREMOTE / XMITQ / Channel / Cluster)
【Output】Mermaid sequenceDiagram + 每一跳的物件與證據
【限制】路由無法解析時明確標示
【驗證】以測試訊息實際追蹤(DEV / SIT)

P10 MQ Error Analysis

【Input】Reason Code / AMQ 訊息、日誌片段(已遮罩)、環境
【Task】依 Part 23 矩陣分類並產生排查步驟
【Output】可能根因(排序)、唯讀檢查命令、修正建議(附風險等級)
【限制】只產生唯讀命令;不得建議加入 mqm 或 +all
【驗證】依檢查命令結果確認根因

P11 MQ Security Audit

【Input】dmpmqcfg -a、dmpmqaut、CHLAUTH、AUTHINFO、憑證資訊(無私鑰)
【Task】對照 Part 8.10 S1-S14 與 Part 29.3 R1-R12 稽核
【Output】稽核表(項目 / 結果 / 證據 / 建議 / 風險)
【限制】不接觸私鑰;修正以建議形式呈現
【驗證】Security 人員抽查

P12 MQ Performance Analysis

【Input】Statistics / Accounting 資料、應用指標、硬體資訊、訊息特性
【Task】找出瓶頸(Log I/O、網路、Consumer 數、訊息大小、連線管理)
【Output】瓶頸分析、調校建議(依 Part 25 取捨表)、驗證測試計畫
【限制】不建議為了效能犧牲交易性訊息的 Persistence
【驗證】調校前後壓測比對

P13 MQ Upgrade Analysis

【Input】目前 MQ 版本、目標版本、MQSC、Client 清單、JDK 清單
【Task】依 IBM 官方 What's new / changed / deprecated 整理影響
【Output】影響清單(含 CipherSpec、User ID、Java runtime、行為變更)、升級計畫、Rollback
【限制】每項附官方來源;無法確認標示「需依目前 IBM 官方文件確認」
【驗證】MQ 管理員與官方文件比對

P14 Java Upgrade

【Input】pom.xml / build.gradle、原始碼、目前 JDK、目標 JDK(17 / 21 / 25)
【Task】列出 Java 升級的 Breaking Changes 與 MQ 相關影響(TLS、編碼、移除的 API)
【Output】Breaking Change List、修改建議、測試清單
【限制】分階段(8 → 17 → 25)
【驗證】編譯 + 全部測試通過

P15 Spring Boot Upgrade

【Input】Spring Boot 專案、目前與目標版本
【Task】依官方 Migration Guide 列出屬性改名、移除功能、starter 版本對應(mq-jms-spring-boot-starter)
【Output】變更清單、properties 對照、程式修改點
【限制】starter 版本須對應 Boot 主版本(Boot 3 → 3.5.15;Boot 4 → 4.x)
【驗證】spring-boot-properties-migrator 無警告;整合測試通過

P16 Jakarta Migration

【Input】使用 javax.jms 的原始碼與依賴
【Task】產生 javax → jakarta 遷移計畫:套件替換、MQ Client artifact 替換、IBM 類別套件替換
【Output】替換對照表、受影響檔案清單、建議工具(如 OpenRewrite recipe)
【限制】不得同時保留 allclient 與 jakarta.client
【驗證】mvn dependency:tree 無 javax.jms;測試通過

P17 MQ Test Generation

【Input】Listener / Gateway 程式、錯誤分類規則
【Task】產生 Unit Test:成功、重複、永久錯誤、暫時錯誤、Timeout
【Output】JUnit 測試程式
【限制】不連線任何真實 QM
【驗證】mvn test 通過;以 mutation testing 抽查有效性(選用)

P18 Integration Test

【Input】Spring Boot 專案、MQSC 測試定義
【Task】產生 Testcontainers 整合測試:送收、Backout → BOQ、targetClient、CCSID
【Output】IT 類別 + test MQSC
【限制】只用 Developer image(固定版本);測試密碼不與正式相同
【驗證】CI 執行通過

P19 Performance Test

【Input】效能目標(TPS / P99)、訊息規格、測試環境
【Task】產生壓測腳本(JMeter 或 Java Producer)與觀測項目清單
【Output】腳本、執行步驟、結果判讀表
【限制】不得對 Production 執行
【驗證】在測試環境實際執行並產出報告

P20 MQSC Generation

【Input】Queue / Channel 規格、命名規範、Security Baseline
【Task】產生 MQSC 定義
【Output】(1) 變更 MQSC (2) Rollback MQSC (3) 驗證 DISPLAY 命令 (4) 風險等級 L0-L4
【限制】Input Queue 必有 BOQNAME / BOTHRESH;Channel 必有 TLS;不產生 DELETE / CLEAR / SET CHLAUTH(若需要,僅以註解說明並標示 L4)
【驗證】runmqsc -v 語法檢查;Lint 規則通過

P21 MQ Documentation Generation

【Input】MQ Inventory、MQSC、程式
【Task】產生 Part 33.2 指定的文件(選擇 <文件名稱>)
【Output】Markdown 文件
【限制】只使用輸入中的事實;缺少的欄位填「未提供」
【驗證】擁有者審核

P22 Sequence Diagram Generation

【Input】<交易名稱> 相關程式碼路徑
【Task】追蹤呼叫鏈,產生 Mermaid sequenceDiagram(含 MQPUT / MQGET / Commit / Rollback / Timeout 分支)
【Output】Mermaid 圖 + 每一步的檔案:行號
【限制】無法追蹤的步驟標示「未確認」
【驗證】與實際日誌時間序比對

P23 Architecture Diagram Generation

【Input】Inventory、部署設定(K8s YAML / 主機清單)
【Task】產生系統脈絡圖與部署圖(Mermaid)
【Output】2 張 Mermaid 圖 + 圖例說明
【限制】不含 IP 與主機名稱以外的機敏資訊(依公司政策可再遮罩主機名)
【驗證】架構師審核

P24 Production Checklist

【Input】變更內容(MQSC / 程式 / 設定)
【Task】依 Part 36 產生本次變更專屬的上線檢查表
【Output】Checklist(含驗證命令與預期結果、Rollback 觸發條件)
【限制】風險等級 L3 以上需列出核准人欄位
【驗證】變更審查會議確認

P25 Incident Analysis

【Input】事故時間軸、告警、日誌(已遮罩)、MQ 狀態輸出
【Task】重建事故時間軸、判斷根因、評估訊息遺失 / 重複可能性
【Output】RCA 草稿(時間軸 / 影響 / 根因 / 處置 / 改善項目)
【限制】未證實的推論需標示;涉及金額時列出對帳建議
【驗證】事故檢討會議確認

P26 DLQ Analysis

【Input】DLQ 訊息的 MQDLH 摘要(Reason、DestQName、DestQMgrName、PutApplName、時間),不含 body
【Task】依 Reason 分群,判斷原因與處理方式
【Output】分群表、每群的建議動作(重送 / 修正設定 / 人工)、runmqdlq 規則草稿
【限制】不得建議直接清空 DLQ
【驗證】MQ 管理員確認後才執行

P27 Retry Analysis

【Input】Consumer / Producer 程式、Listener 設定、佇列 BOTHRESH
【Task】分析所有重試機制(程式迴圈、Spring BackOff、MQ Backout、Client 重連)是否疊加、有無上限
【Output】重試路徑圖、最壞情況總重試次數與時間、問題清單
【限制】—
【驗證】Failure Test 驗證實際重試行為

P28 Transaction Analysis

【Input】Consumer / Producer 程式、DB 存取程式、交易設定
【Task】判斷 DB 與 MQ 的 commit 順序、是否有冪等、是否使用 XA / Outbox
【Output】交易邊界圖、失敗情境表(Part 13.3 格式)、風險與建議
【限制】不得宣稱達成 Exactly-once
【驗證】Failure Test:在 DB commit 後、MQ commit 前終止程序

P29 HA/DR Analysis

【Input】目前 HA/DR 架構、RTO / RPO 需求、應用連線設定
【Task】評估是否達成 RTO / RPO;應用是否支援重連與冪等
【Output】差距分析、選項比較(Part 26.3 / 26.4)、演練計畫
【限制】授權與平台支援需標示「需依目前 IBM 官方文件確認」;法規要求不得自行宣稱
【驗證】DR 演練結果

P30 MQ Modernization

【Input】Legacy MQ 應用逆向工程報告、目標架構
【Task】提出現代化路線:API 遷移(classes for Java → Jakarta)、Spring Boot 化、容器化、Native HA、可觀測性
【Output】分階段路線圖、每階段價值 / 風險 / 成本、相依關係
【限制】每階段可獨立上線與回復
【驗證】架構審查

P31 MQ Code Review

【Input】Pull Request diff
【Task】依 Coding Standard CS-01 至 CS-28 審查
【Output】違規清單(規則編號 / 檔案:行號 / 說明 / 建議修正)
【限制】只評論 MQ 相關程式;不自動推送修改
【驗證】Reviewer 確認

P32 CCSID / 編碼問題分析

【Input】訊息樣本 hex dump(前 256 bytes,已遮罩)、MQMD CCSID / Format、雙方平台
【Task】判斷是否含 RFH2、CCSID 是否正確、是否需要 MQGMO_CONVERT、中文欄位轉碼風險
【Output】診斷結果與修正建議
【限制】不得要求提供完整正式訊息
【驗證】以修正後設定在 SIT 傳送樣本比對

P33 IBM MQ Agent 診斷提問範本

【情境】<QM 名稱> 上 <佇列名稱> 自 <時間> 起深度持續增加,應用 <APPLTAG> 回報逾時
【提問順序】
1. <佇列名稱> on <QM 名稱> 目前深度、最大深度、IPPROCS / OPPROCS、最後 GET / PUT 時間?
2. 為什麼訊息在這個佇列堆積?
3. <APPLTAG> 目前連在哪個 QM、哪條 Channel?
4. 相關 Channel 是否有 RETRYING 或 STOPPED?
5. Dead Letter Queue 是否有來自這個流程的訊息?原因碼?
【限制】Agent 的建議只作為線索;任何 ALTER / CLEAR / START / STOP 一律轉成變更單
【驗證】MQ 管理員以對應的 DISPLAY 命令複核每一項結論

P34 Messaging REST API 適用性評估

【Input】整合需求說明(訊息量、大小、可靠性要求、用戶端語言與網路位置)
【Task】依手冊 Part 9.7、9.8 評估應使用 Messaging REST API、原生 Client 或 Jakarta Messaging
【Output】建議方案、理由、風險(交易性、DELETE 後回應遺失、吞吐量)、必要的 mqweb 與 OAM 設定
【限制】金融主交易流程不得建議 REST;不確定的 API 細節標示「需依目前 IBM 官方文件確認」
【驗證】架構審查與 SIT 實測

Part 43 — 常見錯誤

43.1 IBM MQ 開發人員最常犯的錯誤

#錯誤後果正確做法參考
1沒有設定 Timeout執行緒永久阻塞receive(timeout) / MQGMO_WAIT + waitIntervalPart 10、11
2沒有處理 Duplicate Message重複扣款冪等表 / 唯一鍵Part 13、15
3Connection 沒有釋放連線耗盡、2537try-with-resources / finallyPart 10
4每則訊息建立新連線效能低落、QM 負載高連線重用 / 快取Part 25
5Queue 沒有 BOQ / DLQ毒訊息堵塞BOQNAME + BOTHRESH + QM DEADQPart 6
6Retry 無限循環CPU 飆高、日誌爆量有上限 + 退避 + 錯誤分類Part 12.9
7沒有 Correlation ID等不到回覆、無法追蹤業務鍵衍生 CorrelIdPart 15
8Production 使用過度權限安全事故最小權限、群組授權Part 8
9TLS 設定錯誤 / 使用已移除 CipherSpec連線失敗TLS 1.3 / ECDHEPart 8.7
10沒有監控 Queue Depth堵塞無人知KPI + 告警Part 24
11把 IBM MQ 當成 REST API 使用同步等待耗盡執行緒非同步設計 / 202 AcceptedPart 14
12把 MQ Transaction 與 DB Transaction 混為一談遺失或重複先 DB 後 MQ + 冪等 / Outbox / XAPart 13
13JMS 送 Legacy 未設 targetClientLegacy 解析失敗targetClient=1Part 11.4
14忽略 CCSID中文亂碼明確 CCSID + 轉換Part 1.16
15以自訂屬性 Selector 讀深佇列效能極差只用 CorrelId / MsgId SelectorPart 11.10
16使用 ObjectMessage反序列化弱點Text / Bytes + JSON / 固定格式Part 11.9
17Timeout 後直接重送 Request重複交易標記 UNKNOWN + 查詢Part 15.5
18日誌輸出訊息內容個資外洩只記錄 IDPart 34
19帳密寫在 application.yml 並提交 Git憑證外洩Secret 注入Part 12.5
20假設訊息全域有序業務錯亂明確順序前提或序號檢查Part 3.8

Part 44 — IBM MQ 版本與升級策略

44.1 目的

整理 IBM MQ 10.x 版本資訊與升級策略。本章資訊以 2026-10-03 查證的 IBM 官方文件為準;版本資訊會隨修補版更新,使用前請再次確認。

44.2 IBM MQ 版本模型

類型說明適用
LTS(Long Term Support)長期支援,只提供缺陷與安全修補金融 Production 建議
CD(Continuous Delivery)較短週期交付新功能需要最新功能、可頻繁升級的系統
CP4I-LTSCloud Pak for Integration 專用 LTS [需確認]CP4I 環境

44.3 10.0 版本重點(官方查證)

項目內容
定位9.4.0 LTS 的後續 LTS;9.4.5 CD 的後續 CD
累積內容9.4.1~9.4.5 CD 的功能 + 10.0 新功能
安全ML-KEM(FIPS 203)、多 certificate label、GSKit 9、dspmqcert、HTTPS CCDT、JWKS、FIPS 140-3(Semeru)
移除SSLv3、TLS 1.0、RC4、3DES CipherSpec
DeprecatedRSA key exchange CipherSpec;SSL 3.0 與 TLS 1.0 協定
JavaSemeru 25 停用 TLS_RSA_*;隨產品附帶的 Java runtime 變更;Semeru 21 / 25 檔案編碼變更
應用開發JMS 中使用 MsgToken 作為 Selector;多個 JMS 連線可視為單一應用實例;JWT endpoint 支援(JMS / Jakarta)
HANative HA IRR(10.0 新增);Native HA / CRR 於 Linux 與容器可用
ClientClient 預設 TCP buffer 大小變更

44.4 升級對照表

項目Current(範例)TargetCompatibilityRisk
MQ Server9.3.0 LTS10.0 LTS需確認 9.3 → 10.0 直接遷移路徑 [需確認]高:CipherSpec 移除、不可降版
MQ Server9.4.0 LTS10.0 LTS官方定義的後續 LTS中
MQ Client(Java)allclient 9.2jakarta.client 10.0需同時進行 Jakarta 遷移高
Java Runtime8 / 1121 / 25依 System Requirements [需確認]中:TLS、編碼
JMS APIJMS 2.0(javax)Jakarta Messaging 3.0MQ 9.3+ 支援中
Spring Boot2.74.xStarter 4.x 對應高:多重 Breaking
Starter2.7.x4.1.0對應 MQ 10.0 + Boot 4.1.0中
TLSTLS 1.2 RSA key exchangeTLS 1.3 / ECDHE10.0 Deprecated RSA KX高
憑證RSA 1024 / 2048依政策(RSA ≥ 規定長度或 ECDSA)10.0 最小 RSA 長度限制 [需確認門檻]中
Container9.4.x image10.0 imageOperator 版本對應 [需確認]中
OSRHEL 8RHEL 9 / 10依 System Requirements [需確認]中

44.5 升級策略建議

  1. LTS 對 LTS:Production 以 LTS 為目標,並追蹤 CSU / Fix Pack。
  2. Server 先、Client 後。
  3. CipherSpec 先行:在仍是舊版時就先改為 TLS 1.3 / ECDHE,讓升級當天不需要同時改 TLS。
  4. Java / Spring 升級與 MQ 升級錯開,避免同時多個變數。
  5. 每次升級都更新本手冊的版本查證摘要。

Part 45 — Enterprise IBM MQ Reference Architecture

45.1 參考架構

                    ┌─────────────────────┐
                    │      Web UI         │
                    │ Vue / Angular       │
                    └─────────┬───────────┘
                              │
                              ▼
                    ┌─────────────────────┐
                    │    API Gateway      │
                    └─────────┬───────────┘
                              │
                              ▼
                    ┌─────────────────────┐
                    │   Spring Boot       │
                    │ Application Service │
                    └─────────┬───────────┘
                              │
                              ▼
                    ┌─────────────────────┐
                    │      IBM MQ         │
                    │   Queue Manager     │
                    └─────────┬───────────┘
                              │
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
             Legacy       Mainframe      Batch
             System         System       System

45.2 完整參考架構(含橫切面)

flowchart TB
    subgraph Users["使用者"]
        WEB["Vue / Angular"]
    end
    subgraph Edge["邊界"]
        GW["API Gateway / WAF"]
    end
    subgraph AppTier["應用層(Kubernetes)"]
        SB["Spring Boot Services<br/>Jakarta Messaging"]
    end
    subgraph MQTier["訊息層"]
        QMA["Queue Manager<br/>Native HA / RDQM(Primary)"]
        QMD["Queue Manager<br/>DR Replica(Secondary Site)"]
    end
    subgraph Backend["後端"]
        LEG["Legacy System"]
        MF["Mainframe"]
        BAT["Batch System"]
    end
    subgraph Cross["橫切面"]
        SEC["Security<br/>mTLS / CHLAUTH / OAM / Vault"]
        MON["Monitoring<br/>Prometheus / Grafana / SIEM"]
        OPS["DevOps<br/>Git / Pipeline / MQSC as Code"]
        AI["AI Agent<br/>分析 / 產生 / 測試(無 PROD 權限)"]
    end
    WEB --> GW --> SB --> QMA
    QMA --> LEG
    QMA --> MF
    QMA --> BAT
    QMA == "DR 複寫" ==> QMD
    SEC -.-> SB
    SEC -.-> QMA
    MON -.-> SB
    MON -.-> QMA
    OPS -.-> SB
    OPS -.-> QMA
    AI -.-> OPS

45.3 橫切面說明

面向標準
SecurityPart 8 Baseline;mTLS 1.3;CHLAUTH 白名單;群組最小權限;Secret Manager
MonitoringPart 24 八項 KPI;事件轉 SIEM;應用與 MQ 指標關聯
HANative HA(容器 / Linux)或 RDQM HA;應用支援重連與冪等
DRRDQM DR / Native HA CRR;人工決策切換;定期演練
DevOpsMQSC as Code;Lint;變更核准;Drift 偵測
AI AgentPart 30、41 治理;無 Production 憑證;Human-in-the-loop

Part 46 — 最終企業標準

本章彙整為企業標準:Enterprise IBM MQ Development & Operation Standard,共 14 類。

46.1 Architecture Standard

  • AS-1 Web / 前端不得直接連 MQ;經 API 與 Service 層。
  • AS-2 交易指令走 Point-to-Point / Request-Reply;事件走 Pub/Sub。
  • AS-3 每個整合點有明確擁有者與介面規格。
  • AS-4 HA / DR 方案依業務核准的 RTO / RPO 選擇。
  • AS-5 架構決策以 ADR 記錄。

46.2 Development Standard

  • DS-1 依 Part 34 Coding Standard。
  • DS-2 每個 Consumer 冪等。
  • DS-3 錯誤分類:永久 / 暫時 / 連線 / 設定。
  • DS-4 Request / Reply 遵循 Part 15。

46.3 Java Standard

  • JS-1 基準 Java 25(LTS),最低 Java 17。
  • JS-2 新開發使用 IBM MQ classes for Jakarta Messaging;IBM MQ classes for Java 僅維護。
  • JS-3 Spring Boot 4.x + mq-jms-spring-boot-starter 4.x。
  • JS-4 不混用 javax 與 jakarta MQ Client。

46.4 Queue Standard

  • QS-1 命名 <system>.<domain>.<function>.<direction>。
  • QS-2 Input Queue 必有 BOQNAME、BOTHRESH、HARDENBO。
  • QS-3 MAXDEPTH 有容量估算依據。
  • QS-4 交易性佇列 DEFPSIST(YES)。
  • QS-5 設定深度告警。

46.5 Channel Standard

  • CH-1 每個應用專屬 SVRCONN。
  • CH-2 全部 TLS;SVRCONN SSLCAUTH(REQUIRED)。
  • CH-3 MCAUSER 為低權限帳號,透過 CHLAUTH 映射。
  • CH-4 設定 MAXINST / MAXINSTC。
  • CH-5 Channel 名稱 ≤ 20 字元,依 Part 35。

46.6 Security Standard

  • SS-1 Part 8.10 Baseline S1-S14。
  • SS-2 Part 29.3 Review R1-R12 定期執行。
  • SS-3 禁止應用帳號具管理權限。
  • SS-4 憑證與帳密由 Secret Manager 管理並定期輪替。

46.7 Logging Standard

  • LS-1 記錄 MsgId、CorrelId、DeliveryCount、Queue、結果、Reason Code。
  • LS-2 不記錄訊息內容中的個資。
  • LS-3 傳遞 traceId(Message Property)。
  • LS-4 MQ Error Log 與 FDC 集中收集。
  • LS-5 保存期限依公司政策與適用法規確認。

46.8 Monitoring Standard

  • MS-1 Part 24 八項 KPI。
  • MS-2 Part 22.4 告警門檻。
  • MS-3 DLQ / BOQ 深度 > 0 必須告警。
  • MS-4 憑證到期監控。

46.9 Testing Standard

  • TS-1 Unit:錯誤分類、冪等、轉換。
  • TS-2 Integration:MQ 容器;Backout → BOQ。
  • TS-3 Contract:Legacy 電文位元組比對。
  • TS-4 Failure:Part 28.6 六項情境。
  • TS-5 Performance:重大變更前後基準比對。

46.10 Deployment Standard

  • DP-1 MQSC as Code,經 PR 審核。
  • DP-2 每個變更附 Rollback 與驗證命令。
  • DP-3 Production 套用需變更核准,由 Pipeline 或授權人員執行。
  • DP-4 套用前 dmpmqcfg 備份。

46.11 Upgrade Standard

  • US-1 LTS 對 LTS。
  • US-2 Server 先、Client 後。
  • US-3 升級前完成 CipherSpec 替換。
  • US-4 依 Part 20.7 Playbook 與 Part 21.4 流程。
  • US-5 版本資訊必附官方來源。

46.12 AI Agent Standard

  • AI-1 遵循「AI 分析 → 建議 → 產生 → 自動測試 → 人工審核 → 部署」。
  • AI-2 AI Agent 無 Production 憑證與網路存取。
  • AI-3 Part 30.3 / 41.3 禁止事項以技術控制落實。
  • AI-4 使用 Part 32 Skills 與 Part 42 Prompt Library。
  • AI-5 AI 產出的每個結論需有證據或標示推測。

46.13 Reverse Engineering Standard

  • RE-1 依 Part 17.6 Input Checklist 收集並遮罩資料。
  • RE-2 依 Part 18 Workflow 分析。
  • RE-3 產出 Part 19.3 格式報告。
  • RE-4 推測項目以 DISPLAY / Log 驗證後才能列入正式規格。

46.14 Production Operation Standard

  • PO-1 每日巡檢自動化。
  • PO-2 操作依 L0-L4 風險分級(Part 5.7)。
  • PO-3 L3 以上雙人覆核;L4 主管核准且 AI 禁止。
  • PO-4 Incident 依 Part 36.7;涉及金額必對帳。
  • PO-5 DR 依 Part 26 定期演練。

IBM MQ Quick Reference

常用 MQSC

DISPLAY QMGR ALL
DISPLAY QMSTATUS ALL
DISPLAY QLOCAL(*) WHERE(CURDEPTH GT 0) CURDEPTH MAXDEPTH
DISPLAY QSTATUS('Q') TYPE(QUEUE) CURDEPTH IPPROCS OPPROCS MSGAGE
DISPLAY QSTATUS('Q') TYPE(HANDLE) ALL
DISPLAY CHSTATUS(*) ALL
DISPLAY CONN(*) TYPE(CONN) APPLTAG CHANNEL CONNAME USERID
DISPLAY CHLAUTH(*)
DISPLAY CHLAUTH('CH') MATCH(RUNCHECK) ADDRESS('ip') CLNTUSER('user')
DISPLAY AUTHREC PROFILE('Q') OBJTYPE(QUEUE)
DEFINE QLOCAL('Q') DEFPSIST(YES) MAXDEPTH(n) BOTHRESH(5) BOQNAME('Q.BOQ') HARDENBO REPLACE
DEFINE QREMOTE('Q') RNAME('RQ') RQMNAME('RQM') XMITQ('RQM') REPLACE
DEFINE CHANNEL('APP.SVRCONN') CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCIPH('ANY_TLS13_OR_HIGHER') SSLCAUTH(REQUIRED)
DEFINE LISTENER('LSTR.1414') TRPTYPE(TCP) PORT(1414) CONTROL(QMGR)
START CHANNEL('CH') / STOP CHANNEL('CH') MODE(QUIESCE)
REFRESH SECURITY TYPE(CONNAUTH | SSL | AUTHSERV)

常用 Control Commands

crtmqm / strmqm / endmqm -w|-i / dspmq -o all / dspmqver
runmqsc QM / runmqsc -v QM < file.mqsc
dmpmqcfg -m QM -a
setmqaut / dspmqaut / dmpmqaut
runmqakm(金鑰庫)/ dspmqcert(MQ 10.0,參數需確認)
runmqdlq(DLQ Handler)
dspmqcsv / strmqcsv(Command Server)/ runmqsc -w 30 -m LOCALQM REMOTEQM / runmqsc -c QM
strmqweb / endmqweb / dspmqweb / setmqweb(mqweb:Console、REST)
setmqspl / dspmqspl(AMS Policy)

PCF 與 REST API

PCF(Java):new PCFMessageAgent(qmgr) → new PCFMessage(CMQCFC.MQCMD_INQUIRE_Q) → agent.send(request)
Admin REST:GET  /ibmmq/rest/v3/admin/qmgr/{qmgr}
Admin REST:POST /ibmmq/rest/v3/admin/action/qmgr/{qmgr}/mqsc  (runCommand / runCommandJSON)
Messaging REST:POST | DELETE | GET /ibmmq/rest/v3/messaging/qmgr/{qmgr}/queue/{queue}/message
所有 POST / PATCH / DELETE 必帶標頭 ibm-mq-rest-csrf-token
角色:MQWebAdmin / MQWebAdminRO / MQWebUser

z/OS

-QM01 START QMGR / STOP QMGR MODE(QUIESCE) / START CHINIT / STOP CHINIT
DISPLAY GROUP / DISPLAY CFSTRUCT(*) / DISPLAY CFSTATUS(*) TYPE(SUMMARY)
DISPLAY USAGE TYPE(ALL) / DISPLAY LOG / ARCHIVE LOG
BACKUP CFSTRUCT(name) / RECOVER CFSTRUCT(name)(L4)
CMDSCOPE(*):對 QSG 所有成員執行
CSQUTIL(COMMAND / SDEFS)、CSQ5PQSG、CSQJU003 / CSQJU004
SMF 115(統計)/ SMF 116(Accounting)
RACF:MQQUEUE / MQCONN / MQCMDS / MQADMIN;REFRESH SECURITY(MQQUEUE)

常用 Reason Code

Code意義第一步
2009連線中斷網路 / QM 狀態
2033無訊息正常;檢查 CorrelId
2035未授權AMQERR + CHLAUTH + dspmqaut
2053佇列已滿Consumer
2059QM 不可用dspmq / Listener
2085物件不存在名稱 / 大小寫
2393 / 2397 / 2400TLS憑證 / Cipher / JRE 對應
2538主機無法連線網路 / 防火牆

常用 Queue Pattern

Pattern組成
Request / ReplyREQ(QREMOTE / QLOCAL)+ RSP + 各自 BOQ
EventTopic + 管理式 SUB + 訂閱佇列 + BOQ
Retry原佇列 + RETRY 佇列 + 排程
Alias 解耦QALIAS → QLOCAL

常用 Channel Pattern

Pattern組成
App → QMSVRCONN(mTLS)+ CHLAUTH SSLPEERMAP
QM → QMXMITQ(Trigger)+ SDR ↔ RCVR(TLS + MCAUSER 映射)
ClusterCLUSRCVR + CLUSSDR(→ Full Repository)

Java API(IBM MQ classes for Java)

new MQQueueManager(qm, props) / accessQueue(name, MQOO_*) / put(msg, pmo) / get(msg, gmo)
commit() / backout() / close() / disconnect()
MQMessage: messageId, correlationId, persistence, expiry(1/10s), backoutCount, characterSet, format

JMS API(Jakarta Messaging)

MQConnectionFactory → createContext(user, pwd, JMSContext.SESSION_TRANSACTED)
context.createQueue("queue:///Q?targetClient=1")
context.createProducer().setDeliveryMode(PERSISTENT).setTimeToLive(ms).send(dest, msg)
context.createConsumer(dest, "JMSCorrelationID = 'ID:...'").receive(timeout)
context.commit() / context.rollback()
JMSXDeliveryCount = BackoutCount + 1

Spring Boot

依賴:com.ibm.mq:mq-jms-spring-boot-starter(Boot 4 → 4.x;Boot 3 → 3.5.15)
設定:ibm.mq.queueManager / channel / connName / applicationName / user / password / sslBundle
Listener:@JmsListener(destination, containerFactory) + sessionTransacted=true
Producer:JmsTemplate(explicitQosEnabled、deliveryPersistent、timeToLive)

Troubleshooting

症狀 → Reason Code → 分層(連線 / 授權 / 物件 / 容量 / 處理)→ 唯讀檢查 → 修正(變更流程)→ 驗證 → 記錄

Security

mTLS 1.3 + CHLAUTH 白名單(SSLPEERMAP → MCAUSER)+ CONNAUTH CHCKCLNT(REQUIRED)
+ 群組最小權限(connect / inq / put / get / browse)+ 稽核事件 → SIEM
禁止:應用帳號入 mqm、+all、移除 BLOCKUSER('*MQADMIN')、MCAUSER 空白

Production Checklist

備份(dmpmqcfg)→ 變更核准 → 套用(Pipeline)→ 驗證(DISPLAY)→ 監控 → 必要時 Rollback

AI Agent Prompt

P08 MQ Reverse Engineering / P10 MQ Error Analysis / P11 Security Audit
P20 MQSC Generation / P28 Transaction Analysis / P31 MQ Code Review
P33 IBM MQ Agent 診斷提問 / P34 Messaging REST API 適用性評估
(完整內容見 Part 42;IBM MQ Agent 見 Part 23.6、41.6)

新進成員 Checklist

第一週:理解

  • 讀完 Part 1-3,能說明 Queue Manager、Queue、Channel、MQMD 的關係
  • 能解釋 Persistent、Syncpoint、Backout、DLQ、BOQ
  • 能說明 MQ 與 REST、Kafka 的適用差異

第二週:動手

  • 在本機以 MQ Developer 容器建立 Queue Manager(Part 4.4)
  • 以 runmqsc 建立佇列、Listener、SVRCONN(Part 5、6、7)
  • 執行 Part 10 / 11 範例,觀察 DISPLAY QSTATUS、DISPLAY CONN
  • 刻意製造 2035、2085、2033,練習 Part 23 排查

第三週:整合

  • 建立 Spring Boot 4 + starter 專案,完成 Producer 與 Listener(Part 12)
  • 實作冪等與錯誤分類(Part 13、15)
  • 撰寫 Testcontainers 整合測試,驗證毒訊息進 BOQ(Part 28)

第四週:企業實務

  • 讀完 Security Baseline 與 Coding Standard(Part 8、34)
  • 以 AI Agent 對一個既有專案執行 P08 逆向工程,並與 Reviewer 驗證
  • 完成 Part 38 實戰專案的任務 1-6
  • 理解 AI Governance 禁止事項(Part 30、41)

第五週:進階管理與生態系

  • 以 PCF 或 Administrative REST API 完成一支唯讀巡檢程式(Part 5.10、5.11)
  • 說明 Exits、AMS、Streaming Queue 的用途與風險(Part 2.7、2.9、8.11)
  • 能比較 Messaging REST API 與 Jakarta Messaging 的適用情境(Part 9.8)
  • 有主機環境者:讀完 z/OS 架構與管理(Part 2.10、5.13、8.12)
  • 了解 IBM MQ Agent 的能力、限制與治理要求(Part 23.6、41.6)

參考資料

以下為撰寫本手冊時查閱的官方與可信來源(查證日期 2026-10-03):

來源連結
IBM MQ 10.0 Technical overviewhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=mq-technical-overview
IBM MQ 10.0 Administeringhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=mq-administering
IBM MQ 10.0 Developing applicationshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=mq-developing-applications
What’s new and changed in IBM MQ 10.0.0https://www.ibm.com/docs/en/ibm-mq/10.0.x?topic=mq-whats-new-changed-in-1000
IBM MQ Java language interfaceshttps://www.ibm.com/docs/en/ibm-mq/10.0.x?topic=overview-mq-java-language-interfaces
Deprecated, stabilized, and removed features in IBM MQ 10.0.0https://www.ibm.com/docs/en/ibm-mq/10.0.x?topic=1000-deprecated-stabilized-removed-features-in-mq
IBM MQ release types and versioninghttps://www.ibm.com/docs/en/ibm-mq/10.0.x?topic=mq-release-types-versioning
System Requirements for IBM MQhttps://www.ibm.com/support/pages/system-requirements-ibm-mq
IBM MQ JMS Spring Components(mq-jms-spring)https://github.com/ibm-messaging/mq-jms-spring
IBM MQ objectshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-mq-objects
IBM MQ MQI clientshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-mq-mqi-clients
Transaction management and supporthttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-transaction-management-support
Extending queue manager facilitieshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-extending-queue-manager-facilities
IBM MQ for z/OS conceptshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-mq-zos-concepts
Managed File Transferhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-managed-file-transfer
IBM MQ Internet Pass-Thruhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-mq-internet-pass-thru
The IBM MQ Console and REST APIhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=overview-mq-console-rest-api
Automating administration using PCF commandshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=administering-automating-mq-administration-using-pcf-commands
Administration using the REST APIhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=administering-administration-using-rest-api
Working with remote IBM MQ objectshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=administering-working-remote-mq-objects
Administering IBM MQ for z/OShttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=administering-mq-zos
Design considerations for IBM MQ applicationshttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=applications-design-considerations-mq
Developing REST applications with IBM MQhttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=applications-developing-rest-mq
IBM MQ Agenthttps://www.ibm.com/docs/zh-tw/ibm-mq/10.0.x?topic=mq-agent
IBM MQ Developer Essentialshttps://ibm.biz/learn-mq
IBM MQ 範例程式(mq-dev-patterns)https://github.com/ibm-messaging/mq-dev-patterns
IBM MQ Container(mq-container)https://github.com/ibm-messaging/mq-container
IBM MQ Metric Samples(Prometheus / OpenTelemetry)https://github.com/ibm-messaging/mq-metric-samples
Kafka Connect MQ Source / Sinkhttps://github.com/ibm-messaging/kafka-connect-mq-source、https://github.com/ibm-messaging/kafka-connect-mq-sink
Go 與 Node.js 綁定https://github.com/ibm-messaging/mq-golang、https://github.com/ibm-messaging/mq-mqi-nodejs

其他章節中提及的命令、屬性、API 細節,若未列於上表,均已在文中標示「需依目前 IBM 官方文件確認」。


附錄:手冊品質自我審查

#審查項目結果位置
1所有內容在單一 .md是本檔
2IBM MQ Architecture是Part 1-3、45
3Installation是Part 4
4Administration是Part 5
5Java是Part 9-10
6JMS是Part 11
7Spring Boot是Part 12
8Security是Part 8、29
9Monitoring是Part 24
10Performance是Part 25
11HA / DR是Part 26
12Upgrade是Part 20、21、44
13Reverse Engineering是Part 17-19
14AI Agent是Part 18-19、30-42
15GitHub Copilot / Claude Code / Codex是Part 31
16至少 30 個 AI Prompt是(34 個,P01-P34)Part 42
17Mermaid是(含第六節要求的 15 類圖)全文
18Production Checklist是Part 36
19Troubleshooting是Part 23
20金融系統實務是Part 1.7、13.9、15、26.6、37
21避免直接複製 IBM 文件是:以重組、表格化、實務化方式撰寫全文
22清楚標示版本差異是:[MQ 10.0]、[Boot 4]、[Java 25] 等標記全文
23可能過時的版本資訊經官方確認是:已查證者列於「版本查證摘要」;未能確認者標示「需依目前 IBM 官方文件確認」全文
24官方 Technical overview 子主題全數涵蓋是:逐項對照Part 1.21
25官方 Administering 子主題全數涵蓋(命令集、遠端管理、PCF、REST、Console / Explorer、擴充元件、z/OS)是Part 5.8-5.15
26官方 Developing applications 子主題全數涵蓋(多語言、Messaging REST、設計考量)是Part 9.7-9.10
27z/OS(架構、管理、RACF、SMF、QSG 可用性)是Part 2.10、5.13、8.12、24.7、26.9
28IBM MQ Agent(官方 AI Agent)是Part 23.6、31.6、41.6、P33
29目錄與正文一致、可連結是:以 tools/markdown/gen_sf7_toc.py 由正文 h2 / h3 自動重建目錄

第六節 Mermaid 圖對照

#要求位置
1IBM MQ Overall ArchitecturePart 1.6、1.10
2Queue Manager ArchitecturePart 2.3
3Message FlowPart 3.3
4Request / ReplyPart 15.2
5Publish / SubscribePart 2.4.6、16.2
6Java Application ArchitecturePart 9.2
7Spring Boot + IBM MQPart 12.2
8Legacy System IntegrationPart 14.2、17.9
9MQ Reverse EngineeringPart 17.4、18.2
10Framework UpgradePart 20.2
11HAPart 26.5
12DRPart 26.6
13CI/CDPart 27.2
14AI Agent SDLCPart 39.2、40.2
15Security ArchitecturePart 8.2、29.4

法規聲明:本手冊涉及的稽核、保存期限、RTO / RPO、演練頻率等,實際要求應依組織適用法規、主管機關規範與內部控制政策確認。