您现在的位置：程式碼之家 >> 數據庫知識 > >> MySQL 資料庫 >> MySQL 綜合教學

JIRA 連接 MySQL 數據庫完整配置指南：建庫、驅動、數據源、已知問題規避

編輯：MySQL 綜合教學

JIRA 連接 MySQL 數據庫完整配置指南：建庫、驅動、數據源、已知問題規避

JIRA (Data Center/Server) 官方推薦使用 MySQL 作為後端數據庫。本文匯總官方文檔與實戰經驗，涵蓋 MySQL 版本兼容性、建庫授權、JDBC 驅動部署、三種配置方式、dbconfig.xml 詳解、啟動驗證及五大已知坑點規避方案。

前置條件檢查

MySQL 版本： 查閱 Supported Platforms 確認 JIRA 版本支持的 MySQL 版本（通常 5.6、5.7、8.0）。
遷移場景： 若遷移服務器，先導出 XML 備份，再傳輸數據。
共庫場景： 若同一 MySQL 實例跑 JIRA + Confluence，按 Confluence 更嚴格要求 配置（如 transaction-isolation=READ-COMMITTED），兼容 JIRA。
停止 JIRA： 配置前關閉 JIRA 服務（除運行 Setup Wizard）。

步驟一：創建數據庫與用戶（MySQL 側）

-- 1. 登錄 MySQL
mysql -u root -p

-- 2. 創建用戶 (替換  為 JIRA 應用服務器 IP/主機名)
CREATE USER 'jiradbuser'@'' IDENTIFIED BY 'StrongPass2024!';

-- 3. 創建數據庫：必須指定 utf8 字符集與 utf8_bin 排序規則 (JIRA 強制要求)
CREATE DATABASE jiradb CHARACTER SET utf8 COLLATE utf8_bin;

-- 4. 授權：僅授予 JIRA 所需權限，避免 ALL PRIVILEGES
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX 
ON jiradb.* TO 'jiradbuser'@'' IDENTIFIED BY 'StrongPass2024!';
FLUSH PRIVILEGES;

-- 5. 驗證權限
SHOW GRANTS FOR 'jiradbuser'@'';

關鍵點： CHARACTER SET utf8 COLLATE utf8_bin 是 JIRA 強制要求（區分大小寫排序），utf8mb4 在舊版 JIRA 可能不支援，新版請查閱文檔確認。

步驟二：部署 MySQL JDBC 驅動

推薦驅動： MySQL Connector/J 5.1.x (JDBC 4.0/4.1/4.2)，不要用 Resin 驅動（有已知問題）。
獲取： 官網下載 → 選 Platform Independent → 解壓獲取 mysql-connector-java-5.1.xx-bin.jar。
部署： 複製到 <JIRA_INSTALL_DIR>/lib/ 目錄。
升級場景： 若升級 JIRA 且原使用推薦驅動，升級程序會自動遷移 lib/ 下現有驅動，無需手動操作。
重啟 JIRA： 驅動放置後必須重啟 JIRA 服務加載。

步驟三：配置數據庫連接（三種方式擇一）

方式 1：JIRA Setup Wizard (首次安裝)

瀏覽器訪問 JIRA URL，啟動向導。
Configure Language and Database 頁：
Database Connection → My own database
Database Type → MySQL
填寫連接字段（見下表），Test Connection → Save。

方式 2：JIRA Configuration Tool (現有實例)

# Windows
\bin\config.bat

# Linux/Unix
/bin/config.sh

彈出 GUI → Database 標籤 → Database Type: MySQL → 填寫字段 → Test Connection → Save → 重啟 JIRA。
若報錯 Could not load SWT library，參考官方 KB。

方式 3：手動編輯 `dbconfig.xml` (JIRA WAR / 無 GUI 環境)

文件位置：<JIRA_HOME>/dbconfig.xml (JIRA Home 目錄，非安裝目錄)。

若不存在，創建並貼入模板：

<?xml version="1.0" encoding="UTF-8"?>
<jira-database-config>
  <name>defaultDS</name>
  <delegator-name>default</delegator-name>
  <database-type>mysql</database-type>  <!-- 必須指定，否則建表失敗 -->
  <jdbc-datasource>
    <url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;characterEncoding=UTF8&amp;sessionVariables=storage_engine=InnoDB</url>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <username>jiradbuser</username>
    <password>StrongPass2024!</password>
    <pool-min-size>20</pool-min-size>
    <pool-max-size>20</pool-max-size>
    <pool-max-wait>30000</pool-max-wait>
    <validation-query>select 1</validation-query>
    <min-evictable-idle-time-millis>60000</min-evictable-idle-time-millis>
    <time-between-eviction-runs-millis>300000</time-between-eviction-runs-millis>
    <pool-max-idle>20</pool-max-idle>
    <pool-min-idle>10</pool-min-idle>
  </jdbc-datasource>
</jira-database-config>

XML 轉義： URL 中 & 必須寫作 &。

連接字段詳解

字段	dbconfig.xml 位置	說明
Hostname	`<url>` 中 `jdbc:mysql://dbserver:3306/...`	MySQL 服務器 IP/主機名
Port	`<url>` 中 `...://dbserver:3306/...`	TCP 端口，默認 3306，可留空
Database	`<url>` 中 `.../jiradb?`	步驟一創建的數據庫名
Username	`<username>`	步驟一創建的用戶名
Password	`<password>`	用戶密碼

步驟四：啟動 JIRA 並驗證

啟動 JIRA 服務 / 部署 WAR 包。
觀察日志 <JIRA_HOME>/log/atlassian-jira.log，確認無數據庫連接錯誤。
瀏覽器訪問 JIRA，完成剩餘設置。

⚠️ 五大已知問題與規避方案

問題	現象	根因	解決方案
主機名字符串精確匹配	授權用 `localhost`，JIRA 連 `127.0.0.1` → 找不到表權限錯誤	MySQL 權限表 `Host` 列按字符串精確匹配	授權與連接完全一致：同用 `localhost` 或同用 `127.0.0.1` 或同用具體 IP
連接關閉	長時間空閒後操作報 `Communications link failure`	MySQL 默認 `wait_timeout=8h` 斷開空閒連接，連接池未驗證	1. 連接池配置 `validation-query=select 1` + `test-while-idle=true` 2. MySQL 端 `wait_timeout` 設大於連接池 `min-evictable-idle-time` 3. 參考 Surviving Connection Closures
密碼特殊字符	密碼含 `$`, `%`, `@` 等 → 連接失敗	XML/屬性文件解析轉義問題	官方指引：`dbconfig.xml` 用 `$` 轉義 `$`，或用不含特殊字符的密碼
存儲引擎必須 InnoDB	MySQL 5.5 前默認 MyISAM → JIRA 事務失效、數據損壞	JIRA 需要事務支援	URL 必須帶 `sessionVariables=storage_engine=InnoDB`，或 `my.cnf` 設 `default-storage-engine=InnoDB`
二進制日誌格式	啟用 binlog 且格式為 STATEMENT → 創建 Issue 報錯	JIRA 使用 READ-COMMITTED 隔離級，僅支援 ROW 格式 binlog	`my.cnf` 設 `binlog_format=ROW`
4 字節字符不支援	Emoji/生僻字存儲異常	JIRA 歷史版本不支援 utf8mb4	查閱版本文檔，新版可能已支援，舊版勿存 4 字節字符

總結

JIRA 接入 MySQL 核心路徑：建庫指定 utf8_bin → 授權最小權限 → 部署 Connector/J 5.1 → 三選一配置數據源 (Wizard/Config Tool/dbconfig.xml) → URL 必帶 storage_engine=InnoDB → 啟動驗證 → 規避五大已知坑 (主機名匹配、連接驗證、密碼轉義、InnoDB 強制、ROW binlog)。嚴格遵循此清單，可將數據庫層故障率降至最低。