校验并加载导入包¶

加载导入包由 Specivo 完成，而不是本工具，并且需要 Specivo 0.11.0 或更高版本。所有迁移工具的导入命令都相同，本页只说明 Jira 导入包需要注意的地方。完整说明见 Specivo 用户指南中的从其他项目管理系统导入。

先备份

正式导入前，先备份 Specivo 的数据库和数据目录。

把导入包复制到 Specivo 服务器，或挂载到 api 容器中，放在应用可写的目录下（导入时会在导入包旁边保存一个小的链接文件）。然后按以下顺序执行：

# 1. Check the bundle. Reads only the bundle: no database is touched.
python -m specivo.cli.import_data --source bundle --path jira-export --validate

# 2. Rehearse. The whole import runs in a transaction that is always rolled back.
python -m specivo.cli.import_data --source bundle --path jira-export --dry-run

# 3. Import.
python -m specivo.cli.import_data --source bundle --path jira-export

使用 Docker 时，每条命令前加上 docker compose exec api，路径改用容器内的路径。

需要仔细阅读的是演练（dry run）的报告。它会列出 Specivo 选定的项目标识、已经存在的状态和追踪器（Tracker）、缺少邮箱地址的账户，以及所有无法迁移的内容。

常用选项¶

选项	用途
`--merge-duplicate-statuses`	复用已有的同名状态、追踪器或优先级，而不是再创建一份。由 Jira 自行管理的项目（团队管理的项目）有自己的工作项类型和状态，因此“Task”“Done”这类名称可能出现两次，此选项会把它们合并。
`--project-key-map IDENTIFIER=KEY,...`	指定某个项目在 Specivo 中的项目标识。工具写入的标识符是小写的 Jira 项目键，因此 `ops=OPS2` 会把 Jira 的 `OPS` 导入为 Specivo 的 `OPS2`。演练报告会显示每个项目选定的标识。
`--project IDS`	只加载导入包中的部分项目，按 Jira 项目 id（数字 id，逗号分隔）指定，而不是按项目键。
`--continue-import`	在同一 Jira 站点的早先导入基础上追加。从第二次加载开始必须带上。
`--links-file PATH`	把链接文件保存在此路径（见下文）。
`--files-path DIR`	从此目录读取附件文件，而不是导入包自带的 `files/`。
`--resume RUN_ID`	继续一次中断的加载。运行 id 会在每次运行结束时打印。
`--import-admins`	让 Jira 管理员在 Specivo 中也成为管理员。默认情况下他们会以普通账户导入，并在报告中列出。
`--report-json PATH`	同时把报告写入文件。

Jira 账户导入后没有密码，每个人都要重新设置密码（或通过单点登录登录）。

分批加载¶

如果按项目逐个导出，就把各部分依次加载：

python -m specivo.cli.import_data --source bundle --path exports/acme \
    --links-file /import/jira-links.sqlite
python -m specivo.cli.import_data --source bundle --path exports/ops \
    --links-file /import/jira-links.sqlite --continue-import

链接文件是一个很小的 SQLite 文件。它记录导入包中指向尚未导入内容的部分：正文里提到的工作项（Issue）、关联、父工作项等。之后的每次加载都会尽量补全这些引用，顺序不限；等到没有待处理项时，文件会被删除。同一站点的每次加载都要使用同一个链接文件。默认情况下，它会在导入包旁边创建为 specivo-links.jira.<site name>.sqlite。

导入后有人在 Specivo 中编辑过的文本会保持原样，不会被改动。

查看还有哪些引用在等待补全：

python -m specivo.cli.admin import-map pending --links-file /import/jira-links.sqlite

切换前的增量同步¶

先提前导入、切换前再补齐增量，是迁移繁忙团队最稳妥的方式。

提前一到两周导出并加载全部内容，让大家先在 Specivo 里熟悉一下。
临近切换时，用相同的 --instance 再次导出同一站点。
带上 --continue-import 加载新的导入包。Specivo 只会添加此后新建的记录。

已导入的记录会被识别并跳过，不会更新。因此，工作项在导入后又在 Jira 中被修改的内容不会被复制过来；请把最终导出安排在 Jira 上的工作已经停止之后。

切换完成、确认不再从该站点导入后，管理员可以运行 python -m specivo.cli.admin import-map purge --system jira --instance SITE --yes 清除相关的记录（其含义见 Specivo 指南），并删除链接文件。

工作项编号¶

Specivo 按加载顺序为项目中的工作项编号（ACME-1、ACME-2……）。工具按 Jira 键的顺序写入工作项，但已删除或已移动的工作项的键不会留下空号，所以 Specivo 的编号可能与 Jira 不同。工作项之间的引用使用 Jira 的 id，因此链接仍然正确。Jira 键会随工作项一起保存在导入包的 extra 数据中。

加载之后¶

打开几个项目，把工作项数量与 Jira 对比一下。
为 Specivo 分配了占位邮箱地址的账户填上真实邮箱。当 Jira Cloud 账户对执行导出的账户隐藏了邮箱地址时就会出现这种情况，工具会告诉你有多少个这样的账户。
检查每个项目的成员和角色。