시작하며
위키(컨플루언스) 마이그레이션 이야기
안녕하세요, 카카오페이 기술전략팀 안드레아스입니다. 지난번에 지라 마이그레이션 경험기로 찾아뵌 이후 두 번째로 인사드립니다. 이번에는 아틀라시안 위키 공식 명칭인 컨플루언스(Confluence, 이하 ‘위키’)에서 마이그레이션을 수행한 경험을 말씀드리겠습니다.
기존에는 카카오에서 관리하는 위키를 카카오페이도 같이 쓰고 있었으며, 카카오페이 전용 위키는 없었습니다. 우리 카카오페이는 여러 가지 이유로 전용 위키를 도입하기로 결정했습니다. 위키 마이그레이션은 지라 마이그레이션을 마치고 23년도 상반기에 진행하기로 계획했습니다. 그러나, 계획을 변경하여 위키 마이그레이션도 바로 진행하기로 결정했습니다. 직원들로부터 카카오페이 전용 위키로의 마이그레이션 요구가 지속적으로 있었고, 판교 IDC 화재 이후 카카오페이 내 주요 문서는 독립적으로 관리해야 한다는 이유에서였습니다. 위키는 콘텐츠 위주이고 마이그레이션 대상도 많지 않아 손쉽게 진행될 거라 예상을 했지만, 역시나 세상에 쉬운 일은 없었습니다. 그 쉽지 않았던 사건들을 쭉 풀어 나가겠습니다.
계획을 세우고 테스트를 진행하다
지라 마이그레이션에서 테스트의 중요성을 일깨워 주었기 때문에, 위키도 당연히 테스트 환경을 구축하고 진행하기로 결정하였습니다. 위키는 콘텐츠 기반으로 구성되어 있기 때문에 지라보다는 훨씬 쉬울 것이라고 예상했습니다. 마이그레이션을 위해 수집한 각종 문서나 데이터 등에서도 특이점을 찾기는 어려웠습니다. 지라와 마찬가지로 계획을 세우고 테스트할 대상을 선정하였습니다. 대상은 첨부파일과 콘텐츠와 첨부파일이 가장 많은 것을 선택하였습니다. 카카오 테스트 위키에서 약 5시간 동안 Export를 받았으며, 용량은 대략 (첨부파일 포함) 60GB 정도였습니다. 위키 마이그레이션은 특별한 플러그인이 없기 때문에 위키 관리자 페이지에서 제공하는 Restore 기능을 이용했습니다.
Import를 시작하자마자 오류가 발생했네요. 뭐 당연한 것이라 생각했습니다. XML 파싱하면서 발생한 오류로 위키 콘텐츠 오류가 아니라서 어떤 이유인지 알 수가 없었습니다. Export로 받은 Zip 파일 압축을 풀고 각종 문서 정보를 포함하고 있는 XML Data 파일을 확인했습니다. XML 콘텐츠 파일 용량이 10GB 정도 되다보니 파일을 오픈하는 것도 쉽지 않았습니다. 파일을 작은 용량으로 잘라 처리한 후 병합해봤지만 큰 파일을 활용하는 것 자체가 어려웠습니다. 다행히 vi (문서 편집기 일종)를 이용하여 용량이 큰 XML 파일을 오픈하고 수정할 수 있었습니다. 물론 vi도 완벽하지는 않았습니다. 일부 첨부 파일에서 한글이 깨져서 보이더라구요.
XML 파일을 열어 알 수 없는 문자를 모두 찾아내었습니다. 알 수 없는 문자는 위키 페이지에서는 보이지 않고, 어떤 경로로 특수 문자들이 포함이 되었는지는 알 수가 없었습니다. 때문에 일일이 찾아내어 모두 제거했습니다.
다시 Import를 수행했지만, 여전히 새로운 형태의 XML 파싱 오류를 발견했습니다. 다행히 아틀라시안에서 파싱 오류를 처리할 수 있는 도구를 제공하고 있어 쉽게 처리할 수 있었습니다.
어렵게 XML 파싱 오류를 모두 제거하고, 이제 해당 오류를 제거하여 마이그레이션한 위키 스페이스를 검증할 차례입니다. 위키 스페이스 검증에서 몇 가지 중대한 오류를 찾았습니다.
- 일부 한글로 된 첨부 파일명이 깨짐(깨진 규칙을 알 수 없고, 정상적인 한글 파일도 다수 있기 때문에 문제 해결이 쉽지 않음)
- DB 데이터에 등록된 첨부 파일이 실제 파일 시스템에는 존재하지 않음
- 서로 콘텐츠가 연관이 되어 있는 경우 연관된 스페이스까지 Import가 수행되었지만, 연관된 스페이스의 첨부 파일은 Import가 되지 않음(내가 원하는 스페이스만 단독으로 Import 처리 불가)
이와 같이 전혀 예상치 못한 오류를 해결할 방안이 쉽게 떠오르지 않았습니다. 결국 실제 운영 마이그레이션 일정을 연기하게 되었습니다.
문제를 단순하게 만들다
쉬울 것이라 생각했던 작업들은 전혀 예상하지 못한 문제들을 마주하며 해결될 기미가 보이지 않았습니다. 그래서 문제를 좀 더 단순하게 쪼개어 생각해 보기로 했습니다. 먼저 지라와 마찬가지로 콘텐츠와 첨부 파일을 분리해서 작업을 수행해 보기로 결정하였습니다. 며칠 고민한 끝에 새로운 방법을 찾았지만, 해당 방법으로 잘 진행될지는 미지수였습니다. 그럼에도 실행해 봐야 결과를 알 수 있기에 과감하게 진행해 보기로 마음먹었습니다.
폴더 구조
위키에서 첨부 파일의 폴더와 이름은 총 7단계로 나누어져 있으며, 7단계는 스페이스와 콘텐츠 키 정보를 통해서 폴더를 구성하고 있습니다.
- 최상단 ver003 폴더 아래 위치
- 샘플 스페이스: 카카오페이 이터레이션 과제(Space ID : 3735553, page ID : 3702790)
| 단계 | 폴더 이름 | 샘플 ID | 설명 |
|---|---|---|---|
| 1단계 | 53 | 553 % 250 | Space. ID의 뒤에서 3자리를 250으로 나눈 나머지 |
| 2단계 | 3자리 | 235 | Space ID 중간 3자리 735 / 250 의 나머지 |
| 3단계 | Space ID | 3735553 | Space ID 전체 |
| 4단계 | 2-3자리 | 790 | Page ID 뒤에서 3자리 |
| 5단계 | 2-3자리 | 202 | Page ID 중간 3자리 702 / 250 의 나머지 |
| 6단계 | Page ID | 3702790 | Page ID 전체 |
| 7단계 | Content ID | 3702915 | Content ID 전체 |
이를 구성하기 위해서는 카카오 위키 스페이스와 콘텐츠 키 정보가 필요했습니다. 정보를 얻기 위해서는 DB 쿼리로 데이터를 직접 조회해야 하며, 카카오 측의 도움으로 DB 데이터를 얻을 수 있었습니다.
- 최상단 ver003 폴더 아래 위치
카카오 측에 직접 DB 쿼리까지 만들어서 제공하였고, 각 스페이스에 포함된 첨부파일은 tar 파일로 별도로 받을 수 있었습니다. 카카오 위키에서 Export 받은 스페이스 zip 파일에서 첨부 파일을 삭제 후 다시 zip 파일로 압축하여 Import를 수행했습니다. 다행히 큰 이슈 없이 Import가 완료되었습니다.
그런데, 문제는 어떻게 첨부파일을 신규로 만들어진 스페이스 콘텐츠 페이지와 매핑을 하느냐였습니다. 위키는 지라와 달리 콘텐츠를 Import를 하면 기존의 key (페이지 ID) 정보를 무시하고 새로운 key를 생성하여 콘텐츠를 만들어냈습니다. 이를 해결하기 위해 기존 스페이스 및 콘텐츠 키와 새롭게 만들어지는 스페이스 및 콘텐츠 키를 매핑하는 정보를 만들었으며, 사전에 이를 임시 테이블로 만들어 등록해 두었습니다.
매핑 테이블 기준으로 첨부파일 이름을 비교, 복사하여 전체 폴더 체계를 만들었습니다. 폴더 체계를 만들어주는 부분은 파이썬으로 개발했고, 첨부파일 복사 및 DB 테이블에 데이터 등록은 자바로 만들었습니다. 이 두 언어로 개발된 프로그램을 제어하면서 데이터 복사 및 삭제 이동 명령어를 수행할 쉘 스크립트를 만들어 서버에서 직접 수행했습니다.
오랜만에 개발을 하는 입장에서 정말 시간 가는 줄 모르게 코딩을 했던 것으로 기억합니다. 정신없이 개발하고 테스트하고, 검증하기까지 약 일주일 이상 걸렸네요. 개발된 프로그램 결과가 큰 이슈 없이 완료되고 검증까지 끝났을 때는 개인적으로도 무척 기분이 좋았습니다. 문제를 단순화하고 복잡한 이슈를 작게 분할해서 하나씩 해결하기로 결정한 것에 스스로에게 뿌듯함을 느꼈습니다.
운영 마이그레이션
마이그레이션 일정과 카카오 위키 프리징 공지 등 실제 마이그레이션을 수행하기 위해, 전사 공지와 마이그레이션 이후 변화된 부분, 또는 마이그레이션이 지원이 안되는 부분 등을 정리했습니다. 사전에 마이그레이션 대상을 선정했기 때문에 작업에는 큰 이슈가 없이 진행되었고, 개발된 프로그램도 잘 동작했습니다. 물론 마이그레이션 완료 후 크고 작은 몇 가지 오류가 있었지만, 어렵지 않게 해결이 되었습니다.
지라/위키 셀프 회고
지라부터 위키까지 대부분 경험하지 못한 마이그레이션을 누구의 도움 없이 혼자 해결했다는 것에서 스스로에게 무척 자랑스러웠습니다. 물론 이런 큰 업무를 혼자서만 단독으로는 할 수 없습니다. 저에게 가장 소중한 카카오페이 크루들이 있었기에 이 어려운 작업을 해낼 수 있었다고 생각합니다.
- 고마운 분들: 레오(인프라플랫폼팀), 비비(서비스협의체) 그리고 테스트를 지원해 주신 모든 크루 분들
- 기술전략팀 리더 앨빈 이하 우리 팀원 분들
입사한 지 얼마 되지 않았기 때문에 모든 것이 서툰 저였지만 동료들 도움으로 여기까지 온 것 같습니다. 다시 한번 지라/위키 마이그레이션 작업을 도와주신 모든 크루분들에게 진심으로 감사 인사드립니다. 때로는 경험이 독이 되는데요, 기존 경험으로 쉽다고 생각했던 부분에서 놓치는 부분이 발생하였습니다. 자만심은 항상 이슈를 몰고 온다는 걸 다시 한번 느꼈고, 이 모든 과정에서 스스로를 돌아보는 계기가 되었습니다. 그렇기 때문에 이번 업무가 저에게는 더욱 소중하게 다가왔던 것 같습니다.
마치며
카카오페이는 이제 카카오에서 지라와 위키를 독립할 수 있는 기반이 마련되었습니다. 즉, 카카오페이만의 독자적인 지라/위키를 만들어 갈 수 있고, 더 나아가 업무 문화를 더 효율적으로 지원할 수 있는 기초를 마련했다고 할 수 있겠습니다. 이 글을 쓰는 시점에 전사에 지라 정책을 모두 변경하는 큰 작업을 진행하고 있는데요, 변경이라는 것은 기존 것을 개선하고 새로운 것을 취하기 때문에 그만큼 시간과 노력이 필요합니다. 또한 혼자만의 힘으로는 절대 변화를 가져올 수 없습니다. 모든 크루분들 도움을 받아 과감하게 카카오페이만의 개선된 비즈니스 기반을 마련할 수 있었습니다. 앞으로 새로운 협업 도구와 업무 환경에서도 유연하게 확대할 수 있는 기틀을 마련하겠습니다. 또한, 개발 부서뿐만 아니라 스탭 부서들도 지라/위키를 잘 활용할 수 있도록 교육과 문서 제공 등 지원을 아끼지 않을 예정입니다.
끝으로 지라/위키 도입과 정책 변경 등을 통해서 과연 개발 및 사업 수행에 얼마나 많은 도움이 되었는지, 또는 불편한 점은 없었는지 등 의견을 청취할 예정입니다. 많은 의견을 통해 지라/위키가 업무에 도움이 될 수 있는 환경으로 변모할 수 있기를 기대합니다. 지라 마이그레이션 경험기에 이어 위키 마이그레이션 이야기까지 읽어 주신 점 감사합니다.
