Specivo 文档

故障排查

工具不开始导出

提示信息 含义
give --url, or set JIRA_URL 没有提供站点地址。
give --email and --api-token ... or --pat 没有提供凭据，或者两种凭据都提供了。只提供一种。
... are all set: unset the ones for the other kind of site Cloud 变量和 JIRA_PAT 同时设置了。取消其中一组。
name at least one project key 传入 --project KEY，或设置 JIRA_PROJECTS。
... already holds a bundle / is not empty --out 指向的是已有的导入包，或是一个非空目录。换一个新路径。
put credentials in --email/--api-token or --pat, never in the URL --url 中包含了用户名或密码。把它们去掉。
未知项目（退出状态 2） 项目键不存在，或者该账户无权浏览它。检查项目键和账户的访问权限。
属于另一次导出的状态 之前有一次未完成的运行使用了不同的选项。传入 --restart，或沿用原来的选项。

如果凭据类型与站点不匹配（例如对 Cloud 站点使用个人访问令牌），工具同样会拒绝。请使用身份验证中说明的凭据。

401 和 403 响应

  • 401 表示凭据未被接受。Cloud 站点检查邮箱地址和 API 令牌，Data Center 站点检查个人访问令牌。令牌可能已过期或被撤销。
  • 整个项目返回 403 表示该账户无权浏览这个项目。在 Jira 中给账户授权。
  • 某一类数据返回 403 不会中断导出。工具会计数并继续：
  • 自定义字段上下文（Cloud 上需要 Administer Jira（管理 Jira）权限）：该字段随后会应用到有工作项使用它的项目；
  • 关注者（View voters and watchers（查看投票人和关注者））：只统计关注者数量，不迁移；
  • 项目的看板：冲刺以工作项中引用的为准；
  • 附件：计入“被 Jira 拒绝”。

查看清单文件中的 not_carried_over，可以知道发生了哪些情况、各发生了多少次。

附件

  • 附件缺失。超过 --max-attachment-size（默认 100 MB）的文件会被跳过并计数。用更高的限制再运行一次（例如 --max-attachment-size 2G，或 0 表示不限制）：工具只下载上一次漏掉的文件。
  • 未找到（404）。Jira 列出了该附件，但文件已经不存在。会被计数。
  • 磁盘空间。大型站点需要足够的空间存放导入包中的附件，以及工作状态。

速率限制与导出缓慢

调用过快时，Jira Cloud 会返回 429 或 503。工具会等待后重试，每个请求最多重试六次（见速率限制）。如果仍然失败，工具会停止并给出提示。稍等一会儿，然后 再次运行同一条命令，已经读取过的数据不会重复读取。

要更温和一些，可以降低 --page-size。一次只导出一个项目也能分散负载。

运行中途停止

再次运行同一条命令即可。见运行中断时。如果工具因状态问题拒绝运行，要么是选项变了（传入 --restart 重新开始），要么是状态由另一个版本的工具写入（删除它，或传入 --restart）。

导入 Specivo 时的问题

现象 处理方法
--validate 报告 unresolved_ref 或 count_mismatch 导入包已损坏或不完整。重新导出。不要编辑这些文件。
某个分包出现 external_ref 警告 按项目逐个导出时属正常现象。见导入各个分包。
导入被拒绝，提示该来源之前已导入过 加上 --continue-import。同一站点从第二次导入起都需要它。
出现重复的状态、追踪器或优先级 导入时加上 --merge-duplicate-statuses。
第二个进行中的冲刺变成了计划中 Specivo 每个项目只允许一个进行中的冲刺。这会在报告中列出，属于预期行为。
有些人的邮箱是 @invalid 地址 Jira 隐藏了他们的邮箱地址。导入后补上真实地址。
提到其他分包中工作项的文字仍是纯文本 另一个分包尚未导入。用同一个 --links-file 导入它。import-map pending 会列出等待处理的内容。
某段文字没有变成链接 导入后有人在 Specivo 中编辑过它。Specivo 从不覆盖已编辑的文字。
导入中途停止 加上 --resume RUN_ID 再运行一次。每个阶段独立提交。

重新运行

整个流程的每一步都可以安全地重复：

  • 再次运行 导出 会继续中断的运行，或开始一次新的运行。
  • 再次导入同一个导入包 不会创建任何新内容（需要 --continue-import）。
  • 导入同一站点的较新导出 只会添加此后新建的记录，不会更新已导入的记录。

如果需要彻底重来，恢复导入前的 Specivo 备份，然后重新导入。

获取帮助

报告问题时，请附上工具版本（specivo-jira-migration --version）、你运行的命令（去掉凭据）、站点是 Cloud 还是 Data Center，以及错误信息。不要发送导入包或状态目录：它们包含你的数据和他人的邮箱地址。