# Postra 이메일 통합 관리 플랫폼 사용자 가이드 **문서 관리 정보** - **소속**: AI Infra실 (AI Infra Department) - **문서 버전**: v0.10.5 - **최종 수정일**: 2026년 7월 24일 - **대상**: Postra 이메일 플랫폼 일반 사용자, 팀원 및 업무 담당자 --- ## 1. 시스템 소개 및 주요 이점 **Postra**는 기업 및 조직의 이메일 자산을 안전하게 보호하고 통합 관리하기 위해 AI Infra실에서 개발한 온프레미스/폐쇄망 기반의 차세대 이메일 클라이언트 및 데이터 플랫폼입니다. ``` +-----------------------------------------------------------------------------------+ | Postra Web Workspace | | +-------------------+ +--------------------------------+ +------------------+ | | | Navigation Bar | | Thread List View | | Message Reader | | | | - Inbox / Archive | | - Smart Threading (RFC822) | | - HTML Safe | | | | - Accounts Status | | - Labels & Status Badges | | - Bluemonday | | | | - Rules Engine | | - RRF Hybrid Search Filters | | - Security Scan | | | | - AI Search | | - Real-time Sync Indicator | | - Reply & Action | | | +-------------------+ +--------------------------------+ +------------------+ | +-----------------------------------------------------------------------------------+ ``` ### 주요 비즈니스 및 기술적 이점 1. **멀티 계정 통합 워크스페이스**: 사내외 여러 POP3, IMAP, SMTP 계정을 단일 통합 웹 워크스페이스(`/ui/`)에서 일관되게 관리합니다. 2. **제로 트러스트 봉투 암호화(Envelope Encryption)**: 비밀번호 및 이메일 원문, 첨부파일은 KEK/DEK 이중 암호화로 보호되어 데이터 유출을 원천 차단합니다. 3. **AI 의미론적 검색 (Semantic Search)**: 키워드 일치 검색뿐만 아니라 질문이나 문맥을 이해하는 AI 벡터 기반 자연어 검색을 지원합니다. 4. **스마트 자동화 규칙 엔진**: 수신되는 메일에 조건별 라벨링, 중요 표시, 자동 아카이브, 스노우즈(Snooze) 스케줄링을 자동 수행합니다. 5. **실시간 악성 첨부파일 차단**: ClamAV 및 YARA 엔진과 연동하여 위험 확장자 및 악성코드를 수신 단계에서 사전 격리합니다. --- ## 2. 화면 구성 및 인터페이스 (UI Layout) Postra 웹 워크스페이스는 직관적인 3단 반응형 레이아웃으로 설계되었습니다. ### 2.1 사이드바 (Navigation Sidebar) - **[새 메일 작성]**: 이메일 작성 및 초안(Draft) 편집 모달을 호출합니다. - **메일함 뷰어**: - **전체 메일함**: 수신된 전체 메일을 스레드 단위로 조회합니다. - **받은 편지함 (Inbox)**: 처리가 필요한 활성 수신 메일함입니다. - **안읽은 메일함**: 미확인 수신 메일만 필터링합니다. - **중요 메일함**: 별표(Star)로 표시된 주요 업무 메일 모음입니다. - **보관함 (Archive)**: 처리 완료되어 아카이브된 메일 보관소입니다. - **스노우즈 (Snoozed)**: 지정 시각까지 일시 숨김 처리된 메일함입니다. - **계정 목록 & 실시간 수집 인디케이터**: 연동된 계정의 상태(Active, Credential Error) 및 백그라운드 수집 진행 상태를 실시간 표시합니다. - **규칙 관리**: 수신 메일 자동화 처리 규칙을 등록/관리합니다. - **AI 메일 검색**: 벡터 기반 자연어 검색 전용 페이지로 이동합니다. ### 2.2 메일 스레드 목록 (Thread List) - **스마트 스레딩 (RFC822)**: 동일 대화 주제(`References`, `In-Reply-To`, `SubjectKey`)로 묶인 이메일을 하나의 스레드 뷰로 그룹핑합니다. - **상태 배지**: 읽음/안읽음, 라벨, 중요 표시, 보안 스캔 상태, 첨부파일 유무를 한눈에 파악합니다. - **수집 인디케이터**: 백그라운드 수집 시 진행률(Progress: N/M)이 상단에 실시간 인디케이터로 표시됩니다. ### 2.3 메일 본문 뷰어 (Message Reader) - **HTML Safe 뷰어**: `bluemonday` 보안 정책이 적용되어 스크립트, 픽셀 트래커, 외부 악성 웹 리소스가 자동 세니타이징(Sanitizing)된 안전한 HTML 화면을 제공합니다. - **액션 툴바**: 답장(Reply), 전체 답장(Reply All), 전달(Forward), 라벨 추가/제거, 중요 표시, 스노우즈, 아카이브, 삭제 명령을 즉시 수행합니다. --- ## 3. 메일 계정 연동 및 진단 (Account Setup & Diagnostics) ### 3.1 POP3 / IMAP 수신 계정 연동 1. 사이드바 하단 **[계정 관리]** → **[새 계정 추가]** 메뉴를 선택합니다. 2. 수신 서버 프로토콜 및 접속 정보를 입력합니다: | 설정 항목 | 입력 값 예시 | 설명 | | --- | --- | --- | | **계정 이름 (Name)** | `AI Infra 업무 메일` | 사용자가 식별할 계정 별칭 | | **이메일 주소 (Email)** | `user@company.com` | 계정 이메일 주소 | | **수신 프로토콜** | `POP3` 또는 `IMAP` | 메일 수신 프로토콜 선택 | | **수신 호스트 (Host)** | `pop3.company.com` | POP3/IMAP 서버 도메인 또는 IP | | **수신 포트 (Port)** | `995` (POP3S) / `993` (IMAPS) | 암호화 포트 (110, 143 평문도 지원) | | **보안 프로토콜** | `SSL/TLS` / `STARTTLS` / `Plain` | `SSL/TLS` 사용 권장 | | **사용자명 (Username)** | `user@company.com` | 수신 서버 로그인 아이디 | | **비밀번호 (Password)** | `********` | 수신 서버 접속 암호 | ### 3.2 발신 SMTP 계정 연동 - 동일 화면 하단 **[발신(SMTP) 설정]**에서 발신 정보를 설정합니다: - **SMTP 호스트/포트**: `smtp.company.com` / `465` (SMTPS) 또는 `587` (STARTTLS) - **인증 방식**: `PLAIN`, `LOGIN`, `NONE` 중 선택 - **SMTP 비밀번호**: 수신 비밀번호와 다를 경우 입력 (동일 시 빈칸 유지) ### 3.3 5단계 연결 진단 (Diagnostic Pipeline) 계정 저장 전 **[연결 진단 (Test Connection)]** 버튼을 누르면 다음 5단계 파이프라인 검사가 수행됩니다: 1. `dns`: 수신/발신 서버 호스트의 DNS IP 조회 검사 2. `secret_acquire`: 비밀값 암호화 SecretStore 복호화 검사 3. `protocol`: POP3/IMAP/SMTP 프로토콜 핸드셰이크 검사 4. `connect_tls_auth`: TLS 세션 생성 및 사용자 인증 검사 5. `uidl`: 수신 서버 UIDL 커맨드 정상 응답 여부 확인 --- ## 4. 메일 동기화 및 수신 관리 (Sync & Mail Operations) ### 4.1 수집 모드 - **수동 동기화 (Manual Sync)**: 계정 옆 **[동기화]** 버튼 클릭 시 즉시 수집 작업을 실행합니다. - **자동 스케줄링 (Auto Sync)**: 백그라운드 워커가 설정된 주기(기본 5분)마다 자동으로 신규 메일을 체크합니다. - **IMAP IDLE 실시간 Push**: IMAP 계정의 경우 IDLE 연결을 유지하여 메일 도착 즉시 실시간으로 수집합니다. ### 4.2 메일 관리 액션 - **라벨 관리**: `업무`, `긴급`, `결재` 등 사용자 지정 라벨을 추가하거나 제거합니다. - **스노우즈 (Snooze)**: 메일을 잠시 숨긴 후 지정 시각(`1시간 후`, `내일 아침`, `다음 주`)에 다시 상단에 복원시킵니다. - **아카이브 (Archive)**: 처리 완료된 메일을 받은 편지함에서 보관함으로 이동하여 메일함을 정리합니다. --- ## 5. AI 의미론적 메일 검색 (AI & Semantic Search) Postra는 BM25 키워드 검색과 AI 벡터 검색을 결합한 **RRF(Reciprocal Rank Fusion) 하이브리드 검색**을 제공합니다. ### 5.1 검색 사용 방법 1. 사이드바 **[AI 메일 검색]** 메뉴를 선택합니다. 2. 자연어로 궁금한 내용이나 맥락을 입력합니다: - *예시*: `"지난달 AI 서버 증설 관련 예산 승인받은 메일"` - *예시*: `"보안 점검 조치 사항 및 가이드 문서"` 3. AI 벡터 검색 엔진이 제목과 본문 내용의 의미를 분석하여 연관도 순으로 결과를 출력합니다. --- ## 6. 메일 작성 및 첨부파일 보안 스캔 (Compose & Security) ### 6.1 이메일 작성 및 초안 자동 저장 - **[새 메일 작성]**을 클릭하여 수신자(`To`), 참조(`Cc`), 제목 및 HTML 본문을 작성합니다. - 작성 중인 내용은 실시간으로 **초안(Draft)**에 자동 저장됩니다. ### 6.2 악성 첨부파일 자동 차단 - 파일 첨부 시 사내 ClamAV/YARA 스캐너가 실시간 검사를 수행합니다. - 실행 파일(`.exe`, `.bat`, `.sh`), 이중 확장자, 압축 폭탄 파일은 위험으로 분류되어 수발신이 자동 차단됩니다. --- ## 7. 자주 묻는 질문 및 문제 해결 (Troubleshooting & FAQ) ### Q1. 연결 진단 중 `secret_acquire` 오류가 발생합니다. > **원인**: Pod 재기동 또는 서버 환경 변경으로 인해 비밀번호 암호화 키(KEK) 상태가 갱신된 경우 발생합니다. > **해결방법**: 계정 수정 페이지에서 이메일 비밀번호를 다시 입력하고 **[저장하기]**를 누르면, Self-Healing 매커니즘에 의해 최신 키로 자동 재암호화되어 즉시 정상 복구됩니다. ### Q2. 동기화 중 `authentication failed; account moved to credential_error` 상태가 됩니다. > **원인**: 수신 서버 비밀번호가 변경되었거나 인증에 3회 이상 연속 실패한 경우입니다. > **해결방법**: 메일 서버 접속 암호를 확인한 후 계정 설정에서 비밀번호를 업데이트하십시오. --- ## 8. 전체 릴리즈 이력 (Release History: v0.1.0 ~ v0.10.5) | 버전 | 릴리즈 일자 | 주요 변경 및 신규 기능 | | --- | --- | --- | | **v0.1.0** | 2026-07-18 | MVP 최초 릴리즈: Go 기반 POP3 수집, SMTP 발송 코어, CLI 및 REST API 기초 구현 | | **v0.2.0** | 2026-07-18 | 오프라인 폐쇄망 배포용 CGO-Free 정적 바이너리 및 `scratch` Docker 이미지 빌더 반영 | | **v0.3.0** | 2026-07-18 | IMAP 프로토콜 수신 어댑터, Prometheus 메트릭(`/metrics`), Web UI 초기 버전 도입 | | **v0.3.1** | 2026-07-18 | 헬스 프로브(`/healthz`), 검색 결과 커서 페이지네이션 및 빌드 버전 일원화 | | **v0.4.0** | 2026-07-23 | Web UI 3단 반응형 워크스페이스 개편 및 Bluemonday HTML Safe 뷰어 적용 | | **v0.4.1** | 2026-07-23 | REST API(`/api`), Web UI(`/ui`), Streamable HTTP MCP(`/mcp`) 8480 단일 포트 바인딩 | | **v0.5.0** | 2026-07-23 | RFC822 `References`/`In-Reply-To`/`SubjectKey` 기반 자동 대화 스레드 그룹핑 | | **v0.5.1** | 2026-07-23 | 자동화 수신 규칙 엔진 확장 (자동 삭제, 라벨 부여/제거, 중요 표시, Snooze) | | **v0.5.2** | 2026-07-23 | ClamAV / YARA 연동 첨부파일 악성코드 보안 스캔 및 위험 파일 차단 감사 로그 | | **v0.6.0** | 2026-07-23 | POP3/IMAP 소켓 타임아웃 튜닝 및 대용량 배치 DB 트랜잭션 수집 성능 개선 | | **v0.7.0** | 2026-07-23 | PostgreSQL DSN 연동(`POSTRA_STORAGE_DRIVER=postgres`), 실시간 싱크 인디케이터 UI | | **v0.8.0** | 2026-07-24 | MCP RBAC 권한 제어, IMAP IDLE Push 수신, RRF 하이브리드 검색, Milvus 벡터 DB 연동 | | **v0.8.1** | 2026-07-24 | 웹 UI 브랜딩 에셋(SVG/PNG 로고 아이콘, 파비콘) 정적 라우팅 및 템플릿 임베딩 | | **v0.8.2** | 2026-07-24 | 어드민 재초기화 시 `users_pkey` 중복 충돌(SQLSTATE 23505) 해결 (`EnsureUser` 멱등성 보장) | | **v0.8.3** | 2026-07-24 | 수신 워커 예외 복구(`defer recover()`) 및 SecretStore KEK 유실 시 자가 치유(Self-Healing) | | **v0.8.4** | 2026-07-24 | 대용량 메일 파싱 즉시 메모리 참조 해제 및 수집 루프 가비지 컬렉션(GC) 튜닝 | | **v0.8.5** | 2026-07-24 | 리더 선출 DB 지연 시 활성 작업 오검출 방지 (`RecoverStaleJobsExcept` 방어 반영) | | **v0.9.0** | 2026-07-24 | 수집 루프 내 `FreeOSMemory()` 제거로 OS 스레드 급사 방지, DB 암호화 SecretStore(`DBStore`) 추가 | | **v0.9.1** | 2026-07-24 | 메일 원문 및 첨부파일 BLOB을 DB에 암호화 직렬화 보관하는 `DBObjectStore` 구현 | | **v0.9.2** | 2026-07-24 | `db_test.go` 자동화 테스트 구축 및 SIGTERM 수신 시 안전한 워커 Graceful Shutdown | | **v0.10.0** | 2026-07-24 | 장애 모니터링 웹 대시보드(`/ui/admin/incidents`) 및 REST API(`/api/incidents`) 구축 | | **v0.10.1** | 2026-07-24 | 백그라운드 스케줄러, IDLE, 임베딩 작업 전체에 2중 예외 복구 래퍼 적용하여 크래시 완전 차단 | | **v0.10.2** | 2026-07-24 | 메모리 폭증 및 시스템 이상 원인 메일을 Audit Log 및 Incident에 자동 채록하는 파이프라인 구축 | | **v0.10.3** | 2026-07-24 | OIDC SSO 로그인 시 기존 부트스트랩 어드민 계정과 매핑 처리 및 세션 쿠키 검증 강화 | | **v0.10.4** | 2026-07-24 | OIDC 핸드셰이크 실패 상세 사유 표출 및 CSRF 하드닝 보안 강화 | | **v0.10.5** | 2026-07-24 | 메일 본문 뷰어 가독성 폰트, 블루문데이 세니타이징 CSS 스타일 디자인 고도화 | --- *AI Infra실 — Postra 이메일 플랫폼 사용자 가이드 v0.10.5*