운영과 문제 해결

설치 뒤 서버를 오래 안전하게 쓰는 방법(버전·백업·복원·업데이트)과, 자주 만나는 문제의 해결 방법입니다. 서버 명령은 모두 설치 폴더(mailer-kit)에서 실행합니다. 띄우기·다시 띄우기·업데이트는 언제나 sudo ./install.sh … 로 하세요 — docker compose up 을 직접 쓰면 다른 버전이 뜰 수 있습니다.

버전 확인

• 관리 화면 위쪽 이름 옆에 작게 v1.2.3 처럼 나오고, [설치 확인] 탭 "버전" 줄에도 있습니다
• 서버에서 한눈에 보기 (버전·발송 모드·컨테이너·디스크·마지막 백업·새 버전):

sudo ./install.sh status

• 설치 폴더의 mailer.env 에 MAILER_VERSION=1.2.3 처럼 정확한 버전이 적혀 있어야 합니다. 업데이트·되돌리기가 이 값을 기준으로 합니다
• 새 버전 알림: 하루 한 번 소개 사이트(https://mailer.rousme.com/latest.json)를 확인해 [설치 확인] 탭 "새 버전" 줄과 화면 위쪽에 알립니다 (보내는 정보는 없음). 끄려면 mailer.env 에 UPDATE_CHECK_URL=off 를 넣고 sudo ./install.sh. 바뀐 점은 변경 기록

백업

서버 안에만 두면 서버와 함께 잃습니다. 한 달에 한 번은 관리 화면 [백업] 탭에서 비밀번호를 정해 내려받아 내 PC 나 다른 저장소에 두세요. 그 비밀번호를 잊으면 복원할 수 없습니다.

백업에 들어가는 것: DB(계정·주소록·동의 기록·발송 기록·템플릿·API 키·발송 제외), DKIM 키, 비밀번호들, 인증서, 설치값(mailer.env), DMARC 보고서. 들어가지 않는 것: 로그, Mailpit 시험 메일, 보내는 중이던 대기열(복원 때 다시 보내 중복되지 않도록).

복원

백업 파일(.mkbak 또는 .tar.gz)을 서버에 올린 뒤:

sudo ./install.sh restore /root/mailer-backup-mail.example.com-20261001-0330.mkbak

1. .mkbak 이면 내려받을 때 정한 비밀번호를 묻습니다
2. 파일이 손상되지 않았는지 검사하고, 언제·어느 버전에서 만든 백업인지와 지금 서버와 다른 점(도메인 등)을 보여 줍니다
3. 확인하면 지금 상태를 먼저 백업한 뒤 복원합니다 (20~60초 멈춤)
4. 백업의 설치값이 지금과 다르면 어느 쪽을 쓸지 묻습니다
5. 중간에 실패하면 복원 직전 상태로 저절로 되돌아갑니다

지금 버전보다 새 버전에서 만든 백업은 복원하지 않습니다. 먼저 그 버전 이상으로 업데이트 하세요.

업데이트와 되돌리기

sudo ./install.sh update          # 최신 버전으로
sudo ./install.sh update 1.2.4    # 정한 버전으로

1. 발송 중이면 멈춥니다 — 발송이 끝난 뒤 다시 하세요
2. 새 이미지를 받습니다 (비공개면 판매자 토큰을 묻고, 받은 뒤 바로 로그아웃 — 이미지 받기)
3. 바뀐 점(주의할 것 포함)을 보여 주고 확인을 받습니다
4. 업데이트 직전 백업을 만들고 바꿉니다 (20~40초 동안 발송·관리 화면이 멈춤)
5. 새 버전이 제대로 뜨지 않으면 저절로 원래 버전으로 돌아갑니다

업데이트한 뒤 문제가 있으면 바로 전 버전으로:

sudo ./install.sh rollback

DB 형식이 바뀐 업데이트였다면 DB 가 업데이트 직전 백업으로 돌아가므로, 그 사이 쌓인 발송 기록·주소록 변경은 사라집니다 (확인할 때 알려 줌).

새 서버로 옮기기

서버 업체를 바꾸거나 더 큰 서버로 옮길 때. 같은 도메인이면 DKIM 키가 그대로라 DNS 는 A·PTR·SPF 의 IP 만 바꾸면 됩니다.

1. 지금 서버의 관리 화면 [백업] 에서 [지금 백업] → [내려받기] (비밀번호 정하기)
2. 새 서버에 설치 — 같은 도메인·같은 이름으로 답합니다. 그다음 예전 서버와 같은 버전으로 맞춥니다: 예전 서버에서 sudo ./install.sh status 로 버전을 보고, 새 서버가 더 낮으면 sudo ./install.sh update 그버전 (백업은 만든 버전보다 낮은 버전에 복원되지 않습니다)
3. 백업 파일을 새 서버에 올리고 sudo ./install.sh restore 파일 — "백업의 설치값으로 바꿀까요?" 에는 N(지금 것 그대로). 백업의 설치값에는 예전 서버 IP 가 들어 있습니다
4. DNS 바꾸기: mail·mailer 의 A 레코드, SPF 의 ip4: 를 새 IP 로. 새 서버 업체 콘솔에서 PTR
5. [설치 확인] 탭이 모두 통과하면 예전 서버를 끕니다
6. 새 IP 는 평판이 없습니다 — 발송량을 한 번에 옮기지 말고 IP 예열 을 다시 합니다 (앞의 1~2주는 짧게 해도 되는 경우가 많음)

반송 사유별 대처

반송 사유는 [발송 결과] 탭(API 발송 줄을 누르면 처리 과정)과 [발송 로그] 탭에서 봅니다. 앞의 숫자 3자리가 핵심입니다: 5xx 는 영구 실패, 4xx 는 일시 실패(자동으로 다시 보냄).

메일이 반송 없이 스팸함으로만 간다면: 인증 결과(Gmail 원본 보기의 SPF·DKIM·DMARC)를 먼저 보고, 모두 PASS 면 평판·내용 문제입니다 — 양을 줄이고 받는 사람이 기다리는 메일부터 보내며 IP 예열 을 이어 갑니다.

차단 목록(블랙리스트)

스팸 발송원으로 의심되는 IP·도메인을 모아 두는 목록입니다 (Spamhaus·SpamCop·Barracuda 등). 받는 서버들이 참고합니다.

1. 확인: sudo ./install.sh check 의 "IP 평판" 부분, 또는 각 목록 사이트의 조회 페이지(Spamhaus 는 check.spamhaus.org)에서 IP 검색
2. 원인 찾기: 최근에 산 목록·오래된 목록에 보냈는지, 스팸 신고가 많은 메일이 있었는지, 587 계정 비밀번호가 새어 누군가 이 서버로 보냈는지([활동 기록]·[발송 로그])
3. 원인을 고친 뒤, 목록 사이트의 해제(delist) 요청 절차를 따릅니다. 대부분 무료이고 며칠 안에 풀립니다
4. 설치 직후부터 올라 있었다면 예전 사용자의 기록입니다 — 서버 업체에 IP 교체를 요청하는 것이 가장 빠릅니다

587 계정 비밀번호가 새었다고 의심되면 새 비밀번호로 바꿉니다 (메일 서버가 다시 시작되어 30초쯤 멈춤):

sudo docker compose exec james rm /control/smtp-password
sudo docker compose restart james
sudo docker compose exec james cat /control/smtp-password

그 계정을 쓰는 프로그램들의 설정도 새 비밀번호로 바꿉니다. (mailer.env 에 SMTP_PASSWORD 를 직접 적어 둔 경우는 그 값을 바꾸고 sudo ./install.sh 를 다시 실행)

HTTPS 인증서

관리 화면과 메일 서버(587·25)의 인증서는 Let's Encrypt 에서 자동으로 받고 자동으로 갱신합니다 (유효 기간이 짧아 — 지금은 90일, 앞으로 더 짧아질 예정 — 만료 전에 알아서 갱신).

• 남은 날: [설치 확인] 탭 "서버" 표
• "아직 발급 안 됨" 이면: 관리 화면 주소·메일 서버 이름의 A 레코드가 이 서버인지, 서버 업체 방화벽에서 80·443 이 열려 있는지 확인합니다. 고치면 몇 분 안에 받습니다
• 메일 서버 인증서가 새로 나오면 메일 서버에 자동으로 넣고 다시 시작합니다 (발송 중이면 끝난 뒤)
• 짧은 시간에 여러 번 실패하면 Let's Encrypt 가 한동안(최대 몇 시간) 발급을 막습니다. 원인을 고친 뒤 기다리면 됩니다

디스크

• 남은 공간: sudo ./install.sh status 의 디스크 줄, 또는 df -h /
• 로그는 컨테이너마다 크기가 제한되어(10MB × 3개) 스스로 커지지 않습니다. 백업은 개수가 제한됩니다 (매일 14·직접 10·업데이트 전 5·복원 전 5)
• 공간이 모자라면: [백업] 탭에서 오래된 백업 지우기, 업데이트 뒤 남은 예전 이미지 정리 sudo docker image prune, Mailpit [비우기]
• 20% 아래로 떨어지면 서버 디스크를 늘리는 것이 가장 쉽습니다

비밀번호를 잊었을 때

자주 묻는 질문

하루에 몇 통까지 보낼 수 있나요? 서버는 1초에 수십 통을 내보낼 수 있지만, 실제 한계는 받는 쪽이 이 IP·도메인을 얼마나 믿느냐입니다. IP 예열 을 거쳐 늘리세요.

서버를 다시 켜면요? 모든 구성 요소가 자동으로 다시 뜹니다. 화면에서 보내던 작업은 "중단됨" 으로 남고 이어서 보내지 않으므로 [발송] 탭 "최근 작업" 에서 확인하세요. 발송 API 로 받은 메일은 대기열에 남아 있다가 이어서 보냅니다.

발신 도메인을 나중에 더할 수 있나요? sudo ./install.sh --reconfigure 에서 "발신 도메인" 에 쉼표로 더한 뒤, 새 도메인의 SPF·DKIM·DMARC 를 [설치 확인] 탭대로 넣습니다.

서버 IP 가 바뀌었어요. A 레코드·SPF 의 IP·PTR 을 새 IP 로 바꾸고, sudo ./install.sh --reconfigure 에서 "이 서버 공인 IP" 를 고칩니다. 새 IP 는 예열이 다시 필요합니다.

Gmail 에 "구독 취소" 버튼이 안 보여요. 광고 메일에는 수신거부 헤더가 들어 있지만, Gmail 은 발송 이력이 쌓인 발송자에게만 버튼을 보여 줍니다. 시간이 지나면 나타납니다.

다른 프로그램(쇼핑몰 솔루션 등)에서 이 서버로 보낼 수 있나요? 두 가지 방법이 있습니다. 587 포트(SMTP, 아이디 sender·비밀번호는 위)로 넘기거나, 발송 API(연동 가이드)를 씁니다. 발송 API 가 결과 조회·중복 방지·템플릿을 지원해 더 편합니다.

문제가 해결되지 않아요. sudo ./install.sh status 결과와 sudo docker compose logs --tail 100 web james 의 마지막 부분을 판매자에게 보내 주세요. 비밀번호·토큰은 지우고 보내세요.