Postra 이메일 통합 관리 플랫폼 관리자 가이드

문서 관리 정보

• 소속: AI Infra실 (AI Infra Department)
• 문서 버전: v0.10.5
• 최종 수정일: 2026년 7월 24일
• 대상: 시스템 관리자, DevOps/Infra 엔지니어, 보안 담당자

1. 아키텍처 및 소스 패키지 구성 (Architecture & Directory Layout)

Postra는 단일 바이너리 배포부터 K8s 기반 다중 노드 고가용성(HA) 아키텍처까지 확장 가능하도록 Hexagonal Architecture 포트-어댑터 패턴으로 구성되어 있습니다.

+-----------------------------------------------------------------------------------+
|                                 cmd/postra/main.go                                |
|  - CLI Subcommands / Single-binary Serve Entrypoint / Graceful Shutdown           |
+-----------------------------------------------------------------------------------+
                                          |
+-----------------------------------------------------------------------------------+
|                               internal/application                                |
|  - App Core / sync.go / accounts.go / rules.go / auth.go / oidc.go / incidents.go |
+-----------------------------------------------------------------------------------+
          |                               |                               |
+-------------------+           +-------------------+           +-------------------+
| internal/adapters |           | internal/adapters |           | internal/adapters |
|  /secretstore     |           |  /objectstore     |           |  /persistence     |
|  - LocalStore     |           |  - LocalStore     |           |  - SQLite3 (WAL)  |
|  - DBStore        |           |  - DBStore        |           | internal/adapters |
|  - Envelope AES   |           |  - Encrypted      |           |  /pgstore         |
+-------------------+           +-------------------+           |  - PostgreSQL     |
                                                                |  - pgvector       |
                                                                +-------------------+

1.1 소스 패키지 상세 레이아웃

• cmd/postra: 서브커맨드(init, serve, mcp, account, secret, sync, search 등) 핸들러 및 SIGTERM/SIGINT 수거 루틴
• internal/application: 비즈니스 유스케이스 코어 (App, Sync, Account, Rule, Auth, OIDC, Incident)
• internal/domain: 도메인 엔티티 정의 (Message, MailAccount, SecretHandle, Incident, Job)
• internal/adapters/secretstore: AES-256-GCM Envelope 암호화 레코드 스토어 (LocalStore, DBStore)
• internal/adapters/objectstore: 메일 원문 MIME 및 첨부파일 암호화 객체 스토어 (LocalStore, DBObjectStore, EncryptedStore)
• internal/adapters/persistence: SQLite3 데이터베이스 어댑터 (WAL 모드, FK 활성화)
• internal/adapters/pgstore: PostgreSQL + pgvector 인덱스 지원 어댑터
• internal/adapters/mailparse: RFC822/MIME 디코더 및 bluemonday HTML Safe 세니타이저
• internal/adapters/malware: ClamAV 및 YARA 연동 첨부파일 보안 검사 엔진
• internal/transport/httpapi: REST API 핸들러 (/api/...) 및 API 토큰 인증 미들웨어
• internal/transport/webui: HTML 템플릿 웹 인터페이스 (/ui/...)
• internal/transport/mcpserver: Model Context Protocol SSE 및 Streamable HTTP 서비스 (/mcp)

2. 배포 및 환경변수 완벽 레퍼런스 (Environment Configuration)

Postra는 설정 파일(config.json) 또는 환경변수(POSTRA_*)를 통해 동작을 정밀하게 제어합니다.

2.1 전체 환경변수 레퍼런스 표

3. 어드민 계정 및 SSO 관리 (Identity & Authentication)

3.1 어드민 계정 멱등성 초기화 (EnsureUser)

Postra 기동 시 bootstrapAdmin 프로세스가 실행되어 어드민 계정(admin@postra.local)을 검증합니다.

• SQLite 쿼리: INSERT INTO users ... ON CONFLICT(login_id) DO UPDATE SET ...
• PostgreSQL 쿼리: INSERT INTO users ... ON CONFLICT (login_id) DO UPDATE SET ...
• SQLSTATE 23505 (users_pkey) 중복 키 에러가 발생하지 않도록 멱등성(Idempotency)이 완벽히 보장됩니다.

3.2 OIDC / OAuth2 SSO 설정 절차

1. SecretStore에 OIDC Client Secret을 안전하게 저장합니다:

   postra secret set --type oidc_client_secret --label "Keycloak SSO Client Secret"
   # 출력을 통해 시크릿 참조 키(예: sec_a1b2c3d4) 확인
   

2. 환경변수 설정 후 서버를 실행합니다:

   export POSTRA_OIDC_ENABLED=true
   export POSTRA_OIDC_ISSUER="https://auth.company.com/realms/postra"
   export POSTRA_OIDC_CLIENT_ID="postra-client"
   export POSTRA_OIDC_CLIENT_SECRET_REF="sec_a1b2c3d4"
   ./postra serve
   

4. Envelope Encryption & SecretStore 구조

Postra는 사내 민감 데이터 보호를 위해 2중 봉투 암호화 메커니즘을 적용합니다.

                  +-----------------------------------+
                  |  POSTRA_KEK (Master 32-Byte Key)  |
                  +-----------------------------------+
                                    |
                         Encrypts / Decrypts
                                    v
+-----------------------------------------------------------------------+
| Envelope Structure (crypto.Envelope)                                  |
| - KeyVersion: 1                                                       |
| - EncryptedDEK: Base64(AES-GCM-KW(DEK))                               |
| - Ciphertext:   Base64(AES-GCM-Payload(Data, AAD))                    |
+-----------------------------------------------------------------------+

4.1 SecretStore 암호화 레코드 스키마 (secrets.enc.json / db_secrets)

{
  "sec_8f9a2b1c": {
    "envelope": {
      "key_version": 1,
      "nonce": "...",
      "encrypted_dek": "...",
      "ciphertext": "..."
    },
    "owner": "admin",
    "type": "mail_password",
    "label": "업무 메일 수신 암호",
    "version": 1,
    "revoked": false
  }
}

4.2 KEK 로테이션 및 Self-Healing

• 비밀값 로테이션 (CLI):

  postra secret rotate --ref sec_8f9a2b1c
  

• 자가 치유 (Self-Healing): KEK 변경 또는 파드 교체로 secret_acquire 에러 발생 시, Web UI 계정 편집 페이지에서 비밀번호를 다시 입력하고 저장하면 최신 KEK로 자동 재암호화 및 등록이 완료됩니다.

5. ObjectStore 백엔드 및 저장 구조 (Object Storage)

Postra는 메일 원문(RFC822 MIME) 및 첨부파일을 두 가지 어댑터 방식으로 관리합니다.

5.1 LocalObjectStore (파일 시스템 기반)

• 경로: $POSTRA_DATA_DIR/objects/{raw|att}/xx/yyyy...
• 파일명: SHA-256 해시값 기반의 2자 서브디렉터리 분할 저장

5.2 DBObjectStore (데이터베이스 기반)

• 테이블: object_blobs
• 스키마 DDL (PostgreSQL 기준):

  CREATE TABLE IF NOT EXISTS object_blobs (
      bucket VARCHAR(64) NOT NULL,
      object_key VARCHAR(255) NOT NULL,
      content_type VARCHAR(128) NOT NULL,
      size_bytes BIGINT NOT NULL,
      data BYTEA NOT NULL,
      created_at BIGINT NOT NULL,
      PRIMARY KEY (bucket, object_key)
  );
  

6. 장애 모니터링 및 이벤트 파이프라인 (Incidents & Observability)

Postra v0.10.0+는 장애 및 시스템 이벤트 추적 파이프라인을 지원합니다.

6.1 대시보드 및 REST API

• 대시보드: http://<HOST>:8480/ui/admin/incidents
• REST API: GET /api/incidents?severity=error&limit=50
• JSON 응답 구조:

  [
    {
      "id": "inc_99a8b7c6",
      "severity": "warning",
      "category": "sync_interrupted",
      "title": "POP3 Sync Interrupted",
      "detail": "Connection reset by peer during retrieve",
      "created_at": 1774345200
    }
  ]
  

6.2 Prometheus 메트릭 수집 (/metrics)

• postra_sync_total{status="succeeded|failed"}: 동기화 처리 건수
• postra_messages_fetched_total: 수집된 신규 이메일 수
• postra_outbox_pending_messages: 발송 대기 큐 크기
• postra_attachment_blocked_total: 악성 첨부파일 차단 횟수

7. 전체 릴리즈 이력 (Release History: v0.1.0 ~ v0.10.5)

AI Infra실 — Postra 이메일 플랫폼 관리자 가이드 v0.10.5