认证与配置¶
工具运行需要三样东西：Jira 站点地址、凭据，以及要导出的项目标识。每一项都可以通过命令行选项或环境变量提供。
凭据¶
通过环境变量传递凭据，这样它们不会出现在进程列表和 shell 历史中。工具不会把凭据写入任何地方，也不会打印出来。
使用某个账户的邮箱地址，以及为该账户创建的 API 令牌。
export JIRA_URL=https://your-site.example
export JIRA_EMAIL=[email protected]
export JIRA_API_TOKEN=your_api_token_here
工具会向站点查询（/rest/api/2/serverInfo）它属于哪一种类型，并拒绝另一种类型的凭据。如果同时设置了邮箱和令牌变量以及 JIRA_PAT，工具会因为无法判断而拒绝运行：请取消设置属于另一种站点类型的变量。
使用专用账户
为迁移单独创建一个账户，并授予它对待迁移项目的读取权限。迁移完成后可以删除令牌。该账户不需要在 Jira 中修改任何内容。
账户所需的权限列在概览页面。
配置项¶
| 配置项 | 选项 | 环境变量 | 说明 |
|---|---|---|---|
| 站点地址 | --url |
JIRA_URL |
站点的基础地址。 |
| Cloud 邮箱 | --email |
JIRA_EMAIL |
仅 Cloud。 |
| Cloud API 令牌 | --api-token |
JIRA_API_TOKEN |
仅 Cloud。建议使用环境变量。 |
| Data Center 令牌 | --pat |
JIRA_PAT |
仅 Data Center。建议使用环境变量。 |
| 项目 | --project KEY |
JIRA_PROJECTS |
可重复指定，或用逗号分隔。 |
| 导入包中的站点名称 | --instance NAME |
无 | 见下文。 |
选项优先于环境变量。工具本身没有配置文件：如果你把这些值保存在文件里，运行前先把它加载到 shell 环境中，并确保该文件只有你本人可读。
每次运行必须提供 --url（或 JIRA_URL）、凭据、至少一个项目，以及 --out。缺少任何一项，工具都会以退出状态 2 终止，并提示需要补充什么。
站点名称（--instance）¶
每个导入包都会记录它来自哪个系统、哪个安装实例。对本工具来说，系统是 jira，安装实例就是 站点名称：默认取 --url 的主机名（如果站点部署在某个路径下，则加上该路径）。
Specivo 会在这个名称下记住每条 Jira 记录对应到了哪条 Specivo 数据。正因如此，你可以：
- 重复加载同一份导出而不产生重复数据；
- 日后再次导出该站点，只补充新增内容；
- 逐个项目导出，各部分之间仍能相互关联。
因此，对同一个 Jira 站点的每次导出都要使用相同的站点名称。只要每次给的 --url 一致，默认值就已经满足这一点。以下情况需要自行设置 --instance：两次导出之间地址发生了变化（同一个 Jira 换了主机名），或者要把两个不同的 Jira 站点迁入同一个 Specivo，需要区分开来。
输出位置¶
--out PATH 指定导入包的写入位置：一个新建或空的目录，或者以 .zip 结尾的路径（也可以加 --zip）。工具不会覆盖已有的导入包，也不会写入非空目录。