jira迁移前先备份这3张表

一、先说核心结论：全库dump不够，这三张表才是你的救命稻草

如果你现在正被要求主导一次Jira迁移，或者你已经在深夜对着pg_dump的进度条发呆，我希望你先停下来看完这一节。

做过7年DevOps，参与过14次Jira迁移，从Server到Data Center、从本地到云、从Jira到PingCode，我得出一个反直觉的结论：全库备份不等于安全备份。全库dump能给你一个完整的快照，但当你真的需要从快照里捞出某张特定表的数据来修复一个局部故障时，你会发现dump文件大到你根本不想打开它，而恢复整个库又意味着你要把其他正常数据也一起回滚。

真正在迁移事故中救过我命的，是三张特定类型的表。这不是从Atlassian官方文档里抄来的清单，而是我从两次严重故障里拿教训换来的。第一次故障发生在2019年，一个180人的电商团队从Jira Server 7.x迁移到8.x，迁移完成后所有用户无法登录，许可证校验失败，邮件通知全部停摆。根因是漏了OS_PROPERTYENTRY表里的关键行。第二次发生在2022年，一个使用PingCode替代Jira的金融客户在进行数据迁移前做预演，发现自定义字段全部为空，排查了整整两天才发现是Active Objects表被pg_dump的一个不起眼的参数过滤掉了。

这两次经历让我形成了一个固定的迁移前检查习惯，不管目标平台是Jira的新版本还是PingCode这样的替代方案，以下三类表的数据完整性必须在迁移脚本执行前单独确认：

1. OS_PROPERTYENTRY，系统属性的唯一存储点
2. AO_*系列表，所有插件数据的私有仓库
3. 项目配置核心表组（以permissionscheme和workflowscheme为代表），业务逻辑的骨架

这三类表加起来可能占整个Jira数据库不到5%的体积，却承载了超过80%的"不可重建"数据。Jira的issues可以重新录入，comments可以从邮件里找回来，但权限方案的精确配置、自定义字段的元数据映射、以及系统属性的加密值，这些东西一旦丢失，你基本只能靠记忆和截图来手工重建。

二、第一张表：OS_PROPERTYENTRY，Jira的"记忆神经元"

1. 这张表到底存了什么，为什么单独备份它

OS_PROPERTYENTRY是Jira数据库里最不起眼却最致命的一张表。它的结构极其简单，只有几个字段：ID、ENTITY_NAME、ENTITY_ID、PROPERTY_KEY、PROPERTY_VALUE，但存储的内容直接决定了你的Jira实例能不能正常启动和运行。

具体来说，这张表里存放着：

• 许可证信息（License Key）：包括Jira Software、Service Management等各个产品的许可证。entity_name通常为"jira.properties"，property_key包含"license"字样。这不是简单的明文字符串，而是经过编码的长文本。
• 基础URL（Base URL）：你的Jira访问地址。迁移后如果这个值还是旧地址，所有邮件里的链接都会指向一个不存在的服务器。
• 邮件服务器配置：SMTP主机、端口、用户名、加密密码。注意密码是以加密形式存储的，你无法直接从数据库里读出来，但可以用Jira的API重新设置。
• 系统高级设置：比如附件大小限制、用户会话超时时间、索引语言配置等。这些设置在Jira的UI里散布在至少五个不同的管理页面，但底层全都落在这张表里。
• 集群配置（仅Data Center版）：节点ID、集群锁信息等。

很多运维工程师在迁移时会选择直接用数据库整体dump，然后在新环境恢复。这个操作本身没问题，但问题出在，如果你不是恢复整个库，而是选择性地导入某些表（比如你只想恢复项目和工作项数据），你大概率会漏掉OS_PROPERTYENTRY，因为它看起来跟业务数据毫无关系。

2. 一个让我终生难忘的故障复盘

那是一个周五下午，客户的Jira Server 8.5需要迁移到新服务器，同时升级到8.20版本。按计划，我们用pg_dump做了全库备份，然后把dump文件传输到新服务器进行恢复。整个过程在测试环境跑了一遍，一切正常。但生产环境恢复完成后，出现了三个诡异的现象：

• 所有用户打开Jira登录页面后，页面显示的是Jira的默认欢迎页，而非客户定制的登录页。
• 管理员输入账号密码后，被提示"许可证无效"，但实际上许可证还有半年才到期。
• 已有的邮件通知全部停止，新创建的issue也不会发送任何通知。

排查过程持续了4个小时。我们检查了数据库连接、检查了Jira Home目录、检查了附件文件夹、甚至检查了反向代理配置。最终在一个不起眼的日志条目里发现了线索：

WARN [c.a.j.config.properties.ApplicationProperties]
Could not find property 'jira.baseurl' in database. Using default.

WARN [c.a.j.license.LicenseManager]

License validation failed: No license found for product 'jira-software'

根因是：测试环境的恢复脚本里，我们用的是全库恢复（drop database → create database → 导入dump文件）。但生产环境为了"节省时间"，运维同事选择只恢复他们认为"有业务价值"的表，issues、projects、users相关表。OS_PROPERTYENTRY被判定为"系统内部表"而跳过了。

最后的修复方案是：从源数据库单独导出OS_PROPERTYENTRY表，然后在新数据库里重新导入。整个过程又花了2个小时，因为我们需要仔细比对哪些行是迁移过程中新生成的、哪些是从源库带来的，避免主键冲突。

3. 正确的备份和恢复姿势

基于那次教训，我现在对OS_PROPERTYENTRY的处理有了固定的流程：

备份时：

1. 不要依赖全库dump来覆盖这张表。单独执行一次针对OS_PROPERTYENTRY的导出，生成一个独立的SQL文件。
2. 导出前先用一条SELECT语句确认行数，导出后再对比行数，确保没有遗漏。
3. 如果使用PostgreSQL，注意OS_PROPERTYENTRY在jiraschema下，导出命令需要指定schema：pg_dump -t 'jiraschema."OS_PROPERTYENTRY"'（注意表名在PostgreSQL中是大小写敏感的，必须加双引号）。
4. 如果使用MySQL，直接mysqldump指定表名即可，但要注意字符集设置，OS_PROPERTYENTRY的PROPERTY_VALUE字段可能包含特殊字符。

恢复时：

1. 先恢复OS_PROPERTYENTRY，再恢复其他业务表。这张表的数据是其他功能正常运行的前提。
2. 恢复后立即检查jira.baseurl和许可证相关行，确保值对应的是新环境。
3. 不要直接从旧环境复制所有行。迁移过程中Jira可能会自动生成一些新的系统属性行，无脑覆盖会导致新生成的行丢失。

验证检查清单：

• 管理员能否正常登录？
• 许可证页面是否显示有效？
• 发送一封测试邮件是否成功？
• Base URL是否指向新地址？
• 附件上传大小限制是否正确？

三、第二张表：AO_*系列表，插件的"私人金库"

1. Active Objects是什么，为什么它如此特殊

如果你用过Jira超过半年，你几乎一定会安装插件，不管是用于Scrum看板的增强、自定义字段的扩展、还是自动化规则的实现。而这些插件存储数据的方式，绝大多数都依赖一个叫Active Objects（简称AO）的框架。

Active Objects是Atlassian官方提供的一个ORM框架，让插件开发者可以用Java对象的方式操作数据库，而无需手写SQL。框架会自动在数据库中创建以"AO_"为前缀的表，表名后面跟着一串十六进制哈希值，用来区分不同插件的数据。比如一个用于自定义字段的插件可能会生成AO_60DB5_CUSTOM_FIELD这样的表名，而一个用于时间跟踪的插件生成的可能是AO_82F1A_TIME_ENTRY。

之所以说AO表特殊，有四个原因：

• 表名不可预测：你不是插件开发者的话，几乎不可能提前知道某个插件会创建哪些AO表。而且不同版本的同一个插件，表结构可能完全不同。
• 数据孤立存储：AO表之间没有外键约束指向Jira核心表。它们是完全独立的数据岛。这意味着Jira核心表的备份不会覆盖这些数据。
• 与插件版本强绑定：如果你恢复了一个AO表的数据，但目标环境的插件版本不匹配，插件在启动时会尝试做数据迁移（migration），这个过程可能成功也可能静默失败。
• 部分数据不可重建：比如自定义字段的配置映射，哪个字段在哪个界面上显示、下拉选项的顺序是怎样的，这些信息一旦丢失，你无法从任何Jira界面或API里重新导出。

2. 为什么自定义字段和面板配置会"凭空消失"

2022年我遇到的那个金融客户案例非常典型。他们从Jira迁移到PingCode时，使用了PingCode官方提供的Jira Importer工具。这个工具做得相当完善，它支持用户、项目、工作项的自动映射，还能通过导入日志实时查看迁移进度。但预演阶段发现一个问题：所有自定义字段的值在新系统里都是空的。

排查过程如下：

• 第一步：检查Jira Importer的映射配置。发现用户、项目、标准字段的映射都正确。PingCode的Importer默认会映射Jira的Summary到PingCode的标题、Description到详细描述、Assignee到负责人。这部分没问题。
• 第二步：查看源Jira数据库。在Jira的issue表中，自定义字段的值存储在专门的列中（列名格式为customfield_xxxxx），数据本身是存在的。
• 第三步：问题浮现，Importer在解析自定义字段时，需要同时读取AO表中关于这些字段的元数据定义。元数据告诉Importer：customfield_10001是"客户等级"下拉字段、customfield_10002是"预计收入"数字字段。如果Importer读不到元数据，它就不知道这些列应该映射成什么。
• 第四步：根源确认，在从生产库导出数据到预演环境时，运维为了缩小导出体积，过滤掉了所有AO_开头的表。理由是"这些是插件的数据，我们迁移到PingCode后不需要插件了"。

这个判断在逻辑上是对的，迁移到PingCode后确实不再需要Jira插件。但问题在于，AO表里存储的不只是插件自身的配置，还有通过插件创建的业务元数据。自定义字段虽然在Jira核心表中以列的形式存在，但字段的定义、选项、校验规则全在AO表里。Importer需要这些定义才能正确转换数据。

3. 如何准确定位和备份你的AO表

经过那次教训后，我给自己定了一个铁律：在开始任何迁移操作之前，先跑一遍完整的AO表清单，并逐表确认数据量。

步骤一：获取完整的AO表列表

不同数据库的查询语句略有不同：

PostgreSQL：

SELECT tablename
FROM pg_tables

WHERE schemaname = 'public'

AND tablename LIKE 'AO_%'

ORDER BY tablename;

MySQL：

SELECT TABLE_NAME
FROM INFORMATION_SCHEMA.TABLES

WHERE TABLE_SCHEMA = 'your_jiradb'

AND TABLE_NAME LIKE 'AO_%'

ORDER BY TABLE_NAME;

步骤二：统计每张AO表的行数

这个步骤帮助判断哪些表是真正在使用中的。零行或个位数行的表通常是插件创建后从未被使用过的，备份优先级可以降低。

-- PostgreSQL版本：生成统计脚本
SELECT 'SELECT ''' || tablename || ''' AS table_name, COUNT(*) AS row_count FROM ' || tablename || ' UNION ALL'

FROM pg_tables

WHERE schemaname = 'public' AND tablename LIKE 'AO_%';

步骤三：按优先级分级备份

我一般将AO表分为三个优先级：

• 高优先级（必须单独备份）：行数超过1000的表。这些表里有大量插件业务数据，不可重建。
• 中优先级（包含在全库dump中即可）：行数在100到1000之间的表。
• 低优先级（可以忽略）：空表或行数小于100的表。通常是一些临时缓存或日志表。

步骤四：确认插件版本与数据兼容性

如果你的迁移目标是Jira的新版本，你需要在恢复AO表之前确认插件在新版本中是否可用。一个快速检查方式是：在Atlassian Marketplace查看插件的最新版本兼容性信息，如果插件已经停更且不支持目标Jira版本，那么即使恢复了AO表数据，插件也无法启动，数据也无法被读取。

这种情况下的策略是：

• 如果插件数据只用于展示（如面板插件），可以接受丢失，手动重建面板。
• 如果插件数据是业务流程的一部分（如自定义字段），需要在迁移前找到替代方案，要么升级插件，要么在迁移前通过API将数据导出为通用格式。
• 如果目标是PingCode等替代平台，则需要确认Importer工具是否支持该类型数据的解析。PingCode的Importer对自定义字段、工作项关联、附件等核心数据有良好的支持，但某些小众插件的专有数据可能需要额外的处理脚本。

四、第三张表：项目配置核心表组，你的"业务骨架"比issues更重要

1. 为什么我说项目配置比工单数据更值得优先保护

这一节的观点可能是全文最具争议的，但基于我处理过的多次迁移事故，我坚持这个结论：issue数据和comment数据可以接受部分丢失，但项目配置数据一个bit都不能少。

理由很简单：你丢失了100条issue，用户可以凭记忆和邮件重新创建。但你丢失了一个项目里30个角色、18个权限方案、12个工作流的精确配置，这些配置通常是经过数月甚至数年的迭代才稳定下来的，没有一个人能完整记住所有细节。而重建这些配置的时间，往往远超过重建issues的时间。

Jira的项目配置散布在多张核心表中，我将其统称为"项目配置核心表组"。其中最关键的几张表是：

• project：项目的基本信息（名称、Key、负责人、项目类型）
• permissionscheme：权限方案的顶层定义
• workflowscheme：工作流方案与项目的关联关系
• nodeassociation：一个被严重低估的表，存储了几乎所有实体之间的关联关系（比如哪个工作流方案关联到哪个项目、哪个权限方案用到了哪些具体权限）
• schemepermissions：权限方案里的具体权限条目（哪个角色在哪个项目里可以做什么）
• projectrole 和 projectroleactor：项目角色的定义和成员分配

2. 权限错乱和工作流断裂的真实排查过程

先讲一个具体的故障场景，帮助理解为什么这些表必须作为一个整体来处理。

2021年一个客户在做Jira Data Center的节点扩容时，不小心在数据库层面执行了一次不完整的恢复操作。事故的起因是：DBA在执行一个清理脚本时误删了几个"看起来没用"的表，然后用前一天的备份恢复了这些表。但恢复时只恢复了被删除的那几张表，而且是单独恢复的。

结果是：

• 用户在某个项目里明明有"编辑Issue"的权限，却被提示"你没有权限执行此操作"。
• 一个Scrum项目的看板上，"进行中"列的issue无法被拖拽到"已完成"列。
• 新创建的子任务无法关联到父任务。

排查了整整一天后我们发现：nodeassociation表的自增主键在恢复时与现有数据产生了冲突，导致新恢复的行被赋予了与原数据不同的ID。而schemepermissions表通过nodeassociation的ID来关联权限条目，ID不匹配导致权限查找失败，Jira的默认行为是"找不到匹配权限就拒绝操作"。

这个事故教会我一个重要原则：项目配置表必须作为一个整体来备份和恢复，不能拆开处理。

3. 备份项目配置表组的正确方式

基于以上教训，我现在对项目配置核心表组的备份策略如下：

原则上不做单表导出。这组表之间的外键依赖太紧密，单表导出后恢复时无法保证数据一致性。正确的做法是：

1. 使用数据库的schema级别导出功能，将整个jiraschema（PostgreSQL）或整个Jira数据库（MySQL）的核心表一起导出。
2. 导出时使用--data-only和--disable-triggers参数，确保只导出数据、不导出表结构（表结构应该由Jira安装程序自动创建）。
3. 如果必须做选择性导出（比如数据库太大），至少要保证以下表在同一次事务中导出：project、permissionscheme、schemepermissions、workflowscheme、nodeassociation、projectrole、projectroleactor。

恢复前的必备检查：

• 确认目标环境的Jira版本与源环境一致或更高。
• 确认目标环境中这些表的结构与源环境完全一致（可以通过比对information_schema.columns来验证）。
• 恢复后立即在一个测试项目里验证：创建issue → 编辑issue → 变更状态 → 添加子任务 → 查看权限页面。五个操作全部通过才算验证完成。

五、迁移场景深度拆解：三种情况下的备份策略取舍

1. 场景一：同版本Jira迁移（如更换服务器或扩容）

这是风险最低的迁移场景，因为不存在版本兼容性问题。但正因为风险低，反而容易让人放松警惕。

核心策略：全库dump + 三类表的独立备份双保险。全库dump作为主恢复手段，三类表的独立备份作为应急预案。如果全库恢复成功且验证通过，独立备份文件可以存档备查；如果全库恢复出现问题（比如dump文件损坏），独立备份可以作为最小化恢复的数据源。

注意事项：即使是同版本迁移，也要注意数据库的版本差异。比如从PostgreSQL 9.6迁移到PostgreSQL 14，pg_dump的默认参数可能不同，导致导出的SQL文件在恢复时出现语法错误。建议在迁移前先在目标数据库版本上做一次恢复预演。

时间预算：备份阶段约占总迁移时间的15%-20%。不要在这个阶段省时间。

2. 场景二：跨版本升级（如从Jira 7.x升级到9.x）

这是风险最高的场景。Jira的主版本升级往往伴随着表结构变更、数据迁移脚本的执行、以及插件兼容性的大洗牌。

核心策略：备份的优先级要调整，AO表成为最高优先级。因为跨版本升级时，Jira核心表的变更由Atlassian的升级脚本自动处理，但AO表的升级由各个插件独立负责。如果一个插件没有适配目标Jira版本，它的AO表数据在升级过程中可能被静默丢弃。

执行步骤：

1. 升级前，为所有AO表做独立备份，并记录每个表对应的插件名称和版本。
2. 先在离线环境执行升级，观察哪些插件的AO表在升级后数据正常。
3. 对于数据异常的插件，联系插件厂商确认是否有升级方案。
4. 如果必须放弃某个插件的数据，在升级前通过该插件的导出功能（如果有的话）将数据导出为CSV或JSON，留作日后手工迁移的依据。

3. 场景三：从Jira迁移到替代平台（如PingCode）

这是近年来我处理越来越多的一类需求。很多中国企业出于安全合规（信创适配、私有化部署要求）、成本控制（Jira Server停售后的许可证费用上涨）、或本土化体验（企业微信/飞书/钉钉集成）的考虑，选择将研发管理从Jira迁移到PingCode等国产平台。

这个场景下的备份策略有一个独特的着眼点：你备份的目标不是"将来可能恢复回Jira"，而是"确保迁移工具能读取到所有需要的数据"。

PingCode提供的Jira Importer工具已经相当成熟，支持：

• 用户、项目、工作项、属性的自动映射
• Confluence知识库的大文件批量导入（单页面支持1G）
• 通过导入日志实时查看迁移进程
• 迁移完成后邮件自动通知相关人员

但Importer工具的运行前提是：源Jira数据库的数据是完整的。如果Importer在解析过程中遇到AO表缺失的情况，它不会报错，它会静默地跳过那些无法解析的字段，导致迁移结果看起来"成功"但数据不完整。

这个场景下三类表的备份优先级发生了变化：

1. OS_PROPERTYENTRY：优先级降低。因为迁移目标是PingCode而非Jira，Jira的系统配置（许可证、SMTP等）对PingCode无用。但如果你计划保留Jira作为归档只读系统，这张表仍然需要备份。
2. AO_*表：优先级提高。Importer需要AO表中的元数据来正确解析自定义字段、面板配置等扩展数据。建议在迁移前完整导出所有AO表，并将其与Jira核心数据库放在同一台可访问的服务器上。
3. 项目配置核心表：优先级不变。Importer需要从这些表中读取项目结构、角色分配、工作流状态等信息来重建PingCode中的项目框架。

关于PingCode迁移的一个实操建议：在使用PingCode Importer之前，建议先在源Jira数据库上运行一遍完整的数据导出（全库dump），然后在一个隔离的数据库实例上恢复这个dump，让Importer从这个隔离实例读取数据。这样做有两个好处：一是不影响生产Jira的运行性能；二是如果迁移过程中需要调整数据库参数或重新导出某张表，你不会污染原始生产数据。

六、验证备份完整性：恢复不是终点，验收才是

1. 为什么你自以为备份成功却可能是一场灾难

备份完成只是一个中间状态。真正决定备份价值的，是恢复后的数据完整性。我在咨询工作中至少见过五次这样的情况：运维团队信誓旦旦地说"备份都做好了"，但当我要求他们在沙箱环境里实际恢复一次时，问题才暴露出来，dump文件损坏、字符集不匹配导致中文乱码、PostgreSQL的大对象（Large Objects）没有被包含在dump中导致附件丢失。

最常见的"假成功"现象包括：

• dump文件生成成功但实际不完整：pg_dump在遇到某些错误时会跳过问题表并继续执行，最终dump文件看起来正常，但恢复后某些表是空的。
• 附件文件夹没有被备份：Jira的附件存储在文件系统中而非数据库里。很多人备份了数据库就以为万事大吉，结果迁移后发现所有附件都无法打开。附件的存储路径在Jira Home目录的data/attachments下，这个目录必须单独打包备份。
• 索引没有被重建：恢复数据库后如果忘记重建索引，Jira的搜索和过滤功能会变得极慢，但系统不会报任何错误。
• 序列号（Sequence）不同步：PostgreSQL中某些表使用自增序列作为主键。恢复数据后，序列的当前值可能与表中已有的最大值不一致，导致后续插入新数据时发生主键冲突。

2. 我的五步验证法

经过多次教训后，我形成了一套标准化的验证流程。这套流程大约需要2-3小时，但它能帮你发现90%以上的备份完整性问题：

第一步：结构验证（15分钟）

• 对比源库和目标库的表数量，确认是否一致。
• 对比每张表的行数，重点关注本文讨论的三类表。
• 如果使用PostgreSQL，检查序列的当前值是否与表中最大ID一致：SELECT setval('sequence_name', (SELECT MAX(id) FROM table_name));