김주무관의 전자정부프레임워크 Next.js 변환기전자정부프레임워크 Next.js 전환 FAQ

FAQ 별책

전자정부프레임워크 Next.js 전환 FAQ

한 번에 펼쳐 읽기

전환을 검토하는 실무자, 운영자와 의사결정자가 가장 자주 묻는 질문을 한 편에 모았다.

이 FAQ의 답은 “Next.js*로 바꾸면 무조건 빠르고 싸진다”는 홍보 문구가 아니다. 이 프로젝트에서 조사·구현·병행 운영·30일 안정화를 거치며 확인한 원칙과 공식 문서를 바탕으로 작성했다.

제품 버전, Oracle* 라이선스, 보안 규정과 조직의 업무 조건은 기관마다 다르다. 실제 적용 전에는 운영 중인 버전의 공식 문서와 내부 규정을 다시 확인해야 한다.

전환 과정에서 나온 실무 질문을 한자리에 모아 답하는 정보시스템팀

1. 전환 판단

Q1. 전자정부 표준프레임워크*를 Next.js로 바꾸면 무엇이 좋아집니까?

반복되는 Java* 계층과 JSP* 화면 코드를 줄이고 TypeScript*로 API*와 화면의 계약을 가까이 둘 수 있다. Server Component*, Route Handler*와 Client Component*를 업무 특성에 맞게 조합할 수 있고, Node.js* 중심으로 빌드*·테스트 도구를 통일할 수 있다.

그러나 업무 규칙, Oracle SQL*과 보안 책임이 사라지는 것은 아니다. 이 프로젝트에서 확인한 개선은 Next.js라는 이름 하나가 아니라 다음 변경이 함께 만든 결과였다.

불필요한 SQL 열과 호출 횟수 정리
API 계약과 자동 비교
JSP·jQuery* 화면의 컴포넌트*화
로그*·메트릭*·요청 ID* 연결
Jenkins*의 반복 가능한 배포

Q2. Java보다 Node.js가 항상 가볍고 빠릅니까?

아니다. 런타임만 보고 결론 내릴 수 없다. JVM* heap*, JEUS* 설정, Node.js 프로세스 수, 캐시*, SQL, 동시 사용자와 서버 사양을 같은 조건에서 측정해야 한다.

이 이야기의 시스템에서는 일부 API와 화면이 빨라지고 애플리케이션 메모리가 줄었지만, Oracle 실행 시간이 대부분인 대금 현황은 차이가 작았다. 다른 시스템에서도 같은 수치가 나온다는 보장은 없다.

Q3. Next.js는 프론트엔드 전용 아닙니까?

아니다. Next.js는 React* 화면뿐 아니라 Node.js 서버에서 실행되는 Route Handler, Server Component, 인증과 동적 렌더링*도 제공한다.

브라우저
  → Nginx
  → Next.js Node.js 서버
      ├─ 화면 렌더링
      ├─ /api/v1 Route Handler
      ├─ 인증·권한·업무 Service
      └─ Oracle Repository

다만 브라우저에서 실행할 코드와 서버에서만 실행할 코드를 분명하게 나눠야 한다. DB* 비밀번호와 Oracle 연결 코드는 Client Component에 들어가면 안 된다.

Q4. 전자정부 표준프레임워크를 한 번에 전부 다시 만드는 것이 빠르지 않습니까?

대부분의 복잡한 업무 시스템에서는 위험이 크다. 이 프로젝트는 Nginx*를 앞에 두고 /leg/와 /new/를 나눈 뒤, 검증을 통과한 기능부터 옮겼다.

이는 공개된 레거시 현대화 방식인 Strangler Fig Pattern*과 같은 점진 전환 원칙이다. Martin Fowler와 Microsoft의 설명도 기존 시스템 옆에 신규 기능을 만들고, 프록시를 통해 기능별로 트래픽을 옮긴 뒤 의존성*이 사라지면 레거시를 종료하는 흐름을 제시한다.

기존 시스템의 기능을 하나씩 신규 시스템으로 옮기는 점진 전환 구조

Q5. 어느 시스템이 전환 대상인지 어떻게 판단합니까?

화면 수만 세지 않는다. 다음을 먼저 조사한다.

업무 상태와 승인 절차
사용자·조직·업체별 권한
MyBatis* 동적 SQL*과 Oracle 전용 문법
프로시저*, 트리거*, DB 링크*와 배치
첨부·엑셀·결재·메일 등 외부 연계
월말·연말 집중 업무
현재 오류율·p50·p95·p99*와 자원 사용량
원복*과 서비스 중단 가능 시간

규모가 작아 보여도 프로시저와 외부 연계가 많으면 난도가 높을 수 있다.

Q6. 기존 디자인도 전부 새로 만들어야 합니까?

그럴 필요는 없다. 이 프로젝트는 사용자가 업무와 화면을 동시에 다시 배우지 않도록 기존 메뉴, 검색 조건, 표의 열 순서와 주요 버튼 위치를 먼저 보존했다.

JSP·Tiles 구조는 Next.js layout.tsx와 React 컴포넌트로 옮겼다. 기능 전환이 안정된 뒤 별도 사용자 조사에 따라 디자인을 개선하는 편이 위험이 낮다.

2. Oracle과 SQL

Q7. Oracle 데이터베이스도 바꿔야 합니까?

아니다. 이 프로젝트는 기존 Oracle 하나를 계속 사용한다.

기존 Spring·MyBatis ─┐
                     ├→ 같은 Oracle
신규 Next.js·Knex  ──┘

전환 기간에 애플리케이션은 둘이지만 데이터 원본을 두 벌로 만들지 않았다. 쓰기 기능은 메뉴별로 한 시스템만 책임졌다.

Q8. 왜 Prisma 대신 Knex와 node-oracledb를 사용합니까?

도구 이름보다 현재 Oracle 버전, 지원 범위와 기존 SQL의 복잡성이 중요하다. 이 프로젝트는 Knex의 oracledb dialect와 Oracle 공식 Node.js 드라이버*인 node-oracledb를 사용했다.

Knex 공식 안내에는 oracledb 설치와 설정, Oracle의 DATE, NUMBER, CLOB 반환 방식을 조정하는 fetchAsString이 설명되어 있다. Knex로 표현하기 어려운 Oracle 전용 SQL과 프로시저는 바인드 변수*를 사용한 명시적 SQL로 유지했다.

특정 ORM*의 Oracle 지원 여부는 버전마다 바뀔 수 있으므로 도입 시점의 공식 지원 목록과 제한을 다시 확인한다.

Q9. MyBatis의 `<if>` 같은 동적 SQL을 Knex에서도 만들 수 있습니까?

가능하다. Query Builder 객체에 조건별로 where, whereIn, join 등을 추가한다.

const query = knex("PROJECT")
  .select("PROJECT_ID", "PROJECT_NAME")
  .where("USE_YN", "Y");

if (criteria.ownerId) {
  query.andWhere("OWNER_ID", criteria.ownerId);
}

if (criteria.statuses?.length) {
  query.whereIn("STATUS", criteria.statuses);
}

가상의 .if() 문법을 기대하기보다 TypeScript의 if와 함수 조합을 사용한다. 조건이 복잡하면 이름 있는 함수로 분리해 어떤 권한·검색 조건이 붙는지 테스트한다.

Q10. 기존 SQL과 신규 SQL의 글자가 완전히 같아야 합니까?

아니다. Knex가 별칭, 괄호와 바인드 표현을 다르게 만들 수 있다.

판정은 다음처럼 나눈다.

SAME: 정규화한 SQL 구조와 결과가 같음
EQUIVALENT: SQL 모양은 다르지만 바인드·권한·업무 결과가 동등함
DIFFERENT: 조건, 정렬, 건수나 값이 허용 없이 다름

우연히 샘플 결과 몇 건이 같은 것만으로 통과시키지 않는다. 실행 계획*, 경계값과 권한 조건도 확인한다.

Q11. 프로시저와 Oracle 전용 문법도 모두 Knex로 바꿔야 합니까?

아니다. CONNECT BY, 복잡한 힌트, 패키지 프로시저와 성능 중요 SQL을 억지로 Query Builder로 바꾸면 오히려 읽기 어려울 수 있다.

Knex의 raw 또는 node-oracledb의 execute에 바인드 변수를 사용하고 Repository* 안에 격리한다. 문자열 연결로 사용자 입력을 SQL에 붙이지 않는다.

Q12. Oracle 연결은 요청마다 새로 만듭니까?

아니다. 애플리케이션 시작 시 연결 풀*을 만들고 요청마다 연결을 빌린 뒤 반드시 반환한다.

node-oracledb 공식 문서는 oracledb.createPool(), pool.getConnection()과 사용 후 connection.close()를 권장한다. poolMin, poolMax, 대기 시간은 Oracle 세션* 한도와 실제 동시 부하를 측정해 정한다.

연결을 반환하지 않으면 풀이 고갈되어 새 요청이 기다리거나 실패할 수 있다.

Q13. 트랜잭션* 방식은 Spring*과 같습니까?

개념은 같지만 구현은 자동으로 같아지지 않는다. Service*가 트랜잭션 경계를 정하고 같은 connection 또는 Knex transaction 객체를 모든 Repository에 전달해야 한다.

오류가 발생하면 rollback*하고, 성공했을 때만 commit*한다. 감사 기록이 업무 변경과 같은 트랜잭션에 들어가야 한다면 파일 로그만 남겨서는 안 된다.

Knex의 일부 transaction 옵션은 Oracle에서 지원되지 않을 수 있으므로 공식 문서와 실제 Oracle 격리 수준을 확인한다.

3. 화면·렌더링*·보안

Q14. Next.js 화면은 모두 브라우저에서 그립니까?

아니다. 정적 렌더링*, 동적 서버 렌더링, Server Component와 Client Component를 함께 사용할 수 있다.

공개 도움말: 정적 렌더링 가능
사용자별 프로젝트 목록: 요청 시 권한을 확인하는 동적 경로
검색 폼·모달: 필요한 범위만 Client Component

정적·동적은 결과를 언제 만드는지에 대한 구분이고, Server·Client Component는 코드가 어디서 실행되는지에 대한 구분이다.

Q15. 사용자별 ERP 화면을 정적 페이지로 만들면 더 빠르지 않습니까?

권한별 데이터가 섞일 위험이 있다. 프로젝트, 계약, 금액, 인력과 결재 화면은 로그인* 사용자와 역할을 서버에서 확인해야 한다.

캐시를 적용하려면 사용자·조직·업체별 키, 권한 변경, 로그아웃과 개인정보 저장 여부를 먼저 설계해야 한다. 성능을 위해 사용자별 업무 데이터를 공개 정적 파일로 만들면 안 된다.

Q16. jQuery는 보안에 취약하므로 모두 제거해야 합니까?

jQuery라는 이름 자체가 곧 취약점은 아니다. 위험은 지원이 끝난 구버전, 검증되지 않은 플러그인, 문자열을 .html()이나 .append()에 넣는 DOM* 조작과 서버 권한 검사 누락에서 생긴다.

React도 dangerouslySetInnerHTML을 잘못 사용하거나 API 권한 검사를 빠뜨리면 취약해진다. 라이브러리를 바꾸는 것과 별개로 XSS*, CSRF*, CSP*와 서버 인가를 검증한다.

Q17. 버튼을 숨기면 권한 제어가 된 것 아닙니까?

아니다. 사용자는 주소나 API를 직접 호출할 수 있다.

버튼 노출은 사용성이고, 최종 권한 판단은 Route Handler와 Service에서 사용자·역할·조직·업체·프로젝트 범위를 검사해야 한다. 권한 없는 호출에는 일관된 401 또는 403 응답을 반환하고 감사 기록을 남긴다.

Q18. `.env` 파일에 비밀번호를 쓰면 자동으로 암호화*됩니까?

아니다. .env는 일반 문자 파일이다.

이 프로젝트는 .env에 ENC[...] 암호문만 두고 마스터 키*는 systemd credential*처럼 별도 경로로 주입했다. 암호문과 키를 같은 파일이나 Jenkins 작업 공간에 두면 분리 효과가 없다.

로그인 비밀번호는 복호화* 가능한 암호화가 아니라 salt*가 있는 검증용 해시*를 사용한다. 설정 비밀번호 암호화와 사용자 비밀번호 해시는 목적이 다르다.

Q19. 전자정부 표준프레임워크의 PBE* 암호문을 그대로 사용할 수 있습니까?

Node.js에서도 호환 구현은 가능하지만 기존 알고리즘, salt, 반복 횟수, 문자 인코딩과 출력 형식을 정확히 알아야 한다.

취약한 과거 알고리즘을 영구히 복제하지 않는다. 테스트 벡터로 한시적 호환성을 검증한 뒤 AES-256-GCM* 같은 승인된 방식으로 재암호화하고 키 교체 절차를 만든다.

4. API 우선 전환과 검증

Q20. 왜 화면보다 API를 먼저 만듭니까?

화면과 데이터를 동시에 바꾸면 차이의 원인을 찾기 어렵다.

먼저 /api/v1의 입력, 응답과 오류를 OpenAPI*로 고정하고 같은 조건으로 Spring·MyBatis와 Next.js API를 비교한다. API가 통과한 뒤 JSP 화면을 TSX*로 옮기면 데이터 차이와 화면 차이를 분리할 수 있다.

Q21. OpenAPI는 인터넷에 공개하는 API라는 뜻입니까?

아니다. OpenAPI는 API 계약을 기계와 사람이 읽을 수 있게 표현하는 표준이다. 폐쇄망* 내부 API에도 사용할 수 있다.

문서 공개 범위는 별도 보안 정책으로 정한다. 운영자용 내부 경로와 예제에 비밀번호, 개인정보와 실제 계약 데이터를 넣지 않는다.

Q22. 기존과 신규 API는 어떻게 비교합니까?

같은 사용자 역할, 검색 조건, 기준 시각과 테스트 데이터를 양쪽에 전달한다.

다음 차이는 정규화할 수 있다.

날짜와 시간대 표현
NULL과 빈 문자열
숫자와 금액 형식
정렬 순서가 계약상 무관한 목록

필드, 행 수, 값, 오류 코드와 페이징을 비교하고 차이를 JSON*과 사람이 읽는 보고서로 남긴다.

Q23. 등록·승인·지급도 양쪽에 동시에 보내 비교합니까?

운영에서는 절대 그렇게 하지 않는다. 중복 등록, 중복 승인과 중복 지급이 발생할 수 있다.

쓰기 기능은 격리된 테스트 데이터, rollback 가능한 트랜잭션, 사전·사후 스냅샷과 감사 기록으로 검증한다. 운영에서는 기능별 쓰기 책임 시스템을 하나만 둔다.

Q24. 로컬 AI*가 비교 프로그램과 변환 코드를 만들면 사람이 검토하지 않아도 됩니까?

아니다. 로컬 AI는 초안 작성과 반복 작업을 돕지만 통과 여부를 결정하지 않는다.

명세와 금지 사항을 먼저 제공한다.
생성된 코드의 타입·테스트·SQL을 검토한다.
AI가 만든 비교기에 의도적인 오류를 넣어 탐지 여부를 시험한다.
담당자와 승인자가 원본 로그를 확인한다.

AI 서비스가 멈춰도 개발·빌드·배포가 가능해야 한다.

5. Nginx와 배포

Q25. JEUS를 제거하면 애플리케이션 서버가 완전히 없어집니까?

Java WAS*는 없어지지만 동적 업무를 실행할 서버 프로세스는 남는다. Next.js의 인증, API와 동적 렌더링은 Node.js에서 실행된다.

사용자 → Nginx → Next.js Node.js → Oracle

Nginx는 TLS*, 요청 제한, 정적 파일과 리버스 프록시*를 담당한다. 업무 Service와 Oracle 처리를 Nginx가 대신하지 않는다.

Q26. Next.js 공식 문서도 Nginx 같은 리버스 프록시를 권장합니까?

그렇다. Next.js 자체 호스팅 안내는 애플리케이션 서버를 인터넷에 직접 노출하기보다 Nginx 같은 리버스 프록시를 앞에 두어 비정상 요청, 느린 연결 공격, 요청 크기와 rate limit*를 처리하도록 권장한다.

streaming*을 사용하면 프록시 buffering* 설정도 확인해야 한다. 여러 인스턴스를 운영할 때는 캐시 공유와 배포 버전 일치도 별도로 설계한다.

Q27. Next.js를 Nginx에서 정적 디렉터리로만 서비스할 수 있습니까?

공개 안내처럼 완전 정적인 사이트는 output: "export"로 만들 수 있다. 그러나 사용자별 인증, cookie*, 동적 Route Handler, Server Action과 요청 시 Oracle 조회가 필요한 ERP 전체에는 맞지 않는다.

이 프로젝트는 Node.js 서버를 실행하고 Nginx가 내부 포트로 전달한다. 정적 파일과 동적 요청의 책임을 구분한다.

Q28. `next dev`를 테스트베드*나 운영계에서 사용하면 안 됩니까?

안 된다. 개발 모드는 파일 감시, Fast Refresh*, 개발용 오류와 요청 시 컴파일을 포함하므로 운영 성능과 결과물을 대표하지 않는다.

테스트베드와 운영계에서는 next build로 만든 production* 결과물을 next start 또는 standalone* server.js로 실행한다. 화면에 개발 도구 표시가 보이면 실행 모드부터 확인한다.

Q29. standalone 결과물만 복사하면 됩니까?

Next.js 공식 output 안내에 따르면 .next/standalone은 필요한 런타임 파일과 최소 server.js를 만든다. public과 .next/static은 기본적으로 자동 복사되지 않으므로 배포 방식에 따라 함께 복사하거나 별도 정적 서버에서 제공해야 한다.

이 프로젝트는 배포 스크립트에 해당 파일 복사, 해시 확인과 health check*를 포함했다.

Q30. `/leg/`와 `/new/`를 함께 운영할 때 가장 자주 틀리는 것은 무엇입니까?

다음 항목을 특히 주의한다.

proxy_pass 끝의 /에 따른 경로 보존·제거
Next.js basePath
JSP의 루트 절대 경로와 리다이렉트*
JSESSIONID와 신규 session cookie 충돌
두 시스템의 쓰기 책임 중복
업로드 크기와 다운로드 권한
로그인 후 원래 주소 복귀

같은 Oracle을 사용해도 애플리케이션 경로와 session은 분리할 수 있다.

Q31. Jenkins가 운영까지 자동 배포하면 위험하지 않습니까?

검증과 복사를 자동화하되 운영 승인은 사람에게 남길 수 있다. Jenkins 공식 Pipeline* 문서는 input 단계로 실행을 멈추고 승인된 사용자의 확인을 기다리는 방식을 제공한다.

Jenkinsfile*은 소스와 함께 버전 관리하고, Build Agent*는 폐쇄망 내부 저장소만 사용한다. 테스트베드에서 통과한 같은 artifact*를 운영으로 승격하며 운영 서버에서 다시 빌드하지 않는다.

Q32. Jenkins에 운영 비밀번호를 넣어도 됩니까?

가능하면 Jenkins가 운영 비밀 원문을 운반하지 않게 설계한다. 대상 서버의 systemd credential이나 승인된 비밀 관리 경로에서 실행 시점에 읽도록 한다.

Jenkins credential을 사용해야 한다면 최소 권한, 승인된 binding, 로그 마스킹과 작업 공간 정리를 적용한다. 콘솔에 전체 환경 변수*를 출력하지 않는다.

Q33. 배포에 실패하면 어떻게 원복합니까?

release*별 디렉터리에 새 결과물을 풀고 health check가 성공한 뒤 current 링크나 Nginx upstream*을 전환한다.

실패하면 previous 신규 release로 되돌린다. 데이터 쓰기가 시작된 뒤에는 파일만 되돌리지 않고 Oracle 데이터, 중복 요청과 감사 이력을 확인한다.

6. 성능과 로그

Q34. Next.js에도 Log4j* 같은 로그 도구가 있습니까?

있다. 이 프로젝트는 Pino*로 요청, 업무, 오류, SQL, 보안, 감사와 외부 연계 로그를 구조화했다.

Pino 파일만으로 모든 감사를 해결하지는 않는다. 중요한 상태 변경은 Oracle 감사 테이블에 같은 트랜잭션으로 저장하고, Nginx와 애플리케이션 로그는 요청 ID로 연결한다.

Q35. 로그의 시작 시각과 종료 시각을 빼면 성능을 알 수 있습니까?

대략적인 추적은 가능하지만 정확한 경과 시간은 단조 시계*로 측정한 duration_ms를 사용한다. 시스템 시각 보정과 로그 전송 지연이 벽시계 차이에 영향을 줄 수 있기 때문이다.

Nginx의 request_time, 애플리케이션 전체 시간, Service, DB 대기와 SQL 시간을 분리하면 병목 구간을 찾기 쉽다.

Q36. p50·p95·p99는 무엇입니까?

요청을 빠른 순서로 놓았을 때 해당 비율이 완료된 시간이다.

p50: 절반이 이 시간 안에 완료된 중앙값
p95: 95%가 이 시간 안에 완료
p99: 99%가 이 시간 안에 완료

평균만 보면 일부 매우 느린 요청이 가려질 수 있다. p95와 p99는 느린 사용자의 경험을 확인하는 데 유용하지만 표본 수와 오류율도 함께 봐야 한다.

Q37. 서버 API가 빨라지면 사용자가 느끼는 화면도 빨라집니까?

반드시 그렇지는 않다. JavaScript* 크기, 브라우저 렌더링, 연속 API 호출과 큰 표 때문에 화면이 느릴 수 있다.

서버 p50·p95·p99와 함께 LCP*, INP, CLS, 업무 완료 시간, 오류와 재시도 횟수를 측정한다. 사용자의 “느리다”는 문의를 요청 ID와 연결해 서버·DB·브라우저 중 어느 구간인지 확인한다.

Q38. 성능 차이는 언제 수집해야 합니까?

레거시를 끈 뒤에는 같은 시점의 실제 사용자 비교 자료를 만들 수 없다. 병행 운영 기간에 같은 업무 ID, 비슷한 역할·데이터량·시간대와 동시 부하를 맞춰 수집해야 한다.

SQL 개선, 화면 개선, 런타임 차이와 서버 구성 차이를 구분한다. 측정 뒤 유리한 기준을 새로 만들지 말고 전환 전에 승인 기준을 정한다.

Q39. AWR*과 ASH를 바로 사용해도 됩니까?

Oracle AWR·ASH와 일부 진단 기능은 별도 Diagnostic Pack* 라이선스가 필요할 수 있다. 계약과 라이선스를 확인하지 않고 사용하지 않는다.

사용 권한이 없다면 승인된 동적 성능 뷰, 애플리케이션 구간 측정과 기존 모니터링 도구를 사용한다.

7. 폐쇄망과 공급망

Q40. 인터넷이 없는 환경에서 Next.js 패키지를 어떻게 설치합니까?

외부 준비 구역에서 승인된 버전과 잠금 파일*에 맞는 패키지를 수집하고 해시·라이선스·취약점을 검사한 뒤 내부 패키지 저장소로 반입한다.

폐쇄망 Build Agent에서는 다음처럼 잠금 파일을 강제하고 오프라인 설치를 사용한다.

pnpm install --offline --frozen-lockfile

개발자마다 USB로 임의 패키지를 반입하지 않는다.

Q41. 패키지를 한 번 반입했으면 계속 안전합니까?

아니다. 새 취약점은 나중에 공개될 수 있다.

정기 취약점 정보 반입
잠금 파일과 SBOM* 보관
패키지 해시와 서명 확인
더 이상 지원되지 않는 버전 조사
긴급 보안 패치 절차

업데이트가 필요하다고 운영 서버에서 인터넷을 임시로 열지 않는다.

Q42. 로컬 AI를 사용하면 소스가 자동으로 안전해집니까?

외부 전송 위험은 줄일 수 있지만 내부 권한, 모델 로그와 프롬프트에 비밀이 들어가는 위험은 남는다.

운영 개인정보·비밀번호·개인키·실제 계약 데이터를 입력하지 않는다. AI가 만든 코드도 같은 보안 검사, 테스트와 동료 검토를 통과해야 한다.

8. 일정·조직·종료

Q43. 전환 기간은 화면 수로 계산하면 됩니까?

안 된다. 동적 SQL 조합, 프로시저, 외부 연계, 권한 수, 첨부와 월말 업무가 더 큰 변수다.

일정 약속 전에 기능·SQL·데이터·보안·운영 조사를 수행하고 API 비교가 끝난 범위만 화면 일정으로 넘긴다.

Q44. 외주업체에 전체를 맡기면 내부 인력이 없어도 됩니까?

어렵다. 외주업체는 구현을 도울 수 있지만 업무 규칙, 권한 해석, 운영 승인과 데이터 책임은 발주 조직에 남는다.

내부 담당자는 최소한 다음을 소유해야 한다.

OpenAPI와 업무 규칙
Oracle 계정·권한과 데이터 책임
테스트 승인과 중단 기준
소스·Jenkinsfile·SBOM과 배포 기록
장애·원복·백업 문서

Q45. 운영 중 수정이 계속되면 레거시를 영원히 못 끄는 것 아닙니까?

신규 시스템 수정은 정상적인 운영 활동이다. 중요한 것은 수정이 개발계, 테스트베드와 자동 Pipeline을 거쳐 같은 release로 배포되는지다.

이 프로젝트는 전면 오픈 후 30일 동안 수정·배포를 계속하면서 데이터·권한·오류·성능과 저빈도 업무를 관찰했다. 종료 조건을 통과한 D+30에 JEUS를 내렸다.

Q46. 왜 30일입니까?

모든 프로젝트에 30일이 정답은 아니다. 이 프로젝트에서는 월간 업무 주기, 저빈도 업무 확인과 조직의 원복 정책을 고려해 정한 안정화 기간이었다.

30일은 시간이 지나면 자동 종료되는 날짜가 아니라 최종 승인 시점이다. 월말 업무가 실행되지 않았거나 중대 오류가 남았다면 연장해야 한다.

Q47. JEUS를 종료하면 자료도 모두 삭제합니까?

아니다. 실행 서비스와 일상적 원복 의존은 끝내되 다음을 승인된 기간 동안 보존한다.

최종 WAR*와 소스 식별자
JEUS와 애플리케이션 설정
MyBatis XML·배치·외부 연계 목록
JDK·라이브러리·라이선스 버전
배포·기동·종료와 복구 절차
감사 로그 위치와 파일 해시

비밀번호와 개인키는 보존 묶음에 넣지 않고 필요할 때 새로 발급받는다.

Q48. Oracle도 함께 종료합니까?

아니다. 이 프로젝트의 업무 데이터 원본은 계속 Oracle에 있다.

레거시 전용 DB 계정과 불필요한 권한·방화벽 규칙은 종료하고, 신규 계정의 최소 권한과 연결 풀을 유지한다. 신규 DB로 데이터를 다시 옮기는 사업은 별도 범위다.

Q49. 전환 성공을 무엇으로 판단합니까?

기술 이름이 아니라 다음 결과로 판단한다.

데이터·권한·감사 기록의 허용되지 않은 차이 0건
핵심 업무 완료율과 오류율 기준 통과
성능·자원·사용자 경험의 측정 가능한 결과
반복 가능한 빌드·배포·원복
보안·백업·복구와 운영 인수
특정 담당자의 야근과 기억에 의존하지 않는 운영

팀 전체가 정시에 퇴근할 수 있어야 전환이 끝났다는 마지막 원칙도 여기에 포함된다.

9. 실패를 줄이는 시작 순서

Q50. 지금 시작한다면 무엇부터 해야 합니까?

다음 순서를 권한다.

1. 업무·화면·권한·SQL·연계 목록 작성
2. 현재 데이터 결과와 성능 기준선 수집
3. Oracle은 유지하고 목표 구조 확정
4. /api/v1 OpenAPI 계약 작성
5. MyBatis·Next.js 자동 비교기 구축
6. 조회 API부터 결과 일치 확인
7. 쓰기 트랜잭션·감사·중복 방지 검증
8. 통과한 API의 JSP를 TSX로 변환
9. Nginx에서 기존·신규 경로 병행 운영
10. 사용자 경험과 성능 비교
11. Jenkins로 같은 release 승격 자동화
12. 안정화 조건 통과 뒤 JEUS 종료

가장 먼저 화면을 예쁘게 다시 만드는 순서는 권하지 않는다. 데이터와 권한이 같은지 증명할 방법부터 만든다.

10. 참고 자료

다음 공개 자료의 원칙을 FAQ에 반영했다.

Next.js 자체 호스팅 안내: https://nextjs.org/docs/app/guides/self-hosting
Next.js standalone output: https://nextjs.org/docs/app/api-reference/config/next-config-js/output
Next.js 정적 export의 지원 범위: https://nextjs.org/docs/app/guides/static-exports
node-oracledb 연결과 연결 풀: https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html
Knex 설치와 Oracle dialect: https://knexjs.org/guide/
Knex Query Builder: https://knexjs.org/guide/query-builder
Knex transaction 지원 범위: https://knexjs.org/guide/transactions
Jenkins Pipeline 문법과 승인 단계: https://www.jenkins.io/doc/book/pipeline/syntax/
Jenkins Pipeline as Code: https://www.jenkins.io/doc/book/pipeline/pipeline-as-code/
Martin Fowler의 Strangler Fig Application: https://martinfowler.com/bliki/StranglerFigApplication.html
Microsoft의 Strangler Fig Pattern 설명: https://learn.microsoft.com/azure/architecture/patterns/strangler-fig

공개 사례와 공식 문서는 방향을 정하는 참고 자료다. 실제 전환 승인은 이 시스템의 데이터 비교, 보안 검토와 운영 시험 결과로 내려야 한다.

— FAQ 별책 끝 —다음 · 주석 별책전산 전문 용어 주석 별책

FAQ 별책

전자정부프레임워크 Next.js 전환 FAQ

한 번에 펼쳐 읽기

전환을 검토하는 실무자, 운영자와 의사결정자가 가장 자주 묻는 질문을 한 편에 모았다.

이 FAQ의 답은 “Next.js*로 바꾸면 무조건 빠르고 싸진다”는 홍보 문구가 아니다. 이 프로젝트에서 조사·구현·병행 운영·30일 안정화를 거치며 확인한 원칙과 공식 문서를 바탕으로 작성했다.

제품 버전, Oracle* 라이선스, 보안 규정과 조직의 업무 조건은 기관마다 다르다. 실제 적용 전에는 운영 중인 버전의 공식 문서와 내부 규정을 다시 확인해야 한다.

전환 과정에서 나온 실무 질문을 한자리에 모아 답하는 정보시스템팀

1. 전환 판단

Q1. 전자정부 표준프레임워크*를 Next.js로 바꾸면 무엇이 좋아집니까?

반복되는 Java* 계층과 JSP* 화면 코드를 줄이고 TypeScript*로 API*와 화면의 계약을 가까이 둘 수 있다. Server Component*, Route Handler*와 Client Component*를 업무 특성에 맞게 조합할 수 있고, Node.js* 중심으로 빌드*·테스트 도구를 통일할 수 있다.

그러나 업무 규칙, Oracle SQL*과 보안 책임이 사라지는 것은 아니다. 이 프로젝트에서 확인한 개선은 Next.js라는 이름 하나가 아니라 다음 변경이 함께 만든 결과였다.

불필요한 SQL 열과 호출 횟수 정리
API 계약과 자동 비교
JSP·jQuery* 화면의 컴포넌트*화
로그*·메트릭*·요청 ID* 연결
Jenkins*의 반복 가능한 배포

Q2. Java보다 Node.js가 항상 가볍고 빠릅니까?

아니다. 런타임만 보고 결론 내릴 수 없다. JVM* heap*, JEUS* 설정, Node.js 프로세스 수, 캐시*, SQL, 동시 사용자와 서버 사양을 같은 조건에서 측정해야 한다.

이 이야기의 시스템에서는 일부 API와 화면이 빨라지고 애플리케이션 메모리가 줄었지만, Oracle 실행 시간이 대부분인 대금 현황은 차이가 작았다. 다른 시스템에서도 같은 수치가 나온다는 보장은 없다.

Q3. Next.js는 프론트엔드 전용 아닙니까?

아니다. Next.js는 React* 화면뿐 아니라 Node.js 서버에서 실행되는 Route Handler, Server Component, 인증과 동적 렌더링*도 제공한다.

브라우저
  → Nginx
  → Next.js Node.js 서버
      ├─ 화면 렌더링
      ├─ /api/v1 Route Handler
      ├─ 인증·권한·업무 Service
      └─ Oracle Repository

다만 브라우저에서 실행할 코드와 서버에서만 실행할 코드를 분명하게 나눠야 한다. DB* 비밀번호와 Oracle 연결 코드는 Client Component에 들어가면 안 된다.

Q4. 전자정부 표준프레임워크를 한 번에 전부 다시 만드는 것이 빠르지 않습니까?

대부분의 복잡한 업무 시스템에서는 위험이 크다. 이 프로젝트는 Nginx*를 앞에 두고 /leg/와 /new/를 나눈 뒤, 검증을 통과한 기능부터 옮겼다.

이는 공개된 레거시 현대화 방식인 Strangler Fig Pattern*과 같은 점진 전환 원칙이다. Martin Fowler와 Microsoft의 설명도 기존 시스템 옆에 신규 기능을 만들고, 프록시를 통해 기능별로 트래픽을 옮긴 뒤 의존성*이 사라지면 레거시를 종료하는 흐름을 제시한다.

기존 시스템의 기능을 하나씩 신규 시스템으로 옮기는 점진 전환 구조

Q5. 어느 시스템이 전환 대상인지 어떻게 판단합니까?

화면 수만 세지 않는다. 다음을 먼저 조사한다.

업무 상태와 승인 절차
사용자·조직·업체별 권한
MyBatis* 동적 SQL*과 Oracle 전용 문법
프로시저*, 트리거*, DB 링크*와 배치
첨부·엑셀·결재·메일 등 외부 연계
월말·연말 집중 업무
현재 오류율·p50·p95·p99*와 자원 사용량
원복*과 서비스 중단 가능 시간

규모가 작아 보여도 프로시저와 외부 연계가 많으면 난도가 높을 수 있다.

Q6. 기존 디자인도 전부 새로 만들어야 합니까?

그럴 필요는 없다. 이 프로젝트는 사용자가 업무와 화면을 동시에 다시 배우지 않도록 기존 메뉴, 검색 조건, 표의 열 순서와 주요 버튼 위치를 먼저 보존했다.

JSP·Tiles 구조는 Next.js layout.tsx와 React 컴포넌트로 옮겼다. 기능 전환이 안정된 뒤 별도 사용자 조사에 따라 디자인을 개선하는 편이 위험이 낮다.

2. Oracle과 SQL

Q7. Oracle 데이터베이스도 바꿔야 합니까?

아니다. 이 프로젝트는 기존 Oracle 하나를 계속 사용한다.

기존 Spring·MyBatis ─┐
                     ├→ 같은 Oracle
신규 Next.js·Knex  ──┘

전환 기간에 애플리케이션은 둘이지만 데이터 원본을 두 벌로 만들지 않았다. 쓰기 기능은 메뉴별로 한 시스템만 책임졌다.

Q8. 왜 Prisma 대신 Knex와 node-oracledb를 사용합니까?

도구 이름보다 현재 Oracle 버전, 지원 범위와 기존 SQL의 복잡성이 중요하다. 이 프로젝트는 Knex의 oracledb dialect와 Oracle 공식 Node.js 드라이버*인 node-oracledb를 사용했다.

Knex 공식 안내에는 oracledb 설치와 설정, Oracle의 DATE, NUMBER, CLOB 반환 방식을 조정하는 fetchAsString이 설명되어 있다. Knex로 표현하기 어려운 Oracle 전용 SQL과 프로시저는 바인드 변수*를 사용한 명시적 SQL로 유지했다.

특정 ORM*의 Oracle 지원 여부는 버전마다 바뀔 수 있으므로 도입 시점의 공식 지원 목록과 제한을 다시 확인한다.

Q9. MyBatis의 `<if>` 같은 동적 SQL을 Knex에서도 만들 수 있습니까?

가능하다. Query Builder 객체에 조건별로 where, whereIn, join 등을 추가한다.

const query = knex("PROJECT")
  .select("PROJECT_ID", "PROJECT_NAME")
  .where("USE_YN", "Y");

if (criteria.ownerId) {
  query.andWhere("OWNER_ID", criteria.ownerId);
}

if (criteria.statuses?.length) {
  query.whereIn("STATUS", criteria.statuses);
}

가상의 .if() 문법을 기대하기보다 TypeScript의 if와 함수 조합을 사용한다. 조건이 복잡하면 이름 있는 함수로 분리해 어떤 권한·검색 조건이 붙는지 테스트한다.

Q10. 기존 SQL과 신규 SQL의 글자가 완전히 같아야 합니까?

아니다. Knex가 별칭, 괄호와 바인드 표현을 다르게 만들 수 있다.

판정은 다음처럼 나눈다.

SAME: 정규화한 SQL 구조와 결과가 같음
EQUIVALENT: SQL 모양은 다르지만 바인드·권한·업무 결과가 동등함
DIFFERENT: 조건, 정렬, 건수나 값이 허용 없이 다름

우연히 샘플 결과 몇 건이 같은 것만으로 통과시키지 않는다. 실행 계획*, 경계값과 권한 조건도 확인한다.

Q11. 프로시저와 Oracle 전용 문법도 모두 Knex로 바꿔야 합니까?

아니다. CONNECT BY, 복잡한 힌트, 패키지 프로시저와 성능 중요 SQL을 억지로 Query Builder로 바꾸면 오히려 읽기 어려울 수 있다.

Knex의 raw 또는 node-oracledb의 execute에 바인드 변수를 사용하고 Repository* 안에 격리한다. 문자열 연결로 사용자 입력을 SQL에 붙이지 않는다.

Q12. Oracle 연결은 요청마다 새로 만듭니까?

아니다. 애플리케이션 시작 시 연결 풀*을 만들고 요청마다 연결을 빌린 뒤 반드시 반환한다.

node-oracledb 공식 문서는 oracledb.createPool(), pool.getConnection()과 사용 후 connection.close()를 권장한다. poolMin, poolMax, 대기 시간은 Oracle 세션* 한도와 실제 동시 부하를 측정해 정한다.

연결을 반환하지 않으면 풀이 고갈되어 새 요청이 기다리거나 실패할 수 있다.

Q13. 트랜잭션* 방식은 Spring*과 같습니까?

개념은 같지만 구현은 자동으로 같아지지 않는다. Service*가 트랜잭션 경계를 정하고 같은 connection 또는 Knex transaction 객체를 모든 Repository에 전달해야 한다.

오류가 발생하면 rollback*하고, 성공했을 때만 commit*한다. 감사 기록이 업무 변경과 같은 트랜잭션에 들어가야 한다면 파일 로그만 남겨서는 안 된다.

Knex의 일부 transaction 옵션은 Oracle에서 지원되지 않을 수 있으므로 공식 문서와 실제 Oracle 격리 수준을 확인한다.

3. 화면·렌더링*·보안

Q14. Next.js 화면은 모두 브라우저에서 그립니까?

아니다. 정적 렌더링*, 동적 서버 렌더링, Server Component와 Client Component를 함께 사용할 수 있다.

공개 도움말: 정적 렌더링 가능
사용자별 프로젝트 목록: 요청 시 권한을 확인하는 동적 경로
검색 폼·모달: 필요한 범위만 Client Component

정적·동적은 결과를 언제 만드는지에 대한 구분이고, Server·Client Component는 코드가 어디서 실행되는지에 대한 구분이다.

Q15. 사용자별 ERP 화면을 정적 페이지로 만들면 더 빠르지 않습니까?

권한별 데이터가 섞일 위험이 있다. 프로젝트, 계약, 금액, 인력과 결재 화면은 로그인* 사용자와 역할을 서버에서 확인해야 한다.

캐시를 적용하려면 사용자·조직·업체별 키, 권한 변경, 로그아웃과 개인정보 저장 여부를 먼저 설계해야 한다. 성능을 위해 사용자별 업무 데이터를 공개 정적 파일로 만들면 안 된다.

Q16. jQuery는 보안에 취약하므로 모두 제거해야 합니까?

jQuery라는 이름 자체가 곧 취약점은 아니다. 위험은 지원이 끝난 구버전, 검증되지 않은 플러그인, 문자열을 .html()이나 .append()에 넣는 DOM* 조작과 서버 권한 검사 누락에서 생긴다.

React도 dangerouslySetInnerHTML을 잘못 사용하거나 API 권한 검사를 빠뜨리면 취약해진다. 라이브러리를 바꾸는 것과 별개로 XSS*, CSRF*, CSP*와 서버 인가를 검증한다.

Q17. 버튼을 숨기면 권한 제어가 된 것 아닙니까?

아니다. 사용자는 주소나 API를 직접 호출할 수 있다.

버튼 노출은 사용성이고, 최종 권한 판단은 Route Handler와 Service에서 사용자·역할·조직·업체·프로젝트 범위를 검사해야 한다. 권한 없는 호출에는 일관된 401 또는 403 응답을 반환하고 감사 기록을 남긴다.

Q18. `.env` 파일에 비밀번호를 쓰면 자동으로 암호화*됩니까?

아니다. .env는 일반 문자 파일이다.

이 프로젝트는 .env에 ENC[...] 암호문만 두고 마스터 키*는 systemd credential*처럼 별도 경로로 주입했다. 암호문과 키를 같은 파일이나 Jenkins 작업 공간에 두면 분리 효과가 없다.

로그인 비밀번호는 복호화* 가능한 암호화가 아니라 salt*가 있는 검증용 해시*를 사용한다. 설정 비밀번호 암호화와 사용자 비밀번호 해시는 목적이 다르다.

Q19. 전자정부 표준프레임워크의 PBE* 암호문을 그대로 사용할 수 있습니까?

Node.js에서도 호환 구현은 가능하지만 기존 알고리즘, salt, 반복 횟수, 문자 인코딩과 출력 형식을 정확히 알아야 한다.

취약한 과거 알고리즘을 영구히 복제하지 않는다. 테스트 벡터로 한시적 호환성을 검증한 뒤 AES-256-GCM* 같은 승인된 방식으로 재암호화하고 키 교체 절차를 만든다.

4. API 우선 전환과 검증

Q20. 왜 화면보다 API를 먼저 만듭니까?

화면과 데이터를 동시에 바꾸면 차이의 원인을 찾기 어렵다.

먼저 /api/v1의 입력, 응답과 오류를 OpenAPI*로 고정하고 같은 조건으로 Spring·MyBatis와 Next.js API를 비교한다. API가 통과한 뒤 JSP 화면을 TSX*로 옮기면 데이터 차이와 화면 차이를 분리할 수 있다.

Q21. OpenAPI는 인터넷에 공개하는 API라는 뜻입니까?

아니다. OpenAPI는 API 계약을 기계와 사람이 읽을 수 있게 표현하는 표준이다. 폐쇄망* 내부 API에도 사용할 수 있다.

문서 공개 범위는 별도 보안 정책으로 정한다. 운영자용 내부 경로와 예제에 비밀번호, 개인정보와 실제 계약 데이터를 넣지 않는다.

Q22. 기존과 신규 API는 어떻게 비교합니까?

같은 사용자 역할, 검색 조건, 기준 시각과 테스트 데이터를 양쪽에 전달한다.

다음 차이는 정규화할 수 있다.

날짜와 시간대 표현
NULL과 빈 문자열
숫자와 금액 형식
정렬 순서가 계약상 무관한 목록

필드, 행 수, 값, 오류 코드와 페이징을 비교하고 차이를 JSON*과 사람이 읽는 보고서로 남긴다.

Q23. 등록·승인·지급도 양쪽에 동시에 보내 비교합니까?

운영에서는 절대 그렇게 하지 않는다. 중복 등록, 중복 승인과 중복 지급이 발생할 수 있다.

쓰기 기능은 격리된 테스트 데이터, rollback 가능한 트랜잭션, 사전·사후 스냅샷과 감사 기록으로 검증한다. 운영에서는 기능별 쓰기 책임 시스템을 하나만 둔다.

Q24. 로컬 AI*가 비교 프로그램과 변환 코드를 만들면 사람이 검토하지 않아도 됩니까?

아니다. 로컬 AI는 초안 작성과 반복 작업을 돕지만 통과 여부를 결정하지 않는다.

명세와 금지 사항을 먼저 제공한다.
생성된 코드의 타입·테스트·SQL을 검토한다.
AI가 만든 비교기에 의도적인 오류를 넣어 탐지 여부를 시험한다.
담당자와 승인자가 원본 로그를 확인한다.

AI 서비스가 멈춰도 개발·빌드·배포가 가능해야 한다.

5. Nginx와 배포

Q25. JEUS를 제거하면 애플리케이션 서버가 완전히 없어집니까?

Java WAS*는 없어지지만 동적 업무를 실행할 서버 프로세스는 남는다. Next.js의 인증, API와 동적 렌더링은 Node.js에서 실행된다.

사용자 → Nginx → Next.js Node.js → Oracle

Nginx는 TLS*, 요청 제한, 정적 파일과 리버스 프록시*를 담당한다. 업무 Service와 Oracle 처리를 Nginx가 대신하지 않는다.

Q26. Next.js 공식 문서도 Nginx 같은 리버스 프록시를 권장합니까?

그렇다. Next.js 자체 호스팅 안내는 애플리케이션 서버를 인터넷에 직접 노출하기보다 Nginx 같은 리버스 프록시를 앞에 두어 비정상 요청, 느린 연결 공격, 요청 크기와 rate limit*를 처리하도록 권장한다.

streaming*을 사용하면 프록시 buffering* 설정도 확인해야 한다. 여러 인스턴스를 운영할 때는 캐시 공유와 배포 버전 일치도 별도로 설계한다.

Q27. Next.js를 Nginx에서 정적 디렉터리로만 서비스할 수 있습니까?

공개 안내처럼 완전 정적인 사이트는 output: "export"로 만들 수 있다. 그러나 사용자별 인증, cookie*, 동적 Route Handler, Server Action과 요청 시 Oracle 조회가 필요한 ERP 전체에는 맞지 않는다.

이 프로젝트는 Node.js 서버를 실행하고 Nginx가 내부 포트로 전달한다. 정적 파일과 동적 요청의 책임을 구분한다.

Q28. `next dev`를 테스트베드*나 운영계에서 사용하면 안 됩니까?

안 된다. 개발 모드는 파일 감시, Fast Refresh*, 개발용 오류와 요청 시 컴파일을 포함하므로 운영 성능과 결과물을 대표하지 않는다.

테스트베드와 운영계에서는 next build로 만든 production* 결과물을 next start 또는 standalone* server.js로 실행한다. 화면에 개발 도구 표시가 보이면 실행 모드부터 확인한다.

Q29. standalone 결과물만 복사하면 됩니까?

Next.js 공식 output 안내에 따르면 .next/standalone은 필요한 런타임 파일과 최소 server.js를 만든다. public과 .next/static은 기본적으로 자동 복사되지 않으므로 배포 방식에 따라 함께 복사하거나 별도 정적 서버에서 제공해야 한다.

이 프로젝트는 배포 스크립트에 해당 파일 복사, 해시 확인과 health check*를 포함했다.

Q30. `/leg/`와 `/new/`를 함께 운영할 때 가장 자주 틀리는 것은 무엇입니까?

다음 항목을 특히 주의한다.

proxy_pass 끝의 /에 따른 경로 보존·제거
Next.js basePath
JSP의 루트 절대 경로와 리다이렉트*
JSESSIONID와 신규 session cookie 충돌
두 시스템의 쓰기 책임 중복
업로드 크기와 다운로드 권한
로그인 후 원래 주소 복귀

같은 Oracle을 사용해도 애플리케이션 경로와 session은 분리할 수 있다.

Q31. Jenkins가 운영까지 자동 배포하면 위험하지 않습니까?

검증과 복사를 자동화하되 운영 승인은 사람에게 남길 수 있다. Jenkins 공식 Pipeline* 문서는 input 단계로 실행을 멈추고 승인된 사용자의 확인을 기다리는 방식을 제공한다.

Jenkinsfile*은 소스와 함께 버전 관리하고, Build Agent*는 폐쇄망 내부 저장소만 사용한다. 테스트베드에서 통과한 같은 artifact*를 운영으로 승격하며 운영 서버에서 다시 빌드하지 않는다.

Q32. Jenkins에 운영 비밀번호를 넣어도 됩니까?

가능하면 Jenkins가 운영 비밀 원문을 운반하지 않게 설계한다. 대상 서버의 systemd credential이나 승인된 비밀 관리 경로에서 실행 시점에 읽도록 한다.

Jenkins credential을 사용해야 한다면 최소 권한, 승인된 binding, 로그 마스킹과 작업 공간 정리를 적용한다. 콘솔에 전체 환경 변수*를 출력하지 않는다.

Q33. 배포에 실패하면 어떻게 원복합니까?

release*별 디렉터리에 새 결과물을 풀고 health check가 성공한 뒤 current 링크나 Nginx upstream*을 전환한다.

실패하면 previous 신규 release로 되돌린다. 데이터 쓰기가 시작된 뒤에는 파일만 되돌리지 않고 Oracle 데이터, 중복 요청과 감사 이력을 확인한다.

6. 성능과 로그

Q34. Next.js에도 Log4j* 같은 로그 도구가 있습니까?

있다. 이 프로젝트는 Pino*로 요청, 업무, 오류, SQL, 보안, 감사와 외부 연계 로그를 구조화했다.

Pino 파일만으로 모든 감사를 해결하지는 않는다. 중요한 상태 변경은 Oracle 감사 테이블에 같은 트랜잭션으로 저장하고, Nginx와 애플리케이션 로그는 요청 ID로 연결한다.

Q35. 로그의 시작 시각과 종료 시각을 빼면 성능을 알 수 있습니까?

대략적인 추적은 가능하지만 정확한 경과 시간은 단조 시계*로 측정한 duration_ms를 사용한다. 시스템 시각 보정과 로그 전송 지연이 벽시계 차이에 영향을 줄 수 있기 때문이다.

Nginx의 request_time, 애플리케이션 전체 시간, Service, DB 대기와 SQL 시간을 분리하면 병목 구간을 찾기 쉽다.

Q36. p50·p95·p99는 무엇입니까?

요청을 빠른 순서로 놓았을 때 해당 비율이 완료된 시간이다.

p50: 절반이 이 시간 안에 완료된 중앙값
p95: 95%가 이 시간 안에 완료
p99: 99%가 이 시간 안에 완료

평균만 보면 일부 매우 느린 요청이 가려질 수 있다. p95와 p99는 느린 사용자의 경험을 확인하는 데 유용하지만 표본 수와 오류율도 함께 봐야 한다.

Q37. 서버 API가 빨라지면 사용자가 느끼는 화면도 빨라집니까?

반드시 그렇지는 않다. JavaScript* 크기, 브라우저 렌더링, 연속 API 호출과 큰 표 때문에 화면이 느릴 수 있다.

서버 p50·p95·p99와 함께 LCP*, INP, CLS, 업무 완료 시간, 오류와 재시도 횟수를 측정한다. 사용자의 “느리다”는 문의를 요청 ID와 연결해 서버·DB·브라우저 중 어느 구간인지 확인한다.

Q38. 성능 차이는 언제 수집해야 합니까?

레거시를 끈 뒤에는 같은 시점의 실제 사용자 비교 자료를 만들 수 없다. 병행 운영 기간에 같은 업무 ID, 비슷한 역할·데이터량·시간대와 동시 부하를 맞춰 수집해야 한다.

SQL 개선, 화면 개선, 런타임 차이와 서버 구성 차이를 구분한다. 측정 뒤 유리한 기준을 새로 만들지 말고 전환 전에 승인 기준을 정한다.

Q39. AWR*과 ASH를 바로 사용해도 됩니까?

Oracle AWR·ASH와 일부 진단 기능은 별도 Diagnostic Pack* 라이선스가 필요할 수 있다. 계약과 라이선스를 확인하지 않고 사용하지 않는다.

사용 권한이 없다면 승인된 동적 성능 뷰, 애플리케이션 구간 측정과 기존 모니터링 도구를 사용한다.

7. 폐쇄망과 공급망

Q40. 인터넷이 없는 환경에서 Next.js 패키지를 어떻게 설치합니까?

외부 준비 구역에서 승인된 버전과 잠금 파일*에 맞는 패키지를 수집하고 해시·라이선스·취약점을 검사한 뒤 내부 패키지 저장소로 반입한다.

폐쇄망 Build Agent에서는 다음처럼 잠금 파일을 강제하고 오프라인 설치를 사용한다.

pnpm install --offline --frozen-lockfile

개발자마다 USB로 임의 패키지를 반입하지 않는다.

Q41. 패키지를 한 번 반입했으면 계속 안전합니까?

아니다. 새 취약점은 나중에 공개될 수 있다.

정기 취약점 정보 반입
잠금 파일과 SBOM* 보관
패키지 해시와 서명 확인
더 이상 지원되지 않는 버전 조사
긴급 보안 패치 절차

업데이트가 필요하다고 운영 서버에서 인터넷을 임시로 열지 않는다.

Q42. 로컬 AI를 사용하면 소스가 자동으로 안전해집니까?

외부 전송 위험은 줄일 수 있지만 내부 권한, 모델 로그와 프롬프트에 비밀이 들어가는 위험은 남는다.

운영 개인정보·비밀번호·개인키·실제 계약 데이터를 입력하지 않는다. AI가 만든 코드도 같은 보안 검사, 테스트와 동료 검토를 통과해야 한다.

8. 일정·조직·종료

Q43. 전환 기간은 화면 수로 계산하면 됩니까?

안 된다. 동적 SQL 조합, 프로시저, 외부 연계, 권한 수, 첨부와 월말 업무가 더 큰 변수다.

일정 약속 전에 기능·SQL·데이터·보안·운영 조사를 수행하고 API 비교가 끝난 범위만 화면 일정으로 넘긴다.

Q44. 외주업체에 전체를 맡기면 내부 인력이 없어도 됩니까?

어렵다. 외주업체는 구현을 도울 수 있지만 업무 규칙, 권한 해석, 운영 승인과 데이터 책임은 발주 조직에 남는다.

내부 담당자는 최소한 다음을 소유해야 한다.

OpenAPI와 업무 규칙
Oracle 계정·권한과 데이터 책임
테스트 승인과 중단 기준
소스·Jenkinsfile·SBOM과 배포 기록
장애·원복·백업 문서

Q45. 운영 중 수정이 계속되면 레거시를 영원히 못 끄는 것 아닙니까?

신규 시스템 수정은 정상적인 운영 활동이다. 중요한 것은 수정이 개발계, 테스트베드와 자동 Pipeline을 거쳐 같은 release로 배포되는지다.

이 프로젝트는 전면 오픈 후 30일 동안 수정·배포를 계속하면서 데이터·권한·오류·성능과 저빈도 업무를 관찰했다. 종료 조건을 통과한 D+30에 JEUS를 내렸다.

Q46. 왜 30일입니까?

모든 프로젝트에 30일이 정답은 아니다. 이 프로젝트에서는 월간 업무 주기, 저빈도 업무 확인과 조직의 원복 정책을 고려해 정한 안정화 기간이었다.

30일은 시간이 지나면 자동 종료되는 날짜가 아니라 최종 승인 시점이다. 월말 업무가 실행되지 않았거나 중대 오류가 남았다면 연장해야 한다.

Q47. JEUS를 종료하면 자료도 모두 삭제합니까?

아니다. 실행 서비스와 일상적 원복 의존은 끝내되 다음을 승인된 기간 동안 보존한다.

최종 WAR*와 소스 식별자
JEUS와 애플리케이션 설정
MyBatis XML·배치·외부 연계 목록
JDK·라이브러리·라이선스 버전
배포·기동·종료와 복구 절차
감사 로그 위치와 파일 해시

비밀번호와 개인키는 보존 묶음에 넣지 않고 필요할 때 새로 발급받는다.

Q48. Oracle도 함께 종료합니까?

아니다. 이 프로젝트의 업무 데이터 원본은 계속 Oracle에 있다.

레거시 전용 DB 계정과 불필요한 권한·방화벽 규칙은 종료하고, 신규 계정의 최소 권한과 연결 풀을 유지한다. 신규 DB로 데이터를 다시 옮기는 사업은 별도 범위다.

Q49. 전환 성공을 무엇으로 판단합니까?

기술 이름이 아니라 다음 결과로 판단한다.

데이터·권한·감사 기록의 허용되지 않은 차이 0건
핵심 업무 완료율과 오류율 기준 통과
성능·자원·사용자 경험의 측정 가능한 결과
반복 가능한 빌드·배포·원복
보안·백업·복구와 운영 인수
특정 담당자의 야근과 기억에 의존하지 않는 운영

팀 전체가 정시에 퇴근할 수 있어야 전환이 끝났다는 마지막 원칙도 여기에 포함된다.

9. 실패를 줄이는 시작 순서

Q50. 지금 시작한다면 무엇부터 해야 합니까?

다음 순서를 권한다.

1. 업무·화면·권한·SQL·연계 목록 작성
2. 현재 데이터 결과와 성능 기준선 수집
3. Oracle은 유지하고 목표 구조 확정
4. /api/v1 OpenAPI 계약 작성
5. MyBatis·Next.js 자동 비교기 구축
6. 조회 API부터 결과 일치 확인
7. 쓰기 트랜잭션·감사·중복 방지 검증
8. 통과한 API의 JSP를 TSX로 변환
9. Nginx에서 기존·신규 경로 병행 운영
10. 사용자 경험과 성능 비교
11. Jenkins로 같은 release 승격 자동화
12. 안정화 조건 통과 뒤 JEUS 종료

가장 먼저 화면을 예쁘게 다시 만드는 순서는 권하지 않는다. 데이터와 권한이 같은지 증명할 방법부터 만든다.

10. 참고 자료

다음 공개 자료의 원칙을 FAQ에 반영했다.

Next.js 자체 호스팅 안내: https://nextjs.org/docs/app/guides/self-hosting
Next.js standalone output: https://nextjs.org/docs/app/api-reference/config/next-config-js/output
Next.js 정적 export의 지원 범위: https://nextjs.org/docs/app/guides/static-exports
node-oracledb 연결과 연결 풀: https://node-oracledb.readthedocs.io/en/latest/user_guide/connection_handling.html
Knex 설치와 Oracle dialect: https://knexjs.org/guide/
Knex Query Builder: https://knexjs.org/guide/query-builder
Knex transaction 지원 범위: https://knexjs.org/guide/transactions
Jenkins Pipeline 문법과 승인 단계: https://www.jenkins.io/doc/book/pipeline/syntax/
Jenkins Pipeline as Code: https://www.jenkins.io/doc/book/pipeline/pipeline-as-code/
Martin Fowler의 Strangler Fig Application: https://martinfowler.com/bliki/StranglerFigApplication.html
Microsoft의 Strangler Fig Pattern 설명: https://learn.microsoft.com/azure/architecture/patterns/strangler-fig

공개 사례와 공식 문서는 방향을 정하는 참고 자료다. 실제 전환 승인은 이 시스템의 데이터 비교, 보안 검토와 운영 시험 결과로 내려야 한다.

— FAQ 별책 끝 —다음 · 주석 별책전산 전문 용어 주석 별책

TEAM

사람들

TEAM

김전산 주무관: 7급, 개발 경력 5년 차. 집에서 Next.js 영상을 본 뒤 폐쇄망 프로젝트 접수 시스템의 전환을 먼저 제안하고, 단계별 검증 일지를 쓴다.
최정보 팀장: 정보시스템팀장. 전환 범위, 일정과 운영 승인을 결정한다. 유행보다 측정 결과와 원복 가능성을 먼저 확인한다.
박개발 사무관: 6급, 개발 경력 12년 차. 전자정부프레임워크, Spring MVC, MyBatis와 보안 규칙을 설명하고 신규 구조를 검토한다.
이코딩 주무관: 7급, 개발 경력 3년 차. Next.js 화면과 API를 구현한다. 처음에는 빠른 화면 개발을 원하지만 백엔드 비교 절차를 받아들인다.
정운영 주무관: 정보시스템팀 운영 담당. 폐쇄망 패키지 반입, 개발계·테스트베드·운영계 승격, Nginx와 장애 원복을 맡는다.
정시스템 주무관: 대시보드·데이터 담당. Oracle과 동적 SQL을 조사하고 MyBatis·Next.js 결과 비교 모듈을 만든다.

1. 전환 판단

Q1. 전자정부 표준프레임워크*를 Next.js로 바꾸면 무엇이 좋아집니까?

Q2. Java보다 Node.js가 항상 가볍고 빠릅니까?

Q3. Next.js는 프론트엔드 전용 아닙니까?

Q4. 전자정부 표준프레임워크를 한 번에 전부 다시 만드는 것이 빠르지 않습니까?

Q5. 어느 시스템이 전환 대상인지 어떻게 판단합니까?

Q6. 기존 디자인도 전부 새로 만들어야 합니까?

2. Oracle과 SQL

Q7. Oracle 데이터베이스도 바꿔야 합니까?

Q8. 왜 Prisma 대신 Knex*와 node-oracledb*를 사용합니까?

Q9. MyBatis의 <if> 같은 동적 SQL을 Knex에서도 만들 수 있습니까?

Q10. 기존 SQL과 신규 SQL의 글자가 완전히 같아야 합니까?

Q11. 프로시저와 Oracle 전용 문법도 모두 Knex로 바꿔야 합니까?

Q12. Oracle 연결은 요청마다 새로 만듭니까?

Q13. 트랜잭션* 방식은 Spring*과 같습니까?

3. 화면·렌더링*·보안

Q14. Next.js 화면은 모두 브라우저에서 그립니까?

Q15. 사용자별 ERP 화면을 정적 페이지로 만들면 더 빠르지 않습니까?

Q16. jQuery는 보안에 취약하므로 모두 제거해야 합니까?

Q17. 버튼을 숨기면 권한 제어가 된 것 아닙니까?

Q18. .env 파일에 비밀번호를 쓰면 자동으로 암호화*됩니까?

Q19. 전자정부 표준프레임워크의 PBE* 암호문을 그대로 사용할 수 있습니까?

4. API 우선 전환과 검증

Q20. 왜 화면보다 API를 먼저 만듭니까?

Q21. OpenAPI는 인터넷에 공개하는 API라는 뜻입니까?

Q22. 기존과 신규 API는 어떻게 비교합니까?

Q23. 등록·승인·지급도 양쪽에 동시에 보내 비교합니까?

Q24. 로컬 AI*가 비교 프로그램과 변환 코드를 만들면 사람이 검토하지 않아도 됩니까?

5. Nginx와 배포

Q25. JEUS를 제거하면 애플리케이션 서버가 완전히 없어집니까?

Q26. Next.js 공식 문서도 Nginx 같은 리버스 프록시를 권장합니까?

Q27. Next.js를 Nginx에서 정적 디렉터리로만 서비스할 수 있습니까?

Q28. next dev를 테스트베드*나 운영계에서 사용하면 안 됩니까?

Q29. standalone 결과물만 복사하면 됩니까?

Q30. /leg/와 /new/를 함께 운영할 때 가장 자주 틀리는 것은 무엇입니까?

Q31. Jenkins가 운영까지 자동 배포하면 위험하지 않습니까?

Q32. Jenkins에 운영 비밀번호를 넣어도 됩니까?

Q33. 배포에 실패하면 어떻게 원복합니까?

6. 성능과 로그

Q34. Next.js에도 Log4j* 같은 로그 도구가 있습니까?

Q35. 로그의 시작 시각과 종료 시각을 빼면 성능을 알 수 있습니까?

Q36. p50·p95·p99는 무엇입니까?

Q37. 서버 API가 빨라지면 사용자가 느끼는 화면도 빨라집니까?

Q38. 성능 차이는 언제 수집해야 합니까?

Q39. AWR*과 ASH를 바로 사용해도 됩니까?

7. 폐쇄망과 공급망

Q40. 인터넷이 없는 환경에서 Next.js 패키지를 어떻게 설치합니까?

Q41. 패키지를 한 번 반입했으면 계속 안전합니까?

Q42. 로컬 AI를 사용하면 소스가 자동으로 안전해집니까?

8. 일정·조직·종료

Q43. 전환 기간은 화면 수로 계산하면 됩니까?

Q44. 외주업체에 전체를 맡기면 내부 인력이 없어도 됩니까?

Q45. 운영 중 수정이 계속되면 레거시를 영원히 못 끄는 것 아닙니까?

Q46. 왜 30일입니까?

Q47. JEUS를 종료하면 자료도 모두 삭제합니까?

Q48. Oracle도 함께 종료합니까?

Q49. 전환 성공을 무엇으로 판단합니까?

9. 실패를 줄이는 시작 순서

Q50. 지금 시작한다면 무엇부터 해야 합니까?

10. 참고 자료