Files

T

ttipo d1ef0da488 feat(docker): 12단계 계정 보안 — 엔진 웹훅 · /api/internal 닫기 · 요청 대상 400

메일 프로그램(IMAP · SMTP) 로그인 기록을 엔진 웹훅으로 받는다.
- 루트 env MAIL_WEBHOOK_SECRET(setup · backend 공용, 운영 필수)과 backend 의 APP_NETWORK_SUBNET
- setup 이 엔진 웹훅을 맞추고(표시 머리글 — 소금 + 키 지문) 서명한 빈 묶음으로 받는 곳을 확인한다
  키를 바꾼 실행 · 게이트웨이 OTP · 테스트 직원의 402 를 따로 다룬다
- nginx 두 server 가 /api/internal/ 을 닫고, 요청 대상의 날 \(경로) · # · 0x80 이상은 location 전에 400
  Express 가 이런 대상을 다시 읽어 닫은 경로(/api/internal · /api/health)가 백엔드에서 열렸다(2026-10-31 리뷰)
- CI "닫는 경로 시험"(두 server × 세 경로의 변형) · 지시어만 세는 정적 검사
- mail/README: 웹훅 · 12단계 전부터 운영 중인 서버를 올리는 차례 · 휴대폰을 잃은 직원(관리 API 명령)
엔진 DNS 가 Custom(운영)이어도 웹훅은 backend 를 푼다 — 메일 컨테이너가 도커 DNS 를 쓴다(개발에서 확인).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-31 17:45:23 +09:00

254 KiB

Raw Blame History

메일 엔진 (Stalwart)

사내 메일은 Stalwart(JMAP) 를 자체 호스팅한다. 직원 로그인 = 메일 계정이다. 웹메일 UI 는 자체 제작하고, 백엔드(NestJS)가 내부 JMAP 으로 메일 엔진에 중계한다.

이미지: stalwartlabs/stalwart:v0.16.27 — 패치까지 고정 (비-root stalwart, UID 2000 · healthcheck 내장. 올릴 때는 docker 스킬 "이미지 버전 고정")
설정값 SSOT: 루트 .env.{APP_ENV} 의 메일 섹션 (env-structure)
초기화·계정 구성: scripts/setup.mjs — 의존성 없음, 여러 번 실행해도 안전
이름은 루트 env 의 PROJECT_NAME 을 따른다 — 컨테이너 ${PROJECT_NAME}-mail, 볼륨 ${PROJECT_NAME}_mail-config·_mail-data, 네트워크 ${PROJECT_NAME}_app-network(신뢰 대역)·${PROJECT_NAME}_edge(frontend ↔ backend). 대용량 첨부(11단계)는 볼륨 ${PROJECT_NAME}_files(파일) · _clamav-db(악성 검사 서명), 컨테이너 ${PROJECT_NAME}-clamav · -clamav-updater, 네트워크 ${PROJECT_NAME}_clamav(backend ↔ 검사기) · _clamav-egress(서명 갱신) — 악성 검사 (ClamAV). 아래 명령은 셸에 한 번 읽어 둔 값을 쓴다:
```
export PROJECT_NAME="$(sed -n 's/^PROJECT_NAME=//p' .env.development)"   # 운영은 .env.production
```

구조

브라우저 ─▶ frontend nginx ─(edge)─▶ backend ──HTTP JMAP (app-network, http://mail:8080)──▶ mail (Stalwart)
                                      │ 로그인: <직원 주소>:<비밀번호> 로 세션 조회 (200 / 401)   │ 25  SMTP 수신
                                      │ 메일함: <직원 주소>%<게이트웨이 주소> 로 대리 접근         │ 465 SMTPS 제출 · 993 IMAPS
                                                                                                │ 443 HTTPS — ACME·MTA-STS 만 (JMAP·관리 API·포털은 403)
                                                                                                ▼ 사내 도메인 밖 (개발 환경만)
                                                                                             mailpit — 외부 수신자 메일 수집

메일 엔진은 app-network 대역 전체를 신뢰한다(자동 차단 예외·게이트웨이 로그인). 그래서 app-network 에는 backend·db·redis·mail(개발은 mailpit 도)만 붙이고, 인터넷을 향한 frontend 는 edge 로만 backend 에 닿는다. setup 이 앱 네트워크에 붙은 컨테이너를 확인한다. 엔진의 DNS 는 메일 전용 리졸버(mail-resolver)가 맡는다 — mail 과 리졸버만 붙는 mail-dns 로 닿는다 (DNS 리졸버와 스팸 차단 목록). 대용량 첨부(11단계)의 파일은 엔진이 아니라 backend 의 볼륨에 두고, 악성 검사기(clamav)는 backend 와만 닿는 clamav 네트워크에 둔다 — app-network(신뢰 대역)에 붙이지 않는다 (악성 검사 (ClamAV)).

브라우저(직원) ─▶ portal.  ┐                                       ┌─(app-network)─▶ db · mail
받는 사람(바깥) ─▶ files.  ┴▶ 외부 프록시 ─▶ frontend nginx ─(edge)─▶ backend ─┤ /app/files = 볼륨 <PROJECT_NAME>_files
                                  (Host 로 server 를 가른다)          └─(clamav — internal)─▶ clamav(clamd) ◀─ 볼륨 <PROJECT_NAME>_clamav-db(읽기 전용)
                                                                                    clamav-updater(freshclam) ─(clamav-egress)─▶ database.clamav.net

구성 요소	위치	비고
`mail` 서비스	`docker-compose.yml` (profile `mail`)	named volume `<PROJECT_NAME>_mail-config`(config.json) · `<PROJECT_NAME>_mail-data`(RocksDB)
`mail-resolver`	`docker-compose.yml` (profile `mail`) · 설정 `mail/resolver/unbound.conf`	엔진 전용 재귀 DNS(unbound) — mail 만 닿는 `mail-dns`(internal)와 자기 바깥 길 `mail-dns-egress` 에만 붙는다. 상태 없음(볼륨 없음) — DNS 리졸버와 스팸 차단 목록
`clamav` · `clamav-updater`	`docker-compose.yml` (운영은 늘 · 개발은 profile `clamav`) · 설정 `mail/clamav/clamd.conf` · `freshclam.conf`	대용량 첨부의 악성 검사기(clamd)와 서명 갱신(freshclam) — 둘로 나눠 검사기는 바깥 길이 없다. 서명은 named volume `<PROJECT_NAME>_clamav-db` — 악성 검사 (ClamAV)
대용량 첨부 파일	backend 의 named volume `<PROJECT_NAME>_files` → `/app/files` (개발도 같다)	기록은 DB. 30일짜리 전송물이라 백업하지 않는다 — 백업 · 대용량 첨부 — 공개 내려받기 호스트
dev 오버라이드	`docker-compose.dev.yml`	운영 포트 제거, `127.0.0.1:${MAIL_ADMIN_PORT}` → 8080 만
`mailpit`	`docker-compose.dev.yml` 전용 (profile `mail`)	비-root(65534), UI `127.0.0.1:${MAILPIT_UI_PORT}`
setup 스크립트	`mail/scripts/setup.mjs`	아래 "setup 스크립트가 하는 일"

포트	운영	개발
25 · 465 · 993 · 443	호스트에 공개 (`0.0.0.0`, IPv4 만 — 보안). 443 의 HTTP 는 MTA-STS 정책 파일만 연다	공개하지 않음
8080 (HTTP JMAP·관리 API)	공개하지 않음 (backend 전용 내부망)	`127.0.0.1:${MAIL_ADMIN_PORT}` (관리 화면·setup 스크립트)
995 pop3s · 4190 sieve	리스너는 있으나 공개하지 않음	—

계정	용도	비밀번호
`<MAIL_ADMIN_LOCAL_PART>@<MAIL_DOMAIN>` (기본 `admin@`)	영구 관리자 — bootstrap 이 `admin@` 으로 만들고, `MAIL_ADMIN_LOCAL_PART` 가 다르면 setup 이 곧바로 그 아이디로 바꾼다. bootstrap 전에만 정할 수 있다 (아래 "문제 해결"). 백엔드는 이 계정의 웹메일 로그인·대리 접근을 막는다	`MAIL_ADMIN_PASSWORD`
복구 관리자 (`MAIL_RECOVERY_ADMIN` 의 아이디)	최초 bootstrap·관리자 복구 전용 슈퍼유저. 값이 있는 동안은 정상 모드에서도 관리자로 로그인된다 — 운영은 env 파일에 두지 않고 일회성 override + `--recovery` 로만 쓴다	`MAIL_RECOVERY_ADMIN`
`MAIL_GATEWAY_USER`	백엔드의 대리 접근 전용 서비스 계정 — 역할 권한은 `authenticate`·`impersonate` 뿐, 신뢰 대역(`APP_NETWORK_SUBNET`)에서만 로그인	`MAIL_GATEWAY_PASSWORD`
`<MAIL_DIRECTORY_LOCAL_PART>@<MAIL_DOMAIN>` (기본 `mail-directory@`)	사내 목록 계정 — 백엔드가 엔진의 계정 목록(Principal)에서 직원 이름·주소만 읽는다. 역할 권한은 `authenticate`·`jmapPrincipalGet`·`jmapPrincipalQuery` 뿐, 게이트웨이 대리 접근으로만 쓰고 메일을 받지 않는다. 복구 관리자로만 만들어진다 (사내 목록 계정)	없음
`ara.kim@` 김아라 · `doyun.lee@` 이도윤 · `seojun.park@` 박서준	개발 전용 테스트 직원	`MAIL_DEV_USER_PASSWORD`

개발 시작

# 0) env 파일 (처음 한 번) — change-me-* 를 무작위 영문·숫자로 교체한다
cp .env.development.example .env.development
cp backend/.env.development.example backend/.env.development

# 1) 기동 — COMPOSE_PROFILES=mail 이 기본이라 backend·db·mail·mail-resolver(메일 전용 DNS)·mailpit 이 함께 뜬다
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development up -d

# 2) 메일 엔진 설정 (처음 한 번 — 이후에도 env 를 바꾸면 다시 실행한다)
node --env-file=.env.development mail/scripts/setup.mjs

확인	주소
관리 화면 (웹 포털)	http://localhost:8180/admin/ — `admin@arasystem.test` / `MAIL_ADMIN_PASSWORD`
직원 셀프서비스	http://localhost:8180/account/
Mailpit (외부 수신자 메일)	http://localhost:8025

첫 실행은 bootstrap → mail 컨테이너를 스스로 재시작(docker restart <PROJECT_NAME>-mail)한 뒤 이어서 진행한다.
출력의 [생성]·[변경]·[유지] 로 무엇이 바뀌었는지 보인다. 두 번째 실행부터는 전부 [유지] 여야 정상이다.
⚠️ 외부 발송 경로(Mailpit)는 setup 이 설정·리로드한 뒤에야 적용된다. 그 전에 외부 주소로 보내면 실제 인터넷으로 나간다. 그래서 스크립트는 Mailpit 경로를 먼저 확정하고 나서 테스트 계정을 만든다. 시험 수신자는 예약 도메인(example.net 등)만 쓴다.
악성 검사기(ClamAV)는 개발에서 기본으로 띄우지 않는다(메모리 1GB 남짓 · 처음 기동에 서명 110MB 를 받는다) — 그동안 다 올린 대용량 파일은 바로 "검사하지 못함"이다. 켜려면 .env.development 에 COMPOSE_PROFILES=mail,clamav 와 CLAMAV_HOST=clamav 를 두고 up -d(backend 가 새 값으로 다시 만들어진다) — 악성 검사 (ClamAV). 서명은 볼륨에 남아 다음에는 바로 뜬다.

개발 메일 데이터를 버리고 처음부터:

docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development rm -sf mail mailpit
docker volume rm "${PROJECT_NAME}_mail-config" "${PROJECT_NAME}_mail-data"
# 이후 1) 2) 를 다시

(docker compose down -v 도 이 볼륨을 지운다 — 의도한 게 아니라면 쓰지 않는다)

setup 스크립트가 하는 일

사전 확인 (아무것도 바꾸기 전) — app-network 의 실제 서브넷이 APP_NETWORK_SUBNET 인지, 앱 네트워크에 정해진 컨테이너 (backend·db·redis·mail·mailpit)만 붙어 있는지, 백엔드 주소가 신뢰 대역 안인지. 어긋나면 엔진 설정을 바꾸지 않고 중단한다 (신뢰 대역을 바꾼 뒤에 알면 전 직원의 메일이 멈추고 백엔드 주소가 자동 차단 예외에서 빠진다). 앱 네트워크에 다른 컨테이너가 있으면 운영은 중단, 개발은 경고. 메일 전용 리졸버도 본다 — mail-dns 네트워크 · 리졸버 주소 · mail 의 dns, 그리고 메일 컨테이너에서 UDP · TCP 로 답하고 DNSSEC 을 검증하는지. 닿지 않는 리졸버에 엔진의 DNS 를 맡기면 바깥 메일이 멈추므로 하나라도 어긋나면 중단한다(답 확인만은 개발에서 [주의] — 개발 메일은 Mailpit 이다). Spamhaus 키가 있으면 그 키로 시험 항목이 나오는지도 본다 (DNS 리졸버와 스팸 차단 목록)
모드 감지 — bootstrap(첫 기동, 8080 만 열림) / bootstrap 완료·재시작 대기 / 정상
bootstrap — 호스트명·기본 도메인·DKIM 키(ed25519·rsa)·로그(표준 출력) → 재시작. 응답의 무작위 관리자 비밀번호는 한 번만 보이므로 data/mail/bootstrap-admin.json(git 무시)에 잠시 보관했다가 교체 후 지운다. ⚠️ Bootstrap/set 은 원자적이지 않다 — 다시 부르면 도메인 중복으로 거부되면서도 tracer 가 하나 더 생겨 설정 오류가 난다. 그래서
- 부르기 전에 data/mail/ 에 실제로 써 보고, 쓸 수 없으면 아무것도 바꾸지 않고 멈춘다
- 재실행 때는 mail 컨테이너의 /etc/stalwart/config.json 으로 "bootstrap 은 끝났고 재시작만 남았다"를 알아보고 재시작만 한다 (Bootstrap/set 은 재시작 전에 이미 이 파일을 쓴다 — 보관 파일이 없어도 다시 부르지 않는다. docker 를 쓸 수 없으면 보관 파일로 판단)
관리자 — <MAIL_ADMIN_LOCAL_PART>@도메인 비밀번호를 MAIL_ADMIN_PASSWORD 로 맞춘다 (나중에 env 값을 바꾸면 복구 관리자로 다시 맞춘다 — 운영은 --recovery). 갓 bootstrap 한 엔진이면 bootstrap 이 만든 admin@ 의 아이디를 MAIL_ADMIN_LOCAL_PART 로 바꾼다 (Bootstrap/set 은 아이디를 받지 않는다). 이미 쓰던 엔진에서 env 아이디의 관리자가 없으면(bootstrap 뒤에 값만 바꾼 경우) 중단한다
자동 차단 예외 — 신뢰 대역을 AllowedIp 로 등록 (기본 보안 설정은 IP 당 인증 실패 하루 100회면 차단하는데, 모든 로그인이 백엔드 IP 하나를 거친다). 신뢰 대역 = MAIL_TRUSTED_NETWORKS, 비우면 APP_NETWORK_SUBNET(compose 가 고정한 app-network 서브넷). 서브넷보다 넓거나 밖에 있는 대역이 들어오면 실패한다. 이 스크립트가 만든 예전 항목은 지운다.
게이트웨이 — 대리 접근 전용 역할 + 서비스 계정. 비밀번호는 env 값, 자격 증명의 허용 IP 는 신뢰 대역만
잠금 — 직원(User) 역할에서 Principal 조회 권한 13개(jmapPrincipal*·davPrincipal*)를 뺀다(→ InvalidateCaches). 공개 443(https 리스너)의 HTTP 는 /.well-known/mta-sts.txt 만 열고 나머지는 403 (x:Http 의 allowedEndpoints) — 보안 메일을 받지 않는 시스템 계정(관리자 · 게이트웨이 · 사내 목록)으로 오는 메일은 RCPT 에서 없는 주소처럼 550 — 받아 놓고 반송하지 않게 (x:MtaStageRcpt 의 script + 시스템 Sieve 스크립트 — 보안 "메일을 받지 않는 시스템 계정")
사내 목록 계정 — 계정 목록 읽기 전용 역할(authenticate·jmapPrincipalGet·jmapPrincipalQuery) + 비밀번호 없는 계정 <MAIL_DIRECTORY_LOCAL_PART>@도메인. 엔진 관리자는 이 권한을 내줄 수 없어 복구 관리자가 있을 때만(개발 · 운영 --recovery) 만들고 맞춘다. 없으면 관리자로 되는 것(표시 이름·저장 한도·비밀번호 빼기)만 맞추고 역할·계정이 없거나 다르면 [주의] — 실패로 끝내지 않는다. 준비되면 백엔드처럼 게이트웨이 대리 접근으로 Principal/query·get 을 해 본다 (사내 목록 계정)
엔진 한도 — 받는 사람 단위 받는 쪽 한도(같은 보낸 도메인 → 한 받는 사람, 기본 시간당 25)를 인증 없는 세션에만 건다 — 로그인한 직원의 발송(웹메일)에는 걸지 않고 바깥에서 들어오는 메일에는 그대로. 설명·key 로 찾고, 없으면 만들지 않고 [주의] (엔진 한도). 계정마다 임시 업로드 크기 합계(x:Jmap 의 uploadQuota — 1시간 동안 올린 양, 기본 50,000,000바이트)를 첨부 합계 한도의 20배(기본 524,288,000바이트 = 25MB × 20) 이상으로 올린다 — 더 크게 둔 값은 내리지 않고, 개수 · 기간 · 한 번 크기는 그대로 (엔진 한도 "임시 업로드 한도"). 엔진 DNS · Spamhaus — 엔진의 DNS(x:DnsResolver)를 메일 전용 리졸버로(운영은 리졸버에 바로 Custom, 개발은 도커 DNS 를 거쳐 System — Mailpit 이름 때문), 스팸 필터의 Spamhaus 두 항목은 키(MAIL_SPAMHAUS_DQS_KEY)가 있고 시험을 통과하면 DQS 로 켜고 아니면 끈다(공개 미러는 쓰지 않는다 — DNS 리졸버와 스팸 차단 목록). 엔진 웹훅(12단계) — 인증 이벤트 셋을 백엔드의 받는 곳(http://backend:<BACKEND_PORT>/api/internal/mail-engine-events)으로 MAIL_WEBHOOK_SECRET 로 서명해 보내는 x:WebHook 하나를 맞춘다(setup 표시 머리글로 찾는다 — 키가 비면 운영은 중단, 개발은 [주의] 뒤 있던 것을 끈다 — 엔진 웹훅). 모두 9 의 리로드로 반영된다
설정 리로드 → 반영 확인 — 메일 컨테이너의 네트워크 주소로 https://…:443/jmap/session 이 403, 내부 8080 이 200 인지 본다. 운영은 바깥에서 쓰는 주소 그대로(MAIL_PUBLIC_URL/jmap/session, 이 스크립트를 돌리는 호스트에서)도 403 인지 본다 — 200 이면 실패(앞단 프록시가 8080 으로 넘기는 구성), 연결 자체가 안 되면 경고와 함께 바깥에서 확인할 curl 명령을 보여 준다. 게이트웨이로 관리자를 대리 접근해 관리 API 가 열리는지도 데이터 없는 호출로 본다 — 열리면 매번 [주의] (보안). 시스템 계정의 RCPT 도 메일 컨테이너 안에서 자기 네트워크 주소의 25 로 보내 550 인지 본다(RCPT 까지만 — 메일은 보내지 않는다). 보낸 사람은 빈 봉투(MAIL FROM:<>)다 — 사내 도메인 밖이라 시범 공존의 MAIL FROM 위조 막기에 걸리지 않고, 어긋나 DATA 까지 가더라도 반송이 생기지 않는다. 엔진의 이번 기동 로그에 "DNS resolver cannot validate DNSSEC"(DANE 꺼짐) 경고가 없는지도 본다 — 리로드는 이 경고를 남기지 않아 기동 로그만 볼 수 있다. 엔진 웹훅은 리로드 뒤 다시 읽어 맞는지 보고([확인] 엔진 웹훅 켜짐), 메일 컨테이너 안에서 서명한 빈 묶음을 받는 곳에 보내 200 인지 본다 ([확인] 엔진 웹훅 — … 받았다 — 401 · 404 는 운영은 실패, 개발은 [주의]. 이번 실행에서 엔진에 키를 넣었으면 401 도 [주의] 와 다음 명령 — 엔진 웹훅)
[개발] 외부 발송 경로 — Relay mailpit:1025 + 발송 전략(사내 도메인은 로컬, 나머지는 mailpit) — 9 의 리로드로 반영된 것을 확인한 뒤에만 11 (7 의 사내 목록 계정은 메일을 보내지도 받지도 못하므로 그보다 먼저 만들어도 된다)
[개발] 테스트 직원 계정 → 게이트웨이 대리 접근, 직원의 계정 목록 조회 차단(Principal/get → forbidden)까지 자체 확인
시범 공존 (MAIL_PILOT_LEGACY_HOST 가 있을 때 — 파일럿 공존) — 바꾸기 전에 도메인 · 서버 이름 · 기존 서버에 닿는지 · 자기 자신이 아닌지를 보고, 막는 것(맨 앞에 주인 표시인 자동 차단 예외 · RCPT 가드 · MAIL FROM 위조 막기 · 기존 서버 IP 예외)을 6 · 8 과 함께 저장해 9 의 리로드로 먼저 걸고, RCPT 가드가 답하는지 본 뒤 → 발송 경로 legacy · 발송 전략 → 리로드 → 도메인 allowRelaying(저장 즉시) → 다시 RCPT · MAIL FROM 을 실제로 보내 확인한다 — 켜기 전에 가드가 2초 안에 답하지 않으면 켜지 않고, 켠 뒤에 답하지 않으면 allowRelaying 을 바로 다시 끄고 멈춘다(끄지 못하면 그렇게 알린다). 값이 비면 거꾸로(allowRelaying 먼저, 꺼진 것을 다시 읽어 확인한 뒤에만 나머지) 지운다 — 운영은 --end-pilot 이 있어야 한다

그 밖의 안전장치:

운영은 docker 를 쓸 수 있어야 한다 — 없으면 아무것도 바꾸지 않고 실패한다 (네트워크·복구 관리자 확인, bootstrap 뒤 재시작).
셸에 APP_ENV·APP_NETWORK_SUBNET 등이 이미 있으면 중단한다. Node 의 --env-file 은 기존 환경변수를 덮어쓰지 않아, 셸에 APP_ENV=development 가 남은 채 .env.production 으로 돌리면 운영에 개발 설정(Mailpit 경로)을 넣게 된다. (MAIL_RECOVERY_ADMIN 은 예외 — 원래 셸에서 일회성으로 주는 값이다. 시범 공존 값 MAIL_PILOT_LEGACY_* 는 개발에서만 예외 — 시험할 때 셸에서 한 번 켜 본다. 운영은 env 파일에 없는 시범 값이 셸에 있어도 중단한다 — 시범 상태는 엔진에 남는 설정이라 env 파일만 보고도 알 수 있어야 한다)
APP_NETWORK_SUBNET 은 사설 대역의 네트워크 주소, 접두 길이 /24~/28 만 받는다 — 이 대역 전체가 신뢰 대역이라 넓게 잡지 않는다 (넓을수록 사무실 LAN·VPN 같은 실제 클라이언트 주소와 겹친다. /28 보다 좁으면 컨테이너 주소가 모자란다).
MAIL_ADMIN_LOCAL_PART 는 백엔드와 같은 형식 규칙(영문·숫자·.·_·-, 앞뒤는 영문·숫자, 64자 이하, 대소문자 무시)이다. 로그인 확인은 2xx 만 "맞음", 401 만 "틀림"으로 보고 그 밖(429·5xx)은 중단한다 — 비밀번호를 잘못 덮어쓰지 않게. 402(비밀번호는 맞고 그 계정에 2단계 인증이 켜져 있음 — 12단계)를 "맞음"으로 보는 것은 테스트 직원뿐이다 — 웹메일에서 2단계 인증을 켠 테스트 직원의 비밀번호를 덮어쓰지 않고, 그 직원의 계정 목록 비공개 확인은 게이트웨이 대리 접근으로, 시범 공존의 인증 발송 확인은 2단계가 꺼진 직원으로 본다(모두 켜져 있으면 [건너뜀]). 게이트웨이가 402 면 아무것도 바꾸기 전에 멈춘다 — 백엔드의 대리 접근이 게이트웨이 자신의 2단계 인증에 걸려 모두 막히고 웹메일 전체가 선다. 관리자 · 복구 관리자에 2단계 인증이 켜져 있어도 멈춘다(비밀번호만으로 관리 API 에 들어가지 못한다).
운영에서는 change-me 예시 값을 거부하고, MAIL_PUBLIC_URL 이 경로 없는 https:// 가 아니면 실패, 발송 전략이 Mailpit 을 가리키면 실패로 보고한다.
운영의 복구 관리자 규칙 — env 파일에 있으면 실패, 셸에 있는데 --recovery 가 없으면 실패, --recovery 실행은 끝에 "복구 관리자 끄기"를 안내하고 종료 코드 3, 그 뒤 일반 실행은 mail 컨테이너에 복구 관리자가 남아 있으면 실패.
관리자 역할 계정이 백엔드 차단 목록(MAIL_ADMIN_LOCAL_PART 관리자 + MAIL_BLOCKED_ACCOUNTS)에서 빠져 있으면 [주의].
종료 코드 0 성공 · 1 실패 · 3 후속 조치 필요(개발에서 docker 를 쓸 수 없는 환경의 재시작, 운영 --recovery 뒤 복구 관리자 끄기 — 안내대로 한 뒤 다시 실행).

백엔드 연결 정보

env (backend 에 compose 가 주입)	값
`MAIL_JMAP_URL`	`http://mail:8080` (내부 JMAP)
`MAIL_DOMAIN`	`arasystem.test` / 운영 `arasystem.it.kr`
`MAIL_GATEWAY_USER` · `MAIL_GATEWAY_PASSWORD`	게이트웨이 주소 · 비밀번호
`MAIL_ATTACHMENT_MAX_SIZE_MB`	첨부 1개 최대 크기 (기본 20). 프론트 nginx 본문 한도는 이 값 + 1MB 로 자동, 외부 프록시는 직접 — docker 스킬 "운영 환경"
`MAIL_ATTACHMENT_TOTAL_MAX_SIZE_MB`	메일 한 통의 첨부 합계 (기본 25, 파일당 한도 이상). setup 이 엔진의 임시 업로드 크기 합계를 이 값의 20배 이상으로 맞추므로 첨부 한도를 바꾸면 setup 도 다시 실행한다 (엔진 한도)
`MAIL_DIRECTORY_LOCAL_PART`	사내 목록 계정 아이디 (기본 `mail-directory`) — setup 과 같은 값을 읽는다 (사내 목록 계정)
`MAIL_WEBHOOK_SECRET`	엔진 웹훅의 서명 키(12단계 — 영문 · 숫자 32자 이상, 운영 필수) — setup 이 같은 값으로 엔진 웹훅을 만든다. 바꾸면 setup 과 backend 를 함께 (엔진 웹훅)
`APP_NETWORK_SUBNET`	앱 네트워크 대역 (기본 `172.16.71.0/24`) — 웹훅 받는 쪽이 접속 주소(소켓)가 이 대역인지 본다

로그인 확인: GET {MAIL_JMAP_URL}/jmap/session + Basic <직원 주소>:<비밀번호> → 200 / 401
메일함 접근: Basic <직원 주소>%<MAIL_GATEWAY_USER> : MAIL_GATEWAY_PASSWORD (게이트웨이 비밀번호 틀림·없는 직원 → 401, 대리 접근 권한 없는 계정 → 403)
사내 목록: Basic <MAIL_DIRECTORY_LOCAL_PART>@<MAIL_DOMAIN>%<MAIL_GATEWAY_USER> : MAIL_GATEWAY_PASSWORD → 세션의 urn:ietf:params:jmap:principals 계정으로 Principal/query·Principal/get (사내 목록 계정 — 계정이 없으면 401, 역할에 authenticate 가 없으면 403)
⚠️ 세션 응답의 apiUrl·downloadUrl·uploadUrl·eventSourceUrl 은 MAIL_PUBLIC_URL 기준 절대 주소다 (개발 http://localhost:8180/jmap/). 백엔드는 이 주소를 따르지 말고 MAIL_JMAP_URL 에 경로만 붙여 쓴다.
Email/query 의 subject 필터는 단어 단위 검색이고 제목 앞의 [태그] 를 떼고 색인하는 것으로 보인다 — 부분 문자열 검색이 아니다.
대리 접근은 메일 엔진 로그 auth.success 에 accountName(대상 직원)·details(게이트웨이)·remoteIp 로 남는다.
신뢰 대역은 자동 차단에서 빠지므로 로그인 무차별 대입 방어는 백엔드가 맡아야 한다 (로그인 엔드포인트 엄격 한도 — security).

사내 목록 계정

백엔드가 사내 목록(계약 3절 "사내 목록" — GET /api/directory-entries 와 받는 사람 추천의 "사내")을 채우려고 엔진의 계정 목록(JMAP Principal)에서 직원 이름·주소만 읽는 전용 계정이다. 직원 역할에서는 이 권한을 뺐으므로(보안) 계정 목록을 읽는 길은 이 계정 하나뿐이다.

항목	값
주소	`<MAIL_DIRECTORY_LOCAL_PART>@<MAIL_DOMAIN>` (기본 `mail-directory@`) — 관리자·게이트웨이 아이디와 같으면 setup 이 아무것도 바꾸기 전에 멈춘다
역할	설명 `사내 목록 — 계정 목록 읽기 전용 [setup.mjs]` · 권한 `authenticate`·`jmapPrincipalGet`·`jmapPrincipalQuery` 뿐 (빼는 권한·물려받는 역할 없음). `authenticate` 가 없으면 대리 접근이 403 이다
계정	표시 이름 `사내 목록 (백엔드 계정 목록 읽기 전용) [setup.mjs]` · 비밀번호 없음 · 저장 한도 `quotas.maxDiskQuota` 1,048,576바이트
쓰는 법	백엔드만 — 게이트웨이 대리 접근 `<사내 목록 주소>%<MAIL_GATEWAY_USER>` 로 세션의 `urn:ietf:params:jmap:principals` 계정에 `Principal/query`·`Principal/get`
엔진이 주는 칸	`id`·`type`(`individual` 개인 · `group` 공용 주소)·`name`(로그인 이름)·`description`(표시 이름)·`email` 뿐 — 비밀번호 같은 칸은 없다. 관리자·게이트웨이·이 계정도 목록에 나오므로 빼는 것은 백엔드 몫이다 (계약 3절 "빼는 계정")
메일	받지 않는다 — 이 주소(+태그 꼴 포함)로 오는 메일은 RCPT 에서 없는 주소처럼 550 이다(보안 "메일을 받지 않는 시스템 계정"). 그 뒤의 막으로 역할에 `emailReceive` 가 없고(배달하지 않는다) 저장 한도도 작다

왜 복구 관리자인가 — 엔진 관리자 역할(System Administrator)에는 jmapPrincipal* 이 없고, 엔진은 역할·계정의 권한을 바꿀 때 바꾼 뒤의 권한 전체를 바꾸는 쪽이 가졌는지 본다. 그래서 관리자로는 이 역할을 만들 수도, 계정에 줄 수도, 이 역할에서 다른 권한을 뺄 수도 없다 (You are not authorized to grant permissions: jmapPrincipalQuery, jmapPrincipalGet). 관리자로 되는 것은 계정의 표시 이름·저장 한도 고치기, 비밀번호 빼기, 계정 지우기다 (2026-10-29, 0.16.27 에서 확인).
언제 만들어지나 — 개발은 setup 을 돌릴 때마다(env 파일에 복구 관리자가 있다). 운영은 운영 배포의 --recovery 실행(첫 배포)에서 만들어진다. 이미 운영 중인 서버는 같은 절차(1 복구 관리자 주기 → up -d mail → 3 --recovery → 4·5 끄기)를 한 번 더 한다 — 이미 맞는 나머지는 [유지] 다.
복구 관리자 없이 돌리면(운영의 보통 실행) — 읽어서 확인하고, 관리자로 되는 것(표시 이름·저장 한도·비밀번호 빼기·옛 계정 지우기)만 맞춘다. 역할·계정이 없거나 역할이 다르면 [주의] 만 내고 실패로 끝내지 않는다 — 그동안 백엔드는 사내 목록 대신 로그인한 직원 기록(최근 90일)을 쓴다 (계약 3절). --recovery 로 돌렸는데 복구 관리자로 로그인하지 못해 맞추지 못했으면 실패로 끝난다(mail 컨테이너를 그 값으로 다시 만들었는지 본다).
비밀번호가 없다 — 이 계정으로는 직접 로그인할 수 없고, 게이트웨이 비밀번호를 가진 백엔드만 대리 접근으로 쓴다. 누가 비밀번호를 넣으면 그것으로 계정 목록(관리자·게이트웨이 주소 포함)을 읽을 수 있으므로 setup 이 다음 실행에서 뺀다(관리자로도 된다).
이 역할은 기본 직원 역할(User)과 따로다 — 직원 역할에서 jmapPrincipal* 을 빼는 단계(setup 스크립트가 하는 일 6)는 이 역할을 건드리지 않는다.

지우거나 바꾸면:

한 일	생기는 일	되돌리기
계정을 지움	대리 접근이 401 → 사내 목록 `503 MAIL_001`, 받는 사람 추천의 "사내"는 로그인한 직원 기록으로	복구 관리자로 setup (운영 `--recovery`)
역할을 지움	계정이 쓰는 동안은 엔진이 거절한다(`objectIsLinked`) — 계정을 먼저 지워야 지워진다	위와 같다
역할에 권한을 더함 · 물려받는 역할을 붙임	그 권한이 이 계정(= 게이트웨이를 가진 백엔드)에 열린다 — setup 이 `[변경]`(복구 관리자) 또는 `[주의]`	복구 관리자로 setup — 관리자로는 뺄 수 없다
역할에서 `authenticate`·`jmapPrincipal*` 을 뺌 (빼는 권한에 넣음 포함)	계정 목록을 읽지 못한다 → 사내 목록 `503 MAIL_001`	복구 관리자로 setup
계정의 역할을 바꿈	위의 둘 중 하나	복구 관리자로 setup
계정에 비밀번호를 넣음	그 비밀번호로 계정 목록을 읽을 수 있다	setup (관리자로도 뺀다)
다른 계정에 이 역할을 줌	그 계정이 계정 목록 전체를 읽는다 — setup 이 `[주의]`	관리 화면 › 계정에서 그 계정의 역할을 바꾼다 (관리자로 된다)
`MAIL_DIRECTORY_LOCAL_PART` 를 바꿈	복구 관리자로 돌린 setup 이 새 계정을 만들고, 그 뒤에 옛 계정(setup 표시 + 이 역할 하나)을 지운다 — backend 도 다시 띄운다(`up -d backend`)	값을 되돌리고 같은 절차

확인 (2026-10-29, 개발 엔진 0.16.27): 처음 실행은 [생성] 둘(역할·계정)과 [확인] 사내 목록 — 대리 접근 … (Principal/query · get), 다시 돌리면 [유지]. 역할에 권한·빼는 권한·물려받는 역할을 붙이고 계정에 비밀번호를 넣은 뒤 돌리면 복구 관리자로 모두 [변경], 복구 관리자 없이 돌리면 계정만 [변경](관리자로)이고 역할은 [주의] · 종료 코드 0. 계정을 지우고 복구 관리자 없이 돌리면 [주의] 사내 목록 계정이 없습니다 (계정 없음) · 종료 코드 0. 아이디를 바꿨다 되돌리면 [생성] 새 계정 · [삭제] 옛 계정.

운영 배포

사전 조건:

메일 전용 호스트 — 25·465·993·443 을 다른 서비스가 쓰지 않는다 (리버스 프록시가 443 을 쓰면 대안 참조 · 프록시가 다른 서버에 있고 사설망으로 붙으면 리버스 프록시가 다른 서버에 있을 때)
MAIL_HOSTNAME 의 A 레코드 → 이 호스트 IP, 그 IP 의 PTR → MAIL_HOSTNAME (PTR)
아웃바운드 25 허용 (클라우드는 기본 차단인 곳이 많다 — 막혀 있으면 외부 릴레이)
아웃바운드 HTTPS — Stalwart 는 기동 때 GitHub 에서 웹 포털을 내려받고, ACME(Let's Encrypt)로 인증서를 받는다
메일 서버 전용 재귀 DNS — compose 에 들어 있다(mail-resolver — 공용·ISP DNS(KT·Google·Cloudflare 등)로는 Spamhaus 조회가 막힌다). 이 서버에서 바깥 53(UDP · TCP)으로 나갈 수 있어야 한다 — 리졸버가 루트부터 각 도메인의 DNS 서버에 직접 묻는다. 막혀 있으면 setup 이 사전 확인에서 멈춘다 (DNS 리졸버와 스팸 차단 목록)
Spamhaus 이용 조건 — 공개 미러는 쓰지 않는다(소규모 · 비상업 용도). Spamhaus 의 "Blocklists via DNS Query" 키를 .env.production 의 MAIL_SPAMHAUS_DQS_KEY 에 넣으면 두 항목을 그 키로 묻고, 비워 두면 두 항목이 꺼진다. 무료 계정은 Fair Use(소규모 · 비상업) 조건이다 — 회사가 대상인지는 Spamhaus 가 판단하고, 안 되면 끈 채로 두거나 유료(30일 체험). 체험 키는 30일이 지나면 답이 멈춘다 — 구독하거나 키를 비우고 setup (멈춘 줄은 다음 setup 이 종료 1 로 알린다 — 주기적으로 돌리거나 계정의 만료일을 본다). 나머지 16개 목록도 이용 조건을 확인한다 (같은 절)
엔진 한도 — 받는 쪽 한도 값, 직원마다 내보내는 양의 한도, 직원마다 1시간 업로드 한도(크기 · 개수)를 정한다 (엔진 한도)
포털(웹메일) 앞의 외부 리버스 프록시 — 요구사항은 docker 스킬 "운영 환경" (같은 주소 배포 · X-Forwarded-For · IPv6 · 본문 한도·시간 제한). 다른 서버의 Nginx Proxy Manager 라면 설정 · TRUST_PROXY 는 리버스 프록시가 다른 서버에 있을 때
APP_NETWORK_SUBNET·EDGE_NETWORK_SUBNET·MAIL_RESOLVER_SUBNET 이 그 호스트의 다른 도커 네트워크와 겹치지 않는다 (겹치면 up 이 "Pool overlaps" 로 실패한다)
저장소는 기본 umask(022)로 클론한다 — mail/resolver/unbound.conf 를 리졸버 컨테이너 사용자(101:102)가 읽어야 한다(umask 077 이면 리졸버가 뜨지 않는다)
rootful 도커 + iptables (도커 기본값). 게시 포트(25·465·993·443)로 들어온 접속이 원래 주소 그대로 컨테이너에 보여야 한다 — rootless 도커(포트 전달이 주소를 바꾼다)나 "iptables": false(모든 접속이 docker-proxy 를 거친다)면 외부 접속이 도커 내부 주소로 보여 자동 차단·게이트웨이 IP 제한이 무력화된다. 배포 뒤 원래 접속 주소 확인으로 확인한다.
setup 을 돌릴 사용자 — docker 를 쓸 수 있어야 한다(docker 그룹, 또는 매번 sudo -E). 저장소는 그 사용자로 클론한다(sudo git clone 금지) — data/ 가 그 사용자 소유여야 setup 이 bootstrap 임시 비밀번호를 보관할 수 있다 (data/.gitkeep 이 있어 클론 때 생긴다).
MAIL_ADMIN_LOCAL_PART 를 bootstrap 전에 정한다 — mailcow 에 실제 admin@ 메일함이 있으면 다른 아이디로 (bootstrap 뒤에는 바꿀 수 없다).
MAIL_DIRECTORY_LOCAL_PART(사내 목록 계정, 기본 mail-directory)가 옮겨 올 메일함과 겹치지 않는다 — 겹치면 setup 이 그 계정을 건드리지 않고 실패한다 (사내 목록 계정).
대용량 첨부(11단계) — .env.production 의 SHARE_PUBLIC_URL(공개 내려받기 호스트 — https://files.arasystem.it.kr, CORS_ORIGIN 에 넣지 않는다) · CLAMAV_HOST=clamav(둘 다 운영 필수 — 없으면 백엔드가 뜨지 않는다), 그 호스트의 DNS · 외부 프록시 Proxy Host (대용량 첨부 — 공개 내려받기 호스트), 악성 검사 서명 갱신의 바깥 HTTPS(database.clamav.net) · 메모리 · 디스크(메모리 예산 — 8GB 서버에 스택 전체 + ClamAV). 첫 up 은 clamav-updater 가 서명을 받는 동안(1~3분) clamav 가 기다린다
계정 보안(12단계) — .env.production 의 MAIL_WEBHOOK_SECRET(엔진 웹훅의 서명 키 — openssl rand -hex 24 로 만든 값, 사람이 지은 값은 쓰지 않는다). 운영 필수다 — 아래 2)의 up 전에 넣는다(없으면 백엔드가 env 검사에서 멈춰 웹메일 전체가 서고, setup 도 멈춘다). 직원에게 미리 알린다 — 2단계 인증을 켜면 아웃룩 · 휴대폰 메일 앱은 앱 비밀번호로 다시 연결해야 한다 (계정 보안)

복구 관리자(MAIL_RECOVERY_ADMIN)는 .env.production 에 적지 않는다. 최초 bootstrap(또는 관리자 비밀번호 복구) 때 셸에서만 잠깐 준다.

export PROJECT_NAME="$(sed -n 's/^PROJECT_NAME=//p' .env.production)"
# 1) 복구 관리자를 일회성으로 준다 — 셸 기록에 남지 않게 read 로 받는다 (compose 는 셸 값이 env 파일보다 우선한다)
read -rsp '임시 복구 비밀번호: ' P; echo; export MAIL_RECOVERY_ADMIN="admin:$P"

# 2) 기동 (mail 은 bootstrap 모드로 뜬다 — 8080 만 열림). sudo 를 쓰면 -E 로 셸 값을 넘긴다
sudo -E docker compose --env-file .env.production up -d --build

# 3) setup --recovery — 호스트에서, docker 를 쓸 수 있는 사용자로 실행한다 (운영은 docker 가 없으면 아무것도 바꾸지 않고 실패한다).
#    8080 을 공개하지 않으므로 mail 컨테이너의 내부 주소로 붙는다 (리눅스 호스트는 컨테이너 IP 로 바로 닿는다).
export MAIL_ADMIN_URL="http://$(sudo docker inspect -f '{{index .NetworkSettings.Networks "'"${PROJECT_NAME}_app-network"'" "IPAddress"}}' "${PROJECT_NAME}-mail"):8080"
#    (A) 호스트 Node (24 LTS 권장, 최소 20.6 — --env-file) — docker 그룹이면 그대로:
node --env-file=.env.production mail/scripts/setup.mjs --recovery
#        docker 그룹이 아니면 sudo 로 (셸 값과 PATH 를 넘긴다). ⚠️ 그러면 이후 실행도 모두 같은 형태로 — data/mail/ 이 root 소유가 된다
sudo -E env "PATH=$PATH" node --env-file=.env.production mail/scripts/setup.mjs --recovery
#    (B) 호스트에 Node 가 없으면 — 공식 배포 파일을 임시 폴더에 받아 그대로 쓴다 (설치하지 않는다, 체크섬 확인. ARM 서버는 linux-arm64)
NODE_DIST=node-v24.22.1-linux-x64; NODE_TMP="$(mktemp -d)"
curl -fsSL -o "$NODE_TMP/$NODE_DIST.tar.xz" "https://nodejs.org/dist/v24.22.1/$NODE_DIST.tar.xz"
curl -fsSL "https://nodejs.org/dist/v24.22.1/SHASUMS256.txt" | grep " $NODE_DIST.tar.xz\$" | (cd "$NODE_TMP" && sha256sum -c -)
tar -xJf "$NODE_TMP/$NODE_DIST.tar.xz" -C "$NODE_TMP" && export PATH="$NODE_TMP/$NODE_DIST/bin:$PATH"
#        → 이후는 (A) 와 같다. 끝나면 rm -rf "$NODE_TMP"
#    --recovery 실행은 설정을 마친 뒤 "복구 관리자 끄기"를 안내하고 종료 코드 3 으로 끝난다 → 4) 로

# 4) 복구 관리자 끄기 — 셸 값을 지우고 mail 컨테이너를 다시 만든다 (빈 값이면 복구 자격 증명은 401 — 검증함)
unset MAIL_RECOVERY_ADMIN P
sudo docker compose --env-file .env.production up -d mail

# 5) --recovery 없이 다시 실행 (3 과 같은 형태 — 컨테이너를 다시 만들었으므로 MAIL_ADMIN_URL 도 다시 구한다)
#    전부 [유지] 이고, 컨테이너에 복구 관리자가 남아 있지 않은지 확인한다 (남아 있으면 실패)
export MAIL_ADMIN_URL="http://$(sudo docker inspect -f '{{index .NetworkSettings.Networks "'"${PROJECT_NAME}_app-network"'" "IPAddress"}}' "${PROJECT_NAME}-mail"):8080"
node --env-file=.env.production mail/scripts/setup.mjs

3)의 --recovery 실행은 사내 목록 계정도 만든다 — 엔진 관리자는 그 권한을 내줄 수 없어 복구 관리자로만 된다 (사내 목록 계정). 이 기능(8단계) 전부터 운영 중인 서버는 1)~5) 를 한 번 더 한다. 5)의 보통 실행은 그 계정이 있고 맞는지 읽어서 확인하고, 없으면 [주의] 만 낸다.
DNS — 2)의 up 이 메일 전용 리졸버(mail-resolver)를 mail 보다 먼저 띄운다. 3)에서 setup 이 리졸버를 확인한 뒤 엔진의 DNS 를 그쪽으로 바꾸고([변경] 엔진 DNS — … Custom), 4)에서 다시 만든 mail 은 그 설정으로 뜬다 — 5)의 출력에 [확인] 메일 전용 리졸버 … 와 [확인] 엔진 기동 로그(…)에 DNSSEC 경고가 없다 가 있어야 한다. Spamhaus 키가 있으면 [확인] Spamhaus 키 … 시험 항목 … 두 줄, 없으면 [주의] MAIL_SPAMHAUS_DQS_KEY 가 없어 … 다 (DNS 리졸버와 스팸 차단 목록). 리졸버 전에 띄운 서버(이 기능 전 배포)는 sudo docker compose --env-file .env.production up -d(mail 이 다시 만들어진다 — 몇 초 끊긴다) 뒤 5)와 같은 형태로 setup 을 한 번 돌린다. up 이 optional dependency "mail-resolver" failed to start 경고를 내면 mail 은 떴지만 리졸버가 unhealthy · 멈춤이다 — 리졸버 장애 때.
엔진 웹훅(12단계) — 5)의 출력에 [유지] 엔진 웹훅 → http://backend:3000/api/internal/mail-engine-events …(처음은 [생성]), [확인] 엔진 웹훅 켜짐 — …, [확인] 엔진 웹훅 — 메일 컨테이너에서 서명한 빈 묶음을 백엔드가 받았다 (HTTP 200 …) 가 있어야 한다. 3)은 백엔드가 아직 뜨는 중이면 마지막 줄이 [주의] … 닿지 못했습니다 일 수 있다(5 에서 본다) — 나머지 확인은 계정 보안 — 운영 확인
12단계 전부터 운영 중인 서버 — 차례가 중요하다(키보다 새 이미지를 먼저 띄우면 백엔드가 env 검사에서 멈춰 웹메일 전체가 선다):
1. .env.production 에 MAIL_WEBHOOK_SECRET 을 넣는다 — printf 'MAIL_WEBHOOK_SECRET=%s\n' "$(openssl rand -hex 24)" >> .env.production(값은 화면에 찍지 않는다. 파일 끝에 줄바꿈이 없으면 앞 줄에 붙으니 먼저 tail -c1 .env.production | xxd 로 0a 인지 본다)
2. sudo docker compose --env-file .env.production up -d --build — backend(마이그레이션 AddAccountSecurity 가 뜰 때 적용된다)와 frontend(/api/internal/ 을 닫는 nginx 스니펫 · 잘못된 요청 대상의 400)를 함께 새로 만든다
3. backend 가 healthy 가 된 뒤(sudo docker compose --env-file .env.production ps backend) 3)처럼 MAIL_ADMIN_URL 을 구해 setup(복구 관리자 없이 — 5 와 같은 형태) → [생성] 엔진 웹훅 · [확인] 엔진 웹훅 — … 받았다
4. 운영 확인 (12단계) — 메일 프로그램으로 한 번 로그인해 로그인 기록에 IMAP 줄이 생기는지 본다
운영 setup 은 끝에 권장 DNS 레코드(DKIM·SPF·MX·DMARC·SRV·MTA-STS·autoconfig)를 출력한다. 그대로 붙이지 말고 아래 전환 절차 순서를 따른다.
TLS 인증서 이름을 MAIL_HOSTNAME 하나로 정한다 (2026-10-31 운영에서 겪음). bootstrap 이 켠 도메인의 자동 인증서(ACME)는 이름을 정하지 않으면 기본 묶음 — mta-sts · autoconfig · autodiscover · ua-auto-config · MX 이름 · 호스트 이름 — 을 한 주문으로 요청하고, ACME 는 하나라도 실패하면 전체가 실패한다. 전환 전에는 그 이름들이 옛 서버(mailcow)를 가리키거나 DNS 에 없으므로 mx1 까지 인증서를 받지 못하고, 엔진은 993 · 465 · 25(STARTTLS)에 자체 서명 인증서(CN=rcgen self signed cert)를 낸다. 관리 화면 Domains › arasystem.it.kr › Certificate Management 의 Additional Hostnames 에 mx1(도메인은 엔진이 붙인다 — Enter 로 항목을 만든 뒤 저장)만 넣고, Management › Tasks › Scheduled 에서 AcmeRenewal 을 한 번 건다(재시작만으로는 바로 요청하지 않는다. 걸 때마다 새로 발급하니 여러 번 걸지 않는다 — Let's Encrypt 같은 인증서 주에 5번). 확인: docker logs --since 5m "${PROJECT_NAME}-mail" 2>&1 | grep -i acme 에 hostname = ["mx1.arasystem.it.kr"] · acme.order-completed, 바깥에서 openssl s_client -connect mx1.arasystem.it.kr:993 의 발급자가 Let's Encrypt. 전면 전환 때 autoconfig · autodiscover · mta-sts 의 DNS 를 새 서버로 옮긴 뒤 그 이름들을 이 목록에 더하고 AcmeRenewal 을 한 번 더 건다.
공개 443 차단은 setup 이 컨테이너 안과 MAIL_PUBLIC_URL(호스트에서) 두 곳에서 확인한다. 호스트에서 자기 공인 주소로 되돌아오는 경로가 막힌 환경이면 경고만 남기므로, 그때는 바깥에서 확인한다: curl -s -o /dev/null -w '%{http_code}\n' https://<MAIL_HOSTNAME>/jmap/session → 403.

bootstrap 직후에 멈췄다면 (다시 실행하기 전에)

setup 이 bootstrap 과 재시작 사이(또는 직후)에 멈췄으면 — 연결 끊김, 권한 오류, 종료 코드 1 — 볼륨을 지우거나 Bootstrap/set 을 손으로 부르지 않는다.

엔진이 어디까지 갔는지 본다: sudo docker exec "${PROJECT_NAME}-mail" test -s /etc/stalwart/config.json && echo "bootstrap 끝남"
실패 원인을 고친다 — 출력의 [실패] 줄. data/mail 에 쓸 수 없다고 나왔다면 소유자를 바꾼다: sudo chown "$(id -u):$(id -g)" data && sudo chown -R "$(id -u):$(id -g)" data/mail (sudo 로 돌릴 거라면 그대로 둔다 — 매번 같은 형태로)
셸에 MAIL_RECOVERY_ADMIN 이 남아 있는 채로 같은 명령(--recovery)을 다시 실행한다. bootstrap 이 끝났으면 재시작만 하고(config.json 으로 판단 — 임시 비밀번호 파일이 없어도 된다) 복구 관리자로 관리자 비밀번호·아이디를 맞춘다.
bootstrap 이 거부되었습니다 (primaryKeyViolation) 가 나오면 문제 해결 의 해당 줄을 본다.

원래 접속 주소 확인 (배포 직후)

자동 차단·게이트웨이 IP 제한은 접속 주소를 믿고 동작한다. 바깥(다른 네트워크의 PC)에서 실제 계정(본인 메일함)으로 IMAP 에 한 번 로그인한 뒤, 메일 엔진 로그의 auth.success 줄의 remoteIp 가 그 PC 의 공인 주소인지 본다. 도커 내부 주소(172.16.71.1 같은 게이트웨이 등)로 보이면 rootless·iptables 설정을 고친다.

틀린 비밀번호로는 확인할 수 없다 — setup 이 정한 로그 수준(info)에서는 실패한 로그인이 로그에 남지 않는다 (2026-10-27 Stalwart 0.16.27 에서 IMAP·HTTP 모두 확인. 성공은 auth.success … listenerId = "imaps", remoteIp = … 로 남는다).

# 바깥 PC 에서 — 연결되면 아래 두 줄을 직접 입력한다 (명령에 비밀번호를 적지 않아 셸 기록에 남지 않는다)
openssl s_client -quiet -connect mx1.arasystem.it.kr:993
#   a LOGIN <본인 주소> <비밀번호>
#   a LOGOUT
# 메일 호스트에서
sudo docker logs --since 5m "${PROJECT_NAME}-mail" 2>&1 | grep 'auth.success' | grep 'imaps' | tail -3

실제 직원 계정은 관리 화면이나 관리 API(x:Account/set)로 만든다. 관리 화면은 공개 443 에서 막혀 있으므로 SSH 터널로 내부 8080 에 붙는다: ssh -L 8180:<mail 컨테이너 IP>:8080 <메일 호스트> → http://localhost:8180/admin/. setup 은 운영에서 직원 계정을 만들지 않는다. ⚠️ 공용 주소(Group 계정)는 일반 관리자로 만들 수 없다 — Group 역할에 관리자 역할에는 없는 Principal 권한 13개가 있어 You are not authorized to grant permissions: jmapPrincipalCreate, … 로 거절된다(2026-10-29 확인, 직원 계정 · 그룹에 구성원 넣기는 관리자로 된다). 공용 주소를 만들 때는 복구 관리자를 쓴다 ("운영 배포" 1)·up -d mail 뒤 그 아이디로 관리 화면 · 관리 API → 4)·5) 로 끈다).
MAIL_HOSTNAME 은 bootstrap 때만 반영된다. 바꾸려면 관리 화면에서 고친다.
관리자 비밀번호를 바꾸려면: env 의 MAIL_ADMIN_PASSWORD 변경 → 위 1)·up -d mail → --recovery 실행 → 4)·5).
이미 서브넷을 고정하기 전에 만든 환경이라면 처음 한 번은 sudo docker compose --env-file .env.production down 후 up -d 로 네트워크와 컨테이너를 함께 다시 만든다. 그냥 up -d 만 하면 네트워크는 새로 만들어지지만 재생성되지 않은 컨테이너가 서비스 이름(db·mail 등) 별칭을 잃어 백엔드가 getaddrinfo ENOTFOUND db 로 뜨지 않는다 (개발 환경에서 확인 — up -d --force-recreate 로도 풀린다).

PTR

메일 호스트 IP 의 역방향 DNS 를 MAIL_HOSTNAME(전환 기간에는 mx1.arasystem.it.kr)으로 설정한다 (가비아가 아니라 IP 를 준 호스팅사 콘솔 또는 지원 요청). A(MAIL_HOSTNAME) → IP 와 PTR(IP) → MAIL_HOSTNAME 이 서로 맞고(FCrDNS), SMTP 인사말(EHLO = MAIL_HOSTNAME)과도 같아야 Gmail·네이버 등이 거부하거나 스팸 처리하지 않는다.

외부 릴레이 (SES 등)

아웃바운드 25 가 막혀 있거나 IP 평판이 나쁠 때 외부 메일을 릴레이로 보낸다. 개발의 Mailpit 경로와 같은 방식이고 인증만 다르다. 관리자 Basic 인증으로 POST {관리 API}/jmap/ (using: ["urn:ietf:params:jmap:core","urn:stalwart:jmap"]):

[
  ["x:MtaRoute/set", { "accountId": "<세션의 urn:stalwart:jmap 계정>", "create": { "ses": {
    "@type": "Relay", "name": "ses", "description": "외부 발송 — Amazon SES",
    "address": "email-smtp.ap-northeast-2.amazonaws.com", "port": 587,
    "authUsername": "<SMTP 사용자>",
    // 비밀번호를 DB 에 두지 않고 mail 컨테이너의 환경변수에서 읽는다 → compose 의 mail.environment 에 추가
    "authSecret": { "@type": "EnvironmentVariable", "variableName": "MAIL_RELAY_PASSWORD" }
  } } }, "0"],
  ["x:MtaOutboundStrategy/set", { "accountId": "<…>", "update": { "singleton": { "route": {
    "match": { "0": { "if": "is_local_domain(rcpt_domain)", "then": "'local'" } }, "else": "'ses'" } } } }, "1"],
  // 리로드 전에는 반영되지 않는다
  ["x:Action/set", { "accountId": "<…>", "create": { "r": { "@type": "ReloadSettings" } } }, "2"]
]

SPF 에 릴레이 쪽을 넣는다 (예: SES 는 include:amazonses.com). DKIM 은 Stalwart 가 보내기 전에 서명한다.
포트별 TLS 방식(587 STARTTLS / 465 암묵적 TLS) 속성은 관리 화면에서 확인한다. 이 예시는 실제 SES 로 검증하지 않았다.

DNS 리졸버와 스팸 차단 목록 (DNSBL)

스팸 필터는 기본으로 외부 차단 목록(DNSBL) 18개를 DNS 로 조회한다 — Spamhaus(zen IP · dbl 도메인), SURBL, URIBL, Barracuda, SpamCop, DNSWL, Mailspike, SenderScore 등 (목록: 관리 화면 Settings › Spam Filter › DNSBL, 또는 x:SpamDnsblServer/query). 이 목록들은 Stalwart 와 별개 서비스라 각자 이용 조건이 있다. 그리고 공용 · ISP DNS(KT 168.126.63.1 · 8.8.8.8 · 1.1.1.1 등)를 거친 조회는 Spamhaus 가 거부한다 — 오류 코드 127.255.255.254 (2026-10-26 개발 환경의 KT DNS 로 늘 등록된 시험 주소를 물어 확인). 그래서 메일 엔진 전용 재귀 리졸버를 compose 에 두고 엔진의 DNS 를 그쪽으로 돌린다. DNSSEC 도 검증해 기동 로그의 "DNS resolver cannot validate DNSSEC. DANE has been disabled" 경고가 사라진다.

메일 전용 리졸버 (`mail-resolver`)

mail ──(mail-dns — internal, MAIL_RESOLVER_SUBNET)──▶ mail-resolver  MAIL_RESOLVER_IP:53 ──(mail-dns-egress)──▶ 루트 · 각 도메인의 DNS 서버
 └──(app-network)──▶ 바깥 25 · 443 (메일 · ACME) — 그대로                                                           (서버 자신의 공인 IP 로)

항목	값
서비스	`docker-compose.yml` 의 `mail-resolver` (profile `mail` — mail 과 함께 뜬다, mail 은 리졸버가 healthy 가 된 뒤에 뜬다. 리졸버가 unhealthy 거나 떠 있지 못하면 compose 가 경고만 내고 mail 을 띄운다 — `required: false`, 리졸버 장애 때). 설정 `resolver/unbound.conf`
이미지	`klutchell/unbound:1.26.2` — NLnet Labs 원본 소스를 체크섬으로 확인해 빌드한 distroless 이미지(셸 없음, `drill` 포함 · 비공식). digest `sha256:50cbeb32b583…`(2026-10-30 `latest` 와 같음). 1.26.2 는 보안 릴리스(2026-10-21 — CVE-2026-96405 이름 압축 풀기로 서비스 저하: 바깥 DNS 서버의 응답으로 닿는다)라 2주를 기다리지 않았다 (docker 스킬 "이미지 버전 고정")
네트워크	`mail-dns` — mail ↔ 리졸버 전용, internal(이 네트워크로는 바깥에 못 나간다), 서브넷 `MAIL_RESOLVER_SUBNET`(기본 `172.16.73.0/24`) · 리졸버 주소 `MAIL_RESOLVER_IP`(기본 `172.16.73.254` — 서브넷의 끝 쪽. 도커는 mail 에 앞쪽부터 차례로 준다). `mail-dns-egress` — 리졸버의 바깥 조회 길, 리졸버 혼자(서브넷은 도커가 정한다). app-network(신뢰 대역)에는 붙이지 않는다
메일 엔진만 닿게	두 네트워크에 붙는 것은 mail · 리졸버뿐(setup 이 확인 — 운영은 그 밖이 있으면 중단). 호스트 포트를 열지 않는다. unbound 의 `access-control` 은 사설 대역 · 자기 자신만 받는다 — 누가 53 을 공개해도 바깥에서 쓰는 열린 리졸버가 되지 않게. 알려진 한계 — `mail-dns` 는 양쪽으로 열린 브리지라 리졸버 쪽에서도 mail 의 포트(관리 API 8080 포함)에 닿는다. 그 주소는 신뢰 대역(`APP_NETWORK_SUBNET`) 밖이라 자동 차단 예외 · 게이트웨이 로그인은 받지 못하고, 관리 API 는 관리자 자격 증명이 있어야 한다 — 리졸버가 뚫렸을 때의 일이라 HTTP 정책 식은 바꾸지 않았다
실행	비-root `101:102`(이미지의 unbound 사용자 — 이미지는 root 로 떠서 내려가는 꼴이라 처음부터 이 사용자로 띄운다) · 권한(capability) 모두 뺌 · `no-new-privileges` · 메모리 128m. 비-root 가 53 에 붙는 것은 도커가 컨테이너마다 `net.ipv4.ip_unprivileged_port_start=0` 으로 두기 때문이다
DNSSEC	검증한다 — 루트 신뢰 앵커는 이미지에 든 `root.key`(KSK-2017 · KSK-2024)이고 RFC 5011 로 스스로 고쳐 쓴다(그래서 `read_only` 로 두지 않는다). 2026-10-30 의 루트 DNSKEY 는 KSK-2024(key tag 38696)가 서명한다
그 밖의 설정	사설 주소로 풀리는 바깥 이름은 버린다(`private-address` — 바깥 도메인의 MX 가 VPC · 도커 네트워크를 가리켜도 엔진이 그쪽으로 보내지 않게, 127/8 은 넣지 않는다 — DNSBL 은 127.0.0.x 로 답한다) · 리졸버 자신도 사설 주소의 DNS 서버에는 묻지 않는다(`do-not-query-address` — 같은 대역. 바깥 도메인이 이름 서버 주소(glue)를 사설 주소로 두어 리졸버가 VPC · 호스트 · 도커 네트워크의 53 에 묻게 만드는 것을 막는다, 127/8 은 기본값이 막는다) · 조회 이름은 필요한 만큼만 위로(QNAME minimisation — 루트 · .net 서버는 DQS 키가 든 이름을 보지 못한다) · 로그는 동작 정보만(`verbosity: 1` — 조회 이름을 남기지 않는다)
healthcheck	`drill-hc localhost @127.0.0.1` — 데몬이 답하는지만 본다(바깥 DNS 가 잠깐 막혀도 mail 이 뜨지 못하는 일이 없게). 바깥 조회 · DNSSEC 은 setup 이 본다

compose 서비스로 둔 까닭 (호스트에 unbound 를 까는 것과 견줌):

개발 · 운영이 같은 정의다 — 개발(Docker Desktop)에서 그대로 띄워 시험하고, 버전 고정 · CI 검사(unbound-checkconf) · 배포 절차(up -d)에 들어간다. 호스트 패키지는 저장소 밖의 상태라 서버를 다시 만들 때 빠뜨리기 쉽다.
메일 엔진만 닿게 네트워크로 가를 수 있다 — 호스트에 깔면 모든 컨테이너(인터넷을 향한 frontend 포함)가 호스트 주소로 닿아, 막으려면 도커의 iptables 와 얽힌 호스트 방화벽 규칙이 필요하다. Ubuntu 의 systemd-resolved(127.0.0.53:53)와 자리도 겹친다.
대가 — 이미지를 판까지 고정하고 우리가 올린다(호스트 apt 는 자동 보안 업데이트를 받는다). NLnet Labs 의 보안 릴리스 공지(https://nlnetlabs.nl/projects/unbound/security-advisories/)를 본다. 리졸버는 엔진 DNS 의 단일 지점이다 — 멈추면 바깥 메일의 DNS 가 모두 실패한다(보내는 메일은 대기열에서 다시 시도, 받는 메일은 검사가 약해진다). 그래서 공용 DNS 로 넘어가는 대체 길은 두지 않는다 — 넘어가면 Spamhaus 가 다시 막는다.

엔진의 DNS (x:DnsResolver 싱글톤 — 0.16.27 의 @type 은 System · Custom · Cloudflare · Quad9 · Google, Custom 은 servers { "<n>": { protocol udp|tcp|tls, address(IP), port } }. @type 만 바꾸는 부분 갱신을 받고 공통 칸(attempts · timeout · enableEdns …)은 그대로 둔다 — 2026-10-30 개발 엔진에서 읽고 바꿔 확인):

환경	setup 이 맞추는 값	길	까닭
운영	`Custom` — `MAIL_RESOLVER_IP:53` 의 UDP + TCP	엔진 → 리졸버	도커 DNS 를 거치지 않아 도커 내부 이름(backend · db …)이 엔진에 풀리지 않는다 — 바깥 도메인의 MX 가 내부 이름을 가리켜도 닿지 않는다. 엔진은 TCP 연결이 있어야 그 리졸버로 DNSSEC 을 믿는다(소스 `common/src/config/smtp/resolver.rs` 의 `ensure_dnssec`)
개발	`System`	엔진 → 도커 DNS(127.0.0.11) → 리졸버	개발의 외부 발송 경로가 도커 내부 이름 `mailpit` 이다 — `Custom` 이면 그 이름을 풀지 못해 바깥 주소 앞 메일이 `delivery.ip-lookup-failed` 로 영구 실패(반송) 했다(2026-10-30 개발). 도커 DNS 는 바깥 이름을 compose 의 `dns`(= 리졸버)로 넘기고 DNSSEC 자료(RRSIG)도 UDP · TCP 그대로 넘긴다

mail 컨테이너의 dns 는 두 환경 모두 이 리졸버다 — 컨테이너 안의 이름 풀기(ACME · 웹 포털 내려받기 · setup 의 getent · curl)도 리졸버로 간다.
바뀐 값은 setup 의 ReloadSettings 로 반영된다(리로드가 엔진 설정 전체를 다시 만든다). 다만 DNSSEC 확인의 경고는 기동 때만 로그에 남는다(리로드 응답 · 로그에는 없다) — setup 은 이번 기동의 로그에서 그 경고를 찾는다([확인] 엔진 기동 로그(…)에 DNSSEC 경고가 없다). 엔진 DNS 를 그 실행에서 바꿨다면 다음 기동부터 새 설정의 확인이다.
서버를 다시 켜면 도커가 compose 의 차례(리졸버 먼저)를 지키지 않아 mail 이 먼저 뜰 수 있다 — 그러면 그 기동은 DNSSEC 을 믿지 못한 채(DANE 꺼짐) · 스팸 필터의 Pyzor 없이(주소를 풀지 못해 그 항목만 빼고 뜬다 — 리졸버 장애 때 3.) 뜨고, 바깥 DNS 는 리졸버가 뜬 뒤부터 된다. 재부팅 뒤에는 sudo docker compose --env-file .env.production restart mail 뒤 setup 으로 [확인] 을 본다 (개발에서 리졸버를 멈춘 채 mail 을 띄워 이 경고가 남고 setup 이 [주의] 로 알리는 것을 확인했다 — 2026-10-30).

setup 이 하는 일 (DNS):

사전 확인 — 바꾸기 전에 (어긋나면 아무것도 바꾸지 않고 종료 1): mail-dns 의 서브넷이 MAIL_RESOLVER_SUBNET 이고 internal 인지 · 구성원이 mail · 리졸버뿐인지 · mail-dns-egress 에 리졸버만 붙었는지(구성원은 운영만 중단, 개발은 [주의]) · 리졸버가 떠 있고 주소가 MAIL_RESOLVER_IP 인지 · mail 이 mail-dns 에 있고 dns 가 그 주소인지, 그리고 메일 컨테이너 안에서 그 주소로 DNSSEC 자료와 함께(DO) 물어 검증된 답(ad)과 서명(RRSIG)이 오는지 — 엔진과 같은 자리 · 같은 주소다. UDP 는 루트 SOA(389B 안팎), TCP 는 루트 DNSKEY(엔진의 기동 확인과 같은 질문 — 소스 ensure_dnssec)를 묻는다. UDP 로 루트 DNSKEY 를 묻지 않는 까닭: 지금 1,139B 인데 루트 키 교체(ZSK 미리 올리기 · KSK-2017 폐기) 동안에는 1,400B 를 넘어 EDNS 1232 의 UDP 로는 잘린다(TC — 답 0 · 서명 0). 엔진은 그때 TCP 로 다시 묻으므로 멀쩡한 리졸버인데 setup 만 멈추게 된다(2026-10-30 리뷰 — EDNS 1100 으로 잘리는 조건을 만들어 확인). 이 답 확인은 운영만 멈추고 개발은 [주의] 뒤 이어 간다 — 바깥 53 이 막힌 개발 망에서도 개발 메일(Mailpit — 도커 DNS 가 푸는 이름)은 되기 때문이다. 다만 리졸버가 바깥에 전혀 닿지 않으면 뒤의 설정 리로드를 엔진이 거절해(Pyzor 주소를 같은 리졸버로 푼다 — 리졸버 장애 때 3.) 개발 setup 도 거기서 종료 1 이다 (2026-10-30 개발에서 리졸버의 바깥 길을 끊어 확인 — 저장한 설정은 남고 restart mail 때 적용된다). 개발 PC 도 리졸버가 바깥 53 에 닿아야 setup 이 끝난다. (이미지에 dig 이 없어 이미지의 perl 로 묻는다 — Debian 기본 perl-base 만 쓴다. 이미지에 perl 이 없으면(docker exec 종료 126 · 127) 리졸버 문제가 아니라 확인 도구 문제로 따로 알린다.)
엔진 DNS — 위 표의 값으로([유지] · [변경] … · 전 System). 견주는 것은 @type 과 서버마다의 protocol · address · port 뿐이다 — 엔진은 Custom 의 servers 를 넣은 그대로 읽어 준다(2026-10-30 개발 엔진에 잠깐 저장해 확인), 엔진이 나중에 칸을 더 붙여 읽어 줘도 매번 [변경] 이 되지 않게.
Spamhaus 두 항목 — 아래.
반영 확인 — 리로드 뒤 이번 기동 로그에 DNSSEC 경고가 없는지. 그 기동의 로그가 남아 있지 않으면(기동 첫 줄 server.startup 이 없다 — 로그 회전 등) "경고 없음"이 아니라 [주의] … 확인하지 못했습니다 다(확인하려면 restart mail 뒤 setup — 몇 초 끊긴다).

MAIL_RESOLVER_SUBNET · MAIL_RESOLVER_IP 는 setup 도 검사한다 — 사설 대역 · 네트워크 주소 · /24~/29 · 앱 네트워크와 겹치지 않음 · 주소는 그 안이고 네트워크 주소 · 첫 주소(도커 게이트웨이) · 끝 주소가 아님. 바꿀 때는 둘을 함께 고치고 docker compose … down 후 up -d(네트워크를 다시 만든다) → setup.

Spamhaus — 조회 키(`MAIL_SPAMHAUS_DQS_KEY`)

공개 미러(zen.spamhaus.org · dbl.spamhaus.org)는 쓰지 않는다 — Spamhaus 의 Fair Use(소규모 · 비상업) 용도다.
키는 Spamhaus 의 "Blocklists via DNS Query"(옛 Data Query Service — DQS) 계정에서 받는다. 무료 계정은 Spamhaus 의 Fair Use(소규모 · 비상업) 조건이다 — 회사가 대상인지는 Spamhaus 가 판단하고(신청 페이지: "If you are a non-commercial entity or individual with low query volumes, you may qualify"), 안 되면 두 항목을 끈 채로 두거나 유료(상업용 30일 체험 뒤 구독)로 간다. 무료 계정 신청 · 공개 미러에서 옮기기 · 시험
키는 서버의 .env.production 에만 둔다(MAIL_SPAMHAUS_DQS_KEY= — 26자 영문 · 숫자). 파일에 없거나 파일과 다른 값이 셸에 있으면 setup 이 멈춘다(셸 값으로는 그 실행만 켜지고 다음 실행이 끈다). 개발은 비워 둔다.
체험(30일) 키는 기간이 끝나면 답이 멈춘다 — 그 전에 구독하거나, 키를 비우고 setup 을 돌려 두 항목을 끈다. 계정이 끝나거나 키가 멈추면 엔진의 Spamhaus 조회는 실패하고 표시(tag)가 붙지 않는다 — 메일은 그대로 받는다(닫히지 않고 열린 쪽 · fail-open). 조회마다 몇 초 늦어질 수 있다 (틀린 키는 SERVFAIL 5초 남짓이거나 답이 없었다 — 아래 표). 엔진 로그에는 남지 않는다(조회 실패 spam.dnsbl-error 도 debug — 아래 "키가 남는 곳"). setup 은 다음에 돌 때에야 시험 항목을 받지 못해 두 항목을 끄고 종료 1 로 알린다 — 그래서 운영은 setup 을 주기적으로 돌려 종료 0 인지 보거나 Spamhaus 계정의 만료일을 본다.

상태	setup 이 하는 일
키 있음 · 시험 통과	그 항목을 DQS 로 켠다 — 조회 이름 식 `ip_reverse + '.<키>.zen.dq.spamhaus.net'` · `value + '.<키>.dbl.dq.spamhaus.net'`. 응답 코드가 공개 미러와 같아 tag 식(점수)은 그대로
키 있음 · 시험 실패	그 항목을 끄고 실패로 보고(종료 1) — 시험은 메일 컨테이너에서 리졸버로 늘 등록된 시험 항목을 묻는다: `2.0.0.127` → `127.0.0.2`(ZEN, `127.0.0.4` · `127.0.0.10` 도 온다) · `dbltest.com` → `127.0.1.2`(DBL). 형식만 맞는 가짜 키는 SERVFAIL(5초 남짓)이거나 12초 안에 답이 없었다(2026-10-30)
키 없음	두 항목을 끈다 — 운영 `[주의]`, 개발 `[참고]`(개발도 운영처럼 끈다: 공개 미러의 비상업 조건은 회사 개발 PC 에도 같고, 키는 운영 서버에만 둔다)
끌 때	조회 이름 식도 엔진 기본(공개 미러)으로 되돌린다 — 옛 키가 엔진에 남지 않게. 지금 식이 무엇이었는지는 키 없이 알린다(`전 켜짐 · 공개 미러 …` · `DQS …(다른 키)`)

키가 남는 곳 — setup 은 키를 출력하지 않는다(식 · 옛 식도). 엔진의 오류 응답 · 거절 사유에 실려 와도 setup 의 출력([변경] · [주의] · [실패] 줄 모두)은 키를 <MAIL_SPAMHAUS_DQS_KEY> 로 바꿔 찍는다. 시험 조회 이름은 표준 입력으로만 넘긴다(docker exec 명령줄 · 도커 이벤트에 남지 않게). ⚠️ 그러나 엔진 설정(두 항목의 조회 이름 식)에 키가 그대로 저장된다 — 관리 화면 · 관리 API(x:SpamDnsblServer/get) · 메일 볼륨 백업으로 보인다. 조회 자체에도 키가 실린다(평문 DNS — DQS 의 방식이다. 위 QNAME minimisation 으로 Spamhaus 앞 단계는 보지 못한다). 엔진은 DNSBL 조회 이름을 debug 수준에서만 남긴다 — 답(spam.dnsbl)도, 실패(spam.dnsbl-error — 조회 이름 전체와 리졸버 오류를 싣는다)도 따로 정한 수준이 없어 기본값 debug 다(0.16.27 소스 crates/trc/src/event/enums_impl.rs 의 EventType::level). 그래서 키가 멈춰 조회가 모두 실패해도 setup 이 둔 info 로그에는 쏟아지지 않는다. 로그 수준을 debug 로 올리면 키가 로그에 남는다.
바꾸거나 비우면 setup 을 다시 실행한다. 항목을 지웠거나 이름을 바꿨으면 setup 은 만들지 않고 [주의] 만 낸다.
나머지 16개 목록 — 운영 전에 각 서비스의 이용 조건(상업적 사용 · 조회량 · 사전 등록)을 확인하고 맞지 않는 것은 관리 화면에서 끈다(setup 은 Spamhaus 두 항목만 맡는다).
조회 거부 응답의 점수 — 0.16.27 기본값에서 Spamhaus 의 거부 · 오류 응답 tag(RBL_SPAMHAUS_BLOCKED_OPENRESOLVER · RBL_SPAMHAUS_BLOCKED · DBL_BLOCKED_OPENRESOLVER · DBL_BLOCKED, 그리고 RECEIVED_…)는 0점이다(개발 엔진의 x:SpamTag, 2026-10-30) — 거부 응답이 정상 메일의 점수를 올리지는 않는다(점수가 붙는다는 사용자 보고는 이 판에서는 아니다). 이 리졸버로는 그 응답이 오지 않는다.

# 리졸버가 Spamhaus 에 막혀 있지 않은지 — 127.0.0.2 는 늘 등록된 시험 주소다 (공개 미러 한 번 — 연결 확인용)
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill 2.0.0.127.zen.spamhaus.org @127.0.0.1 A
#   127.0.0.x 가 오면 정상, 127.255.255.254 면 막혀 있다(공용 · 열린 리졸버로 보인다)
# DNSSEC — dnssec.works 는 flags 에 ad, fail01.dnssec.works 는 SERVFAIL
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill -D dnssec.works @127.0.0.1 A
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill fail01.dnssec.works @127.0.0.1 A
# 엔진 기동 로그의 DNSSEC 경고 — 나오지 않아야 한다
sudo docker logs "${PROJECT_NAME}-mail" 2>&1 | grep 'cannot validate DNSSEC'
# DQS 키는 명령줄에 적지 않는다 — setup 의 "[확인] Spamhaus 키 … 시험 항목 …" 줄로 본다

확인 (2026-10-30, 개발 — Docker Desktop 28.5 · KT 망, 엔진 0.16.27):

리졸버로 2.0.0.127.zen.spamhaus.org → 127.0.0.10 · 127.0.0.4 · 127.0.0.2(UDP · TCP), dbltest.com.dbl.spamhaus.org → 127.0.1.2 — 같은 PC 의 KT DNS 로는 127.255.255.254 였다. dnssec.works 는 ad, fail01.dnssec.works 는 SERVFAIL. 도커 DNS 를 거쳐도(dns 지정) 루트 DNSKEY 의 ad · RRSIG 가 UDP · TCP 그대로 왔다.
엔진 기동 로그 — 리졸버 전(2026-10-26 기동, KT DNS)에는 DnsResolver … cannot validate DNSSEC 경고가 있었고, 리졸버 뒤 System(개발) · Custom(운영 꼴을 개발에서 잠시) 기동 모두 없었다.
메일 — 465 인증 제출로 바깥 주소(Mailpit 에 도착) · 사내 주소(받은편지함), 25 인증 없는 수신(someone@gmail.com → doyun.lee)의 spf=softfail(google 의 SPF 를 실제로 따라감) · dmarc=fail … policy.dmarc=none 이 그대로 나왔다. Custom 으로 바꾼 동안은 Mailpit 경로가 위 표처럼 영구 실패했고, setup 으로 System 에 되돌린 뒤 다시 Mailpit 에 왔다.
setup — 처음 [변경] 둘(Spamhaus 두 항목 끔), 다시 돌리면 바뀐 줄 0 · 종료 0. 형식만 맞는 가짜 키 → 두 항목 꺼진 채 종료 1 · 출력에 키 없음. 리졸버를 멈추면 사전 확인에서 종료 1(바뀐 것 없음). mail-dns 에 다른 컨테이너를 붙이면 개발은 [주의] · 종료 0. 실제 Spamhaus 키로는 아직 시험하지 않았다 — 키를 받은 뒤 운영에서 [확인] Spamhaus 키 … 두 줄을 본다.
리뷰 반영(같은 날) — 루트 DNSKEY(DO)는 1,139B 라 메일 컨테이너에서 EDNS 1100 으로 물으면 UDP 가 잘렸다(TC · 답 0 · 서명 0 — 예전 사전 확인이면 멈췄을 자리). 같은 조건에서 지금 확인(UDP 루트 SOA · TCP 루트 DNSKEY)은 둘 다 ad · 서명 1 로 통과했다. compose 의 required: false — 리졸버 healthcheck 실패(unhealthy) · 설정 오류로 바로 끝남(exited (1)) · 운영 재시작 정책(unless-stopped)으로 재시작을 되풀이함 모두 optional dependency "mail-resolver" failed to start 경고 뒤 mail 이 떴다(5~9초). 바꾸기 전 설정(required 없음)은 dependency failed to start: container … is unhealthy 로 끝나고 mail 이 Created 에 남았다(옛 mail 은 지워진 채). up -d --no-deps mail 은 리졸버를 기다리지 않는다. 엔진의 x:DnsResolver 를 잠깐 Custom 으로 저장해 읽으면 servers 가 넣은 그대로였다(되돌림). domain-insecure 한 줄은 그 도메인만 검증을 끈다(fail01.dnssec.works SERVFAIL → NOERROR, dnssec.works 는 그대로 ad, fail02.dnssec.works 는 그대로 SERVFAIL — 시험용 리졸버 컨테이너). 리졸버의 바깥 길을 끊으면(캐시도 비움) 개발 setup 은 사전 확인을 [주의] 로 넘기고 리로드에서 엔진의 거절(Pyzor 주소)로 종료 1 이었다 — 바뀐 것 0. 그 상태에서 엔진 DNS Quad9 저장 → 리로드 거절 → restart mail 은 DNSSEC 경고 없이 떴다(비상 길 — 리졸버 장애 때). 모두 되돌린 뒤 setup 은 [확인] · 바뀐 줄 0.

참고: Spamhaus — 공용 DNS 로 무료 목록 쓰기, Spamhaus — KT 경유 조회 안내, Stalwart DNSBL 문서

엔진 한도

받는 쪽 한도(x:MtaInboundThrottle — 관리 화면 Settings › MTA › Rates & Quotas › Inbound Rate Limits)는 엔진을 처음 설치하면 아래 두 개다. 한도를 넘은 바깥 메일 서버는 거절이 아니라 미루기(452 4.4.5 Rate limit exceeded 또는 연결 끊김)를 받고 나중에 다시 보낸다 — 늦게 받을 뿐 잃지는 않는다.

한도 (엔진의 설명 · key)	세는 것	기본값	넘으면	setup
`Sender address to recipient throttle` · `senderDomain`·`rcpt`	같은 보낸 도메인 → 같은 받는 사람마다 받는 사람 수 (RCPT TO 때)	시간당 25	그 받는 사람만 `452 4.4.5`	인증 없는 세션에만 건다
`Sender IP throttle` · `remoteIp`	접속 IP 마다 연결 수 (연결할 때)	초당 5	인사 없이 연결을 끊는다	그대로 둔다

바꾸는 까닭 — 기본 조건(match)은 모든 세션({"else":"true"})이라 로그인한 직원의 발송에도 걸린다 (엔진 문서 Rate limits "Default throttles"). 사내 메일은 보낸 도메인이 모두 같아서, 동료 모두 합쳐 한 사람에게 시간당 25통을 넘으면 그 뒤의 웹메일 발송(JMAP 제출)은 그 받는 사람이 452 4.4.5 로 거절됐다 (2026-10-28 개발 엔진 — 로그 smtp.rate-limit-exceeded … id = "MtaInboundThrottle with id …"). 바깥 서버와 달리 엔진은 그 메일을 다시 보내지도 반송하지도 않는다 — 제출 기록의 deliveryStatus 에만 남는다 (백엔드가 읽어 알린다 — 계약 2절 "받는 사람별 결과").
setup 이 하는 일 — 설명과 key 로 찾아(id 는 설치마다 다르다) match 를 {"match":{},"else":"is_empty(authenticated_as)"} 로 맞추고 설정 리로드로 반영한다. 엔진 기본값이 스팸 필터를 인증 없는 세션에만 거는 식(x:MtaStageData 의 enableSpamFilter)과 같다.
- authenticated_as 는 인증한 계정 이름이고, 인증 없는 세션(AUTH 없이 들어온 SMTP — 바깥 서버가 25 로 넣는 메일)이면 빈 값이다. 이 식(RCPT TO 단계)에서 쓸 수 있는 변수다 (MtaInboundThrottle · MtaRcptToVariable · is_empty). 엔진은 저장할 때 식을 검사한다 — 모르는 변수·이 맥락에 없는 변수(HTTP 의 path 등)는 거부한다.
- 웹메일 발송(JMAP 제출)은 엔진 안에서 그 직원 계정으로 인증된 SMTP 세션으로 돌아 빠진다. 메일 프로그램의 SMTP 제출(465, AUTH 뒤)도 같은 까닭으로 빠진다 (465 는 시험하지 않았다).
- 찾지 못하면 만들지 않고 [주의] 만 낸다 — 지웠다면 그대로 두고, 이름을 바꿨다면 그 한도의 match 를 직접 본다.
- 한도 값(rate)·켜짐(enable)은 건드리지 않는다. match 는 실행할 때마다 맞추므로, 받는 사람별 예외처럼 조건을 따로 둬야 하면 이 한도를 끄고(enable: false) 다른 설명으로 새 한도를 만든다 (setup 은 그 한도를 건드리지 않는다).
바깥에서 들어오는 메일(인증 없는 SMTP)에는 그대로 건다 — 같은 바깥 도메인 → 한 사람 시간당 25통.
보낸 IP 한도는 그대로 둔다 — 연결할 때 세는 한도라 웹메일 발송에는 처음부터 걸리지 않는다 (JMAP 제출은 엔진 안의 세션이라 연결 단계를 거치지 않는다 — 0.16.27 소스 smtp/src/inbound/spawn.rs). 조건에 authenticated_as 를 쓰면 엔진이 그 한도를 MAIL FROM 단계로 옮겨(한도는 key 와 식이 쓰는 변수를 모두 아는 첫 단계에서 센다 — 같은 문서 "Evaluation stages", 소스 common/src/config/smtp/queue.rs 의 parse_inbound) 연결이 아니라 MAIL FROM 을 세게 되고, 바깥에서 몰려오는 연결은 더는 막지 못한다.
확인 (2026-10-28, 0.16.27): 바꾼 뒤 웹메일과 같은 방식(대리 접근 JMAP 제출)으로 ara.kim → doyun.lee 30통(초당 40통 남짓)이 모두 250 2.1.5 Queued (엔진 로그에 한도 기록 없음), 인증 없는 SMTP 는 같은 바깥 도메인(example.net) → doyun.lee 26번째부터 452 4.4.5 (로그 id = "MtaInboundThrottle with id …", limit = [25, 3600000ms]). setup 을 이어서 두 번 돌리면 첫 번째는 [변경], 두 번째는 [유지] 다(엔진이 돌려주는 match · key 모양이 그대로 비교된다 — 바뀌면 매번 [변경] 이 나온다).

임시 업로드 한도 (x:Jmap 싱글톤) — 엔진은 계정마다 1시간 동안 올린 것을 크기 합계와 개수로 센다. 첨부 올리기만이 아니라 필터 · 부재중 저장(백엔드가 Sieve 스크립트를 올린다)과 서명 그림이 든 발송(그림마다 하나)도 같은 몫을 쓴다.

설정	뜻	기본값	setup
`uploadQuota`	계정마다 `uploadTtl` 동안 올린 크기 합계	50,000,000바이트	첨부 합계 한도의 20배보다 작으면 그 값으로 올린다 (기본 524,288,000바이트 = 25MB × 20)
`maxUploadCount`	같은 동안 올린 개수	1,000	그대로 둔다
`uploadTtl`	올린 것이 남는 시간 = 위 둘을 세는 창	3,600,000ms (1시간)	그대로 둔다
`maxUploadSize`	한 번에 올리는 크기	50,000,000바이트	그대로 둔다

넘으면 — 그 계정의 업로드가 모두 HTTP 429(Quota exceeded — "You have exceeded the blob upload quota of 1000 files or 50000000 bytes.")로, 올린 것이 만료될 때까지 막힌다. 백엔드는 크기 · 개수 어느 쪽이든 429 REQ_001 로 내리고 로그에 {"reason":"mail-engine-rate-limit","call":"upload"} 를 남긴다. 엔진 로그(info)에는 남지 않는다(크기 합계로 확인).
바꾸는 까닭 (2026-10-29 개발 엔진, 0.16.27) — 한 계정으로 1,000개를 넘기자 그 계정의 필터 저장이 막혔다. 크기 합계도 그대로 걸려서 20MiB 두 개 뒤 세 번째가 429 였다 — 기본값이면 20MB 첨부 세 개로 그 직원의 첨부 · 필터 · 부재중 저장이 1시간까지 막힌다 (계약 2절 "첨부 업로드 한도").
setup 이 하는 일 — uploadQuota 가 첨부 합계 한도의 20배(한 시간에 합계 한도를 꽉 채운 메일 20통)보다 작으면 그 값으로 올리고 설정 리로드로 반영한다.
- 첨부 합계 한도는 백엔드(mail.settings.ts)와 같게 센다 — MAIL_ATTACHMENT_TOTAL_MAX_SIZE_MB(비우면 25)이되 파일 하나 한도 MAIL_ATTACHMENT_MAX_SIZE_MB(비우면 20)보다 작아지지 않고, MB = 1,048,576바이트. 둘 중 하나라도 양의 정수 표기(앞자리 0·부호·소수점 없이)가 아니면 아무것도 바꾸지 않고 멈춘다 — 백엔드 env 검증과 같은 규칙.
- 더 크게 둔 값은 내리지 않는다(운영에서 정한 것). 0 이면 뜻(제한 없음인지)을 확인하지 않았으므로 바꾸지 않고 [주의] 를 낸다.
- 리로드가 있어야 반영된다 — 저장만 한 뒤에는 엔진이 옛 한도로 계속 429 를 냈고(메시지의 바이트 수도 옛 값), ReloadSettings 뒤에 올라갔다 (같은 날 확인).
- 첨부 한도 env 를 바꾸면 backend 를 다시 띄우는 것과 함께 setup 도 다시 실행한다.
개수 · 기간 · 한 번 크기는 그대로 둔다
- 개수 1,000 — 사람이 쓰는 양으로는 닿기 어렵다(한 시간에 첨부 · 필터 저장 · 서명 그림을 합쳐 1,000번). 계정이 털리거나 스크립트가 돌 때 엔진을 지키는 몫으로 남긴다.
- 기간 1시간 — 늘리면 같은 한도를 더 긴 동안 세어 오히려 빡빡해지고, 줄이면 올린 첨부가 메일(임시 저장본)에 붙기 전에 만료될 수 있다(시험하지 않았다).
- 한 번 크기 50,000,000바이트 — 파일당 첨부 한도(기본 20MB)보다 크다. MAIL_ATTACHMENT_MAX_SIZE_MB 를 48 이상(48MB = 50,331,648바이트)으로 올리면 엔진이 그 파일을 400 urn:ietf:params:jmap:error:limit(maxSizeUpload)로 거절하고 사용자에게는 FILE_002 로 보인다 — 그때는 이 값도 함께 올린다(관리 API x:Jmap/set → ReloadSettings).
확인 (2026-10-29, 0.16.27): setup 을 이어서 두 번 돌리면 첫 번째는 [변경] … 524,288,000바이트 … 전 50,000,000, 두 번째는 [유지]. setup 뒤에는 이미 60MiB 를 올린 계정이 20MiB 를 더 올릴 수 있었다(바꾸기 전에는 429). maxUploadCount · uploadTtl · maxUploadSize 는 그대로였다.

운영 전에 정할 것:

메일을 많이 받는 주소 — 같은 바깥 도메인에서 한 사람이 시간당 25통 넘게 받으면 그 뒤는 바깥 서버가 미뤘다가 다시 보낸다(늦게 받는다). 알림 메일(모니터링·결제·배포 알림 등)처럼 한 곳에서 같은 주소로 많이 오는 주소를 먼저 꼽고, 한도를 올리거나(관리 화면 — setup 은 rate 를 건드리지 않는다) 위처럼 따로 한도를 둔다.
한 IP 초당 연결 5개 — 큰 메일 서비스가 여러 연결로 한꺼번에 배달하면 넘을 수 있다(인사 없이 끊기고 바깥 서버가 다시 시도한다 — 늦게 받는다). 메일 프로그램(465)으로 보내는 직원이 사무실 NAT 뒤에 많아도 한 IP 로 센다(연결은 인증 전에 센다 — 시험하지 않았다). 두 한도 모두 넘으면 로그 smtp.rate-limit-exceeded 가 남으니 운영을 시작한 뒤 이 로그로 정한다.
직원마다 내보내는 양의 한도(x:MtaOutboundThrottle)는 비어 있다 — 이제 웹메일 발송에는 엔진의 받는 쪽 한도도 걸리지 않으므로, 남는 것은 백엔드의 요청 수 한도(루트 env THROTTLE_* — IP 당)뿐이다. 계정이 털리거나 잘못 쓰여 한꺼번에 많이 보내면 바깥 서버들의 한도에 걸려 서버 평판이 떨어진다. 보낸 사람마다 한도(key sender — 넘으면 거절이 아니라 대기열에서 미뤄진다, Outbound rate limits)를 둘지 정한다 — 사내 배달에도 걸리는지는 확인하지 않았다.
직원마다 1시간 업로드 한도(크기 · 개수) — setup 은 크기 합계만 첨부 합계 한도의 20배로 올리고 개수(1,000)는 그대로 둔다. 운영을 시작한 뒤 백엔드 로그 "reason":"mail-engine-rate-limit","call":"upload" 로 막힌 직원이 있는지 보고 크기 · 개수를 정한다(엔진 로그에는 남지 않는다). 올린 값은 setup 이 내리지 않는다.

대용량 첨부 (11단계 — 인프라)

일반 첨부 한도(20MB · 합계 25MB)를 넘는 파일은 메일 엔진이 아니라 backend 의 볼륨(<PROJECT_NAME>_files → /app/files)에 조각으로 올리고, 메일에는 받는 사람이 로그인 없이 여는 내려받기 링크(SHARE_PUBLIC_URL/s/<토큰>)를 넣는다. 다 올린 파일은 ClamAV 로 검사한다. 데이터 · 규칙은 계약 4절 "대용량 첨부", env 는 루트 예시 env 의 "대용량 첨부" 칸이다. 이 절은 컨테이너 · 프록시 · 운영만 다룬다.

악성 검사 (ClamAV)

backend ─(clamav — internal · 바깥 길 없음)─▶ clamav  clamd :3310 (INSTREAM)  ◀── 볼륨 <PROJECT_NAME>_clamav-db (읽기 전용)
                                              clamav-updater  freshclam ──(clamav-egress)──▶ database.clamav.net (HTTPS · DNS)
                                                    └──────────────── 볼륨 <PROJECT_NAME>_clamav-db (씀) ──┘

항목	값
서비스	`docker-compose.yml` 의 `clamav`(검사기 clamd) · `clamav-updater`(서명 갱신 freshclam). 운영은 profile 없이 늘 뜬다(`CLAMAV_HOST` 가 운영 필수라 검사기가 없으면 검사가 서 버린다). 개발은 profile `clamav` — `COMPOSE_PROFILES=mail,clamav` + `CLAMAV_HOST=clamav` 일 때만
이미지	공식 `clamav/clamav:1.4.6_base` — digest `sha256:e7399106…`(2026-10-30 manifest list, linux/amd64 만). 1.4 는 ClamAV 의 LTS(2024-08 부터 3년 — 서명을 받을 수 있는 기간, https://docs.clamav.net/faq/faq-eol.html), 1.4.6 은 2026-08-07 보안 릴리스(2주가 지났다). `_base` 는 서명이 들지 않은 이미지다(서명은 볼륨에). 같은 판의 Debian 판(`_base-debian`)은 200MB 검사가 17% 느렸다(23.7초 · 20.3초)
둘로 나눈 까닭	clamd 는 바깥에서 온 파일(악의적인 압축 · 문서)을 연다 — 그 해석기에 구멍이 나도(2026 년에만 heap overflow CVE 여럿) 바깥 · 다른 컨테이너에 닿지 못하게 clamd 는 internal 네트워크 하나에만 둔다. 바깥에 나가는 것은 서명을 받는 freshclam 뿐이고, 그것은 backend · clamd 와 잇지 않는다. 새 서명은 clamd 가 10분마다(`SelfCheck`) 볼륨을 보고 다시 읽는다(`NotifyClamd` 를 쓰지 않는다)
네트워크	`clamav` — backend ↔ clamav 전용, internal. `clamav-egress` — updater 혼자. 둘 다 서브넷은 도커가 정한다(주소로 믿는 곳이 없다 — 기본 주소 풀 172.17~31.x · 192.168.x 이 서버 VPC 와 겹치지 않는지 본다). clamd 는 암호화 없는 TCP 이고 접속을 가리지 않으므로 다른 컨테이너를 붙이지 않는다. app-network(신뢰 대역)에는 붙이지 않는다
실행	둘 다 이미지의 `clamav` 사용자(100:101) · 권한(capability) 모두 뺌 · `no-new-privileges` · `init: true`(PID 1 tini). 이미지의 `/init` 은 root 로 소유자를 바꾸고 freshclam 과 clamd 를 함께 띄우므로 쓰지 않고 `clamd --foreground` · `freshclam --daemon --foreground` 를 바로 띄운다(멈추면 컨테이너가 끝나 재시작 정책을 탄다). clamd 는 띄우기 전에 `/tmp` 의 `clamav-*`(지난번에 검사 중 죽으며 남긴 임시 파일)를 지운다 — 아래 "임시 디스크". 호스트 포트는 어떤 환경에서도 열지 않는다
healthcheck	clamav — 이미지의 `clamdcheck.sh`(3310 PING → PONG). updater — 서명(main · daily)이 있고 daily 가 이틀 안에 바뀌었는지(멈추면 unhealthy 로 보인다 — 검사는 옛 서명으로 이어 간다). clamav 는 updater 가 healthy 가 된 뒤에 뜬다(`required: false` — 서명이 오래됐다고 검사기를 세우지 않는다)
서명 갱신	하루 12번 묻고(DNS TXT `current.cvd.clamav.net`) 새 판이 있을 때만 받는다(cdiff). 받은 서명은 바꿔 넣기 전에 따로 읽어 본다(`TestDatabases yes` — 깨진 서명이 clamd 를 멈추지 않게). 처음 기동은 main · daily · bytecode 110MB(2026-10-30 — 서명 363만 개)를 받는 데 1분 안팎이었다
설정	`clamav/clamd.conf` · `clamav/freshclam.conf` — 이미지 기본 설정을 통째로 바꾼다(저장소는 umask 022 로 클론 — 컨테이너 사용자 100 이 읽어야 한다). 바꾼 뒤에는 `up -d --force-recreate clamav`(또는 `clamav-updater`). CI 의 infra 잡이 `clamconf` 로 읽고 아래 값이 그대로인지 본다

한도 · 판정 (clamd.conf) — 한 파일 한도(MAIL_LARGE_FILE_MAX_SIZE_MB, 최대 2,047MB)까지 끝까지 검사한다:

설정	값	까닭
`StreamMaxLength`	2047M	INSTREAM 으로 받는 양. 같으면 받고 1바이트 넘으면 `INSTREAM size limit exceeded. ERROR` — 백엔드는 이보다 큰 파일을 만들지 않는다
`MaxFileSize`	2047M	한 파일(압축 안의 파일 포함). ClamAV 는 2GiB − 1 넘게는 검사하지 못한다(1.4.6 이 그 위를 2,147,483,645 로 줄이고 경고)
`MaxScanSize`	4094M	파일 하나에서 검사하는 양의 합(압축을 푼 내용까지). 푼 내용은 `/tmp`(컨테이너 쓰기 계층)에 잠시 쓴다
`MaxScanTime`	300000(5분)	1.4 에서는 ZIP 에만 걸린다. 백엔드가 다 보낸 뒤 판정을 기다리는 시간(30분 + 보낸 1MB 마다 1초 — 2,047MB 면 약 64분, 아래 "백엔드 쪽 시간")보다 짧게 둔다 — 넘으면 백엔드가 끊고 미뤄서 처음부터 다시 검사한다
`AlertExceedsMax` · `AlertEncrypted`	yes · yes	끄면 한도를 넘거나 암호가 걸린 파일이 `stream: OK`(깨끗함)로 온다(아래 표의 "끈 때")
`ConcurrentDatabaseReload`	no	서명을 다시 읽을 때 두 벌을 들지 않는다 — 1GB 그대로, 그 30초 안팎 동안 검사 · PING 이 기다린다

판정 실측 (2026-10-30, 개발 — clamd 1.4.6 · 위 설정. 백엔드와 같은 규약의 INSTREAM 시험 클라이언트, 그리고 백엔드로 끝까지):

보낸 것	clamd 의 답 (`\0` 앞)	백엔드 판정
깨끗한 파일(18B · 10MB · 40MB · 2,047MB 무작위)	`stream: OK`	clean
EICAR · EICAR 를 든 zip	`stream: Eicar-Test-Signature FOUND`	infected
암호 zip(ZipCrypto · AES-256 — 안에 EICAR 가 있어도)	`stream: Heuristics.Encrypted.Zip FOUND`	unscannable
암호 7z(내용만 · 머리글까지)	`stream: Heuristics.Encrypted.7Zip FOUND`	unscannable
사용자 암호 pdf / 소유자 암호만 있는 pdf	`stream: Heuristics.Encrypted.PDF FOUND` / `stream: OK`	unscannable / clean
20겹 zip · 파일 12,000개 zip	`stream: Heuristics.Limits.Exceeded.MaxRecursion FOUND` · `…MaxFiles FOUND`	unscannable
풀면 2,100MB · 4,500MB 인 zip(0 으로 채움)	`stream: Heuristics.Limits.Exceeded.MaxScanTime FOUND`(5분)	unscannable
풀면 600MB 인 zip	`stream: OK`(100초)	clean
암호 항목 + EICAR 항목이 함께 든 zip · 한도 넘는 항목 + EICAR	`stream: Eicar-Test-Signature FOUND` — 진짜 서명이 휴리스틱보다 먼저다	infected
`StreamMaxLength` 보다 큰 스트림(시험 clamd — 10M 에 20MB · 10M+1B)	`INSTREAM size limit exceeded. ERROR` 를 보내고 FIN — 클라이언트가 계속 보내면 clamd 쪽이 RST. 클라이언트가 답을 읽기 전에 RST 가 오면 답 없이 `EPIPE` 다(같은 시험에서 한 번은 답, 한 번은 `EPIPE`)	(백엔드 — 설정 오류로 검사 중 그대로 · error)
끈 때(`AlertExceedsMax no`, 시험 clamd — MaxFileSize 5M)	7MB 무작위 · 20겹 zip · 파일 12,000개 zip 모두 `stream: OK`	⚠️ clean 이 된다
⚠️ 시험 clamd(MaxFileSize 5M · MaxScanSize 8M)에서 zip 안의 한도 넘는 항목(6MB · 600MB 의 0)	`AlertExceedsMax yes` 인데도 `stream: OK`	clean — 아래 "알려진 한계"

로그는 instream(<백엔드 주소>@<포트>): <이름> FOUND 만 남는다(파일 이름 없음 · 깨끗한 파일은 남기지 않음). 백엔드는 판정 이름 · 파일 id 를 남긴다.
알려진 한계 — (1) 1.4.6 은 zip 안의 항목이 MaxFileSize·MaxScanSize 를 넘으면 그 항목을 건너뛰고 알리지 않을 때가 있다(위 표의 마지막 줄 — 운영 값에서는 풀면 2GB 가 넘는 zip 이 먼저 MaxScanTime 에 걸렸다). (2) 검사 한 번은 코어 하나로 2,047MB 에 5분 안팎이다(이 PC — 1분에 400MB, 운영 CPU 가 느리면 더 걸린다). zip 밖의 압축(7z · tar.gz 등)은 시간 상한 없이 MaxScanSize(4GB)까지 푼다 — 4,094MB 를 코어 하나로 10분 안팎, 운영 CPU 가 2~~3배 느리면 20~~30분이다. 백엔드의 판정 대기(30분 + 1MB 마다 1초)가 그것을 덮는다 — 넘으면 끊고 미뤄서 처음부터 다시 검사한다(그동안 "검사 중"). (3) 검사는 한 번이다 — 나중에 나온 서명으로 다시 보지 않는다(계약 4절).
백엔드 쪽 시간 (backend/src/modules/file-storage/file-storage.constants.ts) — 연결 10초, 흘려보내는 동안 아무것도 오가지 않으면 10분(clamd 는 받는 대로 임시 파일에 적는다), 다 보낸 뒤 판정까지 30분 + 보낸 1MB 마다 1초(clamavVerdictTimeoutMs — 2,047MB 면 3,847초 ≈ 64분). 연결에는 TCP keepalive(첫 대기 60초)를 켜서 컨테이너째 사라진 clamd(RST 도 오지 않는다)를 긴 판정 대기와 상관없이 1분 남짓에 알아차린다. 어느 쪽이든 끊기면 미뤄서 다시 한다.
CPU — cpus: 2.0(백엔드가 한 번에 2개까지 보낸다) · cpu_shares: 512(다른 컨테이너와 다툴 때 절반 몫 — 웹메일 · 메일 엔진이 먼저). 서버가 2 vCPU 보다 적으면 cpus 를 낮춘다(넘으면 up 이 실패한다).
임시 디스크 — clamd 는 받은 스트림을 /tmp 에 다 쓴 뒤 검사하고 지운다(2,047MB 시험 — 2GB 썼다가 0 으로). 한 번에 2개 × (2GB + 푼 내용 4GB 까지)가 도커 data-root 의 디스크(볼륨과 같은 디스크)에 잠시 든다. 검사 중에 clamd 가 죽으면(OOM 등) 그 임시 파일(/tmp/clamav-<hex>.tmp)은 지워지지 않고, 재시작은 같은 쓰기 계층을 쓰므로 죽을 때마다 쌓인다 — 그래서 compose 가 clamd 를 띄우기 전에 rm -rf /tmp/clamav-* 한다(2026-10-30 시험 clamd: 800MB 를 흘려보내다 죽이기를 두 번 — 고치기 전에는 324MB → 681MB 로 쌓였고, 고친 뒤에는 다시 뜰 때마다 비었다). recreate 없이 restart 만 해도 지운다.

# 상태 — 둘 다 healthy, 서명 판(daily 번호 · 날짜)
sudo docker compose --env-file .env.production ps clamav clamav-updater
sudo docker exec "${PROJECT_NAME}-clamav" sh -c 'echo VERSION | nc localhost 3310'      # ClamAV 1.4.6/<daily 판>/<날짜>
sudo docker logs --tail 20 "${PROJECT_NAME}-clamav-updater"                             # daily.cld updated / database is up-to-date
# 판정 시험 — EICAR 는 파일로 두지 않는다(서버 백신이 지울 수 있다). 백엔드 컨테이너의 node 로 clamav 에 INSTREAM 한 번
sudo docker exec "${PROJECT_NAME}-backend" node -e "const s=require('net').connect(3310,'clamav'),e=Buffer.from('WDVPIVAlQEFQWzRcUFpYNTQoUF4pN0NDKTd9JEVJQ0FSLVNUQU5EQVJELUFOVElWSVJVUy1URVNULUZJTEUhJEgrSCo=','base64'),h=Buffer.alloc(4);h.writeUInt32BE(e.length);s.on('connect',()=>s.end(Buffer.concat([Buffer.from('zINSTREAM\0'),h,e,Buffer.alloc(4)])));s.on('data',d=>console.log(String(d)))"
#   → stream: Eicar-Test-Signature FOUND

대용량 첨부 — 공개 내려받기 호스트

받는 사람은 포털과 다른 호스트(SHARE_PUBLIC_URL — 운영 https://files.arasystem.it.kr)에서 받는다. 털린 계정이 퍼뜨린 악성 파일로 포털 주소까지 차단 목록(세이프 브라우징 등)에 오르는 위험을 떼어 놓고, 포털 쿠키(호스트 한정)도 그 호스트로 가지 않는다. 외부 프록시는 포털과 같은 사설 IP:8080 으로 넘긴다 — 프론트 nginx 가 Host 로 server 를 가른다(frontend/nginx.conf):

	포털 (`portal.` — default_server)	공개 내려받기 (`files.` — `SHARE_PUBLIC_URL` 의 호스트 이름)
화면	웹메일 전부. `/s/…` 는 404	`/s/<토큰>`(SPA 의 공개 라우트 — `index.html`, `no-cache` · `X-Robots-Tag: noindex, nofollow` · `Referrer-Policy: no-referrer`) · `/assets/` · `/favicon.ico` 만. 그 밖(`/` · `/index.html` · `/mail/…`)은 404
API	`/api/…` 전부. `/api/public-links/…` 는 404 `RES_001`(JSON — 대소문자 변형 `/api/Public-Links/…` · `%5C` 도)	`/api/public-links/…` 만(대소문자를 가리지 않는다). 그 밖의 `/api/…` 는 404 `RES_001`, 1m 넘는 본문은 413 `FILE_002`(둘 다 JSON)
두 호스트 공통	원문 요청 대상에 날 `\`(경로) · `#` · 0x80 이상 바이트가 있으면 location 을 고르기 전에 400 `VAL_001`(JSON) — 백엔드가 그 꼴을 다르게 읽어 닫기를 비켜 갔다 (계정 보안 "잘못된 요청 대상은 400")
백엔드	같은 판정으로 두 겹 막는다 — `Host` 의 호스트 이름이 공개 호스트면 `/api/public-links/` 만, 아니면 그것만 404(`modules/file-sharing/public-host.ts`)

SHARE_PUBLIC_URL 이 비었거나 그 호스트 이름이 CORS_ORIGIN 에 있으면 따로 두지 않는다 — 포털이 둘 다 연다(개발 · 같은 호스트 운영. nginx-env.envsh 가 고르고 docker logs 첫 줄에 남긴다). 운영은 넣지 않는다 — CORS_ORIGIN 에 공개 호스트를 넣으면 분리가 꺼진다(백엔드가 운영에서는 기동을 막는다). SHARE_PUBLIC_URL 의 모양(출처 — 경로 · 끝의 / · 끝 점 없이)이 틀리면 frontend 가 뜨지 않는다(nginx-env.envsh: 줄).
조각 올리기 PUT /api/file-uploads/{id}/chunks/{n} 만 본문 17m(조각 16MiB + 여유 — 계약 상수라 env 로 바꾸지 않는다) · 읽기 90초. 요청 본문은 nginx 가 다 받아 둔 뒤 넘긴다(/tmp/client_temp). 그 밖의 /api/file-uploads · /api/file-quota · /api/share-links · /api/share-link-lookups 는 JSON 1m 그대로다. 조각 요청은 포털 호스트로 온다. 이 경로의 오류 로그는 error 부터다 — 조각마다 nginx 가 a client request body is buffered to a temporary file(warn)을 남겨 2GB 파일 하나에 128줄이 쌓였다(본문 버퍼는 키우지 않는다 — 동시 조각 수 × 16MiB 가 메모리에 앉는다).
받기 /api/public-links/<토큰>/files/…(공개) · /api/messages/<id>/large-files/…(앱 안) — 응답 버퍼링 · 압축을 끄고 X-Accel-Buffering: no 를 외부 프록시로 넘긴다(실시간 알림과 같다), Range · If-Range 는 그대로 넘긴다(백엔드가 206 · 416). 머리글 버퍼는 16k(proxy_buffer_size — 한글 255자 파일 이름이면 응답 머리글이 3.5KB 쯤이라 기본 4k 로는 빠듯하다). 동시 연결 — 클라이언트 주소마다 공개 10 · 앱 안 30(사무실 NAT), 전체는 공개 400 · 앱 안 200 을 따로 센다(공개 받기가 가득 차도 직원의 앱 안 받기는 된다). 넘으면 429 REQ_001(JSON). 클라이언트 주소는 X-Forwarded-For 의 마지막 칸(외부 프록시가 이어 붙인 값)이다 — 앞에 꾸민 값을 붙여도 마지막 칸으로 센다. 두 경로는 대소문자 · %2F · 겹 / 를 가리지 않고 같은 설정을 탄다 — 백엔드(Express)의 라우팅이 대소문자를 가리지 않아 /api/Messages/…/LARGE-FILES/… 도 받기 처리기에 닿기 때문이다 (nginx 의 대소문자를 가리는 prefix 에 기대면 한도 · 버퍼링 끔을 비켜 간다 — 2026-10-30 리뷰. CI 의 infra 잡 "대용량 받기 경로 시험"이 변형마다 실제 요청으로 본다). 그릇은 nginx 워커마다 worker_connections 4096(이미지 기본 1024 에서 올림 — frontend/Dockerfile) · frontend 의 열린 파일 수 8192(compose ulimits)다 — 받기 600 개(연결 1,200) · 실시간 알림(브라우저마다 연결 둘) · 포털 요청이 워커 하나에 몰려도 모자라지 않게 (2026-10-30 운영 이미지 시험: 받기 600 개를 붙잡아 둔 채 401번째 공개 · 201번째 앱 안 받기가 429, 그때도 다른 API · 실시간 알림은 200).
느린 받는 사람 (2026-10-30, 운영 이미지 · 개발 백엔드 · 40MB 파일): 조금씩이라도 받아 가면 끊지 않는다 — 초당 120KB 로 80초(읽기 제한 60초를 넘겨) 그대로 받았다. proxy_read_timeout 은 받는 쪽이 느려 nginx 가 백엔드를 읽지 않는 동안에는 돌지 않았다(5초로 줄인 시험에서도 15초 동안 받았다). 받는 쪽이 아무것도 받지 않으면 send_timeout(60초 — 기본값)에 끊긴다 — 소켓 버퍼만큼(5MB) 보낸 뒤 61.7초에 닫고 그 연결 수를 돌려준다(10초로 줄인 시험에서는 10.9초). 끊긴 받기는 브라우저 · 내려받기 관리자가 Range 로 이어 받는다.
접근 로그 — 토큰을 *** 로 가린다(요청 줄 · Referer — 예 "GET /api/public-links/***/files/<id> HTTP/1.1"). 두 가지로 겹쳐 본다: /s/<…> · /api/public-links/<…> 의 그 칸(대소문자 무시 · 길이 상관없음), 그리고 토큰 모양(base64url 딱 43자 — 앞뒤가 [A-Za-z0-9_-] 가 아닌 덩어리, %XY 바로 뒤의 덩어리)이면 경로 어디서든 — nginx 는 정규화해 받지만 로그는 받은 그대로라 //s/<토큰> · /./s/<토큰> · /%73/<토큰> · /x/../s/<토큰> · /api/public%2Dlinks/<토큰> · /api/public-links%2F<토큰> 같은 꼴도 가린다. 43자가 아닌 값(UUID 36자 · 메일 id · 화면 자산 이름 — 가장 긴 것 35자)은 그대로 남는다. 토큰 안을 퍼센트 인코딩으로 쪼갠 꼴은 가리지 못한다(그 토큰을 가진 본인만 만든다). 오류 로그(502 · 504 등)는 지금 정책대로 요청 줄을 그대로 남긴다(운영 담당만 읽는다). 동시 연결 초과는 오류 로그에 남기지 않는다(접근 로그의 429 로 본다).

외부 프록시 (서버 A 의 Nginx Proxy Manager) — 포털 Proxy Host와 같은 칸으로 하나 더 만든다:

칸	값
Domain Names	`files.arasystem.it.kr` (가비아 `files` A → 서버 A 공인 IP — 이미 있다)
Scheme · Forward Hostname / IP · Port	`http` · 서버 B 사설 IP · `8080` — 포털과 같은 곳(Host 는 NPM 이 그대로 넘긴다 — `proxy.conf` 의 `proxy_set_header Host $host`)
Cache Assets · Block Common Exploits · Websockets	끔 · 끔 · 끔 (포털과 같다)
SSL	Let's Encrypt 새 인증서(`files.`) · Force SSL · HTTP/2
Advanced	포털과 같은 다섯 줄(`proxy_read_timeout 150s;` · `access_log off;` · `real_ip_header proxy_protocol;` · `proxy_buffer_size 16k;` · `proxy_busy_buffers_size 16k;` — 포털 Proxy Host). `access_log off;` 는 꼭 — 경로에 내려받기 토큰이 있다(NPM 의 `proxy` 형식은 경로를 그대로 남긴다)

포털 Proxy Host 의 본문 한도(NPM 기본 2000m)는 조각 17MB 보다 크다 — 줄였다면 17MB 이상, 읽기는 이미 150초다.
받기 응답은 우리가 넘기는 X-Accel-Buffering: no 를 NPM(nginx)이 따라 버퍼링하지 않는다 — proxy_ignore_headers 로 이 머리글을 무시하게 했다면 그 호스트에 proxy_buffering off; 를 더한다 (버퍼링하면 느린 받는 사람마다 NPM 이 임시 파일을 1GB 까지 만든다).
받기 응답의 머리글(한글 255자 파일 이름이면 3.5KB 쯤)은 NPM 의 머리글 버퍼에도 들어가야 한다 — NPM v2.16.0 은 버퍼 크기를 정하지 않아 nginx 기본(4k — 그 이미지의 페이지 크기 4096)이고, 넘치면 NPM 이 502(HTML)를 낸다. 그래서 두 Proxy Host 의 Advanced 에 proxy_buffer_size 16k; 와 proxy_busy_buffers_size 16k; 를 함께 넣는다 — 앞의 것만 넣으면 nginx 가 설정을 거절해("proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer) NPM 이 그 Proxy Host 를 Offline 으로 둔다 (2026-10-30, jc21/nginx-proxy-manager:2.16.0 이미지의 OpenResty 1.31.1.1 로 nginx -t — 한 줄만이면 실패, 두 줄이면 통과. 이미지의 nginx.conf · conf.d/include/*.conf 에는 proxy_buffer* 가 없다).
확인: 바깥에서 curl -sI https://files.arasystem.it.kr/ → 404 · curl -s https://files.arasystem.it.kr/api/auth/me → 404 RES_001 · curl -s https://portal.arasystem.it.kr/api/public-links/x → 404 RES_001, 보낸 메일의 링크(/s/…)가 열리고 받아진다. 서버 B 의 sudo docker logs --tail 5 "${PROJECT_NAME}-frontend" 에 토큰이 *** 로 보인다.

메모리 예산

8GB 서버(서버 B) 하나에 스택 전체가 올라간다. 한도(compose deploy.resources.limits.memory)의 합이 실제 메모리를 넘지 않게 둔다 — 평소에는 한도보다 훨씬 적게 쓴다.

컨테이너	한도	평소 (2026-10-30 개발에서 잰 값)	가장 클 때
clamav (clamd)	2g	0.95GB — 서명 363만 개를 읽은 뒤	서명을 다시 읽을 때 1.0GB(두 벌을 들지 않는다), 2GB 검사 중 1.0~1.2GB + 받은 파일의 페이지 캐시(한도 안에서 줄여 쓴다)
clamav-updater (freshclam)	1g	수십 MB	처음 기동(서명 전체를 받아 읽어 봄) 0.7GB, 평소 갱신은 daily 만
mail	1g	0.1~0.3GB
backend	1g	0.3~0.5GB	조각 · 받기는 스트림이라 파일 크기와 상관없다
db · frontend · mail-resolver	512m · 512m · 128m	작다
합	6.15GB	2.5~3GB	나머지 1.8GB 남짓을 커널 · dockerd · 페이지 캐시가 쓴다

ClamAV 의 ConcurrentDatabaseReload 를 켜지 않는다(기본은 켬) — 켜면 서명을 다시 읽는 동안(하루 몇 번) 두 벌(2GB 남짓)을 들어 2g 한도에서 죽는다. 한도를 올려 켜려면 합이 8GB 를 넘지 않는지 다시 본다.
서명은 해마다 는다 — docker stats 의 clamav 가 한도의 80%(1.6GB)를 넘으면 한도를 올리거나(합을 다시 본다) 서버를 키운다.
디스크(블록 스토리지 100GB · 도커 data-root /data/docker) — 대용량 첨부 파일(직원마다 10GB · FILE_STORAGE_MAX_TOTAL_GB) · 메일 볼륨 · DB · 이미지 · ClamAV 의 임시 파일(검사 중 최대 12GB)이 함께 쓴다. 백엔드는 올리기를 만들 때 FILE_STORAGE_MIN_FREE_GB(10GB)를 남긴다 — 메일 볼륨이 자랄 몫을 생각해 FILE_STORAGE_MAX_TOTAL_GB 를 정해 둔다(예: 40).

계정 보안 (12단계 — 인프라)

2단계 인증(인증 앱 TOTP) · 앱 비밀번호 · 로그인 기록. 데이터 · 규칙은 계약 5절 "계정 보안", env 는 루트 예시 env 의 MAIL_WEBHOOK_SECRET 이다. 엔진(0.16.27)이 코드 확인 · 앱 비밀번호를 맡고, 백엔드가 그 앞의 규칙(첫 코드 확인 · 다시 쓴 코드 막기 · 실패 한도 · 웹메일에서 앱 비밀번호 거절)과 로그인 기록을 맡는다. 이 절은 엔진 설정 · 프록시 · 운영만 다룬다.

엔진 웹훅 — 메일 프로그램 로그인 기록

메일 프로그램 ─(993 IMAPS · 465 SMTPS)─▶ mail ─(웹훅 · app-network · 1초 묶음)─▶ backend  POST /api/internal/mail-engine-events → 로그인 기록(90일)
                                               X-Signature = base64(HMAC-SHA256(본문, MAIL_WEBHOOK_SECRET))
바깥 ─▶ 외부 프록시 ─▶ frontend nginx  /api/internal/…  → 404 RES_001 (두 server 모두 — 백엔드로 넘기지 않는다)

엔진에는 계정별 로그인 기록이 없어(공개판 — x:Trace 는 엔터프라이즈 전용) 엔진이 인증 이벤트를 백엔드로 보내고 백엔드가 남긴다. 웹메일 로그인은 백엔드가 스스로 남긴다(엔진에는 백엔드 IP 로 보인다).

항목	값
엔진 객체	`x:WebHook` 하나 — 관리 화면 Settings › Telemetry › Webhooks. setup 이 만들고 맞춘다(여러 번 돌려도 같다). 관리 화면에서 고치지 않는다 — 다음 setup 이 되돌린다
받는 곳	`http://backend:<BACKEND_PORT>/api/internal/mail-engine-events` — compose 의 서비스 이름. mail 과 backend 가 함께 붙는 네트워크는 app-network 하나라 엔진의 접속 주소가 그 대역이다
이벤트	`auth.success` · `auth.failed` · `auth.mfa-required` 만(`eventsPolicy: include`) — 엔진 기본(`exclude` + 빈 목록)은 모든 이벤트다
그 밖의 칸	`level: trace`(이 판은 웹훅에 수준을 쓰지 않지만 새 판 문서는 쓴다 — info 면 debug 인 `auth.failed` · trace 인 `auth.mfa-required` 가 빠진다) · `throttle` 1초(묶음) · `timeout` 5초 · `discardAfter` 5분 · `lossy: false` · HTTP 인증 없음
서명	본문 원문의 HMAC-SHA256 을 base64 로 `X-Signature` 에 — 키 `MAIL_WEBHOOK_SECRET`(`openssl rand -hex 24` 로 만든 값 — 사람이 지은 키는 쓰지 않는다). 키는 엔진 설정에 그대로 저장된다 — 관리 화면 · 관리 API 는 `****` 로 가리지만 메일 볼륨 백업에는 있다
setup 표시	`x:WebHook` 에는 이름 · 설명 칸이 없다 — 머리글 `X-Arasystem-Setup: [setup.mjs] key=<소금>.<키 지문>` 을 setup 표시로 쓴다. 키는 읽으면 `**` 라 키가 바뀌었는지는 이 지문(scrypt — 소금은 setup 이 웹훅을 쓸 때마다 새로 뽑는다)으로 안다. 엔진이 보내는 요청마다 실린다(백엔드는 쓰지 않는다). ⚠️ 관리 화면에서 서명 키만 바꾸면(머리글은 그대로) setup 이 알아채지 못한다** — 키는 env 와 setup 으로만 바꾼다
받는 쪽 (세 겹)	앞단 nginx 가 `/api/internal/` 을 404 `RES_001`(두 server · 대소문자 · `%2F` · `%5C` · 겹 `/` 변형 — `frontend/nginx-internal-api-closed.conf`), 원문 요청 대상에 날 `\`(경로) · `#` · 0x80 이상 바이트가 있으면 location 을 고르기 전에 400 `VAL_001`(두 server — 아래) → 백엔드가 접속 주소(소켓)가 `APP_NETWORK_SUBNET` 인지 → 서명. 하나라도 아니면 401 `AUTH_001` (계약 5절 "엔진 웹훅 받기"). CI 의 "닫는 경로 시험"이 두 server 에서 실제 요청으로 본다
이름 풀기	웹훅은 엔진의 DNS(`x:DnsResolver` — 운영은 리졸버에 바로)가 아니라 메일 컨테이너의 시스템 DNS(도커 DNS)로 `backend` 를 푼다(엔진의 HTTP 라이브러리 기본값 — 0.16.27 소스). 개발 엔진의 DNS 를 운영처럼 Custom 으로 바꿔 확인했다(아래 "확인")

받는 것 — IMAP(993) · SMTP(465) 로그인의 성공 · 실패 · "2단계 필요"(2단계를 켠 계정에 비밀번호로). 엔진 HTTP 리스너의 이벤트(웹메일 확인 · 게이트웨이 대리 접근)도 오지만 백엔드가 버린다. 엔진은 서버 전체의 이벤트를 보낸다 — 사내 직원이 아닌 주소의 실패 등은 백엔드가 거른다 (계약 5절).
끊기면 잃는 기록 — 엔진의 보낼 대기열은 메모리에 있다. 백엔드가 5분 넘게 받지 못하면(discardAfter) 그 묶음을 버리고, 엔진을 다시 띄우면 보내지 못한 것이 사라진다 — 그동안의 메일 프로그램 로그인 기록과 앱 비밀번호의 "마지막 사용"이 빠진다(웹메일 로그인 기록은 백엔드가 남기므로 그대로). 백엔드가 멈춘 동안 엔진 로그에 WARN Webhook collector error (telemetry.webhook-error) … error sending request 가 보낼 것이 있는 동안 1초마다 남고, 5분이 지나 버릴 때 같은 이벤트로 Discarded stale events(버린 수)가 남는다 — 백엔드가 돌아오면 멎는다. lossy: false 라도 엔진의 다른 일을 막지 않는다 — 엔진은 구독자에게 기다리지 않고 넘기고(가득 차면 그 묶음을 메모리에 더 쌓는다), 5분 지난 것은 버린다(0.16.27 소스) (lossy: true 면 쌓인 묶음이 32,768개를 넘을 때 error 수준만 남겨 로그인 이벤트를 버린다).
키를 바꾸면 — 차례: .env.production 의 값을 바꾸고(openssl rand -hex 24) → sudo docker compose --env-file .env.production up -d backend(백엔드가 새 키로 확인) → setup(엔진이 새 키로 서명 — [변경] 엔진 웹훅 — 서명 키 · [확인] … 받았다). 둘 사이에 엔진이 보낸 묶음은 백엔드가 401 로 거절한다(엔진은 5분까지 다시 보낸다) — 둘을 이어서 하고, 그 몇 분의 메일 프로그램 기록은 빠질 수 있다고 본다. setup 을 먼저 돌렸으면 받는 곳 확인이 401 인데, 이번 실행에서 엔진에 키를 넣었으므로 실패가 아니라 [주의] 와 다음 명령(up -d backend 뒤 setup 한 번 더)이다 — 그대로 한 뒤 [확인] … 받았다 를 본다.
키가 비면 — 운영은 setup · 백엔드 모두 멈춘다(운영 필수). 개발은 setup 이 [주의] 를 내고 있던 웹훅을 끈다(enable: false — 지우지 않는다). 키를 넣고 다시 돌리면 켠다.
setup 의 확인 — 리로드 뒤 다시 읽어 setup 의 값 그대로인지([확인] 엔진 웹훅 켜짐), 그리고 메일 컨테이너 안(엔진과 같은 자리 · 같은 DNS)에서 서명한 빈 묶음 {"events":[]} 을 보내 200 인지([확인] 엔진 웹훅 — … 받았다 (HTTP 200 — 백엔드 쪽(받는 곳 · 접속 주소 · 키)이 맞다)). 엔진에 든 키는 읽을 수 없어 표시 머리글의 지문으로만 안다(위 표). 401(키 · 접속 주소)은 운영은 실패, 개발은 [주의](이번 실행에서 키를 넣었으면 운영도 [주의] — 위 "키를 바꾸면"), 안내는 up -d backend. 404(받는 곳이 없는 12단계 전 backend)는 운영은 실패로 up -d --build backend frontend, 개발은 [주의] 로 restart backend 를 안내한다. 닿지 않으면 몇 번 다시 해 본 뒤 [주의]. 서명은 docker exec 의 명령줄이 아니라 표준 입력으로 넘긴다(도커 이벤트 · ps 에 남지 않게).
잘못된 요청 대상은 400 (두 server 모두 — frontend/nginx.conf 의 $request_target_rejected) — 원문 대상에 날 \(경로) · 날 # · 0x80 이상 바이트가 있으면 location 을 고르기 전에 400 VAL_001(JSON — 화면 경로도 같다)로 끝낸다. nginx 는 그 꼴을 닫는 정규식(/api/internal · /api/health · 공개 API)에 맞추지 못하고 원문 그대로 넘기는데, 백엔드의 Express(parseurl)는 # · NBSP(0xA0) 같은 글자가 있으면 옛 url.parse 로 다시 읽어 경로의 \ 를 / 로 바꾼다 — POST /api/internal\mail-engine-events#x 가 개발 백엔드의 웹훅 가드(401)까지 닿았다(2026-10-31 리뷰 — 같은 원인으로 /api/health · 포털의 공개 API 닫기도 11단계 전부터 넘어갔다). 브라우저는 이런 요청을 보내지 않는다(경로의 \ 는 / 로 바꾸고, 비 ASCII 는 퍼센트 인코딩하고, # 뒤는 보내지 않는다). 쿼리의 \ 는 받는다(주소창에 친 검색어 — url.parse 는 ? 앞의 \ 만 바꾼다). %5C 는 nginx 가 \ 로 풀어 고르므로 닫는 정규식이 [/\x5c] 로 받는다(두 겹).
setup 표시 없이 같은 받는 곳으로 가는 웹훅이 있으면 [주의] 만 낸다(사람이 만든 것으로 본다 — 같은 이벤트가 두 번 가거나 다른 키로 서명돼 거절된다) — Settings › Telemetry › Webhooks 에서 지운다.
게이트웨이에는 2단계 인증을 켜지 않는다 — 대리 접근은 게이트웨이 자신의 비밀번호 · OTP 를 확인하므로 백엔드의 대리 접근이 모두 402 로 막혀 웹메일 전체가 선다. setup 은 게이트웨이가 402 면 아무것도 바꾸기 전에 멈춘다 — 아래 "휴대폰을 잃은 직원"의 절차를 게이트웨이 주소로 해서 끈다.
확인 (2026-10-31, 개발 엔진 0.16.27):
- setup — 처음 실행 [생성] → 다시 돌리면 [유지](바뀐 것 0줄). 이벤트를 하나 더하고 timeout 을 바꾼 뒤 → [변경] … 이벤트, timeout, 키 지문을 바꾼 뒤 → [변경] … 서명 키, 키를 비우고 → [주의] · [변경] … 끔, 되돌리면 [변경] … 꺼짐(다시 켬) → [유지]. 읽으면 서명 키는 "****" 다. 옛 모양의 표시 머리글(소금 없음)은 한 번 [변경] … 서명 키 로 맞추고 그다음은 [유지]. 다른 키로 돌리자 받는 곳 확인이 401 → [주의] … 이번 실행에서 엔진에 … 넣었고 · 원래 키로 되돌리자 [확인] … 받았다 (HTTP 200 …). 게이트웨이를 OTP 를 켠 임시 계정으로 가리키자 첫 줄 다음에 [실패] 게이트웨이 계정(…)에 2단계 인증(OTP)이 켜져 있습니다 — 바꾼 것 없음.
- 배달 — 앱 비밀번호로 IMAP · SMTP 로그인, 틀린 비밀번호로 IMAP 로그인을 하자 로그인 기록에 imap 성공(앱 비밀번호 이름) · smtp 성공 · imap 비밀번호 틀림이 생겼고 앱 비밀번호의 "마지막 사용"도 채워졌다(메인).
- 운영 모양의 엔진 DNS — 개발 엔진의 x:DnsResolver 를 운영처럼 Custom(리졸버 172.16.73.254 의 UDP · TCP)으로 바꾸고 리로드한 뒤 IMAP 틀린 비밀번호 한 번 → 백엔드 기록에 imap · 실패 · wrongPassword · 172.16.71.2 가 생겼고 엔진의 웹훅 오류는 없었다. 메일 컨테이너의 /etc/resolv.conf 는 도커 DNS(127.0.0.11)이고 backend 는 앱 네트워크 주소(172.16.71.5)로 풀린다. setup 으로 System 으로 되돌렸다.
- 백엔드가 떠 있지 않을 때 — 리로드 뒤 틀린 비밀번호 로그인 한 번에 엔진이 받는 곳으로 보내려다 위의 warn 을 1초마다 남겼다.

휴대폰을 잃은 직원 — 2단계 인증 끄기

복구 코드는 없다 — 인증 앱을 쓸 수 없게 된 직원은 운영자가 엔진에서 그 직원의 OTP 를 지운다. 직원 비밀번호 없이 된다. 끄면 그 직원은 비밀번호만으로 로그인하고, 웹메일 설정에서 새 휴대폰으로 다시 켠다 (직원 본인은 끄지 못한다 — 엔진이 끌 때 지금 코드를 요구한다). 먼저 본인인지 확인한다(전화 · 대면 등 — 이 절차는 2단계 인증을 비켜 가는 길이다). 바꾸는 것은 그 계정의 비밀번호 자격 증명에 붙은 OTP 하나뿐이다 — 비밀번호 · 앱 비밀번호 · 웹메일 세션은 그대로다.

1) 관리 API (2026-10-31 개발 엔진에서 아래 명령 그대로 확인 — 관리자 Basic, 직원 비밀번호 없음)

8080(관리 API)은 바깥에 열지 않는다 — 메일 호스트에서 backend 컨테이너의 node 로 앱 네트워크의 http://mail:8080 에 붙는다(관리자 아이디 · 도메인 · 주소는 그 컨테이너의 env 를 쓴다). 관리자 비밀번호는 화면에서 받아 환경변수로만 넘긴다 — 명령줄 · 셸 기록 · ps 에 남지 않는다(docker exec -e 이름 은 값을 명령줄에 싣지 않는다).

# 메일 호스트의 저장소 폴더에서 (docker 그룹이면 sudo --preserve-env=… 없이 docker exec 부터)
export PROJECT_NAME="$(sed -n 's/^PROJECT_NAME=//p' .env.production)"   # 개발은 .env.development
read -rp '끌 직원의 주소: ' OTP_TARGET
read -rsp '관리자 비밀번호(MAIL_ADMIN_PASSWORD): ' OTP_ADMIN_PW; echo
export OTP_TARGET OTP_ADMIN_PW
sudo --preserve-env=OTP_TARGET,OTP_ADMIN_PW docker exec -i -e OTP_TARGET -e OTP_ADMIN_PW "${PROJECT_NAME}-backend" node - <<'EOF'
const base = process.env.MAIL_JMAP_URL || 'http://mail:8080';
const admin = `${(process.env.MAIL_ADMIN_LOCAL_PART || 'admin').trim().toLowerCase()}@${process.env.MAIL_DOMAIN}`;
const auth = 'Basic ' + Buffer.from(`${admin}:${process.env.OTP_ADMIN_PW}`).toString('base64');
const target = (process.env.OTP_TARGET || '').trim().toLowerCase();
const using = ['urn:ietf:params:jmap:core', 'urn:stalwart:jmap'];
(async () => {
  const session = await fetch(`${base}/jmap/session`, { headers: { authorization: auth } });
  if (session.status !== 200) throw new Error(`관리자 로그인 실패 (HTTP ${session.status})`);
  const accountId = (await session.json()).primaryAccounts['urn:stalwart:jmap'];
  const call = async (method, args) => {
    const res = await fetch(`${base}/jmap/`, {
      method: 'POST',
      headers: { authorization: auth, 'content-type': 'application/json' },
      body: JSON.stringify({ using, methodCalls: [[method, { accountId, ...args }, 'c']] }),
    });
    const [[name, result]] = (await res.json()).methodResponses;
    if (name === 'error') throw new Error(`${method}: ${result.type}`);
    return result;
  };
  let account = null;
  for (let position = 0; !account; position += 200) {
    const { ids } = await call('x:Account/query', { position, limit: 200 });
    if (ids.length === 0) break;
    const { list } = await call('x:Account/get', { ids, properties: ['name', 'emailAddress', 'credentials'] });
    account = list.find((item) => (item.emailAddress || '').toLowerCase() === target) || null;
  }
  if (!account) throw new Error(`계정이 없습니다: ${target}`);
  const [key, credential] = Object.entries(account.credentials || {}).find(([, item]) => item['@type'] === 'Password') || [];
  if (!key) throw new Error('비밀번호 자격 증명이 없습니다');
  if (!credential.otpAuth) return console.log(`이미 꺼져 있습니다 — ${target}`);
  const result = await call('x:Account/set', { update: { [account.id]: { [`credentials/${key}/otpAuth`]: null } } });
  if (!result.updated || !(account.id in result.updated)) throw new Error(`바꾸지 못했습니다: ${JSON.stringify(result.notUpdated)}`);
  const { list } = await call('x:Account/get', { ids: [account.id], properties: ['credentials'] });
  console.log(list[0].credentials[key].otpAuth ? `아직 켜져 있습니다 — ${target}` : `껐습니다 — ${target} (자격 증명 ${key})`);
})().catch((error) => { console.error(`[실패] ${error.message}`); process.exitCode = 1; });
EOF
unset OTP_ADMIN_PW OTP_TARGET

하는 일: 관리자의 x: 계정(primaryAccounts["urn:stalwart:jmap"])으로 x:Account/query · get(주소 emailAddress 로 찾는다) → 그 계정의 credentials 에서 "@type":"Password" 인 칸(보통 "0" — OTP 가 켜져 있으면 "otpAuth":"****")의 otpAuth 만 x:Account/set 의 {"credentials/<번호>/otpAuth": null} 로 지우고 다시 읽어 본다. secret 은 보내지 않는다("****" 를 보내도 엔진이 원래 값을 둔다).
확인한 것: 시험 직원(seojun.park)에 직원 경로(게이트웨이 대리 접근의 x:AccountPassword/set — currentSecret + otpAuth.otpUrl)로 OTP 를 켜자 Basic 로그인이 402, 위 명령(개발 — arasystem-backend)을 돌리자 껐습니다 — … 와 함께 otpAuth 가 없어지고 Basic 로그인이 200 이었다. 다시 돌리면 이미 꺼져 있습니다. 켤 때의 주소는 계약대로 이름 ARA SYSTEM(띄어쓰기)이었고 엔진이 그 주소로 코드를 확인했다(직원 경로로 끄기도 됨). 끝나고 처음 상태(OTP 꺼짐 · 앱 비밀번호 0개 · 비밀번호 그대로)로 되돌렸다.
웹메일의 "켠 때"(enabledAt)는 서버가 엔진에서 꺼진 것을 보면 지운다 (계약 5절 "2단계 인증").

2) 관리 화면 (운영은 SSH 터널 — ssh -L 8180:<mail 컨테이너 IP>:8080 <메일 호스트> → http://localhost:8180/admin/, 운영 배포 아래 "실제 직원 계정" 줄) — 직접 눌러 보지 못했다:

Management › Directory › Accounts 에서 그 직원을 연다.
Authentication 의 Credentials 에서 비밀번호 자격 증명(Password)을 연다.
Secrets 의 OTP Authentication URI 칸(켜져 있으면 ****)을 비우고 저장한다. 같은 묶음의 Password 칸(****)은 건드리지 않는다 — 그대로 두면 엔진이 원래 값을 지킨다.
확인 — 그 직원이 비밀번호만으로 웹메일에 로그인된다(코드를 묻지 않는다). 위 1)의 명령을 다시 돌리면 이미 꺼져 있습니다 다.

메뉴 · 칸 이름은 개발 엔진의 관리 화면이 그리는 스키마(/api/schema 의 layouts · forms)에서 찾았다. 칸을 비우면 화면이 null 을 보낸다(관리 화면 코드 — 비울 수 있는 글 칸) — 1)과 같은 요청이다. ⚠️ Account › Credentials › Password(직원 셀프서비스 화면)의 Disable 은 지금 코드를 요구한다 — 휴대폰을 잃은 직원에게는 쓸 수 없다.

운영 확인 (12단계)

setup — [확인] 엔진 웹훅 켜짐 — … 과 [확인] 엔진 웹훅 — 메일 컨테이너에서 서명한 빈 묶음을 백엔드가 받았다 (HTTP 200 …) 두 줄이 있다 (운영 배포 5).
메일 프로그램으로 한 번 로그인한다(아웃룩 · 휴대폰 메일 앱 — IMAP 993) → 웹메일 설정 › 로그인 기록에 그 시각의 IMAP 줄(바깥 주소)이 생긴다. 안 생기면 엔진 로그(sudo docker logs --since 10m "${PROJECT_NAME}-mail" 2>&1 | grep -i webhook)와 백엔드 로그를 본다.
바깥에서 막혔는지 — curl -s -X POST https://portal.arasystem.it.kr/api/internal/mail-engine-events → 404 RES_001(JSON), /api/Internal/… · /api/internal%5Cmail-engine-events 도 같다. 날 역슬래시 꼴은 400 이다 — curl -s 'https://portal.arasystem.it.kr/api/health\' → 400 VAL_001(JSON — 외부 프록시가 원문 그대로 넘기는지도 함께 본다).
직원 안내 — 2단계 인증을 켜면 아웃룩 · 휴대폰 메일 앱은 비밀번호로 연결되지 않는다 → 웹메일 설정 › 앱 비밀번호에서 만든 비밀번호로 다시 연결한다(사용자 이름은 메일 주소 그대로). 웹메일 비밀번호를 바꾸면 앱 비밀번호가 모두 지워진다 — 그때도 다시 만든다. 휴대폰을 잃으면 운영자에게 문의한다(위 절).

파일럿 공존 (mailcow 와 함께 — 한 사람 먼저)

전면 전환 전에 한 사람(시범 사용자)만 같은 @arasystem.it.kr 주소로 새 서버(mx1.arasystem.it.kr)를 쓰고, 나머지 직원은 mailcow 에 그대로 둔다. MX 는 mailcow 그대로이고, mailcow 의 Transport Map 이 시범 사용자 주소 하나만 새 서버로 넘긴다. 새 서버 쪽은 루트 env 두 개로 setup 이 맞춘다.

예시 값: 시범 사용자 owner@arasystem.it.kr, 동료(mailcow) colleague@arasystem.it.kr, mailcow mail.arasystem.it.kr(46.250.248.43), 새 서버 IP <MX1_IP>
근거: 2026-10-29 개발 엔진(0.16.27) 조사 · 시험과 mailcow(2026-10 판) 설정 파일 · 문서 조사. mailcow 쪽 절차와 운영의 실제 흐름은 아직 해 보지 않았다 — "개발 확인"이라고 적은 것만 개발 엔진에서 봤다.

메일 흐름

메일	길	새 서버가 하는 일
바깥 → 시범 사용자	바깥 → mailcow(MX · 스팸 검사) → Transport Map → mx1:25	mailcow IP 에서 인증 없이 받는다 — 그 IP 는 SPF(EHLO · MAIL FROM) · 역방향 DNS · DMARC 검사를 하지 않는다(연결 IP 가 mailcow 라 늘 실패한다). DKIM 검증 · 스팸 판정은 그대로
동료 → 시범 사용자	SOGo · 메일 프로그램 → mailcow → Transport Map → mx1:25	사내 도메인 MAIL FROM 을 mailcow IP 에서만 받는다. 받는 쪽 한도 · 자동 차단에서 mailcow IP 를 뺀다
시범 사용자 → 동료	웹메일 · 465 → mx1 → 발송 경로 `legacy` → mailcow:25 → 동료 사서함	새 서버에 없는 사내 주소도 받아서(`allowRelaying`) mailcow 로 넘긴다. DKIM 은 새 selector 로 서명
새 서버가 만든 메일 → 동료	반송 · 필터 전달 · 부재중 → `legacy` → mailcow	봉투 보낸 사람은 빈 봉투 `<>`(반송)이거나 시범 사용자 주소(전달 · 부재중) — mailcow 의 `reject_unlisted_sender` 를 통과한다
시범 사용자 → 바깥	mx1 → 받는 쪽 MX 직접	시범 앞과 같다 — mailcow 를 거치지 않는다(SPF 에 새 IP)
시범 사용자 → 시범 사용자	mx1 안	로컬
인증 없이 mx1:25 로 온, 새 서버에 없는 사내 주소 (mailcow 포함 어디서든)	—	RCPT `550 5.1.2` — 받아 놓고 되돌려 보내지 않는다 (루프 1차 막기)
mailcow 가 아닌 IP 에서 온 사내 도메인 MAIL FROM	—	`550 5.7.1` (위조 막기 — 빈 봉투 `<>` 는 그대로 받는다)

루프는 두 겹으로 막는다 — ① RCPT 가드: 인증 없는 세션의 새 서버에 없는 사내 주소는 받지 않는다 ② 발송 전략: legacy 로는 인증한 제출(웹메일 · 465)과 엔진이 만든 메일(필터 전달 · 부재중 · 반송 · 보고)만 보낸다 — 인증 없이 들어온 메일은 로컬(배달 실패 → 보낸 사람에게 반송, 그 반송은 동료 앞이면 legacy 로). 엔진의 홉 한도(x:MtaStageData 의 maxReceivedHeaders 50 → 450 4.4.6)가 마지막 막이다. RCPT 가드 없이 allowRelaying 만 켜진 상태는 setup 이 만들지 않는다 — 켤 때는 가드가 걸린 뒤에 켜고, 켠 뒤 가드가 답하지 않으면 바로 다시 끄고, 끌 때는 allowRelaying 이 꺼진 것을 엔진에서 다시 읽어 확인한 뒤에만 가드를 뺀다(2026-10-30 리뷰 H1 · M1).

사전 조건

운영 전환 체크리스트의 "1 결정 · 준비" · "2 서버 배포"를 마쳤다 — 새 서버가 mx1 로 떠 있고(운영 배포), setup 을 다시 돌리면 전부 [유지] 다.
DNS 는 더하기만 (가비아) — 전환 절차의 단계 1 · 3 · 4: mx1 A → <MX1_IP> · PTR → mx1.arasystem.it.kr, setup 이 출력한 새 DKIM selector TXT 두 개(v1-ed25519-… · v1-rsa-…), SPF 에 ip4:<MX1_IP>. DKIM TXT 는 첫 시범 실행 전에 퍼져 있어야 한다 — 운영 setup 이 이 호스트의 리졸버로 읽어, 없거나 키가 다르면 켜지 않고 멈춘다. setup 출력의 한 줄은 <이름>.arasystem.it.kr. IN TXT "<값>" 이다 — 가비아의 호스트 칸에는 끝의 .arasystem.it.kr. 를 뗀 이름, 값 칸에는 따옴표 안의 글만 넣는다. RSA 값(420자 안팎)은 setup 이 255자 + 나머지로 나눠 보이지만 가비아는 조각마다 250자 미만 · 모두 500자까지만 받는다 — 조각을 다시 나눠 "…" "…" 꼴로 넣는다(2026-10-31): awk '/v1-rsa-/{on=1} on{print} on && /\)/{on=0}' <setup 출력 파일> | grep -o '"[^"]*"' | tr -d '"\n' | fold -w 210 | sed 's/.*/"&"/' | paste -sd' '. 넣은 뒤 Resolve-DnsName v1-rsa-….arasystem.it.kr -Type TXT -Server ns.gabia.co.kr 로 조각이 이어져 키가 끝까지(…IDAQAB) 들어갔는지 본다. MX · DMARC · autodiscover 는 바꾸지 않는다. mx1 에 AAAA 는 두지 않는다(아래 "주의" 의 IPv6).
새 서버의 계정은 시범 사용자 하나만. 다른 직원 · 별칭 · 공용 주소 · dmarc@ · postmaster@ 는 만들지 않는다(아래 "주의").
새 서버 → mailcow 25 가 열려 있다(setup 이 확인한다 — 운영은 25 만 받는다. 587 · 465 는 인증이 있어야 중계되는데 setup 은 발송 경로에 인증을 넣지 않는다). mailcow 가 새 서버에 붙을 때의 IP 를 안다 — 보통 mail.arasystem.it.kr 의 A(46.250.248.43). 받는 IP 와 나가는 IP 가 다를 수 있다 — 운영 mailcow 는 받기 46.250.248.43 · 나가기 125.143.81.248(KT, PTR 없음)이었다(2026-10-31). 빗나가면 Transport Map 의 Test 가 550 5.7.1 Sender address not allowed 다 — 새 서버 로그 docker logs --since 10m "${PROJECT_NAME}-mail" 2>&1 | grep -o 'remoteIp = [0-9.]*' | sort | uniq -c 에서 Test 의 EHLO(mail.arasystem.it.kr)를 보낸 IP 를 찾아 MAIL_PILOT_LEGACY_IPS 에 콤마로 더하고 setup 을 다시 돌린다. 그 IP 가 고정인지 mailcow 쪽에 확인한다(바뀌면 동료 메일이 다시 550).
MAIL_ADMIN_LOCAL_PART(기본 admin) · MAIL_DIRECTORY_LOCAL_PART(기본 mail-directory) · 게이트웨이 MAIL_GATEWAY_USER 의 @ 앞(예 mail-gateway)이 mailcow 의 실제 주소와 겹치지 않는다 — 셋 다 새 서버의 로컬 주소(메일을 받지 않는 시스템 계정)라, 시범 사용자가 mailcow 의 같은 이름 주소로 보내면 새 서버가 not-found 로 거절한다.
기존 서버 IP(MAIL_PILOT_LEGACY_IPS)에 사람이 만든 자동 차단 예외(x:AllowedIp)가 없다 — setup 이 같은 주소로 시범 표시 항목을 만들어야 한다(같은 주소의 항목은 둘일 수 없다). 있으면 setup 이 멈춘다 — 지운 뒤 다시 실행한다.
시범 사용자의 mailcow 사서함은 그대로 둔다 — Transport Map 은 mailcow 에 있는 받는 사람에게만 먹고, 새 서버가 owner@ 명의로 동료에게 보낼 때도 mailcow 의 reject_unlisted_sender 를 이 사서함으로 통과한다.

시범 주소가 mailcow 에 없던 새 주소일 때 (실제 시범: sysadmin@arasystem.it.kr · 표시 이름 "시스템 관리자" — 직원 메일함이 아니라 관리용 새 주소로 시험한다): mailcow 에 같은 주소의 메일함을 먼저 만든다 — 받기만 하는 자리다. Transport Map 은 mailcow 에 있는 받는 사람에게만 먹어 이 주소 앞 메일을 새 서버로 넘기고, 새 서버가 이 주소로 동료에게 보낼 때 mailcow 의 reject_unlisted_sender 를 이 메일함으로 통과한다. 로그인은 처음부터 막아 둔다 — Active 를 "Disallow login (incoming mail is still accepted)", Allowed protocols 와 SOGo 접근을 모두 끄고 비밀번호는 무작위로(아래 9 를 미리 해 두는 것과 같다). 옛 메일이 없으니 imapsync(아래 5 · 7)는 건너뛰고, 되돌리기의 "mailcow 로 되복사"(되돌리기 3)는 시범 동안 새 서버에 온 · 보낸 메일뿐이다. 새 서버에서 이 주소는 보통 직원 계정(User 역할)이다 — 엔진 관리자(MAIL_ADMIN_LOCAL_PART)가 아니고 백엔드 차단 목록(MAIL_BLOCKED_ACCOUNTS)에도 넣지 않는다(넣으면 웹메일에 로그인하지 못한다). 아래 절차의 owner@ 를 이 주소로 읽는다.

env 와 실행 (새 서버)

.env.production 에 두 값을 적는다 — 셸이 아니라 파일에 (운영은 env 파일에 없는 시범 값이 셸에 있으면 setup 이 멈춘다):

MAIL_PILOT_LEGACY_HOST=mail.arasystem.it.kr   # host · host:port · [host] · [host]:port (포트 기본 25 — 운영은 25 만)
MAIL_PILOT_LEGACY_IPS=46.250.248.43           # mailcow 가 이 서버에 붙을 때의 공인 IPv4 · CIDR (콤마)

그리고 운영 배포 5) 와 같은 형태로(MAIL_ADMIN_URL · sudo 여부도 같게) setup 을 실행한다:

node --env-file=.env.production mail/scripts/setup.mjs

값	받는 꼴	운영에서 막는 것
`MAIL_PILOT_LEGACY_HOST`	`host` · `host:port` · `[host]` · `[host]:port` — 포트는 1~65535, 앞자리 0 없이(기본 25). IPv6 는 받지 않는다	25 가 아닌 포트 · `mailpit` · 점 없는 이름(도커 내부 이름으로 풀릴 수 있다) · 사설 · 특수 IPv4(문서 · 시험 대역 `192.0.2.0/24` · `198.51.100.0/24` · `203.0.113.0/24` · `198.18.0.0/15` · `192.0.0.0/24` 포함) · `MAIL_HOSTNAME`(모든 환경). 이름이 사설 · 특수 주소로 풀려도 멈춘다(실행할 때 메일 컨테이너 안에서 푼다)
`MAIL_PILOT_LEGACY_IPS`	IPv4 · CIDR(네트워크 주소로)을 콤마로	비어 있음(HOST 가 있으면 필수) · 사설 · 특수 대역(위와 같은 문서 · 시험 대역 포함) · `APP_NETWORK_SUBNET` 과 겹침 · `/24` 보다 넓음 · 이 서버 자신의 주소

기존 서버 주소가 IPv4(예: 46.250.248.43)면 발송 경로의 인증서 이름 확인을 끈다(allowInvalidCerts: true — 출력에 알린다). 이름(mail.arasystem.it.kr)이면 mailcow 의 공인 인증서로 확인한다 — 이름을 권한다.
개발은 셸에서 일회성으로 켜 본다(개발만 셸 값을 받는다) — 기존 서버 역은 Mailpit, 기존 서버 IP 는 비우면 백엔드 컨테이너 주소(개발의 시험 SMTP 가 나가는 곳 — 앱 네트워크 전체는 쓰지 않는다): MAIL_PILOT_LEGACY_HOST=mailpit:1025 node --env-file=.env.development mail/scripts/setup.mjs → 값 없이 다시 돌리면 바로 끈다.

setup 이 하는 일

먼저 확인한다 — 하나라도 어긋나면 아무것도 바꾸지 않고 멈춘다. 다만 RCPT 가드 없이 allowRelaying 이 열려 있으면 그것부터 닫는다([변경], 다시 읽어 확인) — 그다음 확인이 모두 맞으면 아래 차례(A → B → C)로 다시 켜고, 어긋나면 닫힌 채 멈춘다(머리글 "allowRelaying 만 닫고 중단합니다"). 닫지 못하면(저장이 거절되거나 · 엔진에 닿지 않거나 · 다시 읽어도 켜져 있으면) 다른 확인 · 설정(경로 · 전략 · C) 없이 멈추되(종료 1), 멈추기 전에 RCPT 가드만 다시 건다 — RCPT 단계 식이 setup 의 것이거나 비었을 때만 가드 갈래를 저장하고 시스템 Sieve 스크립트를 켠 뒤 리로드하고 가드를 확인한다(2026-10-30 3차 리뷰 R1). 멈춤 글이 그 결과를 싣는다 — "대신 RCPT 가드를 다시 걸어 지금은 가드가 답합니다(550 · Nms). relay 는 여전히 켜져 있습니다" 또는 "RCPT 가드도 다시 걸지 못했습니다 — 지금 가드 없이 열려 있습니다" (운영자의 식이면 건드리지 않고 그렇다고 적는다). 어느 쪽이든 관리 화면에서 그 도메인의 relay 허용(allowRelaying)을 끈 뒤 다시 실행한다(N1). 멈출 때는 그 전에 쌓인 확인 실패도 함께 찍는다.

확인	까닭
`x:MtaStageRcpt` 의 `waitOnFail` 이 고정 값이고 4초 이상(기본 5초) · (`allowRelaying` 이 이미 켜져 있으면) 인증 없는 세션의 새 서버에 없는 사내 주소 RCPT 가 2초 안에 550 이다	가드(Sieve)의 거절은 곧바로(개발 0.2~~1.1ms), 엔진 자체의 없는 주소 거절은 `waitOnFail` 뒤(개발 4,999~~5,003ms)다 — 응답 시간으로 둘을 가른다. 가드가 답하지 않으면 relay 를 먼저 닫는다. `waitOnFail` 이 바뀌어 있어도 확인은 보낸다 — 250 이면(시간과 상관없이 가드가 없다) 닫고, 550 이면 relay 를 그대로 두고 `waitOnFail` 문제로 멈춘다(N3)
도메인에 catch-all 이 없다	catch-all 은 `allowRelaying` 보다 먼저라 동료 앞 메일이 catch-all 함으로 간다
하위 주소(`subAddressing`)가 기본(`Enabled` — `+`), 바깥 디렉터리(`directoryId`)가 없다	RCPT 가드가 `+` 를 가정한다 · 엔진의 계정만 로컬로 본다
기존 서버 주소가 엔진의 서버 이름(`x:SystemSettings` 의 `defaultHostname` · `MAIL_HOSTNAME`)과 다르고, 메일 컨테이너 안에서 풀어도 엔진 자신(메일 컨테이너 주소 · 이 호스트의 IPv4 · 서버 이름의 주소 · 루프백)이 아니며, 기존 서버의 인사(220)가 엔진의 서버 이름이 아니다 · (운영) 이름이 사설 · 특수 주소로 풀리지 않는다	자기 자신으로 보내면 메일이 돈다 — 인사 이름으로 보는 것은 DNS · NAT 와 상관없이 잡힌다
메일 컨테이너 안에서 `curl -X NOOP smtp://<기존 서버>:<포트>/<서버 이름>` 이 220 · 250 — 운영은 `--ssl-reqd`(STARTTLS 와 인증서까지, IPv4 주소면 인증서는 보지 않는다)	닿지 않으면 동료 앞 메일이 새 서버 대기열에 쌓인다. 메일은 보내지 않는다. 이미 켜진 시범의 같은 기존 서버가 잠깐 닿지 않거나 이름이 풀리지 않으면 `[주의]` 만 하고 이어 간다(다른 정비를 막지 않는다) — 기존 서버를 바꾸는 실행이면 멈춘다
발송 경로 이름 `legacy` · RCPT 단계 스크립트 · 운영의 발송 전략("사내 도메인은 로컬, 나머지는 경로 하나" 꼴)을 다른 설정이 쓰지 않는다	setup 은 남의 설정을 덮어쓰지 않는다 — 외부 릴레이(SES 등)를 쓰고 있으면 그 경로가 바깥 발송으로 남는다
기존 서버 IP 에 메일 컨테이너 주소가 없다 · (운영) 이 서버 자신의 주소가 없다 · (운영) 기존 서버 이름의 주소가 목록에 있는지(없으면 `[주의]`)	위조 막기를 메일 컨테이너에서 확인한다
기존 서버 IP 에 사람이 만든 자동 차단 예외(`x:AllowedIp`)가 없다	setup 의 시범 표시 항목이 그 주소를 써야 한다(아래 "주인 표시") — 지운 뒤 다시 실행하면 setup 이 같은 주소로 만든다
기존 서버 IP 로만 된 시범 꼴의 갈래(위조 막기 · 검사 예외 · "Sender IP throttle")가 표시 없이 있지 않다 · 한 칸에 setup 꼴의 갈래가 둘 이상이 아니다	같은 원칙(N4) — 운영자가 넣은 같은 IP 의 갈래는 표시를 만든 다음 실행부터 setup 의 갈래와 가를 수 없어 합쳐지고, 시범을 끝낼 때 함께 지워진다. 그 갈래를 지운 뒤(IP 한도는 엔진 기본 — 모든 IP — 으로) 다시 실행한다. 켜진 시범에서 setup 의 시범 표시(자동 차단 예외)만 지워진 것이면 setup 의 갈래도 이렇게 보인다 — 그때는 같은 설명으로 표시를 다시 만들어도 된다. 둘 이상이면 하나만 남기고 지운다. 다른 IP 의 같은 꼴 갈래는 막지 않고 건드리지도 않는다
(운영) 활성 DKIM selector 의 TXT 가 DNS 에 있고 공개 키가 엔진의 키와 같다 — 이 호스트의 리졸버로 읽는다	다르면 mailcow 가 owner 의 메일을 위조로 거절한다(`R_DKIM_REJECT` → `SPOOFED_UNAUTH` — 아래 mailcow 절차 4). 없으면 DMARC 가 SPF 정렬에만 기대게 되어(`R_DKIM_PERMFAIL` 은 0점), 반송(빈 봉투 — SPF 는 HELO 이름으로 본다)이나 SPF 가 빗나간 메일이 거절된다. 처음 켤 때 다르거나 TXT 가 확실히 없으면(ENOTFOUND · ENODATA) 멈춘다 — relay 를 켜지 않는다, TXT 를 넣고 퍼진 뒤 다시(N8). 이미 켜져 있으면 실패로 보고만(닫지 않는다). 리졸버 오류 · 엔진이 공개 키를 주지 않으면 `[주의]`(견줄 수 없음 — 운영에서는 아직 돌려 보지 않았다)

그다음 순서대로 맞춘다 — 막는 것부터:

차례	엔진 설정	값
A	`x:AllowedIp`	기존 서버 IP — 설명 `[setup.mjs] 시범 공존 — 기존 서버(mailcow) 중계 IP` (→ `ReloadBlockedIps`). 시범 설정의 주인 표시라 A 의 맨 앞에서 만든다 — 그 뒤 어디서 멈춰도 다음 실행이 setup 의 갈래 · 한도 예외를 알아본다(N5). 바뀐 IP 의 옛 항목은 식을 모두 고친 뒤에 지운다
A	`x:MtaStageRcpt` 의 `script`	시스템 계정 갈래 + RCPT 가드 — 인증 없는 세션의 새 서버에 없는 사내 주소(+태그 꼴 포함)는 시스템 계정과 같은 스크립트로 `550 5.1.2`
A	`x:MtaInboundThrottle` "Sender address to recipient throttle"	인증 없는 세션 중 기존 서버 IP 가 아닌 것만 센다
A	`x:MtaStageMail` 의 `isSenderAllowed`	맨 앞 갈래 — 인증 없는 세션의 사내 도메인 MAIL FROM 이 기존 서버 IP 가 아니면 false → `550 5.7.1`
A	`x:SenderAuth` 의 `spfEhloVerify` · `spfFromVerify` · `reverseIpVerify` · `dmarcVerify`	맨 앞 갈래 — 기존 서버 IP 면 `disable` (나머지 갈래는 그대로)
A	`x:MtaInboundThrottle` "Sender IP throttle"	기존 서버 IP 를 세지 않는다(찾지 못하거나 엔진 기본 · setup 의 값이 아니면 `[주의]`)
	`ReloadSettings`	A 가 걸린다
	켜기 전 확인	인증 없는 세션의 새 서버에 없는 사내 주소 RCPT 가 2초 안에 550 — relay 가 꺼져 있어도 같은 판별이다(RCPT 단계 Sieve 는 받는 사람 해석보다 먼저 돈다 · 개발 실측 0.3~0.7ms). 아니면 B · C 없이 종료 1(N2)
B	`x:MtaRoute` Relay `legacy`	`<HOST>:<포트>`, STARTTLS 가 있으면 쓴다 — 설명 `시범 공존 — … [setup.mjs]`
B	`x:MtaOutboundStrategy` 의 `route`	0 새 서버의 주소 → 로컬 · 1 그 밖의 사내 주소 + `source` 가 `authenticated` · `autogenerated` · `dsn` · `report` → `legacy` · 2 그 밖의 사내 주소 → 로컬 · 나머지 → 시범 앞의 값(운영 `mx`, 개발 `mailpit`)
	`ReloadSettings`	B 가 걸린다
C	`x:Domain` 의 `allowRelaying`	`true` — 저장 즉시 먹는다(리로드가 필요 없다). 그래서 A · B 가 걸리고 가드를 확인한 뒤에 둔다

갈래 1 의 source 는 허용 목록이다(2026-10-30 리뷰 L1). 0.16.27 의 값은 authenticated(웹메일 · SMTP 인증 제출) · unauthenticated · dmarc_pass(인증 없는 수신) · dsn(반송) · report(보고) · autogenerated(필터 전달 · 부재중 등 Sieve) · unknown(표시가 없는 대기열 메일)이다(소스 smtp/src/queue/mod.rs). 빠진 셋은 legacy 로 가지 않는다 — 인증 없는 수신은 RCPT 가드가 먼저 막고, unknown 은 0.16.27 이 새로 만드는 메일에는 붙지 않는다(옛 판에서 남은 대기열 메일뿐). 엔진 마이너를 올리면 이 목록을 다시 본다.
주인 표시 — 식(위조 막기 · 검사 예외 · "Sender IP throttle")에는 설명 칸이 없어, setup 은 시범 표시가 있는 자동 차단 예외의 주소와 같은 IP 의 갈래만 자기 것으로 본다. 표시가 없으면 같은 꼴이어도 운영자 것으로 보고 켤 때도 끌 때도 건드리지 않는다(시범 설정이 있을 때만 [주의] 로 알린다). 뺄 때는 맨 앞만이 아니라 모든 갈래에서 찾는다. 기존 서버 IP 로만 된 운영자 갈래는 켜기 전에 멈추고(위 확인 표), 한 칸에 setup 꼴의 갈래가 둘 이상이면(setup 은 하나만 넣는다 — 나머지는 운영자가 같은 글로 넣은 것) 켤 때는 멈추고 끌 때는 맨 앞 하나만 빼고 나머지를 남긴다([주의]) — 켤 때도 끌 때도 운영자 갈래를 합치거나 지우지 않는다(N4).
받는 사람 한도("Sender address to recipient throttle")는 표시로 가리지 않는다 — 8단계부터 setup 이 match 를 통째로 정하는 칸이라, 켤 때는 기존 서버 IP 를 뺀 식으로, 끌 때는 "인증 없는 세션에만"으로 되돌린다. 표시를 보는 것은 끄는 실행이 relay 가 켜져 있어 시범 설정을 남길 때 그 예외가 setup 의 것인지 가르는 데뿐이다(N5).

확인 — 메일 컨테이너 안에서 자기 네트워크 주소의 25 로, RCPT 까지만 (메일은 보내지 않는다):

켜기 전(A 의 리로드 뒤 · B 앞): 인증 없는 세션 RCPT TO:<setup-check-<난수>@도메인> → 550 이고 2초 안 (RCPT 가드, 보낸 사람은 빈 봉투). 아니면 relay 를 켜지 않고 종료 코드 1(2차 리뷰 N2). 이미 켜진 시범이면 relay 가 켜진 채로 보고, 가드가 답하지 않으면 곧바로 끈다.
켠 뒤(C 바로 뒤): 같은 확인. 아니면 allowRelaying 을 곧바로 다시 끄고(다시 읽어 확인) 종료 코드 1 — 가드 · 경로는 남겨 두어 원인을 고친 뒤 같은 명령으로 다시 켠다(2026-10-30 리뷰 M1). 끄지 못하면 "끄려 했지만 끄지 못했습니다 — 지금 가드 없이 열려 있을 수 있습니다"로 알린다(N1).
인증 없는 세션 MAIL FROM:<setup-check-<난수>@도메인> → 550 5.7.1 (메일 컨테이너는 기존 서버 IP 가 아니다)
[개발] 인증한 세션(465, 테스트 직원) RCPT TO:<setup-check-…@도메인> → 250 뒤 RSET — 운영은 직원 비밀번호가 없어 하지 않는다(아래 mailcow 절차 4 의 실제 발송으로 본다). 비밀번호는 docker exec 의 환경변수가 아니라 표준 입력으로 넘긴다

다시 돌리면 전부 [유지], 값이 바뀌면 그 칸만 [변경] 이다. 끌 때는 거꾸로 — allowRelaying 을 먼저 끄고(저장 즉시) 엔진에서 다시 읽어 꺼진 것을 확인한 뒤에만 발송 전략 → RCPT 가드 · 위조 막기 · 검사 예외 · 한도 예외 · 자동 차단 예외 → 리로드 → legacy 경로(발송 전략을 되돌린 리로드 뒤 — 걸려 있는 전략이 지워진 경로를 고르는 틈이 없게, L5). 운영은 값을 비우는 것만으로는 끄지 않는다 — env 파일에서 값이 빠진 채 돌리면 "값을 다시 넣거나 --end-pilot" 으로 멈춘다(아무것도 바꾸지 않는다). 개발은 바로 끈다. allowRelaying 은 켜져 있는데 setup 의 legacy 경로가 없으면(관리 화면에서 경로만 지웠을 수도 있다) 누가 켠 것인지 알 수 없어 끄지 않고 실패로 보고하며, 그동안 RCPT 가드 · 위조 막기 · 예외 · 발송 전략도 남긴다(가드 없는 relay 를 setup 이 만들지 않는다). allowRelaying 을 끈 뒤 다시 돌리면 그때 뺀다. 다른 도메인이 allowRelaying 을 켜 두었으면 setup 은 그 도메인을 끄지 않고 시범 설정을 남긴다(RCPT 가드는 모든 사내 도메인을 덮는다) — "다른 도메인 … 이 켜 두어"로 알린다. 시범 설정이 하나도 없는데 allowRelaying 만 켜져 있으면 바꾸지 않고 실패로 알린다(요약 시범 설정 없음 · allowRelaying 켜짐 — 가드 없이 열린 relay 다).

개발 확인 (2026-10-29, 0.16.27 — 기존 서버 역 Mailpit, 기존 서버 IP 역 백엔드 컨테이너):

처음 실행은 A · B · C 가 [생성] · [변경], 다시 돌리면 전부 [유지] · 종료 코드 0. 기존 서버 IP 를 둘로 늘렸다 줄이면 그 칸만 [변경] · [삭제](여러 IP 의 식도 엔진이 받았다).
웹메일 → 새 서버에 없는 사내 주소는 legacy 경로로 한 번 배달(엔진 로그 delivery.delivered … hostname = "<legacy 주소>", Mailpit 의 id 가 같다), 있는 계정은 로컬, 바깥 주소는 개발 외부 경로로, 시스템 계정은 여전히 not-found.
인증 없는 25 의 없는 사내 주소(+태그 포함) 550 · 있는 계정(+태그 · 대문자 포함) 250, 메일 컨테이너의 사내 도메인 MAIL FROM 550 5.7.1, 기존 서버 IP 의 사내 도메인 MAIL FROM 은 받아서 배달(Authentication-Results: … none).
기존 서버 IP 가 새 서버에 없는 주소를 되돌려 보내면 RCPT 550 — Mailpit 에 되돌아 배달된 것이 없고 대기열이 빈다.
기존 서버 주소가 엔진 자신(mail:25) · MAIL_HOSTNAME · 닿지 않는 주소면 아무것도 바꾸지 않고 멈췄다. 값 없이 다시 돌리면 엔진 설정이 시범 앞과 같아졌다(스냅숏 비교) — 웹메일의 없는 사내 주소는 다시 not-found.

개발 확인 (2026-10-30 리뷰 수정 뒤, 기존 서버 역 arasystem-mailpit:1025 — 엔진 로그의 hostname 으로 개발 외부 경로 mailpit 과 가른다):

허용 목록 경로 — 465 인증 제출(queue.authenticated-message-queued) · doyun 의 필터 전달 · 부재중 응답(queue.autogenerated-queued)이 새 서버에 없는 사내 주소로 legacy 에 한 번씩. 부재중은 개발의 .test 도메인 탓에 스팸 점수가 높아(7.5) 시험 동안만 기존 서버 IP 를 스팸 필터에서 빼고 되돌렸다. RCPT 가드 갈래만 잠시 뺀 엔진에서 기존 서버 IP 가 보낸 인증 없는 메일은 legacy 로 가지 않고 로컬 실패(delivery.dsn-perm-fail) → 그 반송은 동료(새 서버에 없는 사내 주소) 앞이라 legacy 로 한 통.
닫힌 쪽(M1) — 위처럼 가드 갈래가 빠진 채 relay 가 열린 엔진 · 시스템 Sieve 스크립트를 끈 엔진(가드 식은 있지만 RCPT 가 250)에서 시범 값으로 돌리자, setup 이 먼저 allowRelaying 을 끄고([변경] … RCPT 가드 없이 allowRelaying 이 켜져 있어 … · … RCPT 가드가 답하지 않아(… 250 2.1.5 OK) …) 가드 · 스크립트를 되살린 뒤 C 로 다시 켰다 — 켠 뒤 확인 1ms 안팎, 종료 코드 0.
이미 켜진 시범(L2) — 기존 서버 역을 멈춘(docker pause) 채 같은 값으로 돌리면 [주의] … 닿지 않습니다 … 이미 켜진 시범이라 이어 간다 · 종료 코드 0. 다른 기존 서버(닿지 않는 포트)로 바꾸는 실행은 멈췄고 엔진 스냅숏이 그대로였다.
H1 — 시범이 켜진 엔진에서 legacy 경로만 지우고 값 없이 돌리면 [유지] … allowRelaying 이 켜져 있어 끝내지 않는다 · 가드 그대로(RCPT 550) · 종료 코드 1. allowRelaying 을 손으로 끈 뒤 다시 돌리자 나머지를 뺐고, 끝난 엔진 스냅숏이 시험 전과 같았다.
켬 → 같은 값으로 다시(전부 [유지]) → 값 없이(끄기 — [삭제] … legacy 가 리로드 뒤) → 다시 값 없이(전부 [유지]) 뒤 엔진 스냅숏이 시험 전과 같았다.

개발 확인 (2026-10-30 2차 리뷰 수정 뒤):

켜기 전 확인(N2) — 처음 켤 때 [생성] 자동 차단 예외(표시)가 A 의 맨 앞에 나오고, A 의 리로드 뒤 relay 가 꺼진 채 [확인] … 켜기 전 확인(allowRelaying 꺼짐): … 곧바로 거절 (… 0.4ms) 다음에 C. 시범이 켜진 엔진에서 relay 만 잠시 끄고 잰 RCPT 5번 0.3~~0.7ms(켠 채로는 0.4~~0.7ms) — relay 와 상관없이 가드의 빠른 550 이다.
다시 읽기(N1) — x:Domain/set(allowRelaying false · true) 바로 뒤 x:Domain/get 100번 모두 저장한 값과 같았다.
waitOnFail 을 바꾼 엔진(N3) — waitOnFail 1s + 가드가 먹는 엔진: [주의] RCPT 가드가 550 으로 답합니다 … 뒤 relay 를 그대로 두고 waitOnFail 문제로 멈춤(종료 1, "켜진 채로 두었습니다"). 거기서 시스템 Sieve 를 끄면 확인이 250 → [변경] … 껐다 · "allowRelaying 만 닫고 중단합니다"(종료 1). waitOnFail 을 되돌리고 다시 돌리자 Sieve 를 되살리고 다시 켰다(종료 0).
운영자 갈래(N4) — 켜기 전 엔진의 spfFromVerify 에 기존 서버 IP 갈래를 손으로 넣자 사전 확인에서 멈췄고(종료 1) 엔진이 그대로였다. 켜진 엔진의 dmarcVerify 에 setup 과 같은 글의 갈래를 하나 더 넣자 "둘 이상"으로 멈췄고(종료 1) 바뀐 것이 없었다.
켬 → 같은 값으로 다시(바뀐 줄 없음) → 값 없이(끄기) → 다시 값 없이 뒤, 그리고 위 시험들을 되돌린 뒤 엔진 스냅숏이 시험 전과 같았다.

mailcow 쪽 절차 (mailcow 호스트 `/opt/mailcow-dockerized` — 아직 해 보지 않았다)

mailcow 2026-10(master) 의 설정 파일 · 화면 · 문서로 정리했다. 운영 중인 mailcow 가 더 오래됐으면 화면 이름이 다를 수 있다 — 0 의 명령으로 먼저 대조한다.

cd /opt/mailcow-dockerized
alias dcx='docker compose exec postfix-mailcow'

SSH 가 없을 때 (mailcow 관리 화면만) — 운영 mailcow 에는 관리 화면만 쓸 수 있다. 아래 절차의 명령은 SSH 가 있을 때의 길이고, 화면으로는 이렇게 한다:

절차	화면으로
0 읽기 점검(명령)	SSH 가 있을 때만 한다 — 없으면 건너뛰고 4 · 6 의 시험 메일과 화면의 로그로 대신 본다. 도메인(백업 MX · "Relay all recipients" 가 꺼져 있는지)과 Synchronizations 는 화면으로 본다
1 postscreen 허용 목록	파일이라 화면으로는 할 수 없다 — 대신 새 서버 IP(`<MX1_IP>`)가 차단 목록에 없는지 본다: Spamhaus IP 조회 · MXToolbox Blacklist Check. PTR(mx1)이 있고 목록에 없으면 보통 postscreen 을 통과한다
2 Fail2ban 예외	그대로 화면 — System → Configuration → Options → Fail2ban parameters
4 · 6 의 로그(`docker compose logs postfix-mailcow` · `rspamd-mailcow`)	System → Information → Logs 의 Postfix · Rspamd (판에 따라 메뉴 이름이 다를 수 있다)
6 `postmap -q` · `postfix reload`	하지 않는다 — Transport Map 은 저장하면 1분 안에 먹는다(reload 없이). 목록의 Test 버튼과 실제 시험 메일로 본다
10 · 되돌리기 2 의 대기열(`postqueue`)	E-Mail → Queue Manager — 대기열을 보고 Flush queue 로 다시 보낸다
되돌리기 1 의 `postfix reload` · `postmap -q`	하지 않는다 — Deactivate 뒤 1분 기다린 다음 시험 메일이 mailcow 사서함에 오는지 본다

읽기만 하는 점검 (SSH 가 있을 때 — 없으면 위 표) — 로컬로 새는 길이 없는지:

grep -n -A3 '^transport_maps' data/conf/postfix/main.cf   # custom_transport.pcre, local_transport, mysql_relay_ne.cf, mysql_transport_maps.cf 차례
dcx postconf -P 'smtpd/pass/smtpd_sender_restrictions'   # permit_mynetworks,reject_unlisted_sender,reject_unknown_sender_domain
dcx cat /opt/postfix/conf/custom_transport.pcre          # 비어 있거나 owner@ · 도메인과 무관해야
dcx postmap -q owner@arasystem.it.kr mysql:/opt/postfix/conf/sql/mysql_virtual_mailbox_maps.cf   # 사서함이 받는 사람으로 살아 있다
docker compose exec acme-mailcow dig +short A    mx1.arasystem.it.kr @172.22.1.254   # <MX1_IP>
docker compose exec acme-mailcow dig +short AAAA mx1.arasystem.it.kr @172.22.1.254   # 비어 있어야

도메인이 백업 MX · "Relay all recipients" 가 아닌지, owner 앞 Sync job 이 없는지(E-Mail → Configuration → Synchronizations)도 본다.

postscreen 예외 — data/conf/postfix/custom_postscreen_whitelist.cidr 에 <MX1_IP>/32 permit (재시작 없이 다시 읽는다). 새 IP 가 차단 목록 하나에만 있어도 postscreen 에서 끊길 수 있다. Forwarding Hosts 에는 넣지 않는다 — 넣으면 그 IP 의 메일은 스팸 검사 · 위조 판정 없이 들어온다.
Fail2ban 예외 — System → Configuration → Options → Fail2ban parameters → "Allowlisted networks/hosts" 에 <MX1_IP> (imapsync 로그인 실패가 쌓여 mx1 IP 가 막히면 SMTP 도 끊긴다).
새 서버 setup — 위 "env 와 실행". 이때부터 새 서버의 owner@ 가 동료에게 보낼 수 있다(mailcow 는 아직 owner 앞 메일을 자기 사서함에 넣는다).
반대 방향부터 시험 — 새 서버의 owner@(웹메일)로 동료에게 한 통. 실사용자에게 영향이 없는 방향이라 먼저 한다:
```
docker compose logs --since 15m postfix-mailcow | grep -E 'from=<owner@arasystem\.it\.kr>|\[<MX1_IP>\]'
#   좋음: client=mx1.arasystem.it.kr[<MX1_IP>] … 다음 줄에 relay=dovecot[…]:24 status=sent
#   나쁨: NOQUEUE: reject … Sender address rejected (mailcow 에 없는 봉투 발신자) · milter-reject … 5.7.1 (rspamd 거절)
docker compose logs --since 15m rspamd-mailcow | grep -E 'SPOOFED_UNAUTH|R_SPF_FAIL|R_DKIM_REJECT|DMARC_POLICY_SOFTFAIL'   # 없어야
```
동료가 받은 메일 머리글이 Authentication-Results … spf=pass dkim=pass (header.s=v1-…) dmarc=pass 이고 X-Spamd-Result 에 SPOOFED_UNAUTH 가 없어야 한다. SPF · DKIM · DMARC 가운데 하나라도 실패하면 mailcow 가 위조로 보고(+50점) 거절한다 — DMARC 가 p=none 이어도 막아 주지 않는다. DKIM 은 키가 있는데 서명이 맞지 않을 때(R_DKIM_REJECT)다 — selector 의 키를 찾지 못하는 것(R_DKIM_PERMFAIL)은 0점이라 SPF 정렬로 DMARC 가 통과하면 받는다. 없는 주소(colleaguee@)로 보내면 mailcow 가 550 → 새 서버가 owner 에게 반송한다(루프 없음).
imapsync 1차 — mailcow → 새 서버, owner 만 (imapsync).

Transport Map 추가 — System → Configuration → Routing → Transport Maps → "Add transport":

칸	값
Destination	`owner@arasystem.it.kr` (`owner+태그@` 도 맞는다)
Next hop	`[mx1.arasystem.it.kr]:25` — 대괄호는 MX 조회를 끈다. 앞에 `smtp:` 를 쓰지 않는다(mailcow 가 붙인다)
Username / Password	비움
"Destination is a regular expression to match against MX name"	끔
Active	켬

목록의 Test 버튼(보내는 주소 colleague@arasystem.it.kr, 받는 주소 owner@arasystem.it.kr — PHP 가 next hop 에 직접 시험 메일을 보낸다)으로 새 서버가 mailcow IP 의 사내 도메인 메일을 받는지 본다. 그다음:

dcx postmap -q owner@arasystem.it.kr     mysql:/opt/postfix/conf/sql/mysql_transport_maps.cf   # smtp_via_transport_maps:[mx1.arasystem.it.kr]:25
dcx postmap -q colleague@arasystem.it.kr mysql:/opt/postfix/conf/sql/mysql_transport_maps.cf   # (출력 없음)
dcx postfix reload                                                                              # 바로 반영 (안 해도 30초~1분)
# 실제 발송 — 바깥(Gmail) · SOGo 동료 · owner 가 든 별칭 · owner+test@ 에서 각 한 통
docker compose logs --since 15m postfix-mailcow | grep -E 'to=<owner(\+[^@]*)?@arasystem\.it\.kr>'   # relay=mx1.arasystem.it.kr[<MX1_IP>]:25 … status=sent

마지막 imapsync(차이분).
owner 의 메일 프로그램을 mx1 로 — IMAP mx1.arasystem.it.kr:993 · SMTP :465, 손으로 설정한다(autodiscover 는 mailcow 를 가리킨다). 휴대폰 ActiveSync 등 옛 프로필은 지운다.
mailcow 의 옛 사서함 접근 줄이기 — 사서함 편집의 Allowed protocols(IMAP · POP3 · SMTP · Sieve · ActiveSync · CalDAV/CardDAV)와 SOGo 접근을 줄이고 앱 비밀번호를 지운 뒤, 마지막 동기화가 끝나면 Active 를 "Disallow login (incoming mail is still accepted)" 로. 지우거나 "Inactive" 로 두지 않는다 — 그러면 owner 앞 메일이 모두 550 이고, 새 서버에서 owner 가 동료에게 보내는 메일도 reject_unlisted_sender 로 거절된다.
며칠 본다 — mailcow Queue Manager(E-Mail → Queue Manager), rspamd 기록, 반송, DMARC 보고서.

지켜볼 것

새 서버에서 owner 가 받은 메일의 X-Spam-Score · X-Spam-Result 를 세 통 본다 — 바깥(Gmail) 한 통, 동료(SOGo) 한 통, DMARC 가 엄격한(p=reject) 바깥 도메인 한 통. mailcow 를 거친 메일은 SPF · DMARC 결과가 없고(Authentication-Results: … none) DMARC_NA · AUTH_NA 가 각 1점 붙는다. 스팸 문턱은 5점이다.

개발에서는 점수가 늘 높다 — 기존 서버 IP 로 넘긴 동료 흉내 메일이 7.5점(.test 도메인 탓 FROM_INVALID · ENV_FROM_INVALID 각 2점, 시험 글의 제목 인코딩 1점). 운영 값으로 판단한다. 조사 때 p=reject 바깥 발신(서명 없음)을 넘기자 이 설정으로 3.5점(받은편지함), 검사 예외가 없을 때는 11.0점(스팸함)이었다.
mailcow 가 8~15점에 붙이는 X-Spam-Flag: YES 는 새 서버 규칙(SPAM_FLAG +5)이 받아 스팸함으로 간다. owner 의 mailcow Sieve · 부재중 · 전달 규칙은 더 돌지 않는다 — 새 서버에 다시 만든다.
동료가 받은 owner 의 메일 — X-Spamd-Result 에 SPOOFED_UNAUTH · R_DKIM_REJECT 가 없어야 한다(위 4).
운영 결과(2026-10-31): 새 서버 → 동료는 spf · dkim(두 selector) · dmarc pass · mailcow 점수 −2.95, Gmail → mailcow → 새 서버는 0.80(ham), 새 서버 → Gmail 은 spf · dkim(RSA) · dmarc pass. Gmail 의 dkim=neutral (no key)(ed25519 selector)는 정상이다 — Gmail 은 ed25519 를 검증하지 않고 RSA 서명이 대신한다.
새 서버 → mailcow 의 첫 전달은 451 timeout processing message(mailcow rspamd)로 두어 번 미뤄질 수 있다 — 처음 보는 IP · 도메인 · DKIM 키를 조회하느라 늦은 것으로 보이고, 새 서버가 2분 · 5분 뒤 다시 보내 전달됐다(반송 없음 — 451 은 일시 오류). 계속되면 mailcow 의 Rspamd 로그를 본다.

되돌리기 (시범을 멈추고 mailcow 로)

mailcow — Transport Maps 의 owner@ 행 → Quick actions → Deactivate(행을 남긴다) → dcx postfix reload. 30초~1분 안에 다시 mailcow 사서함으로 배달된다. dcx postmap -q owner@arasystem.it.kr mysql:/opt/postfix/conf/sql/mysql_transport_maps.cf 가 비어야 한다.
큐에 남은 owner 앞 메일 — dcx postqueue -p 로 보고 dcx postqueue -f (다시 경로를 받아 로컬로).
시범 동안 새 서버로 들어온 메일 · 보낸 메일을 mailcow 로 되복사 — 반대 방향 imapsync(새 서버 → mailcow) 또는 mailcow 의 Synchronizations 에 mx1 IMAP 을 원본으로.
owner 의 mailcow 접근 되살리기 — Active 를 Active 로, Allowed protocols · SOGo · 앱 비밀번호, 메일 프로그램을 mailcow 로.
새 서버 대기열에 동료 앞 메일이 남지 않았는지 본다 — 관리 화면의 메일 대기열(Queue) 또는 관리 API x:QueuedMessage/query · /get. 시범을 끄면 발송 전략이 "사내 도메인 → 로컬"로 돌아가, 아직 mailcow 로 못 간 동료 앞 메일(mailcow 일시 장애 · 지연 — 다시 시도는 3일, 동료 앞 반송은 10번까지)은 다음 시도에서 로컬 배달 실패 → owner 에게 반송된다. 남아 있으면 mailcow 가 받을 수 있게 된 뒤 다 나갈 때까지 기다리거나(대기열에서 바로 다시 시도), 기다릴 수 없으면 그 목록(받는 사람 · 제목)을 적어 두고 끈 뒤 owner 가 mailcow 에서 다시 보낸다.
새 서버 — Transport Map 을 끈 뒤에 시범을 끝낸다: 두 값을 비우고 --end-pilot(아래). 거꾸로 하면 그사이 owner 가 동료에게 보낸 메일이 not-found 로 거절된다.
넣었던 것 정리 — postscreen 예외 줄, Fail2ban 예외. DNS 의 ip4:<MX1_IP> · 새 DKIM TXT 는 남겨도 해가 없다.

시범 끝내기 — 전면 전환

전환 절차대로 모두의 계정을 새 서버에 만들고(단계 2) MX 를 mx1 로 바꾼다(단계 6). 그 뒤:

MX 전파(TTL)가 끝나 mailcow 에 새 수신이 없어지면 mailcow 의 Transport Map 행을 지운다(Remove) — 그때까지 mailcow 로 온 owner 앞 메일은 그대로 새 서버로 넘어온다.
새 서버 — .env.production 의 두 값을 비우고 --end-pilot 으로 실행한다:
```
node --env-file=.env.production mail/scripts/setup.mjs --end-pilot
```
allowRelaying(꺼진 것을 다시 읽어 확인) → 발송 전략 → RCPT 가드 · 위조 막기 · 검사 예외 · 한도 예외 · 자동 차단 예외 차례로 지우고 리로드한 뒤 legacy 경로를 지운다. 다음 실행부터는 --end-pilot 없이 [유지] 시범 공존 — 꺼짐 이다.

계정을 만든 순간부터 그 주소 앞 사내 메일은 새 서버의 로컬 배달이다 — 계정 만들기 → imapsync → MX 바꾸기를 짧게 이어서 한다.
위조 막기(인증 없는 사내 도메인 MAIL FROM 은 mailcow IP 에서만)도 함께 빠진다. 전환 뒤에도 남길지는 정할 일이다(원래 봉투를 그대로 넘기는 바깥 전달 서비스가 막힌다).

주의

시범 기간에는 동료 계정을 새 서버에 만들지 않는다 — 새 서버에 있는 주소는 늘 로컬 배달이라, 만든 순간부터 owner 가 그 동료에게 보낸 메일이 새 서버에 쌓이고 mailcow 로 가지 않는다(동료는 mailcow 에서 읽는데). postmaster@ · dmarc@ · 공용 주소 · 별칭도 같다. 이주 기간에 미리 만들어야 하면 발송 전략을 "옮긴 사람 목록" 꼴로 바꿔야 한다 — setup 은 지원하지 않는다.
DKIM — 동료 앞 메일은 새 selector 두 개(v1-ed25519-… · v1-rsa-…)로 서명된다. 키가 다르면 mailcow 가 위조로 거절하고, TXT 가 없으면 DMARC 가 SPF 정렬에만 기대게 되어 반송(빈 봉투)이나 SPF 가 빗나간 메일이 거절된다(위 mailcow 절차 4). setup 이 활성 selector 를 알리고, 운영에서는 켜기 전에 DNS 와 견준다(처음 켤 때 키가 다르거나 TXT 가 확실히 없으면 allowRelaying 을 켜지 않고 멈춘다 — TXT 는 첫 시범 실행 전에 넣고 퍼진 것을 본다. 리졸버 오류는 [주의]). DNS 를 손으로 관리하는 동안 엔진은 키를 스스로 바꾸지 않는다 — 다만 키를 지우거나 알고리즘을 더하면 새 키를 DNS 에 넣기 전에 쓴다(전환 절차 "주의할 레코드" 의 DKIM 자동 교체).
SOGo 일정 초대 — mailcow 사용자가 SOGo 에서 owner 를 초대하면 메일을 거치지 않고 owner 의 옛 SOGo 달력에 바로 들어간다(알림 메일만 새 서버로 온다 — SOGo 버그 트래커의 관리자 답, 확인하지 않았다).
autodiscover — 그대로 mailcow 를 가리킨다. owner 의 프로그램이 자동 설정을 쓰면 mailcow(새 메일이 없는 옛 함)에 잡힌다 — 손으로 설정한다.
크기 — mailcow 와 새 서버 모두 메일 한 통 100MB(104,857,600바이트 — 새 서버는 엔진 기본값)다. 웹메일 첨부는 따로 MAIL_ATTACHMENT_* 한도다.
IPv6 · SPF — mx1 에 AAAA 를 두지 않는다. mailcow 가 IPv6 로 붙으면 IPv4 예외가 모두 빗나가 동료 메일이 550 5.7.1 이다(mailcow 는 inet_protocols = all). 새 서버 → mailcow 는 IPv4 로만 간다(컨테이너에 IPv6 가 없고 Relay 경로는 IPv4 먼저) — SPF 는 ip4: 만 더한다.
EHLO 이름 — 새 서버가 mailcow 에 붙을 때의 이름은 엔진의 서버 이름(defaultHostname = bootstrap 때의 MAIL_HOSTNAME = mx1)이다. mail.arasystem.it.kr 이면 mailcow 가 "loops back to myself" 로 멈춘다 — setup 은 기존 서버 주소가 서버 이름과 같으면 멈춘다.
사내 오타 주소 — 새 서버에 없는 사내 주소는 모두 "받음"이라, 웹메일의 즉시 not-found(받는 사람별 결과) 대신 mailcow 의 550 → 몇 초 뒤 반송(DSN)이 받은편지함에 온다. 제출 기록에도 남지 않는다(대기열에서 빠지면 250 2.1.5 Queued 로 돌아간다).
사내 목록 — 받는 사람 추천 · 주소록의 "사내"는 새 서버의 계정 목록이라 시범 사용자 혼자만 보인다. 동료는 개인 주소록 · 최근 보낸 사람으로만 나온다(시범 동안 백엔드는 바꾸지 않는다).
주소 추측 막기가 약하다 — RCPT 가드의 거절(Sieve)은 엔진 자체의 없는 주소 거절(5초 대기 · 세션당 실패 5번이면 끊기 · 자동 차단 셈)을 거치지 않는다(개발: RCPT 한 번에 가드 0.2~~1.1ms, 엔진 자체 거절 4,999~~5,003ms — setup 은 이 차이로 가드가 걸렸는지 본다). 시범 중 MX 는 mailcow 라 mx1:25 에 바로 붙는 것은 스캐너뿐이다. 시스템 계정 거절도 같은 성질이다.
mailcow 가 멈추면 — 동료 앞 메일은 새 서버 대기열(local 일정 — 3일)에서 다시 시도하다 반송되고, owner 앞 메일은 mailcow 큐(4시간 뒤 지연 안내, 5일 뒤 반송)에서 기다린다.
DMARC 보고 — 엔진은 자기 도메인(arasystem.it.kr) 메일로는 DMARC · DKIM 실패 보고를 만들지 않는다(소스 smtp/src/reporting/dmarc.rs 의 is_local_report_domain) — rua=dmarc@ 로 보고를 보내 mailcow 의 reject_unlisted_sender 에 걸리는 일은 없다. 다른 도메인에 대한 집계 보고(기본 하루 한 번)는 그 도메인의 rua 로 새 서버가 직접 보낸다(봉투 noreply-dmarc@arasystem.it.kr). mailcow IP 의 DMARC 검사를 끄므로 mailcow 를 거친 메일로는 보고 거리가 생기지 않는다.
mailcow 의 공용 주소 · 별칭(all@ 등)으로 보내면 mailcow 가 펼치고 owner 몫은 새 서버로 되돌아온다(자기 사본 — 확인하지 않았다).

arasystem.it.kr 전환 절차 (mailcow → Stalwart)

전면 전환 전에 한 사람이 먼저 새 서버를 쓴다 — 파일럿 공존(MX 는 mailcow 그대로, 아래 단계 1 · 3 · 4 의 DNS 만 더한다). 시범을 거친 뒤 아래 표대로 모두를 옮기고, MX 를 바꾼 다음 시범 설정을 끝낸다(--end-pilot).

현재 (DNS: 가비아):

레코드	값
`arasystem.it.kr` MX	`10 mail.arasystem.it.kr` (mailcow)
`arasystem.it.kr` TXT (SPF)	`v=spf1 mx ip4:46.250.248.43 -all`
`_dmarc.arasystem.it.kr` TXT	`v=DMARC1; p=none; rua=mailto:dmarc@arasystem.it.kr`
`dkim._domainkey.arasystem.it.kr` TXT	mailcow DKIM (selector `dkim`)

원칙:

메일박스를 먼저 만들고 MX 를 바꾼다. 거꾸로면 없는 주소로 들어온 메일이 반송(550)된다.
새 엔진은 새 호스트명(mx1.arasystem.it.kr) 으로 띄우고 MX 대상만 바꾼다. mail.arasystem.it.kr 은 끝까지 mailcow 를 가리키므로, MX 만 되돌리면 롤백된다.
SPF 가 -all 이다. 새 서버 IP 를 SPF 에 넣기 전에 새 서버에서 외부로 보내면 수신 측이 거부하거나 스팸 처리한다.

단계	할 일	확인
0. TTL 낮추기 (D-3 이상)	MX·SPF TXT·`mx1` A 의 TTL 을 300초로. 기존 TTL 만큼 기다린 뒤 다음 단계	`dig +noall +answer MX arasystem.it.kr` 의 TTL
1. 새 호스트	`mx1.arasystem.it.kr` A → 새 IP, PTR → `mx1.arasystem.it.kr`, `.env.production` 에 `MAIL_HOSTNAME`·`MAIL_PUBLIC_URL` = mx1, 운영 배포	컨테이너 로그에 인증서 발급, `openssl s_client -connect mx1.arasystem.it.kr:993`
2. 같은 주소 생성	모든 직원 주소·별칭·공용 주소 + `dmarc@`(현재 DMARC 리포트 수신처) + `postmaster@`(Stalwart 기본 리포트 수신처). 시범 공존 중이면 전면 전환 때 한다 — 만든 순간부터 그 주소 앞 사내 메일이 새 서버에 쌓인다(파일럿 공존 "주의")	관리 화면 계정 목록
3. DKIM selector 추가	setup 이 출력한 `v1-ed25519-YYYYMMDD._domainkey`·`v1-rsa-YYYYMMDD._domainkey` TXT 를 추가. mailcow 의 `dkim._domainkey` 는 그대로 둔다 (selector 가 달라 공존)	`dig TXT v1-rsa-YYYYMMDD._domainkey.arasystem.it.kr`
4. SPF 갱신	`v=spf1 mx ip4:46.250.248.43 ip4:<새 IP> -all` (+ 권장: `mx1.arasystem.it.kr TXT "v=spf1 a -all"`) — MX 변경·외부 발송 전에	새 서버에서 외부(본인 Gmail 등)로 1통 → 헤더의 `spf=pass dkim=pass`
5. 메일 이전 1차	`imapsync` 로 mailcow → Stalwart 전체 동기화 (아래)	폴더별 메일 수 비교
6. MX 전환	`arasystem.it.kr MX 10 mx1.arasystem.it.kr` 로 교체. mailcow 는 계속 켜 둔다 (전파 중에는 mailcow 로도 들어온다)	외부에서 보낸 메일이 새 엔진 로그에 수신
7. 증분 동기화	MX 전환 직후 · TTL 경과 후 · 정리 직전에 `imapsync` 를 다시 (이미 옮긴 메일은 건너뛴다)	mailcow 로그에 새 수신 없음
8. 병행 1~2주 후 정리	SPF 에서 `ip4:46.250.248.43` 제거, `dkim._domainkey` 삭제, mailcow 중지. 필요하면 `mail.arasystem.it.kr` 을 새 호스트로 옮기고(인증서 포함) `MAIL_PUBLIC_URL` 변경	—

롤백: MX 를 10 mail.arasystem.it.kr 로 되돌린다. 그 사이 새 엔진에 들어온 메일은 반대 방향 imapsync 로 옮긴다.

주의할 레코드:

DMARC — setup 이 출력하는 권장값은 p=reject; rua=mailto:postmaster@… 다. 전환 중에는 지금의 p=none·rua=dmarc@ 를 유지하고, 리포트로 두 서버 모두 통과하는 것을 본 뒤 quarantine → reject 로 올린다.
MTA-STS — 정책이 MX 와 어긋나면 MTA-STS 를 지키는 발신자가 배달에 실패한다. 전환이 끝난 뒤 게시한다.
SRV·autoconfig·autodiscover — 메일 클라이언트(IMAP) 자동 설정용. 웹메일만 쓰면 필요 없다.
DKIM 자동 교체 — 도메인 설정은 dkimManagement: Automatic(rotateAfter 90일 · retireAfter 7일 · deleteAfter 30일)이지만, 0.16.27 은 엔진이 DNS 를 직접 고칠 때(dnsManagement: Automatic + DKIM 게시)만 교체한다. DNS 를 손으로(가비아) 관리하는 지금 설정(dnsManagement: Manual)에서는 활성 키에 교체 일정이 생기지 않아(x:DkimSignature 의 nextTransitionAt 가 비어 있다) bootstrap 때 만든 두 키를 계속 쓴다 (소스 services/src/task_manager/dkim.rs — 일정은 DNS 게시가 있을 때만 잡는다, 엔진 시험 tests/src/automation/dkim.rs 의 "manual DNS" — 교체도 다시 시도도 하지 않는다. 개발 엔진의 두 키도 일정이 없다 — 2026-10-29).
- 주의 — 알고리즘에 활성 키가 없으면 엔진이 새 키를 만들어 DNS 에 게시하기 전에 곧바로 서명에 쓴다(DNS 수동일 때). 키를 지우거나, 알고리즘(algorithms)을 더하거나, dkimManagement 를 다른 값에서 Automatic 으로 바꿀 때가 그렇다 — 그런 일을 하면 새 selector 의 TXT 를 바로 넣는다.
- 자동 DNS(Automatic)라면 새 키를 먼저 게시하고 전파를 확인한 뒤에 쓴다(실패하면 pending 으로 두고 옛 키로 계속 서명).
- 키를 손으로 바꾸는 방법은 아직 확인하지 않았다 — 엔진은 활성(active) 키를 모두 서명에 쓴다. 교체가 필요해지면 개발 엔진에서 먼저 시험한다.

imapsync

imapsync \
  --host1 mail.arasystem.it.kr --ssl1 --user1 '<직원 주소><구분자><마스터 계정>' --password1 '<마스터 비밀번호>' \
  --host2 mx1.arasystem.it.kr  --ssl2 --user2 '<직원 주소>' --password2 '<새 엔진 초기 비밀번호>' \
  --automap --syncinternaldates

원본(mailcow)은 Dovecot 마스터 계정으로 직원 비밀번호 없이 읽는다. mailcow 의 마스터 계정 설정 방법과 로그인 형식(Dovecot 기본 구분자는 *)은 mailcow 문서를 확인해야 한다 (여기서는 검증하지 않았다).
대상(Stalwart)은 계정을 만들 때 정한 초기 비밀번호로 로그인한다. 게이트웨이 대리 접근(%)은 HTTP 에서만 검증했고 IMAP 에서는 확인하지 않았다. 게이트웨이는 신뢰 대역에서만 로그인되므로 외부에서 쓸 수도 없다.
직원 비밀번호는 정책 결정이 필요하다 — 새 초기 비밀번호를 배포하고 첫 로그인 때 바꾸게 하거나, mailcow 의 비밀번호 해시를 그대로 옮길 수 있는지 검토한다 (미검증).

백업

볼륨	내용
`<PROJECT_NAME>_mail-config`	`config.json` (작다). 없으면 bootstrap 모드로 뜬다
`<PROJECT_NAME>_mail-data`	RocksDB — 메일·계정·설정 전체
`<PROJECT_NAME>_files`	대용량 첨부 파일(11단계) — 백업하지 않는다(보낸 날부터 30일짜리 전송물 · 계약 4절). 기록(이름 · 크기 · 링크)은 DB 백업에 든다 — 복원한 뒤 바이트가 없는 파일은 받는 쪽에 "찾을 수 없음"이다. ⚠️ `docker compose down -v` 가 지운다
`<PROJECT_NAME>_clamav-db`	악성 검사 서명 — 백업하지 않는다. 지우면 `clamav-updater` 가 다시 받는다(1분 안팎)

RocksDB 는 실행 중 파일 복사로는 일관성이 보장되지 않으므로 잠시 멈추고 받는다. 멈춘 동안 외부 서버는 배달을 재시도(보통 수일)하므로 짧은 중지로 메일이 유실되지 않는다.

sudo docker compose --env-file .env.production stop mail
sudo docker run --rm -v "${PROJECT_NAME}_mail-config:/config:ro" -v "${PROJECT_NAME}_mail-data:/data:ro" -v "$PWD/backup:/backup" \
  alpine tar czf "/backup/mail-$(date +%Y%m%d-%H%M).tar.gz" -C / config data
sudo docker compose --env-file .env.production start mail

복원은 빈 볼륨에 같은 경로로 풀고(tar xzf … -C / , 소유자 UID 2000 유지) 컨테이너를 띄운다. 복원 연습을 주기적으로 한다.
백업 파일은 다른 장소에도 둔다. 메일 전체가 들어 있으므로 접근을 제한한다.

보안

게이트웨이 비밀번호 = 관리자급 비밀. 전 직원 메일함의 열쇠일 뿐 아니라, 관리자 계정도 대리 접근된다 — <관리자 주소>%<게이트웨이 주소> 로 로그인하면 관리 API(x:Account/get 등)가 열린다 (백엔드 확인, setup 이 매번 [주의] 로 보여 준다).
- Stalwart 0.16.27 에는 대리 접근 대상을 제한하는 방법이 없다 (2026-10-27 확인). 역할 권한(enabledPermissions)은 접속하는 쪽의 권한만 정하고, 테넌트로 나누면 테넌트에 든 게이트웨이는 impersonate 권한 자체를 잃는다 — 테넌트 권한을 Merge·Replace 로 주거나 계정에 직접 줘도 모든 대리 접근이 403(security.unauthorized details = "impersonate") 이었다.
- 그래서 막는 일은 백엔드가 한다 — 관리자(MAIL_ADMIN_LOCAL_PART)·MAIL_BLOCKED_ACCOUNTS 계정은 웹메일 로그인·대리 접근 대상에서 뺀다 (+ 대리 접근한 세션에 관리 권한이 있으면 거부하는 2차 확인). 관리자 계정을 더 만들면 MAIL_BLOCKED_ACCOUNTS 에 넣는다 (빠지면 setup 이 [주의]).
- 지킬 것: 백엔드 env(루트 .env.production)에만 둔다 · 다른 곳에 재사용하지 않는다(관리자·DB 비밀번호와도 다르게) · 무작위로 길게 · 정기 교체 · 게이트웨이 허용 IP(신뢰 대역 = APP_NETWORK_SUBNET)를 넓히지 않는다 — 이 제한이 바깥에서의 사용을 막는 유일한 장치다.
- 교체 절차: .env.production 의 MAIL_GATEWAY_PASSWORD 를 새 무작위 값으로 → node --env-file=.env.production mail/scripts/setup.mjs (운영 배포 3 과 같은 형태 — [변경] 게이트웨이 … 비밀번호) → sudo docker compose --env-file .env.production up -d backend (새 값으로 다시 만든다). setup 과 backend 재생성 사이에는 웹메일이 MAIL_001 로 잠시 멈춘다 — 사용이 적은 시간에 한다. 사용 기록은 auth.success 로그에 남는다.
신뢰 대역 = 고정한 앱 네트워크 서브넷. compose 가 app-network 서브넷을 APP_NETWORK_SUBNET(기본 172.16.71.0/24)으로 고정하고, setup 은 그 안의 대역만 신뢰 대역으로 받는다 (더 넓으면 실패). 예전처럼 도커 주소 풀 전체(172.16.0.0/12·192.168.0.0/16)를 믿지 않는다. app-network 에는 backend·db·redis·mail(개발은 mailpit 도)만 붙인다 — 인터넷을 향한 frontend 는 edge 네트워크로만 backend 에 닿는다 (frontend 가 붙어 있으면 그 주소가 신뢰 대역에 들고 mail:8080 관리 API 에 닿는다. setup 이 구성원을 확인한다).
8080 은 절대 공개하지 않는다 — 평문 HTTP 관리 API·JMAP 이다.
공개 443 은 ACME·MTA-STS 만 — setup 이 x:Http 싱글톤의 allowedEndpoints 를 listener == 'https' && path != '/.well-known/mta-sts.txt' → 403 으로 둔다. 웹메일은 백엔드 → 내부 http(8080)라 영향이 없다.
- 2026-10-26 확인: https 의 /jmap/session·/.well-known/jmap·/admin/·/account/·/login·OAuth 디스커버리·/healthz 는 403, /.well-known/mta-sts.txt 는 200, 내부 8080 은 그대로. 호스트·다른 컨테이너·AllowedIp 에 든 주소에서 와도 403 이다.
- 식의 변수는 listener·path(그 밖에 url·method·remote_ip·local_ip·local_port·protocol·headers·is_tls)가 통하고 url_path·host 등은 저장할 때 거부된다. 바꾼 뒤에는 ReloadSettings 가 있어야 반영된다.
- ⚠️ 루프백(127.0.0.1)에서 온 요청은 정책을 건너뛴다 — 메일 컨테이너 안에서 https://127.0.0.1 로 시험하면 200 이 나온다. 확인은 컨테이너의 네트워크 주소로 한다 (setup 이 그렇게 확인한다). 이미지 healthcheck 는 https 실패 시 http 8080 으로 대체되어 영향이 없다.
- ACME(TLS-ALPN-01)는 TLS 단계에서 끝나 HTTP 경로 제한과 무관하다 (운영 인증서 발급으로는 아직 확인하지 않았다).
- 관리 화면은 SSH 터널로 내부 8080 에 붙는다: ssh -L 8180:<mail 컨테이너 IP>:8080 <메일 호스트> → http://localhost:8180/admin/. 직원 셀프서비스(/account/ — 비밀번호 변경 등)도 공개 443 에서는 막혀 있다. 필요해지면 백엔드 API 로 만든다.
직원은 계정 목록을 볼 수 없다. 기본 User 역할에는 Principal/get 으로 관리자·게이트웨이를 포함한 전체 계정을 보는 권한 (jmapPrincipal*·davPrincipal* 13개)이 있어서, setup 이 뺀다 (역할 권한은 캐시되므로 InvalidateCaches 로 반영).
- 2026-10-26 확인: 테스트 직원의 Principal/get → forbidden. 백엔드를 거친 웹메일(폴더·목록·읽기·첨부 올리기/내려받기·발송·중복 발송 방지)은 그대로 동작.
- ⚠️ 되돌리기는 일반 관리자로는 안 된다 — 관리자 역할(System Administrator)에 이 권한이 없어 "You are not authorized to grant permissions" 로 거부된다. 복구 관리자(일회성)로 x:Role/set update {"<User 역할 id>": {"enabledPermissions/jmapPrincipalGet": true, …}} → InvalidateCaches 를 한다. (setup 은 다음 실행 때 다시 뺀다 — 계속 필요하면 ensureUserRoleWithoutPrincipals 단계를 먼저 고친다)
- 백엔드가 사내 목록을 읽는 것은 따로 만든 사내 목록 계정(권한 셋, 비밀번호 없음)으로만이다 — 직원 역할에 되돌려 주지 않는다 (사내 목록 계정).
- 직원이 공용 주소(Group 계정)의 구성원이 되어도 Group 역할의 Principal 권한을 물려받지 않는다 (2026-10-29 확인 — 구성원이 된 뒤에도 Principal/query → forbidden).
메일을 받지 않는 시스템 계정은 RCPT 에서 거절한다 (backscatter 막기). 관리자 · 게이트웨이 · 사내 목록 계정의 역할에는 emailReceive 가 없다(관리자의 System Administrator 역할도). 그대로 두면 엔진은 그 주소로 온 메일을 RCPT 에서 250 으로 받아 놓고, 배달할 때 거절해(security.unauthorized … details = "emailReceive") 보낸 사람에게 반송(DSN)한다 — 보낸 사람을 위조한 스팸이면 모르는 사람에게 반송이 나가 서버 평판이 떨어진다. 없는 주소는 처음부터 RCPT 에서 550 5.1.2 다.
- setup 이 x:MtaStageRcpt 의 script 식을 "받는 주소가 그 계정이거나 그 +태그 꼴일 때만" 시스템 Sieve 스크립트 arasystem-system-recipients(reject "550 5.1.2 Mailbox does not exist.")를 고르게 맞춘다(ReloadSettings 로 반영). 없는 주소와 같은 응답이라 바깥에서 이 계정들이 있는지도 알 수 없다. 직원 · 공용 주소는 식에 걸리지 않아 스크립트가 돌지 않는다.
- 대상: 게이트웨이 · 사내 목록 계정과, 관리자 역할에 emailReceive 가 없을 때의 관리자 역할 계정 모두(나중에 더 만든 관리자도 — setup 을 다시 돌리면 식에 더해진다). 사내 목록 주소를 setup 이 만들지 않은 계정이 쓰고 있으면 그 주소는 넣지 않는다(실제 메일함일 수 있다).
- 엔진은 식의 rcpt 를 소문자로 주지만 +태그(부주소)는 떼지 않는다 — 그래서 <아이디>+…@<도메인> 꼴을 따로 본다(구분자는 엔진 기본 + 로 가정한다).
- 웹메일에서 이 주소로 보내면(엔진 안의 인증된 세션) 같은 RCPT 에서 끝난다 — 제출의 받는 사람별 결과가 delivered: no · 550 5.1.2 로 바로 오고(계약 2절 "받는 사람별 결과") 반송은 없다.
- RCPT 단계 스크립트(x:MtaStageRcpt 의 script)는 하나뿐이다. 기본값(없음)이거나 setup 이 써 둔 식일 때만 고치고, 다른 설정이 쓰고 있으면 건드리지 않고 [주의] 를 낸다 — 그때는 그 식에 이 계정들일 때 arasystem-system-recipients 를 고르는 갈래를 합친다.
- 확인 (2026-10-29, 0.16.27): 바꾸기 전 세 주소 모두 RCPT 250 → 배달 때 거절 → 보낸 사람(개발은 Mailpit)에게 반송. 바꾼 뒤 대소문자 · +태그 꼴까지 550, 직원 · 직원 +태그 · 이름이 admin 으로 시작하는 직원 · 공용 주소(Group, +태그 포함)는 250 이고 저장됐다. setup 을 이어서 돌리면 [유지], 관리자를 더 만들거나 지우면 [변경].
복구 관리자는 값이 있는 동안 정상 모드에서도 관리자로 로그인된다 (검증함). 운영은 .env.production 에 두지 않고 일회성 override + --recovery 로만 쓴다 — 파일에 있거나, 끝난 뒤 mail 컨테이너에 남아 있으면 setup 이 실패한다 ("운영 배포" 4·5).
포트는 IPv4(0.0.0.0)로만 공개한다. 주소 없이 쓰면 IPv6 로도 열리는데, IPv6 접속은 docker-proxy 가 중계해 컨테이너에는 도커 게이트웨이 주소로 보인다 → 신뢰 대역으로 취급되어 자동 차단 예외와 게이트웨이 IP 제한이 무력화된다. IPv6 수신이 필요하면 Docker 데몬의 IPv6(ip6tables)를 켜 원본 주소가 보존되는 것을 확인한 뒤 바인딩을 추가한다.
X-Forwarded-For 는 기본 설정에서 신뢰하지 않는다 (x:Http 의 useXForwarded: false — 위조 헤더로 IP 판정이 바뀌지 않음을 검증). 프록시 뒤에서 이를 켤 때는 프록시 주소로 한정해야 한다.
신뢰 대역은 자동 차단에서 빠진다 → 무차별 대입 방어는 백엔드 rate limit 이 담당한다.
비밀번호는 영문·숫자로만 — #·따옴표·$·공백은 compose 와 Node(--env-file, # 부터 주석)가 다르게 읽는다.

리버스 프록시와 같은 호스트에 둘 때 (대안)

기본 구성은 Stalwart 가 호스트 443 을 직접 쓴다. 같은 호스트의 리버스 프록시가 이미 443 을 쓰면 아래 중 하나를 택한다. (1~3 은 문서로만 정리 — 검증하지 않았다) 메일 서버를 따로 둘 수 있으면 4 를 권한다 — 프록시와 메일 엔진이 443 을 나눠 쓰지 않는다.

IP 를 하나 더 붙인다 (가장 단순) — 메일 포트를 그 IP 에만 바인딩: "<메일 전용 IP>:443:443" 등. 나머지는 그대로.
SNI 패스스루 — L4 프록시(nginx stream + ssl_preread, HAProxy, Traefik TCP)가 SNI 가 mx1.arasystem.it.kr 인 TLS 를 복호화하지 않고 mail 의 443 으로 넘긴다. Stalwart 가 TLS 와 ACME(TLS-ALPN-01)를 그대로 처리한다. compose 에서 mail 의 443 매핑을 뺀다.
- ⚠️ mail 과 L4 프록시만 붙는 전용 네트워크를 새로 만든다 (예: <PROJECT_NAME>_mail-ingress, 서브넷 고정, 다른 컨테이너를 붙이지 않는다). 함께 쓰는 proxy 네트워크나 app-network 에 mail 을 붙이지 않는다 — 그 네트워크의 모든 컨테이너가 mail:8080(평문 관리 API·JMAP)에 닿는다.
- 프록시의 대상은 서비스 이름(mail)이 아니라 <PROJECT_NAME>-mail:443 으로 적는다 (다른 프로젝트의 mail 과 겹치지 않게).
```
stream {
  map $ssl_preread_server_name $upstream {
    mx1.arasystem.it.kr  <PROJECT_NAME>-mail:443;   # 전용 네트워크로만 닿는다
    default              127.0.0.1:8443;            # 기존 웹 TLS 종단
  }
  server { listen 443; ssl_preread on; proxy_pass $upstream; }
}
```
프록시가 TLS 종단 → mail:8080 — 993·465 용 인증서는 여전히 Stalwart 가 받아야 하므로 ACME 를 HTTP-01 등으로 바꿔야 한다.
메일 서버를 따로 둔다 — 프록시는 지금 서버에 그대로 두고, 새 서버에 웹메일 스택 전체를 올려 메일 엔진이 그 서버의 443 을 직접 쓴다. 프록시는 포털만 같은 VPC 사설망으로 새 서버의 frontend(8080)에 넘긴다 — 공인 IP 를 서버 수만큼만 주는 곳(NCP 등)에서 1 대신. → 리버스 프록시가 다른 서버에 있을 때

⚠️ 2·3 은 Stalwart 에 프록시 주소가 접속 주소로 보인다. 프록시를 app-network(신뢰 대역 APP_NETWORK_SUBNET)에 두면 인터넷 접속이 신뢰 대역으로 취급되어 자동 차단·게이트웨이 IP 제한이 무력화된다(setup 의 구성원 확인에서도 걸린다). 프록시는 반드시 app-network 밖(위의 전용 네트워크)에 두고, PROXY protocol(2 — 리스너별 overrideProxyTrustedNetworks, 검증 필요) 또는 그 프록시로만 한정한 X-Forwarded-For(3)로 원본 주소를 넘긴다. 3 은 공개 443 정책(listener == 'https')이 http 리스너에는 걸리지 않으므로 프록시 쪽에서 /jmap·관리 경로를 따로 막아야 한다.

리버스 프록시가 다른 서버에 있을 때 (NCP 등 — 사설망)

포털의 TLS 를 다른 서버의 리버스 프록시(예: 기존 서버의 Nginx Proxy Manager — 다른 사이트들과 80 · 443 을 함께 쓴다)가 끝내고, 같은 VPC 사설망으로 메일 서버의 frontend(8080)에 넘기는 구성이다 — 위 대안의 4. 메일 서버에는 웹메일 스택 전체(mail · backend · db · frontend)를 그대로 올리고 메일 엔진이 그 서버의 443 을 직접 쓴다(ACME TLS-ALPN · MTA-STS). 예시 값: 서버 A(기존 — NPM) 사설 IP 10.0.1.11, 서버 B(메일 — mx1.arasystem.it.kr) 사설 IP 10.0.1.12.

               portal.arasystem.it.kr (11단계부터 files. 도) → 서버 A 공인 IP     mx1.arasystem.it.kr → 서버 B 공인 IP (PTR 도)
브라우저 ─TLS─▶ 서버 A (기존) Nginx Proxy Manager — 다른 사이트들과 80 · 443 을 함께
                   │ http · 같은 VPC 사설망 → 10.0.1.12:8080        (서버 B 의 ACG: 8080 은 10.0.1.11 에서만)
                   ▼
               서버 B (메일 — 새로)  docker-compose.yml + docker-compose.remote-proxy.yml
                 <PROJECT_NAME>-frontend :8080 (사설 IP 에만 게시) ─(edge)─▶ backend ─(app-network)─▶ db · mail
                 mail 25 · 465 · 993 · 443 (호스트에 직접, 0.0.0.0) ◀── 바깥 메일 서버 · 메일 프로그램 · ACME

선택 파일 docker-compose.remote-proxy.yml 이 바꾸는 것은 frontend 하나다 — proxy 네트워크에서 빼고(서버 B 에는 없다), 8080 을 FRONTEND_PRIVATE_BIND(사설 IPv4:포트)에만 게시하고, 그 값을 먼저 보는 frontend-bind-check 를 붙인다. frontend 의 환경 · nginx 설정(X-Forwarded-For 이어 붙이기 · X-Request-Id · 실시간 알림)과 다른 서비스 · 네트워크(edge · app-network)는 기본 구성과 같다.
서버 A → B 구간은 평문 HTTP 다 — 같은 VPC 사설망 안이라 받아들이고, 그래서 8080 은 서버 A 에서만 받는다(아래 ACG).

NCP 쪽 할 일

할 일	값
서버 B 만들기	서버 A 와 같은 VPC 의 Public 서브넷, 공인 IP 하나, 메모리 8GB (11단계의 ClamAV 까지 같은 서버에 올린다). 다른 VPC 면 Peering 이 있어야 한다 — 이 절은 같은 VPC 만 다룬다
VPC 대역	`APP_NETWORK_SUBNET`(기본 `172.16.71.0/24`) · `EDGE_NETWORK_SUBNET`(기본 `172.16.72.0/24`) · `MAIL_RESOLVER_SUBNET`(기본 `172.16.73.0/24`)과 겹치지 않게 — 겹치면 서버 B 가 그 대역의 VPC 주소(서버 A 등)로 갈 길을 도커 브리지로 보낸다. 겹치면 그 값을 다른 사설 /24 로 바꾸고(리졸버는 `MAIL_RESOLVER_IP` 도 함께) mail setup 을 다시 돌린다. 리졸버의 바깥 길 `mail-dns-egress` 는 도커가 기본 주소 풀(172.17~31.x · 192.168.x)에서 정한다 — VPC 가 그 대역이면 겹치지 않는지 본다
서버 B ACG — 인바운드	TCP 25 · 465 · 993 · 443 ← `0.0.0.0/0` (메일 수신 · 메일 프로그램 · ACME TLS-ALPN · MTA-STS) · TCP 8080 ← 서버 A 사설 IP `/32` 만 · TCP 22 ← 관리 IP 만. 그 밖(80 · 3000 등)은 열지 않는다
서버 B ACG — 아웃바운드	좁힌다면 25(발송 — 열려 있음을 확인했다) · 443 · 80(ACME · 웹 포털 내려받기 · 외부 이미지 중계) · 53 UDP · TCP 를 모든 곳으로(메일 전용 리졸버가 루트 · 각 도메인의 DNS 서버에 직접 묻는다 — NCP 의 DNS 서버만 열면 안 된다)은 남긴다
서버 A ACG — 아웃바운드	좁혀 두었다면 서버 B 사설 IP 의 TCP 8080 을 더한다
Network ACL	서브넷의 NACL 을 바꿔 두었다면 위 포트를 같게 연다
PTR	서버 B 공인 IP → `mx1.arasystem.it.kr` — 가비아가 아니라 NCP 고객지원에 요청한다. 가비아의 `mx1` A 레코드를 먼저 넣는다(정방향 · 역방향이 맞아야 한다 — PTR)
DNS (가비아)	`mx1` A → 서버 B 공인 IP · `portal` A → 서버 A 공인 IP(지금 그대로) · `files` A → 서버 A 공인 IP(11단계)

게시 주소로는 바깥을 막지 못한다 — NCP 의 공인 IP 는 서버 안에 없고 사설 IP 로 옮겨(NAT) 들어와, 사설 IP 에 게시한 8080 에도 공인 IP 로 닿는다. 8080 을 막는 것은 ACG 다. 서버 B 의 ip -4 addr 에 공인 IP 가 없으면 이 경우다 — 바깥 PC 에서 curl -m 5 http://<서버 B 공인 IP>:8080/ 이 시간 초과여야 한다. (NCP 의 NAT · ACG 는 NCP 문서 기준이고 이 저장소에서 시험하지 않았다 — 배포 뒤 아래 "확인"으로 본다)
메일 포트(25 · 465 · 993 · 443)는 기본 구성 그대로 0.0.0.0 에 게시한다. 공인 IP 로 들어온 접속이 원래 주소 그대로 보이는지는 원래 접속 주소 확인으로 본다.
두 서버의 사설 IP 를 바꾸면(서버를 다시 만들면) FRONTEND_PRIVATE_BIND · TRUST_PROXY · NPM 의 Forward IP · ACG 를 함께 고친다.

서버 B — env 와 실행

.env.production(운영 배포)에 셋을 넣는다 — 앞의 둘은 예시 env 의 "리버스 프록시가 다른 서버에 있을 때" 칸, TRUST_PROXY 는 바꾼다:

COMPOSE_FILE=docker-compose.yml:docker-compose.remote-proxy.yml   # 리눅스는 : 로 잇는다
FRONTEND_PRIVATE_BIND=10.0.1.12:8080                              # 서버 B 의 사설 IPv4:포트 (ip -4 addr)
TRUST_PROXY=172.16.72.0/24,10.0.1.11                              # <EDGE_NETWORK_SUBNET>,<서버 A 사설 IP> — 아래 "TRUST_PROXY"

COMPOSE_FILE 은 env 파일에 둔다 — compose 가 --env-file 의 이 값을 읽으므로 이 문서의 운영 명령(sudo docker compose --env-file .env.production …)이 -f 없이 그대로 두 파일을 읽는다. -f 두 개로 쓰면 명령마다 붙여야 하고, 하나라도 빠뜨린 명령은 기본 구성(서버 B 에 없는 proxy 네트워크)으로 돈다. -f 를 주면 COMPOSE_FILE 보다 그쪽이 이긴다.

그다음은 운영 배포 절차 그대로다. 띄우기 전 · 뒤에 본다:

sudo docker compose --env-file .env.production config --networks   # edge · app-network 만 — proxy 가 보이면 COMPOSE_FILE 이 먹지 않았다
sudo docker port "${PROJECT_NAME}-frontend"                         # 8080/tcp -> 10.0.1.12:8080 한 줄
sudo docker compose --env-file .env.production logs frontend-bind-check

게시 주소 확인 — FRONTEND_PRIVATE_BIND 가 비어 있으면 compose 가 바로 멈춘다(required variable FRONTEND_PRIVATE_BIND is missing a value). 값이 있으면 frontend 보다 먼저 frontend-bind-check(셸만 쓰는 한 번짜리 컨테이너 — DB 이미지를 빌린다 · 네트워크 없음 · 비-root)가 RFC 1918 사설 IPv4(10/8 · 172.16/12 · 192.168/16):포트(1~65535, 앞자리 0 없이)인지 본다. 아니면 up 이 service "frontend-bind-check" didn't complete successfully: exit 1 로 멈추고 frontend 는 뜨지 않는다 — 포트뿐인 값(8080 · :8080 — compose 는 모든 주소에 연다) · 0.0.0.0 · 127.0.0.1 · 공인 IP · IPv6. 떠 있던 frontend 의 값을 잘못 바꾸면 compose 가 frontend 를 다시 만든 뒤 띄우지 않으므로 포털이 멈춘다(닫힌 쪽) — 값을 고치고 up -d. 끝나면 멈춰 있어 ps 에는 없고 ps -a 에 Exited (0) 이다. 앱 네트워크에 붙지 않으므로 mail setup 의 구성원 확인과도 상관없다.
확인 (2026-10-30 — compose v2.40.2(윈도) · 5.4.0(리눅스, CI 잡 이미지), 예시 env + 위 값):
- config 의 frontend 는 networks edge 하나, ports host_ip: 10.0.1.12 · published: "8080" · target: 8080, depends_on 에 frontend-bind-check(service_completed_successfully) — 기본 구성과의 차이는 이 셋뿐이고 환경 · healthcheck 는 같다. 맨 위 networks 에 proxy 가 없다.
- COMPOSE_FILE 을 --env-file 에만 두고 -f 없이 돌린 config 가 위와 같았다(윈도는 ; 로 잇는다). COMPOSE_PROFILES=mail 도 그대로 먹었고, -f docker-compose.yml 을 주면 기본 구성이 나왔다.
- frontend-bind-check — 10.0.1.12:8080 · 172.31.255.254:65535 · 192.168.0.10:18080 은 0, 8080 · :8080 · 0.0.0.0:8080 · 127.0.0.1:8080 · 203.0.113.5:8080 · 172.32.0.1:8080 · [::]:8080 · 10.0.1.12:0 · 10.0.1.12:08080 은 1 (10.0.1.12 · 010.0.1.12:8080 · 10.0.1.12:65536 은 compose 가 먼저 거절). 잘못된 값의 up -d 는 종료 코드 1 · frontend Created(시작하지 않음)이고, 떠 있던 frontend 에서 값을 잘못 바꾸면 다시 만들어진 frontend 가 Created 로 남았다 (시험용 프로젝트 — frontend 대신 alpine).

TRUST_PROXY — 서버 A 의 주소 목록

값은 <EDGE_NETWORK_SUBNET>,<서버 A 사설 IP> (예 172.16.72.0/24,10.0.1.11) — 백엔드의 운영 env 검증이 받는다(2026-10-30 확인). 서버 A 사설 IP 는 frontend 가 보는 접속 주소다 — 서버 A 의 NPM 은 도커지만 서버 밖으로는 서버 A 의 사설 IP 로 나간다. 배포 뒤 sudo docker logs --tail 3 "${PROJECT_NAME}-frontend" 의 첫 칸으로 확인하고, 같은 줄의 X-Forwarded-For(넷째 "…" 칸) 끝이 브라우저의 공인 주소인지 본다.

홉 수 2 도 정상 흐름에서는 같은 IP 를 읽지만 "오른쪽에서 두 번째 주소"를 누가 붙었든 믿는다. 같은 VPC 의 다른 서버가 8080 에 바로 붙으면(ACG 를 잘못 열었을 때) X-Forwarded-For 를 꾸며 백엔드가 그 값을 클라이언트 IP 로 쓴다 — 로그인 실패 한도 · 요청 수 한도가 IP 기준이다. 주소 목록은 서버 A 에서 온 것만 믿어, 다른 곳에서 바로 붙으면 그 서버 자신의 주소로 센다.

frontend 가 받은 `X-Forwarded-For` (백엔드가 보는 접속은 edge 의 frontend)	주소 목록	홉 수 `2`
정상 — `203.0.113.50, 10.0.1.11`	`203.0.113.50`	`203.0.113.50`
브라우저가 꾸밈 — `1.2.3.4, 203.0.113.50, 10.0.1.11`	`203.0.113.50`	`203.0.113.50`
같은 VPC 의 다른 서버가 8080 에 바로 — `1.2.3.4, 10.0.2.20`	`10.0.2.20`	`1.2.3.4` (꾸민 값)
서버 A 의 다른 컨테이너가 8080 에 바로 — `1.2.3.4, 10.0.1.11`	`1.2.3.4` (꾸민 값)	`1.2.3.4` (꾸민 값)

(2026-10-30, 개발 백엔드 컨테이너의 Express 5.2.1 · proxy-addr 2.0.8 과 백엔드의 resolveTrustProxy 로 확인)

남는 것 — 서버 A 의 모든 것(다른 사이트의 컨테이너 포함)은 같은 사설 IP 로 나가 NPM 과 가를 수 없다(표의 마지막 줄). 서버 A 는 믿는 쪽에 든다 — 그 서버에 믿지 못할 것을 두지 않는다. NPM 이 사설 대역에서 온 접속의 X-Real-IP 를 클라이언트 주소로 믿는 것(같은 VPC 의 다른 서버가 NPM 을 거쳐 꾸밀 수 있다)은 아래 고급 칸으로 끈다.

Nginx Proxy Manager 설정

서버 A 의 NPM 에 Proxy Host 를 하나 만든다. 기본값은 NPM v2.16.0(2026-09-24, 지금 최신) 소스로 확인했다 — nginx.conf · proxy.conf · block-exploits.conf · assets.conf · log-proxy.conf · 템플릿 proxy_host.conf · _listen.conf. 서버 A 의 NPM 판이 다르면 같은 파일을 대조한다.

탭 · 칸	값	까닭
Details › Domain Names	`portal.arasystem.it.kr`
Details › Scheme · Forward Hostname / IP · Forward Port	`http` · 서버 B 사설 IP(`10.0.1.12`) · `8080`	`FRONTEND_PRIVATE_BIND` 와 같은 값
Details › Cache Assets	끔	켜면 `.js` · `.css` · `.png` 등으로 끝나는 주소를 NPM 이 30분 캐시한다 — 응답의 `Cache-Control` · `Set-Cookie` 를 무시하고 키가 호스트 + 주소뿐이라(로그인한 사람을 가르지 않는다), 그런 주소의 API 가 생기면 남의 응답이 나간다(지금 서명 그림 · 첨부는 id 로 끝난다). 우리 캐시 머리글(`index.html` no-cache · `/assets/` 30일 immutable)도 지운다
Details › Block Common Exploits	끔	PHP 사이트용 패턴이 메일 검색어에 걸린다 — 아래 표
Details › Websockets Support	끔	웹메일은 웹소켓을 쓰지 않는다 (실시간 알림은 SSE — 보통 HTTP 응답)
Details › Access List	Publicly Accessible	로그인은 웹메일이 한다
SSL › SSL Certificate	Let's Encrypt 새 인증서 (`portal.`)	서버 A 의 80 으로 HTTP-01
SSL › Force SSL	켬
SSL › HTTP/2 Support	켬	실시간 알림 연결이 HTTP/1.1 의 주소당 연결 6개 가운데 하나를 1시간 잡지 않게. NPM → frontend 는 HTTP/1.1 이다(`proxy_http_version 1.1`)
SSL › HSTS Enabled	선택	켜면 브라우저가 이 주소를 https 로만 연다
Advanced › Custom Nginx Configuration	아래 다섯 줄	템플릿이 server 단계, 이 Proxy Host 의 `access_log` · `error_log` 뒤에 넣는다. `location /` 는 쓰지 않는다(쓰면 NPM 이 기본 location 을 빼고 그것을 쓴다)

# 첨부 올리기 — 프론트 nginx 가 백엔드를 150초까지 기다린다(/api/mail-attachments). NPM 기본은 http 단계 90s
proxy_read_timeout 150s;
# 접근 로그에 검색어 · 토큰(쿼리)이 남지 않게 — NPM 의 proxy 형식은 "$request_uri"(쿼리째)와 Referer 를 남긴다.
# 접속 기록은 프론트 nginx 의 접근 로그(쿼리 없음 · 브라우저 주소는 X-Forwarded-For 칸)로 본다
access_log off;
# 사설 대역에서 온 접속의 X-Real-IP 를 클라이언트 주소로 받지 않는다 — NPM 기본은 받는다(nginx.conf 의 set_real_ip_from · real_ip_header).
# 이 호스트는 PROXY protocol 로 받지 않아 바꿔 넣을 주소가 없으므로 접속 주소가 그대로 남는다
real_ip_header proxy_protocol;
# 대용량 첨부 받기(11단계 — 앱 안 받기는 이 포털로 온다)의 응답 머리글이 한글 255자 파일 이름이면 3.5KB 쯤이다 — 기본 4k 로는 빠듯하다(넘치면 502).
# 두 줄을 함께 — 앞의 것만 넣으면 nginx 가 설정을 거절해 이 Proxy Host 가 Offline 이 된다(아래 표 "머리글 버퍼")
proxy_buffer_size 16k;
proxy_busy_buffers_size 16k;

files.arasystem.it.kr — 11단계(대용량 첨부의 공개 내려받기, SHARE_PUBLIC_URL)부터 쓴다. 포털 호스트와 같은 사설 IP:8080 으로 Proxy Host 를 하나 더 만든다 — 위와 같은 칸 · 같은 고급 설정(다섯 줄), 인증서는 files. 로 새로. 접근 로그는 꼭 끈다 — 경로에 내려받기 토큰이 있다. 그 호스트에서 여는 것 · 확인은 대용량 첨부 — 공개 내려받기 호스트.
고급 칸을 저장한 뒤 Proxy Host 가 Online 인지 본다 (NPM 이 저장할 때 nginx -t 를 돌리고, 실패하면 그 설정을 빼고 Offline 으로 오류를 보여 준다 — backend/internal/nginx.js).

v2.16.0 기본값과 이 포털에 필요한 것:

항목	v2.16.0 기본	필요	할 일
본문 한도	`client_max_body_size 2000m` (http)	`MAIL_ATTACHMENT_MAX_SIZE_MB` + 1MB(기본 21m) 이상	그대로 — 줄이면 그 이상으로
읽기 시간	`proxy_read_timeout 90s` (http)	150s 이상(첨부) · 실시간 알림은 25초 ping 보다 길면 된다	고급 칸 150s
응답 전체 시간 상한	없음	실시간 알림 1시간	그대로
응답 버퍼링	nginx 기본(켬) — `X-Accel-Buffering` 을 무시하게 한 곳이 없다	`/api/mail-events` 만 바로 흘려보낸다	그대로 — 프론트 nginx 가 그 응답에 `X-Accel-Buffering: no` 를 넘긴다
압축	`gzip on` · `gzip_types` 없음 → `text/html` 만	`text/event-stream` 은 압축하지 않는다	그대로 — custom `http.conf` 등으로 `gzip_types` 를 넓히지 않는다
`Accept-Encoding`	http 단계에 `proxy_set_header Accept-Encoding ""` 가 있지만, Proxy Host 의 `location /` 가 `proxy.conf` 로 머리글을 따로 정해 물려받지 않는다		그대로 — 브라우저의 값이 frontend 까지 가서 JS · CSS · JSON 은 프론트 nginx 가 압축한다(SSE 는 하지 않는다)
클라이언트가 끊으면	`proxy_ignore_client_abort off`	바로 끊는다	그대로
`X-Forwarded-For`	`proxy.conf` 의 `$proxy_add_x_forwarded_for` (이어 붙인다)	이어 붙인다	그대로
`X-Real-IP` 믿기	`set_real_ip_from` 10/8 · 172.16/12 · 192.168/16 + `real_ip_header X-Real-IP`	사설 대역에서 와도 접속 주소 그대로	고급 칸 `real_ip_header proxy_protocol;`
접근 로그	Proxy Host 마다 `proxy` 형식 — `"$request_uri"`(쿼리째) · Referer	쿼리를 남기지 않는다	고급 칸 `access_log off;`
머리글 버퍼	정하지 않음 → nginx 기본 `proxy_buffer_size` 4k · `proxy_buffers 8 4k` (이미지의 페이지 크기 4096 — 2026-10-30 이미지로 확인)	대용량 받기의 응답 머리글 3.5KB + 여유	고급 칸 `proxy_buffer_size 16k;` + `proxy_busy_buffers_size 16k;` — 앞의 것만이면 `proxy_busy_buffers_size` 의 기본(2 × 16k)이 `proxy_buffers` 의 "하나 뺀 합"(28k)을 넘어 `nginx -t` 가 실패한다(NPM 2.16.0 이미지의 OpenResty 1.31.1.1 로 확인). 버퍼링을 끈 받기는 본문도 이 크기로 넘긴다

Block Common Exploits(block-exploits.conf)는 $query_string 을 대소문자 가려 보고, 걸리면 NPM 의 403(HTML — 표준 실패 JSON 이 아니다)을 낸다. 웹메일에서 걸리는 것:

요청	걸리는 패턴	결과
메일 검색 API `?q=viagra` (소문자 — `valium` · `xanax` · `cialis` · `cocaine` · `tramadol` · `prozac` · `libido` 등)	스팸 낱말	403
`?q=concat(` · `?q=<b>javascript</b>`(`%3C…script…%3E`)	SQL · 스크립트	403
검색 화면 새로 고침 — `/mail/search?q=http://example.com` · `?q=../etc` (화면 주소는 `/` · `:` 를 인코딩하지 않는다)	파일 주입	403
같은 검색어의 API(`q=http:%2F%2F…` · `q=..%2F…`) · 한글 검색어	—	통과

(2026-10-30, block-exploits.conf 를 그대로 넣고 realip · 로그 형식 · 템플릿 차례를 흉내 낸 nginx 1.30.6 으로 확인. 같은 시험에서 사설 주소에서 온 X-Real-IP: 1.2.3.4 가 $remote_addr 를 바꾸고 고급 칸의 real_ip_header proxy_protocol; 이 막는 것, 템플릿의 access_log 뒤의 access_log off; 로 그 Proxy Host 의 로그가 비는 것, location / 가 머리글을 따로 정하면 Accept-Encoding 이 그대로 넘어가는 것도 봤다. 실제 NPM 에는 넣어 보지 않았다)

확인 (배포 뒤)

# 서버 A 에서 — 사설망으로 닿는다 (200)
curl -sS -o /dev/null -w '%{http_code}\n' http://10.0.1.12:8080/
# 바깥 PC 에서 — 공인 IP 의 8080 은 닫혀 있다 (시간 초과)
curl -m 5 http://<서버 B 공인 IP>:8080/
# 서버 B 에서 — 첫 칸이 서버 A 사설 IP, X-Forwarded-For 칸 끝이 브라우저의 공인 주소
sudo docker logs --tail 3 "${PROJECT_NAME}-frontend"

포털에 로그인해 20MB 첨부를 올려 본다(본문 한도 · 150s). 브라우저 개발자 도구 › 네트워크의 mail-events 가 200 으로 열린 채 25초마다 ping 을 받는다(버퍼링 · 압축 없음).
https://portal.arasystem.it.kr/api/health 는 바깥에서 404(RES_001 JSON)다 — 기본 구성과 같다.

문제 해결

증상	조치
`셸 환경변수가 env 파일 값을 가리고 있습니다`	표시된 변수를 지우고 다시 (`unset APP_ENV` · PowerShell `Remove-Item Env:APP_ENV`)
`메일 엔진에 연결할 수 없습니다`	`COMPOSE_PROFILES=mail` 로 떠 있는지, `MAIL_ADMIN_PORT` 가 맞는지. 운영은 `MAIL_ADMIN_URL` 로 컨테이너 내부 주소를 준다 ("운영 배포" 3)
운영에서 `메일 엔진이 응답하지 않습니다: http://mail:8080 (EAI_AGAIN)`	새 셸이라 `MAIL_ADMIN_URL` 이 비었다 — 그러면 도커 안에서만 풀리는 `mail` 로 붙는다. `PROJECT_NAME` · `MAIL_ADMIN_URL` 을 다시 export ("운영 배포" 3). 아무것도 바뀌지 않았다
`Spamhaus 키 … 시험 항목 … 을 받지 못해 그 항목을 꺼 둡니다 — SERVFAIL` (종료 1)	한 번은 일시 오류였다 — setup 을 다시 돌리면 다시 켜진다(2026-10-31). 거듭되면 Spamhaus 계정에서 키 · 서비스(ZEN · DBL)가 켜져 있는지 본다. 그동안 메일은 오간다
mx1 이 자체 서명 인증서(`CN=rcgen self signed cert`)를 낸다 · 로그에 autoconfig · autodiscover · mta-sts 의 `acme.auth-error`	인증서 이름이 기본 묶음이다 — "운영 배포"의 TLS 인증서 줄(Additional Hostnames 에 `mx1` + AcmeRenewal 한 번)
`운영에서는 docker 를 쓸 수 있어야 합니다`	docker 그룹 사용자로, 또는 `sudo -E env "PATH=$PATH" node …` 로 호스트에서 실행 ("운영 배포" 3). 아무것도 바뀌지 않았다
`임시 비밀번호 파일 자리(…/data/mail)에 쓸 수 없어 bootstrap 을 시작하지 않고 중단합니다`	아무것도 바뀌지 않았다. `data/`·`data/mail/` 을 실행하는 사용자 소유로 (`sudo chown "$(id -u):$(id -g)" data && sudo chown -R "$(id -u):$(id -g)" data/mail`) 또는 늘 `sudo -E` 로 — 같은 명령 다시
bootstrap 직후 멈춤 (`bootstrap 은 끝났지만 임시 비밀번호를 보관하지 못했습니다` 등)	bootstrap 직후에 멈췄다면 — 볼륨을 지우지 말고 원인을 고친 뒤 같은 명령(`--recovery`) 다시. config.json 으로 판단해 재시작만 한다
`재시작 후에도 bootstrap 모드입니다 (config.json 은 이미 있음)`	설정 파일이 있는데 엔진이 bootstrap 모드로 떴다 — `docker logs "${PROJECT_NAME}-mail"` 의 기동 오류를 본다. `Bootstrap/set` 을 다시 부르지 않는다
`bootstrap 이 거부되었습니다` + `primaryKeyViolation`	데이터 볼륨에는 이전 설치가 있는데 설정 볼륨에 config.json 이 없다 (예: `_mail-config` 만 지움). 새 설치면 두 볼륨을 다 지우고 처음부터 (`docker volume rm "${PROJECT_NAME}_mail-config" "${PROJECT_NAME}_mail-data"`), 운영 중이던 서버면 백업에서 `_mail-config` 를 복원한다
`사전 확인에 실패해 메일 엔진 설정을 바꾸지 않고 중단합니다`	아래 줄의 항목을 고치고 다시 — 엔진 설정은 그대로다
`앱 네트워크 … 에 신뢰 대역에 있으면 안 되는 컨테이너가 붙어 있습니다`	`docker network disconnect "${PROJECT_NAME}_app-network" <컨테이너>`, compose 의 `networks` 확인 (frontend 는 edge 만). 개발은 경고만
`APP_NETWORK_SUBNET(…) — 접두 길이는 /24 ~ /28 …` · `네트워크 주소로 …` · `사설 대역 …`	사설 대역의 네트워크 주소, `/24`~`/28` 로 (예: `172.16.71.0/24`). 바꾸면 `down` 후 `up -d` 로 네트워크를 다시 만든다
`메일 엔진의 관리자(admin@…)와 MAIL_ADMIN_LOCAL_PART(…) 가 다릅니다`	bootstrap 뒤에 `MAIL_ADMIN_LOCAL_PART` 만 바꿨다 — bootstrap 전에만 바꿀 수 있다. (1) env 를 엔진 관리자의 아이디로 되돌리고 `up -d backend` (가장 간단). (2) 꼭 바꿔야 하면: 복구 관리자로 엔진의 관리자 계정 아이디를 바꾼다(관리 화면 › 계정, 또는 `x:Account/set` `update {"<id>": {"name": "<새 아이디>"}}` — 주소가 함께 바뀐다) → env 를 같은 값으로 → `up -d backend` → setup 재실행
`…(MAIL_ADMIN_LOCAL_PART)로 로그인은 되지만 관리 권한이 없습니다` · `… 는 메일 엔진의 관리자 계정이 아닙니다`	`MAIL_ADMIN_LOCAL_PART` 가 직원 계정을 가리킨다 — 엔진의 관리자 아이디로 맞춘다 (메시지에 엔진의 관리자 목록이 나온다)
`… 의 로그인 확인이 예상하지 못한 응답으로 끝났습니다 (HTTP 429·5xx)`	비밀번호를 덮어쓰지 않으려고 멈췄다. 429 면 몇 분 뒤, 5xx 면 `docker logs` 로 엔진 상태를 본 뒤 다시
`[주의] 게이트웨이로 관리자 … 를 대리 접근하면 관리 API 가 열립니다`	알려진 남은 위험이다 (Stalwart 0.16 은 막을 수 없다) — 보안의 게이트웨이 비밀번호 수칙을 지킨다. 실패가 아니다
`[주의] 관리자 역할 계정 … 가 백엔드 차단 목록에 없습니다`	그 주소를 `MAIL_BLOCKED_ACCOUNTS` 에 넣고 `up -d backend`, 쓰지 않는 관리자라면 지운다
`관리자로 로그인할 수 없습니다`	개발: `MAIL_RECOVERY_ADMIN` 을 채워 `up -d mail` 후 setup 재실행. 운영: "운영 배포" 1)·`up -d mail` → `--recovery` → 4)·5)
`[재시작 필요]` · `[후속 조치]` (종료 코드 3)	안내대로 한 뒤 같은 명령으로 다시 (운영 `--recovery` 뒤에는 `--recovery` 없이)
`MAIL_TRUSTED_NETWORKS 의 … 가 APP_NETWORK_SUBNET(…) 보다 넓거나 그 밖에 있습니다`	`MAIL_TRUSTED_NETWORKS` 를 비우거나(= 서브넷) 서브넷 안의 더 좁은 대역으로
`앱 네트워크 … 의 서브넷(…)이 APP_NETWORK_SUBNET(…) 과 다릅니다`	서브넷을 고정하기 전에 만든 네트워크 — `down` 후 `up -d` 로 다시 만들고 setup 재실행
서브넷을 바꾼 뒤 백엔드가 `getaddrinfo ENOTFOUND db` 로 뜨지 않는다	네트워크만 새로 만들어지고 다른 컨테이너가 서비스 이름 별칭을 잃었다 — `up -d --force-recreate` (또는 `down` 후 `up -d`)
`운영 env 파일에 MAIL_RECOVERY_ADMIN 가 들어 있습니다` 등 복구 관리자 오류	파일에서 지우고 셸에서 일회성으로만 준다 ("운영 배포")
`… 에 복구 관리자(STALWART_RECOVERY_ADMIN)가 남아 있습니다`	`unset MAIL_RECOVERY_ADMIN` 후 `docker compose --env-file .env.production up -d mail`
`백엔드 주소 … 가 신뢰 대역(…) 밖입니다`	`MAIL_TRUSTED_NETWORKS` 를 비우고(= `APP_NETWORK_SUBNET`) setup 재실행
`공개 443 차단 확인 실패`	setup 이 `ReloadSettings` 까지 했는지, `x:Http` 의 `allowedEndpoints` 가 위 식인지 (관리 화면 › Settings › HTTP)
`[주의] 받는 쪽 한도 "Sender address to recipient throttle"(…)을 찾지 못해 만들지 않았습니다`	엔진 기본 한도를 지웠거나 이름을 바꿨다. 지웠다면 그대로 두고, 이름을 바꿨다면 그 한도의 `match` 가 `{"match":{},"else":"is_empty(authenticated_as)"}` 인지 관리 화면에서 본다 (엔진 한도)
웹메일 발송의 받는 사람이 `452 4.4.5 Rate limit exceeded` 로 거절된다	setup 출력에 `받는 쪽 한도 … 인증 없는 세션에만` 이 있는지 본다. 받는 쪽 한도를 새로 만들었다면 그 `match` 도 — 엔진 로그 `smtp.rate-limit-exceeded` 의 `id` 가 어느 한도인지 알려 준다 (엔진 한도)
한 직원의 첨부 올리기 · 필터 · 부재중 저장이 429 `REQ_001` 로 막힌다 (백엔드 로그 `"reason":"mail-engine-rate-limit","call":"upload"`)	엔진의 임시 업로드 한도(계정마다 1시간 — 크기 합계 · 개수)를 넘었다. 올린 것이 만료되면(최대 1시간) 풀린다. setup 출력에 `임시 업로드 한도 — 계정마다 크기 합계 …` 가 있는지 보고, 개수를 넘는 직원이 잦으면 `maxUploadCount` 를 올린다 (엔진 한도 "임시 업로드 한도")
`임시 업로드 한도(x:Jmap 의 uploadQuota = …)를 읽지 못해 바꾸지 않았습니다` · `[주의] 임시 업로드 한도(x:Jmap 의 uploadQuota)가 0 입니다`	엔진이 숫자가 아닌 값(판을 올려 속성이 바뀌었는지 본다)이나 0 을 돌려줬다 — 관리 API `x:Jmap/get` 으로 `uploadQuota` 를 보고 첨부 합계 한도 × 20 이상으로 둔 뒤 `ReloadSettings` (0 이 제한 없음인지는 확인하지 않았다)
`[주의] 사내 목록 계정이 없습니다 (…)`	��구 관리자 없이 돌렸다 — 실패가 아니다. 운영: "운영 배포" 1)·`up -d mail` → 3) `--recovery` → 4)·5) 를 한 번. 개발: `MAIL_RECOVERY_ADMIN` 을 채우고 `up -d mail` 후 setup. 그동안 백엔드는 로그인한 직원 기록으로 사내 목록을 대신한다 (사내 목록 계정)
`[주의] 사내 목록 계정이 setup 기준과 다릅니다 (역할의 권한이 다름 … · 계정의 역할이 다름)`	누가 역할·계정을 고쳤다. 관리자로는 되돌릴 수 없다(엔진이 거절) — 위와 같이 복구 관리자로 setup. 이어서 나오는 `[확인]`·`[주의]` 줄이 지금 백엔드가 읽을 수 있는지 알려 준다
`…(MAIL_DIRECTORY_LOCAL_PART)는 setup 이 만들지 않은 계정의 주소라 …`	그 주소를 실제 계정이 쓴다(그 계정은 건드리지 않았다). `MAIL_DIRECTORY_LOCAL_PART` 를 아무도 쓰지 않는 아이디로 바꾸고 `up -d backend` → setup 재실행
`사내 목록 계정으로 계정 목록을 읽지 못했습니다 — …: 세션 HTTP 403` · `Principal/… → forbidden`	역할에 `authenticate`·`jmapPrincipalGet`·`jmapPrincipalQuery` 가 없거나 빼는 권한에 들었다 — 복구 관리자로 setup. `세션 HTTP 401` 이면 계정이 없거나 게이트웨이 비밀번호·허용 IP 문제다
`[주의] 사내 목록 역할을 다른 계정도 가지고 있습니다: …`	관리 화면 › 계정에서 그 계정의 역할을 바꾼다 (관리자로 된다)
`[유지] 옛 사내 목록 계정 … — 새 계정 … 가 준비된 뒤에 지운다`	`MAIL_DIRECTORY_LOCAL_PART` 를 바꿨는데 새 계정을 아직 만들지 못했다(복구 관리자 없음) — 복구 관리자로 setup 을 돌리면 새 계정을 만들고 옛 계정을 지운다
사내 목록(`GET /api/directory-entries`)이 `503 MAIL_001`	setup 출력의 요약 `사내 목록` 줄을 본다 — 준비되지 않았으면 위 줄들. 준비됐는데도 그러면 backend 의 `MAIL_DIRECTORY_LOCAL_PART` 가 setup 과 같은지 보고 `up -d backend`
`[주의] RCPT 단계 스크립트(x:MtaStageRcpt 의 script)를 다른 설정이 쓰고 있어 바꾸지 않았습니다`	메일을 받지 않는 시스템 계정은 지금처럼 받아 놓고 반송한다. 그 식에 시스템 계정일 때 `arasystem-system-recipients` 를 고르는 갈래를 합치거나, 그 설정이 필요 없으면 기본값(`{"match":{},"else":"false"}`)으로 되돌리고 setup 재실행 (보안)
`시스템 계정의 RCPT 거절 확인 실패 — …`	setup 이 `ReloadSettings` 까지 했는지, `x:MtaStageRcpt` 의 `script` 식과 시스템 Sieve 스크립트 `arasystem-system-recipients`(`isActive: true`)를 관리 API 로 본다. 확인은 메일 컨테이너 안의 `curl` 로 RCPT 까지만 보낸다
`시범 공존 사전 확인에 실패해 메일 엔진 설정을 바꾸지 않고 중단합니다` · `… allowRelaying 만 닫고 중단합니다`	아무것도 바뀌지 않았다 — 뒤의 머리글이면 가드 없이 열려 있던 relay 만 닫았다(위에 `[변경] … allowRelaying 을 껐다`, 엔진에 없는 사내 주소는 다시 550). 아래 줄의 항목을 고친다 — 기존 서버에 닿지 않으면 이 호스트의 바깥 25 · 기존 서버의 STARTTLS · 인증서 이름, 자기 자신으로 풀리면 `MAIL_PILOT_LEGACY_HOST`, 기존 서버 IP 의 사람이 만든 자동 차단 예외 · 기존 서버 IP 로 된 운영자 갈래(아래 줄)는 지운 뒤 다시, `waitOnFail` 은 기본값(5s)으로, DKIM 은 아래 줄 (파일럿 공존 "setup 이 하는 일"). 이미 켜진 시범이면 "시범은 켜진 채로 두었습니다" — 고친 뒤 같은 명령으로 다시 실행한다
`MAIL_PILOT_LEGACY_HOST 가 비어 있는데 메일 엔진에 시범 공존 설정이 남아 있습니다`	운영의 env 파일에서 시범 값이 빠졌다. 시범을 이어 가려면 두 값을 다시 넣고, 끝내려면(전면 전환 — MX 를 옮긴 뒤) 값을 비운 채 `--end-pilot` 으로 실행한다. 아무것도 바뀌지 않았다
`운영의 시범 공존 값(…)은 셸이 아니라 .env.production 에 둡니다`	셸에 `MAIL_PILOT_LEGACY_*` 가 남아 있다 — 파일에 적고 `unset` 뒤 다시
`도메인 … 의 allowRelaying 이 켜져 있습니다 — 시범 설정은 없고(setup 이 켠 것이 아니다) RCPT 가드도 없어 …`	시범을 켠 적이 없는 엔진에서 누가 relay 만 켜 두었다 — 가드 없이 열린 relay 라 엔진에 없는 사내 주소 앞 메일을 받아 놓고 반송한다. setup 은 남의 설정이라 끄지 않는다(요약 `시범 설정 없음 · allowRelaying 켜짐`, 종료 1). 의도한 것이 아니면 관리 화면에서 그 도메인의 relay 허용을 끈다
`도메인 … 의 allowRelaying 이 켜져 있는데 setup 이 만든 시범 발송 경로(legacy)가 없습니다`	누가 켰는지 알 수 없어 끄지 않았다 — 관리 화면에서 `legacy` 경로만 지웠을 수도 있다. RCPT 가드 · 위조 막기 · 예외 · 발송 전략은 남겼다(가드 없는 relay 를 만들지 않는다 — 요약은 `시범 공존 끝내지 못함`). 끝낼 것이면 관리 API `x:Domain/set` 으로 `allowRelaying: false` 뒤 다시 실행하면 나머지를 뺀다. 이어 갈 것이면 시범 값을 넣고(운영은 env 파일) 실행하면 경로를 다시 만든다
`RCPT 가드가 답하지 않아(…) 시범 공존의 allowRelaying 을 켜지 않고 중단합니다`	켜기 전 확인(A 의 리로드 뒤 · relay 꺼진 채)에서 엔진에 없는 사내 주소가 2초 안에 550 이 아니었다 — relay 는 열지 않았다(엔진에 없는 사내 주소는 그대로 550). 가드 · 표시 · 예외는 저장돼 있다. setup 이 리로드까지 했는지, `x:MtaStageRcpt` 의 `script` 와 시스템 Sieve 스크립트 `arasystem-system-recipients`(`isActive`)를 관리 API 로 본 뒤 같은 명령으로 다시 실행한다
`… allowRelaying 을 끄려 했지만 끄지 못했습니다 (…)` 뒤에 `— 대신 RCPT 가드를 다시 걸어 지금은 가드가 답합니다(…)`	가드가 답하지 않아 relay 를 닫으려 했는데 저장이 거절되었거나 · 엔진에 닿지 않았거나 · 다시 읽어도 켜져 있다. setup 이 멈추기 전에 RCPT 가드만 다시 걸었고 지금은 가드가 550 으로 거절한다 — relay 는 켜진 채다. 관리 화면에서 그 도메인의 relay 허용(관리 API `x:Domain/set` 의 `allowRelaying: false`)을 끄고, 꺼진 것을 본 뒤 같은 명령으로 다시 실행한다
`… 끄지 못했습니다 (…)` 뒤에 `RCPT 가드도 다시 걸지 못했습니다 — 지금 가드 없이 열려 있습니다` · `… 열려 있을 수 있습니다`	relay 를 닫지 못했고 가드도 다시 걸지 못했다(저장 · 리로드 실패, 다시 걸었는데 확인이 250 이거나 확인하지 못함, 또는 RCPT 단계 식을 다른 설정이 써서 건드리지 않음) — 지금 열려 있다(있을 수 있다). 관리 화면에서 relay 허용을 바로 끄고, 꺼진 것을 본 뒤 다시 실행한다. 켜기 전 · 켠 뒤 확인에서 끄지 못한 경우(가드는 이미 걸었다)도 "열려 있을 수 있습니다"로 같다. setup 은 그 밖의 설정을 더 바꾸지 않고 멈췄다
`RCPT 가드가 걸리지 않아 시범 공존의 allowRelaying 을 다시 끄고 중단합니다`	켠 뒤 확인에서 엔진에 없는 사내 주소가 2초 안에 550 이 아니었다 — `allowRelaying` 을 다시 껐다(엔진에 없는 사내 주소는 다시 550, owner 가 동료에게 보내는 메일도 `not-found`). 가드 · 경로는 남아 있다. setup 이 리로드까지 했는지, `x:MtaStageRcpt` 의 `script` 와 시스템 Sieve 스크립트 `arasystem-system-recipients`(`isActive`)를 관리 API 로 본 뒤 같은 명령으로 다시 실행한다
`[변경] 시범 공존 — RCPT 가드 없이 allowRelaying 이 켜져 있어 → … allowRelaying 을 껐다` · `… RCPT 가드가 답하지 않아(…) → …`	실행을 시작할 때 relay 가 가드 없이 열려 있었다(누가 RCPT 식을 바꿨거나 시스템 Sieve 스크립트를 껐다) — 먼저 닫았다. 같은 실행이 확인을 마치면 가드를 되살리고 다시 켠다 — 끝이 `[완료]` 면 된 것이다
`시범 공존 확인 실패 — …` (위조 막기 · 인증한 세션)	설정은 저장됐다. setup 이 리로드까지 했는지, `x:MtaStageMail` 의 `isSenderAllowed` · 도메인의 `allowRelaying` 을 관리 API 로 본다. 고치기 어려우면 값을 비우고(운영은 `--end-pilot`) 끈다
`다른 도메인 … 이 allowRelaying 을 켜 두어 시범 설정(…)을 빼지 않았습니다`	시범을 끄는 실행인데 시범 도메인 밖의 도메인이 relay 를 켜 두었다 — RCPT 가드가 모든 사내 도메인을 덮으므로 가드 · 위조 막기 · 예외 · 발송 전략을 남겼다. setup 은 그 도메인을 끄지 않는다 — 의도한 것이 아니면 그 도메인의 relay 허용을 끈 뒤 다시 실행한다
`도메인 … 의 allowRelaying 을 끄려 했지만 다시 읽어도 켜져 있습니다`	시범 도메인의 relay 를 끄는 저장을 엔진이 받았는데 반영되지 않았다 — 시범 설정을 그대로 두었다. 관리 화면에서 relay 허용을 끈 뒤 다시 실행한다
`운영의 MAIL_PILOT_LEGACY_HOST 포트는 25 만 받습니다`	587 · 465 는 인증이 있어야 중계되는데 setup 은 발송 경로에 인증을 넣지 않는다 — mailcow 의 25 를 쓴다(`[mail.arasystem.it.kr]:25` 또는 포트 없이)
`[주의] 시범 꼴과 같은 기존 서버 IP 갈래가 있지만 setup 의 표시 … 에 없는 IP 라 운영자 것으로 보고 건드리지 않습니다`	위조 막기 · 검사 예외 · IP 한도 식에 시범 꼴의 갈래가 있는데 시범 표시(자동 차단 예외)에 없는 IP 다 — 운영자가 넣은 것이면 그대로 둔다(기존 서버 IP 와 같은 IP 면 아래 줄처럼 멈춘다). setup 이 넣은 것인데 표시 항목을 지웠다면 관리 화면에서 그 갈래를 지운다
`… 에 기존 서버 IP(…)로 된 갈래가 setup 의 표시 없이 있습니다 — 운영자가 넣은 것이거나, setup 의 시범 표시 … 가 지워진 것입니다`	켜기 전에 멈췄다(아무것도 바뀌지 않았다). 운영자가 넣은 것이면 — 켜면 다음 실행부터 setup 의 갈래와 가를 수 없어 합쳐지고 끝낼 때 지워지므로 — 그 갈래를 지우고(IP 한도는 엔진 기본 — 모든 IP — 으로) 다시 실행한다(시범 동안은 setup 의 갈래가 같은 일을 한다). 켜진 시범에서 setup 의 시범 표시(자동 차단 예외)만 지워진 것이면 그 IP 로 같은 설명(`[setup.mjs] 시범 공존 — 기존 서버(mailcow) 중계 IP`)의 자동 차단 예외를 다시 만든 뒤 실행해도 된다
`… 에 setup 의 시범 갈래와 같은 글의 갈래가 둘 이상 있습니다`	setup 은 한 칸에 하나만 넣는다 — 나머지는 운영자가 같은 글로 넣은 것이다. 하나만 남기고 지운 뒤 다시 실행한다. 끄는 실행에서는 맨 앞 하나만 빼고 나머지를 남긴다(`[주의] … 맨 앞 하나만 빼고`)
`DKIM TXT … 의 공개 키가 엔진의 키와 다릅니다` · `DKIM TXT … 가 DNS 에 없습니다`	키가 다르면 동료(mailcow) 앞 메일이 위조로 거절되고, 없으면 DMARC 가 SPF 정렬에만 기대게 되어 반송(빈 봉투)이나 SPF 가 빗나간 메일이 거절된다. `setup.mjs --print-dns` 가 보여 주는 selector TXT 로 DNS 를 고치거나 넣고, 바깥에서 `dig TXT <selector>._domainkey.<도메인>` 으로 보인 뒤 다시 실행한다. 처음 켜는 실행이면 relay 를 켜지 않고 멈췄고, 이미 켜진 시범이면 켠 채로 실패만 알렸다
`[주의] 관리자 역할("System Administrator")을 찾지 못했거나 메일을 받게(emailReceive) 바뀌어 …`	관리자 역할의 이름을 바꿨거나 `emailReceive` 를 더했다 — 관리자 주소는 RCPT 거절에서 빠진다(메일을 받는 계정을 막지 않으려고). 관리자가 메일을 받지 않게 둔다면 역할을 되돌린다
`Password is too weak`	더 길고 무작위인 값으로 (예: `change-me-in-local-env` 는 통과, `devpassword1` 은 거부)
`리졸버 네트워크 … 가 없습니다` · `… 가 리졸버 네트워크 … 에 없습니다` · `… 의 dns(…)가 MAIL_RESOLVER_IP(…) 하나가 아닙니다` · `… 컨테이너가 없습니다`	메일 전용 리졸버가 든 compose 로 아직 다시 띄우지 않았다 — `docker compose … up -d`(mail-resolver 를 띄우고 mail 을 다시 만든다 — 몇 초 끊긴다) 뒤 setup. 아무것도 바뀌지 않았다
`… 가 떠 있지 않습니다`(mail-resolver)	`docker logs "${PROJECT_NAME}-mail-resolver"` — 설정 오류면 줄 번호가 나온다(`unbound-checkconf`). `could not open … unbound.conf`·`Permission denied` 면 저장소를 umask 077 로 클론했다 — `chmod 644 mail/resolver/unbound.conf`. 고친 뒤 `docker compose … up -d`
mail-resolver 가 `Address already in use` 로 뜨지 않는다	다른 컨테이너가 `MAIL_RESOLVER_IP` 를 먼저 가져갔다(도커는 앞쪽부터 차례로 준다). `docker compose … up -d --force-recreate mail-resolver mail`, 되풀이되면 `MAIL_RESOLVER_IP` 를 서브넷의 끝 쪽으로
`… 의 … 주소(…)가 MAIL_RESOLVER_IP(…) 와 다릅니다` · `서브넷(…)이 MAIL_RESOLVER_SUBNET(…) 과 다릅니다` · `internal 이 아닙니다`	env 를 바꾼 뒤 컨테이너 · 네트워크를 다시 만들지 않았다 — `docker compose … down` 후 `up -d`(네트워크 · 컨테이너를 함께), 그다음 setup
`리졸버 … 가 메일 컨테이너에서 DNSSEC 을 검증한 답을 주지 않습니다`	리졸버가 바깥에 묻지 못하거나 DNSSEC 이 깨졌다 — 괄호 안이 답마다의 결과다(UDP 루트 SOA · TCP 루트 DNSKEY). 이 서버의 바깥 53(UDP · TCP) 아웃바운드(NCP ACG), `docker exec "${PROJECT_NAME}-mail-resolver" drill . @127.0.0.1 NS`, 서버 시계(DNSSEC 은 시각을 본다), `docker logs` 의 리졸버 오류. 운영은 아무것도 바꾸지 않고 멈췄다. 개발은 `[주의]` 뒤 이어 가지만(개발 메일은 Mailpit), 리졸버가 바깥에 전혀 닿지 않으면 뒤의 리로드를 엔진이 거절해 거기서 종료 1 이다(아래 줄)
`[실패] x:Action/set 요청이 거부되었습니다` + `생성 거부 (reload): validationFailed — Invalid address: failed to lookup address information`	엔진이 설정을 다시 만들며 스팸 필터의 Pyzor 주소(`public.pyzor.org`)를 mail 컨테이너의 DNS(= 메일 전용 리졸버)로 풀지 못해 리로드를 통째로 거절했다 — 리졸버가 바깥에 닿지 못한다. `docker exec "${PROJECT_NAME}-mail-resolver" drill public.pyzor.org @127.0.0.1 A` 로 보고 리졸버 장애 때. 저장한 설정은 남아 있다(다음 리로드 · `restart mail` 때 적용)
`메일 컨테이너(…)에서 리졸버를 확인하지 못했습니다 — 메일 컨테이너에 perl 이 없음(docker exec 종료 코드 127)`	리졸버 문제가 아니다 — setup 은 메일 이미지의 perl 로 묻는데 `MAIL_IMAGE` 를 바꾼 새 이미지에 perl 이 없다(`docker exec "${PROJECT_NAME}-mail" perl -v`). 운영은 여기서 멈춘다 — 이미지를 되돌리거나, setup 의 리졸버 확인(`DNS_PROBE_SCRIPT`)을 그 이미지에 맞춘다. 개발은 `[주의]`
`[주의] … 의 이번 기동 … 로그가 남아 있지 않아 … DNSSEC 을 검증했는지 확인하지 못했습니다`	mail 이 오래전에 떠서 그 기동의 로그가 회전(`json-file` 의 `max-size` · `max-file` 등)으로 지워졌다 — 실패가 아니다(메일 · 리졸버는 사전 확인대로다). 확인하려면 `docker compose … restart mail`(몇 초 끊긴다) 뒤 setup
compose `up` 이 `optional dependency "mail-resolver" failed to start` 경고를 낸다	mail 은 떴지만 리졸버가 unhealthy · 멈춤이라 바깥 DNS(바깥 메일 · SPF · DKIM · DNSBL)가 안 된다 — 리졸버 장애 때
특정 회사(도메인)로만 메일이 안 간다 · 그 도메인에서 온 메일만 SPF · DKIM · DMARC 가 `temperror`	그 도메인의 DNSSEC 이 깨졌을 수 있다(리졸버가 검증해 SERVFAIL 로 답한다) — DNSSEC 이 깨진 도메인
`[주의] 리졸버 네트워크 … 에 mail · mail-resolver 밖의 컨테이너가 붙어 있습니다` · `리졸버의 바깥 길 … 에 다른 컨테이너가` (운영은 실패)	그 컨테이너도 리졸버에 닿는다(리졸버도 그 컨테이너에 닿는다) — `docker network disconnect <네트워크> <컨테이너>`, compose 의 `networks` 확인
`[주의] 엔진이 … 때 리졸버로 DNSSEC 을 검증하지 못했다고 남겼습니다`	mail 이 리졸버보다 먼저 떴거나(서버 재부팅 — 도커는 compose 의 차례를 지키지 않는다. `docker compose … restart mail` 뒤 setup 으로 다시 본다), 리졸버가 TCP 로 답하지 못한다. 메일은 오가고 DANE 만 꺼진다. 리로드도 같은 확인을 다시 하지만 결과가 로그에 남지 않아 기동 로그로만 본다
`[주의] MAIL_SPAMHAUS_DQS_KEY 가 없어 Spamhaus 두 항목 … 을 꺼 둔다` (운영)	키가 없으면 늘 나온다 — 실패가 아니다. 키를 받으면 `.env.production` 에 넣고 setup (DNS 리졸버와 스팸 차단 목록 "Spamhaus")
`Spamhaus 키(…)로 … 시험 항목 … 을 받지 못해 그 항목을 꺼 둡니다`	키가 틀렸거나 · 계정이 끝났거나(체험 30일이 지났다 — 구독하거나 키를 비우고 setup) · 그 서비스(IP · 도메인)가 계정에서 꺼져 있다(꺼진 서비스는 SERVFAIL). Spamhaus 계정 화면에서 키 · 서비스를 본 뒤 setup. 그 항목은 꺼진 채다 — 공개 미러로 묻지 않는다. 키가 멈춘 뒤 이 실행 전까지는 엔진의 조회가 실패해 표시가 붙지 않았다(fail-open — "Spamhaus" 절)
`MAIL_SPAMHAUS_DQS_KEY 는 Spamhaus 가 준 26자 영문 · 숫자 키여야 합니다` · `운영의 MAIL_SPAMHAUS_DQS_KEY 는 셸이 아니라 …`	키를 `.env.production` 에 따옴표 · 공백 없이 그대로 넣는다(셸에는 두지 않는다 — `unset MAIL_SPAMHAUS_DQS_KEY`)
`[주의] 스팸 차단 목록 …(STWT_…)을 찾지 못해 맞추지 않았습니다`	엔진 기본 항목을 지웠거나 이름을 바꿨다 — 바꿨다면 그 항목의 조회 이름 · 켜짐을 관리 화면 › Settings › Spam Filter › DNSBL 에서 직접 본다
외부로 보낸 메일이 Mailpit 에 없다	setup 의 `[확인] 설정 리로드 완료` 가 나왔는지. 로그: `docker logs "${PROJECT_NAME}-mail"` 의 `delivery.*`. `delivery.ip-lookup-failed … hostname = "mailpit"` 이면 개발 엔진의 DNS 가 `Custom` 이다 — setup 을 다시 돌리면 `System` 으로 돌아온다
대용량 파일이 오래 "검사 중"이다 · 백엔드 로그에 검사기 오류(세 번째부터 error)	검사기가 멈췄거나 닿지 않는다 — 판정 없이 받게 되는 일은 없다(닫힌 쪽), 고치면 백엔드가 차례대로 다시 한다(1분부터 두 배씩 1시간까지). `sudo docker compose --env-file .env.production ps clamav clamav-updater`(둘 다 healthy) · `sudo docker logs --tail 30 "${PROJECT_NAME}-clamav"` · 백엔드에서 `sudo docker exec "${PROJECT_NAME}-backend" node -e "const s=require('net').connect(3310,'clamav');s.on('connect',()=>s.write('zPING\0'));s.on('data',d=>{console.log(String(d));process.exit(0)});s.on('error',e=>{console.log(e.code);process.exit(1)})"` → `PONG`. `ENOTFOUND` 면 clamav 가 없다(`up -d`), `ECONNREFUSED` 면 서명을 읽는 중이거나 죽었다(로그). clamav 가 `Exited` 면 서명이 없거나(updater 를 먼저 본다) 메모리 한도(`docker inspect … OOMKilled`) — 악성 검사 (ClamAV)
2GB 가까운 파일만 오래 "검사 중"이다	검사 한 번이 백엔드의 판정 대기(30분 + 보낸 1MB 마다 1초 — 2,047MB 면 약 64분)를 넘는다 — 넘으면 끊고 미뤄서 처음부터 다시 검사한다. 코어 하나로 2GB 에 5분 안팎(개발 PC)이라 보통은 넉넉하다 — 운영 CPU 가 아주 느리거나 zip 밖의 큰 압축(7z · tar.gz — 시간 상한 없음, `MaxScanSize` 4GB 까지 푼다)이면 더 걸린다. 백엔드 로그의 `clamd 가 다 받은 뒤 …초 안에 판정을 보내지 않았습니다` · clamav 로그에 그 판정이 늦게 남는지 본다. 한 번에 둘을 검사하면 `cpus`(2.0)를 나눠 쓴다 — CPU 를 늘리거나 백엔드에 알린다
`clamav-updater` 가 unhealthy · 서명이 오래됐다 (`echo VERSION \| nc localhost 3310` 의 날짜)	updater 의 healthcheck 는 daily 서명이 이틀 넘게 바뀌지 않으면 실패한다. `sudo docker logs --tail 50 "${PROJECT_NAME}-clamav-updater"` — 바깥 HTTPS · DNS(`database.clamav.net` · `current.cvd.clamav.net`)가 막혔거나(NCP ACG 아웃바운드 443 · 53), CDN 이 잦은 요청으로 잠시 막았거나(`You are on cool-down until …` — 그 시각까지 기다린다, 컨테이너를 되풀이해 다시 만들지 않는다), 판이 끝나(EOL) 서명을 주지 않는다(`clamav/clamav` 판을 올린다 — docker 스킬 "이미지 버전 고정"). 검사는 옛 서명으로 이어 간다
`up` 이 `optional dependency "clamav-updater" failed to start` 경고를 내고 `clamav` 가 곧 끝난다	처음 기동에서 서명을 받지 못했다(updater 가 unhealthy — clamd 는 서명이 없으면 뜨지 않는다). updater 로그를 보고 고친 뒤 `up -d`. 서명 볼륨을 지웠다면 updater 가 다시 받는 1분 안팎을 기다린다
대용량 파일을 올릴 수 없다 — 507 `FILE_006`	서버 총량(`FILE_STORAGE_MAX_TOTAL_GB`) 또는 디스크 여유(`FILE_STORAGE_MIN_FREE_GB`)에 걸렸다 — `df -h /data/docker` · `sudo docker system df -v`(볼륨 `<PROJECT_NAME>_files` 크기). 기간이 지나거나 끊은 링크의 파일은 한 시간마다 지워진다. ClamAV 가 검사하는 동안 `/tmp` 에 잠시 쓰는 몫(최대 12GB)도 같은 디스크다
받는 사람이 내려받기에서 429 `REQ_001`	프론트 nginx 의 동시 연결 수 — 같은 주소에서 공개 받기 10개 · 앱 안 받기 30개, 또는 전체 공개 받기 400개 · 앱 안 받기 200개(따로 센다)를 넘었다(접근 로그의 429 — 대소문자를 바꾼 경로도 같은 수로 센다). 백엔드의 요청 수 한도(공개 받기 IP 당 1분 300회)와 같은 코드다 — 백엔드 로그에 없으면 nginx 쪽이다. 사무실 NAT 뒤에서 앱 안 받기가 잦으면 `frontend/nginx.conf` 의 수를 올린다(전체를 올리면 `worker_connections` · `nofile` 그릇도 다시 본다 — 받기 하나가 연결 둘)
내려받기만 502(HTML — NPM 의 오류 화면)이고 다른 화면 · API 는 된다	외부 프록시(NPM)의 머리글 버퍼에 받기 응답 머리글이 넘쳤다 — 긴 한글 파일 이름이면 3.5KB 를 넘는다. 두 Proxy Host 의 Advanced 에 `proxy_buffer_size 16k;` · `proxy_busy_buffers_size 16k;` 가 있는지 본다(Nginx Proxy Manager 설정). NPM 의 오류 로그(NPM 컨테이너 안 `/data/logs/proxy-host-<번호>_error.log` — 2.16.0 템플릿)에 `upstream sent too big header` 가 남는다. 프론트 nginx 는 16k 다 — 프론트 nginx 의 502 면 JSON `SYS_001` 이다
NPM 의 Proxy Host 가 Offline — `"proxy_busy_buffers_size" must be less than …`	Advanced 에 `proxy_buffer_size 16k;` 만 넣었다 — `proxy_busy_buffers_size 16k;` 를 함께 넣고 저장한다
clamav 의 디스크(쓰기 계층)가 줄지 않는다 · `docker system df` 의 clamav 컨테이너가 크다	검사 중에 clamd 가 죽으며 남긴 임시 파일이다(`/tmp/clamav-<hex>.tmp` — 받던 스트림 · 푼 내용). compose 는 clamd 를 띄울 때마다 지우므로 다시 뜬 뒤에도 크면 지금 검사 중인 것이다(한 번에 2개 × 최대 6GB). `sudo docker exec "${PROJECT_NAME}-clamav" du -sh /tmp` · `ls -la /tmp`. 자주 죽는다면 까닭을 본다 — `docker inspect -f '{{.State.OOMKilled}} {{.RestartCount}}' "${PROJECT_NAME}-clamav"`(메모리 한도 — 메모리 예산) · `docker logs`
frontend 가 뜨지 않는다 — `nginx-env.envsh: SHARE_PUBLIC_URL 은 공개 내려받기 화면의 출처…`	`.env.production` 의 `SHARE_PUBLIC_URL` 을 `https://호스트[:포트]` 로(경로 · 끝의 `/` · 끝 점 없이) 고친 뒤 `up -d frontend`
`up` 이 `all predefined address pools have been fully subnetted` 로 멈춘다	도커 기본 주소 풀(172.17~31.x · 192.168.x — 네트워크 31개)이 다 찼다 — 서브넷을 정하지 않은 네트워크(`clamav` · `clamav-egress` · `mail-dns-egress`)를 만들 자리가 없다. 쓰지 않는 네트워크를 지운다(`docker network prune` — 개발 PC 는 다른 프로젝트 · CI 의 것이 쌓인다)

리졸버 장애 때

메일 전용 리졸버(mail-resolver)가 멈추거나 바깥에 묻지 못하면 엔진의 바깥 DNS 가 모두 실패한다 — 바깥으로 보내는 메일은 MX 를 찾지 못해 대기열에서 다시 시도하고, 받는 메일은 SPF · DKIM · DMARC · DNSBL 검사가 약해진다. 사내 메일 · 웹메일은 그대로 된다. 다만 설정 리로드가 막힌다(엔진이 Pyzor 주소를 풀지 못해 리로드를 통째로 거절 — 아래 3.). 표시는 compose 의 optional dependency "mail-resolver" failed to start 경고, setup 사전 확인의 … 가 떠 있지 않습니다 · … DNSSEC 을 검증한 답을 주지 않습니다, setup · 관리 화면 리로드의 validationFailed — Invalid address: failed to lookup address information 다. 자동으로 공용 DNS 로 넘어가는 길은 두지 않는다 (넘어가면 Spamhaus 가 다시 막고, 장애를 모른 채 지나간다 — 메일 전용 리졸버 "대가"). 아래는 사람이 고르는 길이다.

리졸버부터 고친다 (운영 명령 — 개발은 docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development):
```
sudo docker ps -a --filter "name=${PROJECT_NAME}-mail-resolver"        # Up (healthy) 여야 한다
sudo docker logs --tail 20 "${PROJECT_NAME}-mail-resolver"              # 설정 오류면 파일 · 줄 번호가 나온다
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill . @127.0.0.1 NS  # 바깥(루트)에 묻는가
# 설정을 고쳤으면 리졸버만 다시 만든다 (설정 파일만 바뀌면 compose 가 다시 만들지 않는다 — mail 은 그대로 둔다)
sudo docker compose --env-file .env.production up -d --force-recreate mail-resolver
```
healthy 가 되면 setup 을 돌려 [확인] 메일 전용 리졸버 … 를 본다("운영 배포" 5)와 같은 형태). mail 이 리졸버 없이 떴다면 그 기동은 DANE 이 꺼지고 Pyzor 가 빠진 채다 — setup 의 리로드가 둘 다 다시 만들지만 리로드의 DNSSEC 확인은 로그에 남지 않으므로, 확인하려면 sudo docker compose --env-file .env.production restart mail(몇 초 끊긴다) 뒤 setup 의 [확인] 엔진 기동 로그(…)에 DNSSEC 경고가 없다 를 본다.
mail 이 리졸버 때문에 뜨지 않을 때 — compose 는 리졸버가 unhealthy · 멈춤(설정 오류로 바로 끝남) · 재시작을 되풀이해도 경고만 내고 mail 을 띄운다 (mail 의 depends_on 이 required: false — 2026-10-30 개발에서 셋 다 확인. 리졸버의 healthcheck 가 unhealthy 로 판정할 때까지는 기다린다 — 최대 2분쯤). 그래도 mail 이 Created 에 남았다면(required 를 지운 compose 등) 리졸버를 기다리지 않고 띄운다:
```
sudo docker compose --env-file .env.production up -d --no-deps mail
```
리졸버를 곧 고칠 수 없을 때 — 비상 길: 엔진 DNS 를 공용 DNS 로. 엔진 DNS 를 System 으로 돌려도 소용없다 — mail 컨테이너의 dns: 가 같은 리졸버라 도커 DNS 도 바깥 이름을 그 리졸버에 묻는다. 관리 API(관리 화면의 DNS Resolver 설정과 같다 — 운영은 SSH 터널, "운영 배포")로 @type 을 Quad9 이나 Cloudflare 로 저장한 뒤 리로드가 아니라 mail 을 다시 띄운다 (외부 릴레이와 같은 호출 형식):
```
[["x:DnsResolver/set", { "accountId": "<세션의 urn:stalwart:jmap 계정>", "update": { "singleton": { "@type": "Quad9" } } }, "0"]]
```
```
sudo docker compose --env-file .env.production restart mail     # 몇 초 끊긴다
```
- 리로드(ReloadSettings · 관리 화면의 Reload)는 이때 엔진이 거절한다 — 설정을 다시 만들며 스팸 필터의 Pyzor 주소(public.pyzor.org)를 mail 컨테이너의 DNS(= 죽은 리졸버)로 풀다 실패하면 리로드 전체를 버린다(validationFailed — Invalid address: failed to lookup address information). 기동은 그 항목(Pyzor)만 빼고 뜬다(로그 registry.build-error … SpamPyzor) — 0.16.27 소스 crates/common/src/config/mailstore/spamfilter.rs · crates/common/src/cache/reload.rs. 2026-10-30 개발에서 리졸버의 바깥 길을 끊고 확인했다: System 으로 다시 띄우면 DNSSEC 경고(엔진 DNS 가 안 된다), Quad9 저장 뒤 리로드는 위 거절, restart mail 뒤에는 DNSSEC 경고 없이 떴다(엔진 DNS 가 Quad9 로 된다 — Pyzor 만 빠진 채).
- 엔진은 @type 만 바꾸는 부분 갱신을 받고, 두 값 모두 기본이 "useTls": true(DNS over TLS — 바깥 853/TCP)다. 이 서버에서 바깥 853 이 막혀 있으면 "useTls": false 를 함께 준다(53 UDP · TCP).
- 그동안은 공용 DNS 를 거친다 — 공용 DNS 조회를 거부하는 차단 목록은 답하지 않아 검사가 약해진다(메일은 오간다). mail 컨테이너 자체의 이름 풀기(Pyzor · ACME · getent)는 여전히 리졸버라 안 된다.
- 리졸버를 고친 뒤 setup 을 다시 돌린다 — 사전 확인을 통과하면 [변경] 엔진 DNS — … Custom … · 전 Quad9 처럼 리졸버로 되돌리고 리로드한다(개발은 System) — 그 리로드가 빠졌던 Pyzor 도 다시 만든다. 기동 로그로 DNSSEC 을 확인하려면 그 뒤 restart mail 한 번과 setup([확인] 엔진 기동 로그 …). 운영 setup 은 리졸버가 확인되기 전에는 사전 확인에서 멈춰 엔진 DNS 를 바꾸지 않는다 — 비상 길을 연 채로 돌려도 공용 DNS 가 그대로 남으니 리졸버부터 고친다 (개발 setup 은 [주의] 뒤 이어 가며 System 으로 저장한다 — 개발은 Mailpit 이라 비상 길이 필요 없다).

DNSSEC 이 깨진 도메인 (특정 회사로만 메일이 안 간다)

메일 전용 리졸버는 DNSSEC 을 검증한다 — 서명이 깨진 도메인(만료된 RRSIG · 키를 바꾸다 상위의 DS 를 고치지 못함 등)은 SERVFAIL 이 된다. 그 도메인으로 보내는 메일은 MX 를 찾지 못해 대기열에서 다시 시도하다 끝내 반송되고, 그 도메인에서 오는 메일은 SPF · DKIM · DMARC 조회가 temperror 다. 검증을 켜면서 새로 생길 수 있는 증상이다(검증하지 않는 DNS 로는 답이 왔다). 다른 회사로는 잘 간다면 이것부터 본다.

그 도메인 쪽 문제인지 본다 — 검증을 끄고(CD 비트) 물으면 답이 오는데 검증하면 SERVFAIL 이면 그 도메인의 DNSSEC 이 깨졌다:
```
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill <도메인> @127.0.0.1 MX        # rcode: SERVFAIL
sudo docker exec "${PROJECT_NAME}-mail-resolver" drill -o CD <도메인> @127.0.0.1 MX  # rcode: NOERROR + 답 → DNSSEC 이 깨졌다
```
(예: 시험용으로 일부러 깨 둔 fail01.dnssec.works 는 앞 줄 SERVFAIL, 뒷줄 5.45.109.212 — 2026-10-30.) CD 로 물어도 SERVFAIL 이면 DNSSEC 이 아니라 그 도메인의 DNS 서버가 답하지 않는 것이다 — 아래 예외로 풀리지 않는다. 바깥 도구로도 한 번 더 본다: https://dnsviz.net/ · https://dnssec-analyzer.verisignlabs.com/ (빨간 표시 — 다른 검증 리졸버(Google · Cloudflare)도 같은 SERVFAIL 을 준다).
그 도메인의 관리자에게 알린다 — 그쪽이 고치면 저절로 풀린다(unbound 는 검증 실패를 1분만 기억한다 — val-bogus-ttl 기본값 60).
급하면 그 도메인만 검증 예외로 — mail/resolver/unbound.conf 의 server: 안에 한 줄 더하고 리졸버만 다시 만든다:
```
    domain-insecure: "example.com"
```
```
sudo docker compose --env-file .env.production up -d --force-recreate mail-resolver   # 몇 초 동안 바깥 DNS 가 끊긴다(엔진이 다시 시도한다)
```
그 도메인과 하위 도메인 전체의 DNSSEC 검증을 끈다 — 그 도메인으로 가는 메일의 DANE 도 꺼진다. 다른 도메인은 그대로 검증한다 (시험용 리졸버 컨테이너에서 fail01.dnssec.works 만 SERVFAIL → NOERROR, dnssec.works 는 그대로 ad · fail02.dnssec.works 는 그대로 SERVFAIL — 2026-10-30). 예외는 저장소 파일이라 커밋 기록에 남는다 — 그쪽이 고친 것을 1. 로 확인하면 지운다.

254 KiB Raw Blame History Unescape Escape