From 7a47c3e75a43501f0a9fe08a8e72174c8b6b7c64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=AC=B8=ED=98=95=EC=84=9D?= Date: Tue, 11 Aug 2026 17:02:42 +0900 Subject: [PATCH] =?UTF-8?q?=EC=9E=A5=ED=97=8C=20=EB=A0=88=EA=B1=B0?= =?UTF-8?q?=EC=8B=9C=20=EB=A6=AC=EB=88=85=EC=8A=A4=EC=A0=84=ED=99=98=20?= =?UTF-8?q?=EA=B2=80=ED=86=A0/=EC=9E=A5=ED=97=8C=20=EB=A0=88=EA=B1=B0?= =?UTF-8?q?=EC=8B=9C=20=EC=84=9C=EB=B2=84=20=ED=9A=8C=EC=88=98=20=EB=B0=8F?= =?UTF-8?q?=20Linux=20=EC=9A=B4=EC=98=81=20=EC=A0=84=ED=99=98=20=EC=8B=9C?= =?UTF-8?q?=EB=82=98=EB=A6=AC=EC=98=A4=20=EC=B4=88=EC=95=88.md=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ... 회수 및 Linux 운영 전환 시나리오 초안.md | 219 ++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 장헌 레거시 리눅스전환 검토/장헌 레거시 서버 회수 및 Linux 운영 전환 시나리오 초안.md diff --git a/장헌 레거시 리눅스전환 검토/장헌 레거시 서버 회수 및 Linux 운영 전환 시나리오 초안.md b/장헌 레거시 리눅스전환 검토/장헌 레거시 서버 회수 및 Linux 운영 전환 시나리오 초안.md new file mode 100644 index 0000000..98639c1 --- /dev/null +++ b/장헌 레거시 리눅스전환 검토/장헌 레거시 서버 회수 및 Linux 운영 전환 시나리오 초안.md @@ -0,0 +1,219 @@ +# 장헌 레거시 서버 회수 및 Linux 운영 전환 시나리오 초안 + +> 상태: 회의용 초안 +> 목적: 레거시 서버를 회수하기 전에 신규 Linux/Docker 운영 환경으로 안전하게 전환하기 위한 범위·순서·담당·중단 및 롤백 기준을 합의한다. +> 원칙: 이 문서는 전환 계획이다. 운영 서버 변경·배포·레거시 서버 회수의 실행 승인은 별도로 받는다. + +## 1. 회의에서 먼저 결정할 사항 + +| 결정 항목 | 회의에서 확정할 내용 | 결정 담당 | +| --- | --- | --- | +| 전환 대상 | 7개 핵심 서비스, `worker_mng`, `proj_new2`, `apiLibrary`의 포함 범위와 제외 범위 | 업무·개발 책임자 | +| 운영 기준 소스 | Gitea `main`의 배포 대상 커밋 SHA와 승인 기준 | 개발·배포 책임자 | +| 전환 일시 | 입력 중지 시작, 최종 동기화, 신규 서비스 공개, 레거시 회수 예정일 | 업무·운영 책임자 | +| DB 기준 시점 | 최종 덤프 생성 시각과 신규 DB 복원 완료 확인 방법 | DB 책임자 | +| 업무 파일 기준 | `intranet_file`, `factory_file`, `apiLibrary/log`의 이관 범위·보존 기간 | 업무·운영 책임자 | +| 도메인 전환 | 신규 서버 주소, DNS/프록시 전환 담당자와 확인 절차 | 인프라 책임자 | +| 롤백 | 장애 판단 기준, 레거시 복귀 가능 기간, 데이터 처리 방법 | 전환 책임자 | + +## 2. 전환의 전체 구조 + +```text +레거시 서버 신규 Linux 운영 서버 +──────────────────────────────────────────────────────────────── +PHP 원본 소스 ──> Gitea main 기준 이미지 ──> Docker 웹 컨테이너 +운영 DB ──> 최종 DB dump/복원 ──> DB 영속 저장소 +업무 파일 ──> 1차 복사 + 최종 동기화 ──> /opt/jang-data/* +원본 보관본 ──> SHA-256 검증 ──> /opt/jang-archive/* + ↓ + 스테이징 검증 + ↓ + 운영 공개·도메인 전환 +``` + +## 3. 컨테이너와 실제 파일 저장 위치 + +파일 보관 전용 컨테이너를 새로 만들지 않는다. 운영 Linux 서버의 실제 폴더를 기존 웹 컨테이너 경로에 **볼륨 마운트**한다. + +```text +운영 서버 실제 디스크 웹 컨테이너 내부 +/opt/jang-data/intranet_file ────────> /var/www/html/intranet_file +/opt/jang-data/factory_file ────────> /var/www/html/factory_file +/opt/jang-data/apiLibrary-log ────────> /var/www/html/apiLibrary/log +``` + +따라서 사용자가 웹 화면에서 업로드한 파일은 컨테이너가 아니라 운영 서버의 `/opt/jang-data/...` 아래에 남는다. 컨테이너 재배포·재생성 뒤에도 파일이 유지된다. + +Compose 설정은 아래와 같은 형태로 관리한다. 실제 변수명과 대상 경로는 현재 `docker-compose*.yml`과 운영 `.env`를 기준으로 최종 확인한다. + +```yaml +services: + web: + volumes: + - ${INTRANET_FILES_ROOT}:/var/www/html/intranet_file + - ${FACTORY_FILES_ROOT}:/var/www/html/factory_file + - ${API_LIBRARY_LOG_ROOT}:/var/www/html/apiLibrary/log +``` + +## 4. DB 이관 시나리오 + +DB dump는 기준 데이터를 옮기는 방법이다. 단, 레거시에서 사용자가 계속 입력하는 동안 만든 1차 dump만으로 운영 전환을 완료하면 마지막 입력분이 누락될 수 있다. + +| 단계 | 작업 | 완료 확인 | +| --- | --- | --- | +| 1차 리허설 | 레거시 DB dump를 신규 격리/스테이징 DB에 복원 | 로그인·핵심 조회·테이블 수·대표 데이터 확인 | +| 사전 검증 | 신규 코드와 복원 DB로 핵심 업무 흐름 검사 | 오류 로그·DB 연결·파일 연계 확인 | +| 전환 동결 | 레거시의 신규 입력·결재·파일 업로드를 중지 | 공지·담당자 확인 | +| 최종 dump | 동결 시점의 레거시 DB를 dump | dump 파일 크기·해시·생성 시각 기록 | +| 최종 복원 | 신규 운영 DB에 최종 dump 복원 | 복원 로그·핵심 테이블·계정 확인 | +| 공개 전 확인 | 신규 서버에서 로그인·조회·입력·결재 등 핵심 검사 | 업무 책임자 승인 | + +> DB dump는 비밀정보와 운영 데이터를 포함할 수 있다. Git·일반 문서·채팅에 저장하지 않고, 접근 권한이 제한된 백업 경로에서 관리한다. + +## 5. 대용량 업무 파일 이관 시나리오 + +### 5.1 분리 보관 원칙 + +| 대상 | Git main 반영 여부 | 운영 저장 방식 | +| --- | --- | --- | +| PHP·JS·CSS·템플릿 등 소스 | 반영 | Gitea 및 Docker 이미지 | +| `intranet_file` 업무 첨부·문서·PDF | 반영하지 않음 | `/opt/jang-data/intranet_file` | +| `factory_file` Excel·PDF·업무 산출물 | 반영하지 않음 | `/opt/jang-data/factory_file` | +| `apiLibrary/log` 로그 | 반영하지 않음 | `/opt/jang-data/apiLibrary-log` | +| DB dump | 반영하지 않음 | 권한 제한 백업 경로 | +| 비밀번호·토큰·개인키 | 절대 반영하지 않음 | 별도 보안 저장소 | + +### 5.2 파일 이관 순서 + +```text +1차 전체 복사 + ↓ +레거시 업무는 계속 사용 + ↓ +전환 시간에 업로드·수정 중지 + ↓ +새 파일·수정 파일만 최종 동기화 + ↓ +파일 수·용량·대표 파일·권한 확인 +``` + +파일 비교 기준은 `상대 경로 + 파일 크기 + 최종 수정 시간`을 기본으로 한다. 네트워크·용량이 허용되는 범위에서는 중요한 파일 또는 최종 이관본에 대해 SHA-256 해시를 추가 확인한다. + +| 파일 상태 | 판단 | 조치 | +| --- | --- | --- | +| 신규 파일 | 신규 서버 대상 경로에 없음 | 복사 | +| 수정 파일 | 크기 또는 최종 수정 시간이 다름 | 다시 복사 | +| 변화 없음 | 경로·크기·수정 시간이 같음 | 재복사하지 않음 | +| 레거시에서 삭제됨 | 신규에는 남아 있을 수 있음 | 자동 삭제 금지, 목록 검토 후 별도 결정 | + +Windows 레거시 서버에서 Linux 운영 서버로 옮길 때는 WinSCP/SFTP 동기화 또는 SSH 기반 증분 동기화를 사용한다. 전송 전에는 반드시 예정 파일 목록을 미리 보고, **삭제 동기화는 켜지 않는다.** + +### 5.3 파일 생성 검증 + +운영 공개 전 다음을 확인한다. + +- 실제 화면에서 고유한 시험 첨부 파일 1개 업로드 +- 컨테이너 내부 경로와 운영 서버의 영속 경로에 같은 파일이 생성됐는지 확인 +- 다운로드 가능 여부 확인 +- 시험 파일을 화면 기능으로 삭제하고 영속 경로에서도 사라졌는지 확인 +- 웹 프로세스의 쓰기 권한 오류가 없는지 로그 확인 + +## 6. 레거시 원본 소스 보관본 + +모든 레거시 폴더를 한 번에 전환하지 않았으므로, 레거시 PC 회수 전 마지막 원본 소스를 읽기 전용 기준본으로 보관한다. 이는 운영 배포물이 아니라, 이후 누락된 호출·메뉴·배치가 발견될 때 비교하고 추가 전환하기 위한 근거다. + +```text +/opt/jang-archive/legacy-source/YYYYMMDD-cutover/ +├─ legacy-htdocs-source-YYYYMMDD.zip +├─ legacy-htdocs-source-YYYYMMDD.zip.sha256 +├─ MANIFEST.txt +└─ README.md +``` + +| 포함 | 제외 또는 별도 보관 | +| --- | --- | +| PHP·JS·CSS·템플릿·정적 소스 | `intranet_file`, `factory_file` 업무 파일 | +| 전환 후보가 될 수 있는 레거시 모듈 | DB dump | +| 원본 구조를 설명하는 문서·목록 | 비밀번호·토큰·개인키 | +| | 로그·캐시·임시파일·개발 산출물 | + +보관본은 웹 문서 루트·Docker 마운트 경로·Git 저장소에 두지 않는다. 운영 서버 보관본 외에도 별도 백업 저장소에 동일 파일과 SHA-256 파일을 한 부 더 보관한다. 스테이징에는 상시 보관하지 않는다. + +추가 전환이 필요해질 때의 원칙은 다음과 같다. + +```text +보관본을 별도 작업 공간에 복사·해제 + ↓ +현재 main과 비교 + ↓ +필요한 범위만 전용 브랜치에서 PHP 8 전환·테스트 + ↓ +PR 검토·병합·배포 +``` + +## 7. 전환 당일 실행 타임라인 + +| 시점 | 담당 | 작업 | 중단/확인 기준 | +| --- | --- | --- | --- | +| D-7 ~ D-1 | 개발·운영 | main 배포 후보, Compose·환경 변수, 영속 경로, 접근 권한 확인 | 미확정 경로·비밀값은 전환 금지 | +| D-7 ~ D-1 | DB·업무 | 1차 DB·파일 이관 및 스테이징 검증 | 핵심 기능 실패 시 원인 해결 | +| D-1 | 운영 | 롤백 연락망·담당자·도메인 전환 절차 확정 | 책임자 미지정 시 전환 연기 | +| T-시작 | 업무 책임자 | 레거시 입력·결재·파일 업로드 동결 공지 | 동결 확인 전 최종 이관 금지 | +| T+ | DB 책임자 | 최종 DB dump 및 신규 DB 복원 | 복원 실패·검증 실패 시 중단 | +| T+ | 운영 책임자 | 최종 변경 파일 동기화 및 권한 확인 | 파일 수·대표 파일 불일치 시 중단 | +| T+ | 개발·QA | 신규 Docker 기동, 핵심 업무 smoke test | Fatal/Parse·로그인·파일생성 실패 시 롤백 판단 | +| T+ | 인프라 | 도메인·프록시를 신규 서버로 전환 | 전환 전 승인 필요 | +| T+ | 업무·QA | 실사용자 핵심 시나리오 확인 | 결재·첨부·PDF·Excel 등 확인 | +| T+1일 이후 | 운영 | 로그·오류·업무 파일 생성 상태 관찰 | 레거시 회수 전 안정성 확인 | + +## 8. 공개 전 최소 업무 확인 목록 + +| 분야 | 최소 확인 | +| --- | --- | +| 인증 | 지정 계정 로그인·권한 경계·세션 | +| 7개 서비스 | 메뉴 접근·핵심 조회·필수 입력 흐름 | +| 전자결재 | 기안·결재선·처리 상태·결재자 표시 | +| 파일 | 첨부 업로드·다운로드·삭제·영속 경로 생성 | +| 문서 | PDF 생성·다운로드·한글 표시 | +| 공장관리 | Excel·PDF·`factory_file` 생성 및 조회 | +| API | `apiLibrary` 호출·로그 생성·오류 처리 | +| 기술 상태 | PHP Fatal/Parse/Warning/Deprecated, 웹·DB 로그 | + +상세 서비스별 Unit/characterization·통합 테스트 기준은 [`00-service-validation-standard.md`](../00-service-validation-standard.md)를 따른다. + +## 9. 롤백 원칙 + +레거시 서버는 신규 서버 공개 직후 바로 회수하지 않는다. 최소 관찰 기간과 롤백 기준을 회의에서 확정한다. + +| 상황 | 기본 조치 | +| --- | --- | +| 로그인·DB 연결·핵심 메뉴가 동작하지 않음 | 신규 공개 중단 또는 레거시 경로로 복귀 검토 | +| 업로드 파일이 저장되지 않음 | 쓰기 중지, 영속 경로·권한 점검, 필요 시 롤백 | +| DB 최종 복원 데이터가 기준과 다름 | 신규 쓰기 중지, DB 책임자 판단 전 공개 금지 | +| 일부 비핵심 기능만 실패 | 영향·우회 방법·수정 일정 기록 후 책임자 승인으로 제한 운영 여부 결정 | + +> 롤백 뒤 신규 서버에서 생성된 데이터가 있다면, 단순히 서버만 되돌릴 수 없다. DB와 파일의 추가분을 어떻게 처리할지 DB·업무 책임자가 결정해야 한다. + +## 10. 회의 종료 전 확정 체크리스트 + +- [ ] 전환 범위와 제외 범위를 확정했다. +- [ ] 운영 배포 기준 main 커밋 SHA와 승인자를 정했다. +- [ ] 운영 DB·업무 파일·로그의 실제 영속 경로를 정했다. +- [ ] 파일 1차 이관 및 최종 동기화 담당자와 방법을 정했다. +- [ ] DB 최종 dump·복원·검증 담당자와 동결 시각을 정했다. +- [ ] 도메인/프록시 전환 담당자와 공개 확인 절차를 정했다. +- [ ] 롤백 기준, 레거시 보존 기간, 연락망을 정했다. +- [ ] 레거시 최종 원본 소스 보관본과 별도 백업본의 위치를 정했다. +- [ ] 공개 전 최소 업무 확인 항목과 업무 승인자를 정했다. + +## 11. 회의 후 보완할 정보 + +아래 값은 회의에서 확정한 뒤 별도 보안 문서 또는 운영 환경 설정에만 기록한다. + +- 운영 서버 접속·배포 방식과 담당자 +- 실제 호스트 경로와 소유자/권한 +- DB dump 저장 위치와 복원 명령 +- 도메인·TLS·프록시 전환 정보 +- 백업 저장소 위치와 보존 기간 +- 전환 일시, 동결 공지 문구, 비상 연락망 +