在 JBoss 應用伺服器中部署 Hibernate 應用，需完成 JBoss 安裝、環境變數設定、應用封裝（HAR/WAR）、Hibernate 服務配置（hibernate-service.xml）、資料源設定與啟動參數調整等步驟。本文提供一份完整的實戰部署清單，以 MySQL 為例，協助開發者快速建立生產可用的 JBoss + Hibernate 環境。
JBOSS_HOME 指向 JBoss 安裝目錄假設專案名稱為 myproject，部署路徑為 $JBOSS_HOME/server/default/deploy/myproject.har，目錄結構如下：
myproject.har/
├── myproject.war/ # Web 應用檔案 (JSP、Servlet、lib 等)
├── META-INF/
│ └── hibernate-service.xml # Hibernate 服務配置檔 (關鍵)
└── *.hbm.xml / *.class # Hibernate 映射檔與持久化類別<?xml version="1.0" encoding="UTF-8"?>
<server>
<mbean code="org.jboss.hibernate.jmx.Hibernate" name="jboss.har:service=HibernateFactory">
<!-- JNDI 資料源名稱，需與 JBoss 資料源設定對應 -->
<attribute name="DatasourceName">java:/MySqlDS</attribute>
<!-- 資料庫方言 -->
<attribute name="Dialect">net.sf.hibernate.dialect.MySQLDialect</attribute>
<!-- SessionFactory JNDI 綁定名稱，程式碼中透過此名稱查找 -->
<attribute name="SessionFactoryName">java:/hibernate/HibernateFactory</attribute>
<!-- 快取提供者，此處使用簡單的 Hashtable 實作 -->
<attribute name="CacheProviderClass">net.sf.hibernate.cache.HashtableCacheProvider</attribute>
</mbean>
</server>| 屬性 | 用途 | 注意事項 |
|---|---|---|
| DatasourceName | JNDI 資料源參考 | 需與 *-ds.xml 中 <jndi-name> 一致，前綴 java:/ |
| Dialect | SQL 方言 | MySQL 用 MySQLDialect，Oracle 用 OracleDialect 等 |
| SessionFactoryName | SessionFactory JNDI 名稱 | 程式中用 new InitialContext().lookup("java:/hibernate/HibernateFactory") 取得 |
| CacheProviderClass | 二級快取實作 | 生產環境建議改用 Ehcache、Infinispan 等分散式快取 |
$JBOSS_HOME/docs/examples/jca/mysql-ds.xml<jndi-name>MySqlDS</jndi-name> 與 hibernate-service.xml 中的 DatasourceName 對應（含 java:/ 前綴）$JBOSS_HOME/server/default/deploy/ 目錄<datasources>
<local-tx-datasource>
<jndi-name>MySqlDS</jndi-name>
<connection-url>jdbc:mysql://localhost:3306/mydb</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<user-name>root</user-name>
<password>password</password>
<exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</exception-sorter-class-name>
</local-tx-datasource>
</datasources>執行啟動指令並指定部署配置集：
run.bat -c myproject觀察主控台輸出，確認：
MySqlDS 成功綁定jboss.har:service=HibernateFactory 啟動SessionFactory 綁定至 java:/hibernate/HibernateFactorymyproject.war 部署成功| 現象 | 可能原因 | 解決方向 |
|---|---|---|
| NameNotFoundException: MySqlDS not bound | 資料源未部署或 JNDI 名稱不符 | 檢查 *-ds.xml 部署位置與 jndi-name 拼寫 |
| Dialect not set / Unknown dialect | Dialect 屬性遺漏或類別名稱錯誤 | 補全 Dialect 屬性，確認套件路徑正確 |
| SessionFactory 無法查找 | SessionFactoryName 未綁定或查找名稱錯誤 | 確認 JNDI 名稱一致，檢查程式碼 lookup 字串 |
| ClassNotFoundException: Hibernate 類別 | HAR 封裝遺漏 hibernate3.jar 或相依套件 | 將 Hibernate 核心 JAR 放入 HAR 根目錄或 server/default/lib |
$JBOSS_HOME/server/default/lib/ 共享給所有應用，避免重複封裝hibernate.hbm2ddl.auto=validate 啟動時驗證 Schema 一致性min-pool-size、max-pool-size）於 *-ds.xml 中JBoss 整合 Hibernate 的關鍵在於：HAR 封裝結構正確、hibernate-service.xml 與資料源 *-ds.xml 的 JNDI 名稱精準對應、方言與快取策略恰當選擇。遵循本指南步驟，可快速建立穩定的企業級持久化運行環境。
