用 Python 同步 JIRA 数据到本地：从入门到实战

Tue, 14 Jul 2026 12:34:25 -0800

用 Python 同步 JIRA 数据到本地：从入门到实战

一、JIRA 是什么？

JIRA 是 Atlassian 公司开发的一款项目管理和问题追踪工具，广泛应用于软件团队的敏捷开发、Bug 跟踪、需求管理和任务协作中。

简单来说，JIRA 就是一个"一切皆 Issue"的工作流引擎：

需求（Story）是一个 Issue
Bug 是一个 Issue
子任务（Sub-task）也是一个 Issue
每个 Issue 有自己的类型、状态、优先级、经办人、时间估算、自定义字段等

JIRA 的核心价值在于：

能力	说明
工作流定制	每个 Issue 在不同状态间流转（待办→进行中→已完成），可自定义步骤和条件
敏捷看板	Scrum / Kanban 面板，拖拽管理任务
自定义字段	不限于内置字段，可随意添加业务需要的字段
强大的 JQL	JIRA Query Language，类似 SQL 的灵活搜索语言
权限体系	颗粒度到字段级别的权限控制
集成生态	与 Git、CI/CD、Slack、Confluence 深度集成

二、为什么要把 JIRA 数据同步到本地？

虽然 JIRA 提供了 Web UI 和 REST API，但有些场景下把数据拉到本地更高效：

离线备份 — 防止 JIRA 服务故障或配置丢失
自定义分析 — 在本地用 Pandas / SQL 做更灵活的统计报表
数据迁移 — 从 JIRA 迁移到其他平台前的数据整理
自动化处理 — 批量修改、批量提取 Gherkin 用例、合规审计等
性能考量 — 大规模查询时，本地处理比轮询 JIRA API 快得多

三、Python 调用 JIRA 的准备工作

安装依赖

1

pip install jira python-dotenv

jira — Atlassian 官方推荐的 Python 客户端库
python-dotenv — 从 .env 文件加载配置，避免硬编码凭据

配置 `.env` 文件

在项目目录下创建 .env，写入以下内容（请使用你自己的实际值替换示例）：

1
2
3


JIRA_SERVER=https://your-company.atlassian.net/
JIRA_USERNAME=your-email@example.com
JIRA_PASSWORD=your-api-token-or-password

安全提示： 永远不要将包含真实凭据的 .env 文件提交到 Git。请在 .gitignore 中添加 .env。

什么是 API Token？

Atlassian 推荐使用 API Token 而非密码认证：

登录 https://id.atlassian.com/manage-profile/security/api-tokens
点击"Create API token"
复制生成的 token 作为 JIRA_PASSWORD 的值

四、基础用法示例

4.1 连接并列出所有项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from jira import JIRA
import os
from dotenv import load_dotenv

load_dotenv()

jira_server = os.getenv("JIRA_SERVER")
jira_user = os.getenv("JIRA_USERNAME")
jira_pass = os.getenv("JIRA_PASSWORD")

jr = JIRA(server=jira_server, basic_auth=(jira_user, jira_pass))

projects = jr.projects()
print(f"共发现 {len(projects)} 个项目：")
for p in projects:
 print(f" {p.key}: {p.name}")

输出示例：

1
2
3
4
5


共发现 12 个项目：
 PROJ: 我的项目
 BUGS: 缺陷追踪
 DOCS: 文档管理
 ...

4.2 搜索指定项目的 Issue

1
2
3
4
5
6
7
8


# 搜索所有 JQL 都支持的功能
issues = jr.search_issues(
 'project = "PROJ" AND status = "进行中"',
 maxResults=50,
 fields="summary,status,assignee,created",
)
for issue in issues:
 print(f"{issue.key}: {issue.fields.summary}")

常用 JQL 示例：

JQL	含义
`project = PROJ`	PROJ 项目所有 Issue
`assignee = currentUser()`	指派给我的
`updated >= -7d`	最近一周更新的
`status in (Open, "In Progress")`	未关闭的
`ORDER BY created DESC`	按创建时间倒序

4.3 获取 Issue 完整详情

1
2


issue = jr.issue("PROJ-123", fields="*all", expand="changelog")
print(issue.raw) # 完整的 JSON 数据

fields="*all" 返回所有字段（包括自定义字段），expand="changelog" 返回变更历史。

五、实战：把整个 JIRA 同步到本地

下面是一个完整的脚本，它会遍历所有项目、分页拉取全部 Issue、保存为本地 JSON 文件。

完整代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


from jira import JIRA
import os
import json
from datetime import datetime
from dotenv import load_dotenv

# 1. 加载 .env 配置
load_dotenv()

JIRA_SERVER = os.getenv("JIRA_SERVER")
JIRA_USERNAME = os.getenv("JIRA_USERNAME")
JIRA_PASSWORD = os.getenv("JIRA_PASSWORD")

if not all([JIRA_SERVER, JIRA_USERNAME, JIRA_PASSWORD]):
 raise ValueError("请在 .env 中配置 JIRA_SERVER、JIRA_USERNAME、JIRA_PASSWORD")

# 2. 连接 JIRA
jr = JIRA(server=JIRA_SERVER, basic_auth=(JIRA_USERNAME, JIRA_PASSWORD))
print(f"已连接 JIRA: {JIRA_SERVER}")

# 3. 获取所有项目
projects = jr.projects()
print(f"\n共发现 {len(projects)} 个项目:\n")
for p in projects:
 print(f" - {p.key}: {p.name}")

# 创建输出目录
output_dir = os.path.join(os.path.dirname(__file__), "jira_backup")
os.makedirs(output_dir, exist_ok=True)

# 4. 遍历每个项目，获取全部 Issue
for project in projects:
 project_key = project.key
 print(f"\n正在同步项目: {project_key} - {project.name}")

 all_issues = []
 start_at = 0
 page_size = 100

 while True:
 issues = jr.search_issues(
 f'project = "{project_key}"',
 startAt=start_at,
 maxResults=page_size,
 fields="*all",
 expand="changelog",
 )
 if not issues:
 break

 for issue in issues:
 # 逐个获取完整详情
 full_issue = jr.issue(
 issue.key,
 fields="*all",
 expand="changelog,renderedFields",
 )
 all_issues.append(full_issue.raw)
 print(f" ✓ {issue.key}: {issue.fields.summary[:60]}")

 start_at += len(issues)
 if len(issues) < page_size:
 break

 # 保存到 JSON 文件
 output_file = os.path.join(output_dir, f"{project_key}.json")
 with open(output_file, "w", encoding="utf-8") as f:
 json.dump({
 "project_key": project_key,
 "project_name": project.name,
 "synced_at": datetime.now().isoformat(),
 "total_issues": len(all_issues),
 "issues": all_issues,
 }, f, ensure_ascii=False, indent=2)

 print(f" 已保存 {len(all_issues)} 个 Issue → {output_file}")

print(f"\n全部同步完成！数据保存在: {output_dir}")

运行效果

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


已连接 JIRA: https://your-company.atlassian.net/

共发现 12 个项目:

 - PROJ: 我的项目
 - BUGS: 缺陷追踪
 ...

正在同步项目: PROJ - 我的项目
 ✓ PROJ-1: 用户登录功能开发
 ✓ PROJ-2: 修复首页白屏问题
 ✓ PROJ-3: 数据导出性能优化
 ...
 已保存 128 个 Issue → jira_backup/PROJ.json

全部同步完成！数据保存在: jira_backup/

输出的 JSON 结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
 "project_key": "PROJ",
 "project_name": "我的项目",
 "synced_at": "2026-07-14T11:00:00",
 "total_issues": 128,
 "issues": [
 {
 "id": "10001",
 "key": "PROJ-1",
 "self": "https://your-company.atlassian.net/rest/api/2/issue/10001",
 "fields": {
 "summary": "用户登录功能开发",
 "issuetype": { "name": "故事" },
 "status": { "name": "进行中" },
 "assignee": { "displayName": "张三" },
 "created": "2026-06-01T10:00:00.000+0800",
 "updated": "2026-07-10T15:30:00.000+0800",
 "customfield_10602": "Gherkin 用例文本...",
 "description": "作为用户，我想要...",
 "comment": { "comments": [...] },
 ...
 }
 }
 ]
}

六、进阶技巧

6.1 只获取变更的 Issue（增量同步）

如果每天同步一次，没必要每次都全量拉取。用 JQL 按更新日期过滤：

1
2
3
4
5


from datetime import datetime, timedelta

since = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d %H:%M")
jql = f'project = "PROJ" AND updated >= "{since}"'
issues = jr.search_issues(jql, fields="*all")

6.2 导出为 CSV 而非 JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import csv

with open("jira_export.csv", "w", newline="", encoding="utf-8-sig") as f:
 writer = csv.writer(f)
 writer.writerow(["Issue Key", "Summary", "Status", "Assignee", "Created"])
 for issue in issues:
 writer.writerow([
 issue.key,
 issue.fields.summary,
 issue.fields.status.name,
 getattr(issue.fields.assignee, "displayName", ""),
 issue.fields.created,
 ])

6.3 处理大项目（分批导出）

超过 1000 条 Issue 时务必分页，JIRA API 默认单页最多 100 条：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


start_at = 0
page_size = 100
all_issues = []

while True:
 batch = jr.search_issues(
 'project = "PROJ"',
 startAt=start_at,
 maxResults=page_size,
 )
 if not batch:
 break
 all_issues.extend(batch)
 start_at += len(batch)
 print(f"已获取 {start_at} 条...")

6.4 从本地 JSON 还原数据到新 JIRA

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


import json

with open("jira_backup/PROJ.json", "r", encoding="utf-8") as f:
 data = json.load(f)

for issue_data in data["issues"]:
 fields = issue_data["fields"]
 new_issue = jr.create_issue(
 project={"key": "PROJ"},
 summary=fields["summary"],
 description=fields.get("description", ""),
 issuetype={"name": fields["issuetype"]["name"]},
 )
 print(f"已创建: {new_issue.key}")

七、常见问题

Q: JQL 报错 “The character ‘*’ is a reserved JQL character”

* 是 JQL 的保留通配符，必须用引号括起来。错误写法：

1

jr.search_issues("PROJ:*") # ❌ 会报 400 错误

正确写法：

1

jr.search_issues('project = "PROJ"') # ✅

Q: `Project` object has no attribute ’lead’

jr.projects() 返回的是轻量级 Project 对象，不包含 lead 属性。如果确实需要 lead 信息：

1
2


full_project = jr.project("PROJ") # 单独获取完整项目信息
print(full_project.lead.displayName)

Q: 如何处理 JIRA 的 rate limit？

JIRA Cloud 对 API 有速率限制。建议：

每页获取 100 条（最大值），减少请求次数
在每次请求之间添加 time.sleep(0.5)
考虑使用 JIRA Software Data Center（自托管）免除限制

八、总结

JIRA 的 Python API 非常成熟，用 jira 库几十行代码就能完成数据同步。核心要点：

凭据管理 — 用 .env + python-dotenv，绝不硬编码
JQL 查询 — 注意 JQL 保留字符（*、?、[ 等）需要引号
分页 — 超过 100 条必须分页遍历
字段选择 — 用 fields="*all" 获取全部字段，expand="changelog" 获取变更历史
增量同步 — 按 updated >= "日期" 过滤，避免全量重复拉取

本文中的代码示例均使用模拟域名和凭据，实际运行时请替换为你自己的 JIRA 配置。

JIRA on 酒中仙

用 Python 同步 JIRA 数据到本地：从入门到实战

用 Python 同步 JIRA 数据到本地：从入门到实战

一、JIRA 是什么？

二、为什么要把 JIRA 数据同步到本地？

三、Python 调用 JIRA 的准备工作

安装依赖

配置 .env 文件

什么是 API Token？

四、基础用法示例

4.1 连接并列出所有项目

4.2 搜索指定项目的 Issue

4.3 获取 Issue 完整详情

五、实战：把整个 JIRA 同步到本地

完整代码

运行效果

输出的 JSON 结构

六、进阶技巧

6.1 只获取变更的 Issue（增量同步）

6.2 导出为 CSV 而非 JSON

6.3 处理大项目（分批导出）

6.4 从本地 JSON 还原数据到新 JIRA

七、常见问题

Q: JQL 报错 “The character ‘*’ is a reserved JQL character”

Q: Project object has no attribute ’lead’

Q: 如何处理 JIRA 的 rate limit？

八、总结

配置 `.env` 文件

Q: `Project` object has no attribute ’lead’