전자서명 서비스에서 문제가 잇따릅니다. "대용량 PDF 업로드 시 앱 서버가 OOM으로 죽어요." "서명 완료된 문서의 필드가 수정 가능해 무결성 우려가 있어요." "고객이 올린 파일명·내용 한글이 '占쏙옙'으로 깨져요." "다운로드 링크가 영구 공개돼 보안 우려가 있고요." PM·인프라인 당신은 문서·파일 도메인 용어를 알아야 이 문제들을 판단합니다. 이 사전은 파일·문서·전자서명 도메인 용어를 빠르게 해독합니다.
- 1전자서명 도메인(템플릿·워크플로우·서명 필드) 용어를 이해할 수 있다
- 2PDF 처리(렌더링·평탄화·병합·분할)와 무결성의 관계를 설명할 수 있다
- 3presigned URL·오브젝트 스토리지로 대용량 파일을 안전·효율적으로 다루는 법을 설명할 수 있다
- 4인코딩(UTF-8/EUC-KR)·MIME·Base64로 파일 깨짐·전송 문제를 진단할 수 있다
전자서명 도메인
확대
위 그림처럼 전자서명은 템플릿 생성 → 워크플로우 설정 → 발송 → 서명 → PDF Flattening → 완료의 순서로 진행되며, Flattening 단계에서 필드가 고정돼 무결성이 보장됩니다.
템플릿·워크플로우·서명 필드
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Template / Template ID / Document ID | 문서 양식 / 양식·문서 식별 | 재사용 양식 | ★★ |
| Workflow / Recipient / Signer / Approver | 서명 흐름 / 수신자·서명자·승인자 | 순서·역할 | ★★ |
| Form Field / Text·Multiline·Signature·Stamp Field | 입력 필드 종류 | 서명·날인 위치 | ★★ |
| Company Stamp / Embedded Signing | 회사 도장 / 화면 내 서명 | 임베디드 UX | ★★ |
| Document Generation / Bulk Send / Bulk Create / Batch ID | 문서 생성 / 대량 발송·생성 | 대량 처리 → 용어사전 | ★★ |
| Document Status / Completed / Draft Status | 문서 상태 | 진행 추적 | ★★ |
| Webhook Event | 상태 변경 이벤트 알림 | 외부 연동 → 용어사전 | ★★ |
| Audit Trail / Time Stamp / Certificate-based Signature | 감사 추적 / 타임스탬프 / 인증서 기반 서명 | 법적 효력 | ★★ |
핵심: 전자서명은 '누가·언제·무엇에' 서명했는지의 감사 추적(Audit Trail) 과 무결성(서명 후 변경 불가)이 법적 효력의 핵심입니다.
PDF 처리
문서를 만들고 고정하는 작업
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| PDF Rendering | 문서를 PDF로 그림 | 생성 | ★★ |
| PDF Flattening | 폼/레이어를 고정 콘텐츠로 병합 | 서명 후 변경 방지 | ★★ |
| PDF Merge / Split | 병합 / 분할 | 다중 문서 | ★ |
핵심: 서명 완료 후 Flattening(평탄화) 으로 필드를 고정하면 누구도 값을 바꿀 수 없어 무결성이 보장됩니다 — 전자서명의 법적 효력에 직결됩니다.
파일 저장·전송
확대
위 그림처럼 앱 서버를 거치면 대용량 파일에서 OOM이 발생하지만, Presigned URL로 클라이언트가 스토리지에 직접 업로드하면 앱 서버는 URL 발급만 담당해 메모리 부담이 없습니다.
대용량을 안전·효율적으로 다루기
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| File Upload / Download | 업로드 / 다운로드 | 대용량은 직접전송 | ★★ |
| Presigned URL | 한시적 직접 업/다운 URL | 서버 부하↓ → SFTP/배치 파일 송수신과 외부 기관 연계 실무 | ★★★ |
| Object Storage / S3 / MinIO | 오브젝트 스토리지 | 파일 저장 표준 | ★★ |
| Download Token / Access Token | 다운로드 권한 토큰 | 만료·권한 제한 → 용어사전 | ★★ |
| File Size Limit | 업로드 크기 제한 | OOM·악용 방지 | ★★ |
핵심: 대용량 파일을 앱 서버 메모리로 받으면 OOM 위험(용어사전). Presigned URL로 클라이언트가 스토리지에 직접 올리면 서버는 URL 발급만 하고 전송은 스토리지가 전담합니다. 다운로드도 만료시간이 있는 토큰/URL로 보안을 유지합니다.
인코딩 · 형식
확대
위 그림처럼 파일 저장·네트워크 전송·DB 저장 세 계층 모두 UTF-8로 통일해야 한글 깨짐이 없습니다. EUC-KR로 저장하고 UTF-8로 읽으면 '占쏙옙'이 됩니다.
글자 깨짐과 전송 형식
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| MIME Type / Content-Type | 파일 형식 표시 | application/pdf 등 | ★★ |
| Base64 / Binary | 텍스트 인코딩 / 이진 | 전송 형식 | ★★ |
| Encoding / UTF-8 / EUC-KR | 문자 인코딩 / 유니코드 / 한글 구형 | 깨짐 원인 | ★★★ |
핵심: 한글 깨짐('占쏙옙'/'???')은 거의 항상 인코딩 불일치입니다 — 저장과 읽기 인코딩을 UTF-8로 통일하는 것이 표준 해법(InnoDB 스토리지 엔진 구조와 한글 인코딩, Auto Increment의 utf8mb4와 동일 맥락). 레거시·외부 연동에서 EUC-KR이 섞이면 변환 지점을 명확히 합니다.
파일 문제 진단 — 직접 확인
문서 서비스의 단골 문제 셋을 점검합니다.
1) 대용량 업로드: 앱 서버가 파일을 메모리로 받나, presigned로 직접 올리나?
→ 메모리로 받으면 큰 파일에서 OOM([[glossary-backend-java-spring]])
2) 인코딩: 저장/읽기 인코딩이 UTF-8로 통일됐나?
→ file 명령으로 실제 인코딩 확인: file -i upload.csv
3) 다운로드 URL: 만료시간·권한이 있나, 영구 공개인가?
→ 영구 공개면 링크 유출 시 누구나 접근(보안 위험)
file -i orders.csv → charset=euc-kr ← UTF-8 아님! 깨짐 원인
업로드: MultipartFile로 전체 메모리 적재 → 100MB+ 파일서 OOM
다운로드: /files/abc.pdf 영구 공개 → presigned(만료 10분)로 전환 필요
echo '업로드 경로 + 인코딩 + 다운로드 URL 만료 확인'- 대용량 업로드가 앱 서버 메모리로 들어오면 OOM 위험 → presigned URL로 스토리지 직접 업로드 전환(SFTP/배치 파일 송수신과 외부 기관 연계 실무)
- 한글 깨짐이면 file -i로 실제 인코딩 확인 → EUC-KR이면 UTF-8로 변환·통일. 저장·읽기·DB(InnoDB 스토리지 엔진 구조와 한글 인코딩, Auto Increment) 모두 UTF-8인지
- 다운로드 URL이 영구 공개면 유출 시 누구나 접근 → 만료시간 있는 presigned URL/다운로드 토큰으로(용어사전)
- 서명 완료 문서가 수정 가능하면 무결성 위험 → Flattening(평탄화)으로 필드 고정. 감사 추적(누가·언제 서명)이 남는지 확인
상황: 고객이 수십~수백 MB PDF를 업로드하자 앱 서버가 그 파일을 통째로 메모리에 받다 OutOfMemory로 죽고, 같은 서버의 다른 요청까지 마비됩니다.
원인: 파일을 앱 서버 메모리로 받는 구조입니다(MultipartFile 전체 적재 등). 대용량·동시 업로드가 겹치면 Heap을 초과합니다(용어사전의 OOM).
진단:
□ 업로드를 앱 서버가 메모리/디스크로 받나, 스토리지로 직접 보내나?
□ 파일 크기 제한(File Size Limit)이 있나?
□ OOM 시각이 대용량 업로드와 겹치나?
해결: (1) Presigned URL로 클라이언트가 오브젝트 스토리지(S3 등)에 직접 업로드하게 해 앱 서버 메모리를 우회. (2) 부득이 서버 경유 시 스트리밍(전체 적재 대신 흘려보내기)과 크기 제한 적용. (3) 다운로드도 presigned URL로 서버 부하·대역폭을 줄입니다. 대용량 파일은 '앱 서버를 거치지 않게' 설계하는 것이 확장성의 핵심입니다(SFTP/배치 파일 송수신과 외부 기관 연계 실무).
심화 — 서명은 바이트에 묶이고, URL은 소지자에 묶인다
심화: presigned·서명·후처리가 실전에서 충돌하는 지점
용어의 정의보다 위험한 것은 정의에서 빠진 함의입니다. 문서 도메인의 사고는 대부분 "그 용어가 무엇에 묶여 있는가"를 놓칠 때 납니다.
- Presigned URL은 '소지자 = 권한'입니다: 발급받은 사람만이 아니라 그 URL을 가진 누구나 만료 전까지 접근합니다. URL이 액세스 로그·채팅·브라우저 히스토리로 새는 순간 인증이 우회됩니다. 만료는 분 단위로 짧게, 다운로드마다 재발급하고, 업로드용은 Content-Type·크기 조건을 서명에 포함해 악용 여지를 좁힙니다(용어사전).
- 직접 업로드는 '서버가 모른다'는 뜻이기도 합니다: presigned로 스토리지에 직접 올리면 앱 서버는 업로드 완료 여부도, 실제 올라간 파일의 내용도 모릅니다. 클라이언트의 "올렸어요" 신고만 믿으면 선언과 다른 크기·형식의 파일이 그대로 저장됩니다. 스토리지 이벤트 알림이나 확정 API 단계에서 서버가 메타데이터를 재검증하는 절차가 필요합니다.
- 면접 한 단계 더 — "서명자 인증서가 나중에 만료되면 문서는 무효인가?": 아닙니다. 서명 '시점'에 유효했음을 증명할 수 있으면 효력이 유지됩니다 — 그래서 신뢰 기관의 타임스탬프(Time Stamp) 가 감사 추적(Audit Trail)과 함께 법적 효력의 축입니다. 시점 증명이 없는 서명은 분쟁에서 "만료된 인증서의 서명"으로 공격받습니다.
- Base64는 공짜가 아닙니다: 크기가 약 33% 부풀고, JSON 본문에 실으면 파일 전체를 메모리에 올리게 됩니다. 소형 첨부에는 편하지만, 대용량을 Base64 API로 주고받는 설계는 OOM 사고의 예고편입니다 — 대용량은 presigned 직접 전송이 정답입니다(SFTP/배치 파일 송수신과 외부 기관 연계 실무).
상황: 감사 대비로 전자서명이 완료된 계약서 수천 건을 문서보관 시스템으로 이관하면서, 일괄 후처리로 보관 번호와 페이지 번호를 스탬프했습니다. 이후 검증 도구가 전 문서를 '서명 이후 변경됨'으로 판정해 법무팀에 비상이 걸립니다.
원인: 전자서명은 서명 시점 문서 바이트의 해시에 묶여 있습니다. 스탬프·병합·재압축 등 어떤 후처리도 바이트를 바꿔 해시가 달라지고, 서명 검증은 실패합니다. "보이는 내용은 같으니 괜찮다"는 직관이 함정입니다 — 검증은 픽셀이 아니라 바이트를 봅니다.
진단: 원본과 이관본의 해시를 비교해 변경 여부를 확정하고, 이관 파이프라인에서 파일을 다시 쓰는 단계(스탬프·최적화·병합)를 찾아냅니다.
sha256sum original.pdf archived.pdf # 해시가 다르면 이관 중 문서가 변경된 것
해결: (1) 서명 완료 원본은 불변 보관 — 수정 불가 정책의 스토리지에 두고, 스탬프·병합 같은 가공은 사본에만 합니다. (2) 이미 변경된 문서는 전자서명 서비스에서 원본을 재확보합니다(완료 문서와 감사 추적은 서비스에 남아 있습니다). (3) 파이프라인에 '서명 문서 재저장 금지' 가드와 이관 후 해시 대조 검증을 추가합니다. 서명이 끝난 문서는 읽기 전용 유물로 취급해야 합니다.
인프라/플랫폼으로서 문서·파일 서비스는 스토리지 설계가 핵심입니다 — presigned URL로 대용량 전송을 앱 서버에서 분리하고(SFTP/배치 파일 송수신과 외부 기관 연계 실무), 다운로드 토큰 만료·접근 제어로 보안을 지키며, 인코딩(UTF-8 통일)으로 깨짐을 예방합니다. PM은 이 용어로 문서 도메인 요구를 정확히 적습니다 — "presigned 업로드", "서명 후 flattening으로 무결성", "감사 추적", "다운로드 링크 만료" 같은 항목을 인수 기준에 넣어 OOM·무결성·유출 사고를 예방합니다.
다음(마지막) 용어사전에서는 환경 차이·설정·운영 이슈 용어를 정리합니다.
용어 식별 실습으로 굳히기: 용어 식별 — 파일 / 문서 / 전자서명 — 요건·증상을 보고 파일 저장·문서·전자서명 용어를 가려냅니다.