这些说明将帮助您将 JIRA 连接到受支持的 MySQL 数据库。

开始之前

  • 检查您的 MySQL 版本是否受支持。请参见支持的平台
  • 如果您要将 JIRA 迁移至另一服务器,请以 XML 备份的形式将数据导出。然后,可以按照切换数据库中所述,将数据从旧数据库转移到新数据库。
  • 如果您打算在同一 MySQL 服务器上设置 Confluence 和 JIRA,请阅读 Confluence MySQL 设置指南,然后将您的 MySQL 服务器配置为适用于 Confluence 以及 JIRA。请注意,Confluence 的要求比 JIRA 的严格,因此您应该将 MySQL 配置为适用于 Confluence。此配置也将适用于 JIRA。
  • 除非您要运行安装向导,否则请在开始之前关闭 JIRA。

本页内容:

1.创建和配置 MySQL 数据库

  1. 创建 JIRA 连接数据库所用的用户(例如,jiradbuser)。
    请记住此数据库用户名,因为后续步骤中配置与此数据库的 JIRA 连接时要使用它。
  2. 创建供 JIRA 存储事务的数据库(例如,jiradb)。此数据库必须具有 UTF8 字符集。在 MySQL 命令客户端中输入以下命令。
    请记住此数据库名称,因为后续步骤中配置与此数据库的 JIRA 连接时要使用它。

    CREATE DATABASE jiradb CHARACTER SET utf8 COLLATE utf8_bin;

    (如果您想将数据库命名为 jiradb)。

  3. 确保用户具有连接到数据库以及创建和填充表格的权限。可通过以下命令提供这些权限 - 
    对于 MySQL 5.5、MySQL 5.6 以及 MySQL 5.7.0 到 MySQL 5.7.5:

    GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,ALTER,INDEX on <JIRADB>.* TO '<USERNAME>'@'<JIRA_SERVER_HOSTNAME>' IDENTIFIED BY '<PASSWORD>';
    flush privileges;

    对于 MySQL 5.7.6 及以上版本,您还必须包含 REFERENCES 权限:

    GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP,REFERENCES,ALTER,INDEX on <JIRADB>.* TO '<USERNAME>'@'<JIRA_SERVER_HOSTNAME>' IDENTIFIED BY '<PASSWORD>';
    flush privileges;

    提示:

    要确认是否成功授予权限,请以 JIRA 数据库用户身份登录数据库服务器,然后运行以下命令:

    SHOW GRANTS FOR <USERNAME>@<JIRA_SERVER_HOSTNAME>;
  4. 编辑 MySQL 服务器中的 my.cnf 文件(Windows 操作系统上是 my.ini)。(请参见 MySQL 选项文件,了解有关编辑 my.cnf 和 my.ini 的详细说明。)
    找到文件中的 [mysqld] 部分,添加或修改以下参数:

    • 将默认存储引擎设置为“InnoDB”:

      [mysqld]
      ...
      default-storage-engine=INNODB
      ...
    • 将 max_allowed_packet 的值指定为至少 256M:

      [mysqld]
      ...
      max_allowed_packet=256M
      ...
    • 对于 MySQL 5.5 及以下版本,将 innodb_log_file_size 的值指定为至少 256M:

      [mysqld]
      ...
      innodb_log_file_size=256M
      ...
      

      注意:对于 MySQL 5.6 及以上版本,这应该至少设置为 2G。

    • 确保 sql_mode 参数未指定 NO_AUTO_VALUE_ON_ZERO

      // remove this if it exists
      sql_mode = NO_AUTO_VALUE_ON_ZERO
  5. 重新启动 MySQL 服务器以使更改生效:

    • 在 Windows 上,使用 Windows 服务管理器重新启动服务。
    • 在 Linux 上:
      • 根据您的设置,运行以下命令之一:“/etc/init.d/mysqld stop”或“/etc/init.d/mysql stop”或“service mysqld stop”。
      • 然后再次运行同一命令,但是将“stop”替换为“start”。

2.将 MySQL JDBC 驱动程序复制到应用服务器

如果您要升级 JIRA 并且要使用推荐的 MySQL 驱动程序(Connector/J JDBC 驱动程序 v5.1),则可以跳过此部分中的说明。JIRA 升级任务会自动将您现有的驱动程序复制到升级后的安装中。

将 MySQL JDBC 驱动程序复制到应用服务器:

  1. 获取 MySQL 驱动程序:
    • 如果要安装 JIRA,请下载推荐的 MySQL 驱动程序 JDBC Connector/J 5.1
      您可以通过选择“Platform Independent”选项来下载 .tar.gz .zip 文件。从压缩文件中提取驱动程序的 jar(例如,mysql-connector-java-5.x.x-bin.jar)。
    • 如果您要升级 JIRA,但不准备使用推荐的 MySQL 驱动程序 (JDBC Connector/J 5.1),则请在升级之前备份 JIRA 安装中的驱动程序。
      此驱动程序位于 <JIRA 安装目录>/lib/ 目录中。
  2. 将 MySQL JDBC 驱动程序 jar 文件复制到新/升级后安装的 <JIRA 安装目录>/lib/ 目录。如果要使用 Windows 安装程序安装 JIRA,您就需要在运行 Windows 安装程序之后、运行安装向导之前执行此步骤。
  3. 重新启动 JIRA/JIRA 服务。
  4. 如果您是在安装 JIRA,请跳过本页面上的其余说明,然后在浏览器中访问 JIRA,以运行安装向导

请注意:

  • 我们建议使用 MySQL 的 Connector/J 驱动程序(以上链接),因为已经有用户报告使用 MySQL 的 Resin JDBC 驱动程序时遇到了问题。

3.将 JIRA 服务器配置为连接到 MySQL 数据库

有两种方法将 JIRA 服务器配置为连接到 MySQL 数据库:

  • 使用 JIRA 安装向导 — 如果您已经安装了 JIRA,并且是首次进行设置,则可以使用此方法。您的设置将被保存到 JIRA 主目录dbconfig.xml 文件中。
  • 使用 JIRA 配置工具 — 如果您有现成的 JIRA 实例,则可以使用此方法。您的设置将被保存到 JIRA 主目录dbconfig.xml 文件中。

每种配置方法的说明

JIRA 安装向导

JIRA 安装向导将在您第一次在浏览器中访问 JIRA 时显示。

  1. 在第一个屏幕“Configure Language and Database”上,将 Database Connection 设置为 My own database
  2. Database Type 设置为 MySQL
  3. 按照以下数据库连接字段部分所示填写字段。
  4. 测试连接并保存。

JIRA 配置工具

  1. 按以下方法运行 JIRA 配置工具:
  2. 导航至 Database 选项卡,然后将 Database type 设置为 MySQL
  3. 按照以下数据库连接字段部分所示填写字段。
  4. 测试连接并保存。
  5. 重新启动 JIRA。

数据库连接字段

安装向导/配置工具dbconfig.xml说明
Hostname

位于 <url> 标签中(以下示例中的粗体文本):
<url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;characterEncoding=UTF8&amp;sessionVariables=storage_engine=InnoDB</url>

安装 MySQL 服务器的机器的名称或 IP 地址。
Port

位于 <url> 标签中(以下示例中的粗体文本):
<url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;characterEncoding=UTF8&amp;sessionVariables=storage_engine=InnoDB</url>

MySQL 服务器将侦听的 TCP/IP 端口。您可以将此字段留空,以使用默认端口。
Database

位于 <url> 标签中(以下示例中的粗体文本):
<url>jdbc:mysql://dbserver:3306/jiradb?useUnicode=true&amp;characterEncoding=UTF8&amp;sessionVariables=storage_engine=InnoDB</url>

您的 MySQL 数据库的名称(JIRA 会将数据保存在其中)。您应该在上述的步骤 1 中进行创建。
Username

位于 <username> 标签中(以下示例中的粗体文本):
<username>jiradbuser</username>

JIRA 用来连接 MySQL 服务器的用户。您应该在上述的步骤 1 中进行创建。
Password位于 <password> 标签中(以下示例中的粗体文本):
<password>jiradbuser</password>
用户密码 — 用于与 MySQL 服务器进行身份验证。

示例 dbconfig.xml 文件

  • 有关以下 dbconfig.xml 文件中以 pool 开头的 <jdbc-datasource/> 子元素的更多信息,请参阅调整数据库连接
  • JIRA 安装向导和数据库配置工具还将会把元素 <validation-query>select 1</validation-query> 添加到此文件中,通常在运行带有默认 MySQL 安装的 JIRA 时需要它。请参见解决连接关闭问题了解更多信息。
  • 以下示例中的数据库 URL 对应 UTF-8 数据库 — 即您的数据库是使用类似于 create database jiradb character set utf8; 这样的命令创建的;如果您在创建数据库时未指定 character set utf8,则当导入数据时,您可能会收到“Data truncation: Data too long for column”这样的错误,或者面临不受支持的字符被损坏的问题。
  • 以下示例中的数据库 URL 包含 sessionVariables=storage_engine=InnoDB 参数。我们强烈推荐添加此参数,以避免数据损坏。
<?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>password</password>
    <pool-min-size>20</pool-min-size>
    <pool-max-size>20</pool-max-size>
    <pool-max-wait>30000</pool-max-wait>
    <pool-max-idle>20</pool-max-idle>
    <pool-remove-abandoned>true</pool-remove-abandoned>
    <pool-remove-abandoned-timeout>300</pool-remove-abandoned-timeout>
 
    <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-test-while-idle>true</pool-test-while-idle>
    <validation-query-timeout>3</validation-query-timeout>
  </jdbc-datasource>
</jira-database-config>

4.启动 JIRA

现在,您应该已经将 JIRA 配置为连接到 MySQL 数据库。下一步就是启动它!

(tick) 恭喜,您现在已经将 JIRA 连接到了 MySQL 数据库。

已知问题和故障排除

  • 权限中的主机名将按照字符串进行比较 - 如果您在 MySQL 中将权限授予主机名(比如 localhost),则随后必须使用相同字符串来将 JIRA 连接到数据库。所以,不能使用 127.0.0.1,即使它解析到同一位置。此错误会产生找不到表格的警告,因为在设置 JIRA 时,JDBC 连接没有权限创建新表格。
  • 连接关闭 — 如果使用带有以下任何之一的 MySQL 数据库,您可能会遇到连接丢失问题(请参见 JRA-15731 了解详情)。请参阅解决连接关闭问题,了解有关如何解决此问题的信息。
    • JIRA 3.13 或以上版本,
    • Tomcat 5 版本 5.5.25 或以上版本;
    • Tomcat 6 版本 6.0.13 或以上版本;
  • 数据库密码的特殊字符 — JIRA 无法解读数据库密码的特殊字符。
  • 使用 InnoDB 存储引擎 — 5.5 之前的 MySQL 服务器版本使用的默认存储引擎是 MyISAM。因此,在版本 5.5 之前的 MySQL 服务器的默认配置上运行的 JIRA 数据库可能会遇到表格创建问题 (JRA-24124),这可能会导致 JIRA 中数据损坏。我们强烈推荐在数据库 URL 中指定 sessionVariables=storage_engine=InnoDB 参数(如上文所述)。这样可确保写入 JIRA MySQL 数据库的表格将使用 InnoDB 存储引擎,它支持 JIRA 所需的“数据库事务”。

  • 二进制日志记录 — 请注意,JIRA 与 MySQL 之间使用“READ-COMMITTED”事务隔离级别,目前仅支持基于行的二进制日志记录。如果您需要 MySQL 的二进制日志记录功能,则必须将 MySQL 的二进制日志记录格式配置为“row-based”。否则,您可能会在 JIRA 创建事务时遇到问题。

  • 4 字节字符  请注意,JIRA 不支持使用 4 字节字符的 MySQL。