Jira·Confluence를 통째로 미러링하기 — raw를 버리고 synced로

지난 글에서 잡은 큰 그림은 수집 → 요약 → 위키 → 봇이었습니다. 이번 글은 그 첫 단계, "원문을 어떻게 가져올 것인가"에 대한 이야기입니다. 결론부터 말하면, 처음 설계를 한 번 갈아엎었습니다.

처음 설계: raw/에 원천을 쌓는다

처음엔 흔한 데이터 파이프라인처럼 생각했습니다.

• raw/ — 어디서든 긁어온 원천 데이터를 쌓는 곳
• 여기에 Jira·Confluence는 물론, 직접 올린 파일도 함께 둔다
• 이걸 요약해서 위키를 만든다

깔끔해 보였습니다. 그런데 만들다 보니 자꾸 이상한 지점에서 걸렸습니다. 코드가 기존 raw/를 안 쓰려고 하는 것처럼 움직였습니다. 뭔가 개념이 어긋나 있다는 신호였습니다.

문제: '두 개의 진실'이 생긴다

곰곰이 따져 보니, raw/라는 개념 자체가 문제였습니다.

원천이 Jira·Confluence인데 거기에 "직접 올린 파일"까지 섞이면, 원본이 두 군데가 됩니다. Jira에서 이슈가 수정됐을 때, raw/의 사본은 누가 갱신하나요? 직접 올린 파일과 미러된 파일이 충돌하면 뭐가 진짜인가요?

지식 베이스에서 가장 위험한 건 "진실이 두 개"인 상태입니다. 어느 걸 믿어야 할지 모르는 순간, 위키 전체의 신뢰가 무너집니다.

전환: synced/ 미러 — 원문 그대로

그래서 방향을 바꿨습니다.

• raw/ 개념을 완전히 없앤다.
• 대신 synced/ — Jira·Confluence의 원문을 그대로 내려받은 미러만 둔다.
• 파일을 직접 올리는 통로는 없앤다. 모든 입력은 Jira·Confluence에서만 들어온다.

원칙은 단순합니다. 원본은 언제나 Jira·Confluence 한 곳. synced/는 그 사본일 뿐이고, 사람이 손대지 않습니다. 사본이 오염될 일이 없으니 "두 개의 진실" 문제가 사라집니다.

synced/
├── jira/
│   ├── PROJ-1024.md
│   ├── PROJ-1025.md
│   └── ...
└── confluence/
    ├── 3265167451-아키텍처-개요.md
    └── ...

여기서 중요한 결정이 하나 더 있었습니다. 미러는 요약 없이 원문 전체를 가져옵니다. 요약은 다음 단계(위키)에서만 합니다. 원문을 손실 없이 보관해 둬야, 나중에 요약 방식을 바꿔도 다시 긁을 필요가 없기 때문입니다.

증분 수집: 워터마크

수천 건을 매번 처음부터 다시 받는 건 낭비입니다. 그래서 워터마크(watermark) 방식으로 증분만 가져옵니다.

• 마지막으로 어디까지 수집했는지를 상태 파일 하나에 기록합니다.
• 다음 실행 때는 그 이후 변경분만 받아 옵니다.
• 상태 파일을 지우면 전체를 처음부터 다시 받습니다(전체 재수집).

rm -f sync_state.json   # 워터마크 초기화 → 전체 재수집
python sync.py          # 이후엔 변경분만 증분 수집

수집 주기는 1시간에 한 번으로 잡았습니다. 실시간까지는 필요 없고, 팀 문서가 바뀌는 속도엔 1시간이면 충분했습니다.

빈 문서는 거를까?

수집하다 보니 본문이 비어 있는 Jira 이슈가 꽤 나왔습니다. "빈 건 안 가져오는 게 낫지 않을까?" 하고 필터를 고민했는데, 거르지 않기로 했습니다.

이유는 두 가지입니다.

• 지금 비어 있어도 나중에 본문이 채워질 수 있습니다. 그때 다시 편입하려면 오히려 로직이 복잡해집니다.
• 빈 문서라도 제목·담당자·상태·링크 같은 메타데이터는 있습니다. 이건 스크럼봇이나 담당자별 정리에서 쓸모가 있습니다.

필터는 "지금 편해 보이는" 최적화였지만, 지식 베이스에서는 일단 다 담고 나중에 걸러 쓰는 쪽이 안전했습니다.

정리

• 원천은 언제나 한 곳(Jira·Confluence)이어야 한다 → raw/를 버리고 synced/ 미러로.
• 미러는 요약 없이 원문 전체를, 워터마크로 증분만.
• 성급한 필터보다, 일단 다 담아 두기.

이렇게 원문을 안전하게 모아 뒀으니, 다음은 이걸 LLM으로 요약할 차례입니다. 그런데 수천 건을 요약하려니 이번엔 속도가 발목을 잡았습니다. 다음 글에서 vLLM 배치를 어떻게 튜닝했는지 다룹니다.