서버 운영

서버 설치

파발 서버를 인터넷에 공개된 서버 한 대에 도커 컴포즈로 설치하고 운영하는 방법.

파발 서버를 인터넷에 공개된 서버 한 대에 설치하는 방법입니다. 도커 컴포즈로 파발 서버 · PostgreSQL · Caddy(HTTPS) 세 컨테이너를 올리고, 지워지면 안 되는 데이터는 모두 호스트 디렉터리에 바인드합니다. 위에서부터 순서대로 따라 하면 됩니다.

한눈에 보기

준비물

포트

1. 서버 준비

sudo apt update && sudo apt -y upgrade
timedatectl                      # "System clock synchronized: yes" 인지 확인

시간 동기화는 필수입니다. MTProto 메시지 번호가 시각에서 나오므로 서버 시계가 틀어지면 앱이 연결을 되풀이합니다. no 면 sudo timedatectl set-ntp true.

# 방화벽
sudo ufw allow OpenSSH           # 가능하면: sudo ufw allow from <운영자 IP> to any port 22
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw allow 8443/tcp
sudo ufw enable

# 도커 (공식 설치 스크립트)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER     # 다시 로그인하면 sudo 없이 docker
docker compose version            # v2 이상

2. 소스 가져오기

sudo mkdir -p /opt/pabal && sudo chown $USER: /opt/pabal
git clone <저장소 주소> /opt/pabal

개발 컴퓨터에서 복사한다면 키·데이터·로그는 보내지 마세요(rsync --exclude 'keys/' --exclude 'data/' --exclude 'logs/' --exclude '**/target/'). 운영 서버의 RSA 키는 운영 서버가 처음 켜질 때 새로 만듭니다 — 개발용 키를 운영에 쓰면 그 개발 컴퓨터가 운영 트래픽을 풀 수 있는 곳이 됩니다.

3. 데이터 디렉터리 (바인드 마운트)

sudo mkdir -p /srv/pabal/{postgres_data,pabal_server/keys,pabal_server/data,pabal_server/logs,caddy/data,caddy/config,backups}
sudo chown -R 1000:1000 /srv/pabal/pabal_server        # 서버 컨테이너는 uid 1000 으로 돕니다
sudo chown -R $USER: /srv/pabal/backups
sudo chmod 700 /srv/pabal/pabal_server/keys /srv/pabal/backups

4. 설정 파일 .env

cd /opt/pabal/deploy
cp .env.example .env
chmod 600 .env
openssl rand -base64 30 | tr -d '/+=' | cut -c1-32     # 나온 값을 POSTGRES_PASSWORD 에
nano .env

DOMAIN=pabal.me
PUBLIC_IP=203.0.113.10
POSTGRES_PASSWORD=(위에서 만든 값)
PABAL_HOME=/srv/pabal
PABAL_SOURCE=..
PABAL_NETWORK=ssemiya-net
MTPROTO_PORT=8443
HTTP_PORT=80
HTTPS_PORT=443
ADMIN_PORT=8080
ADMIN_TOKEN=
JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=100"
FCM_CREDENTIALS=
FCM_PROJECT_ID=
PUSH_PREVIEWS=true

운영용 컴포즈 파일은 테스트 번호를 끈 채(TELEGRAM_TEST_NUMBERS=false) 서버를 켭니다. 서버가 읽는 설정 값 전체는 관리와 설정 — 환경 변수에 있습니다.

5. DNS

dig +short pabal.me        # 203.0.113.10 이 나와야 함 (반영에 몇 분~몇 시간)

DNS 가 서버를 가리키기 전에 켜도 됩니다. Caddy 가 인증서를 받을 때까지 알아서 다시 시도합니다.

6. 빌드하고 켜기

cd /opt/pabal/deploy
docker network inspect ssemiya-net >/dev/null 2>&1 || docker network create ssemiya-net   # 한 번만
docker compose up -d --build       # 처음엔 몇 분 (Maven 이 라이브러리를 받음)
docker compose ps                  # pabal-server, pabal-postgres, pabal-caddy 가 running (healthy)
docker compose logs -f pabal-server      # Ctrl+C 로 빠져나옴

처음 켤 때 로그에 이런 줄이 나옵니다.

WARN  ServerKeys - Generated a new RSA key at /app/keys/private.pem (fingerprint -3898654385185406269). Clients must embed /app/keys/private.pem.pub
INFO  TelegramServer - JDBC persistence active (jdbc:postgresql://pabal-postgres:5432/pabal)
INFO  BotFather - BotFather is user 100000
INFO  AdminToken - Created the admin token in /app/data/admin-token
INFO  TelegramServer - Website: http://0.0.0.0:8080/ (published at https://pabal.me/)

• 첫 줄은 WARN 이지만 정상입니다(처음 한 번만 키를 만든다는 알림). 다음부터는 Loaded RSA key … (fingerprint …) 가 나옵니다. fingerprint 는 서버마다 다릅니다.
• 테이블은 서버가 켜질 때 스스로 만듭니다.

7. 확인

# 바깥(내 컴퓨터)에서
curl -sI https://pabal.me/ | head -1                              # HTTP/2 200
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/docs/    # 200 — 이 문서
curl -s -o /dev/null -w '%{http_code}\n' https://pabal.me/admin/   # 404 — 관리 화면은 공개되지 않음
curl -s https://pabal.me/docs/server-key.pem | head -1             # -----BEGIN RSA PUBLIC KEY-----
nc -vz 203.0.113.10 8443                                          # succeeded — 앱 포트

# 서버에서
curl -s http://127.0.0.1:8080/health          # {"status":"UP",…}
ls -l /srv/pabal/pabal_server/keys                  # private.pem(600), private.pem.pub

8. 관리 화면과 첫 설정

# 내 컴퓨터에서 (켜 둔 채로)
ssh -N -L 8080:127.0.0.1:8080 <사용자>@203.0.113.10

# 토큰은 서버에서
sudo cat /srv/pabal/pabal_server/data/admin-token

브라우저로 http://localhost:8080/admin/ 을 열고 토큰을 넣습니다. 운영 전에 꼭 할 설정(자세한 것은 관리와 설정):

1. 코드 전달 방식을 SMS 또는 이메일로. "관리 화면" 방식은 운영자가 코드를 하나하나 알려 줘야 합니다.
2. SMS 또는 이메일(SMTP) 값을 넣고 저장 → 테스트 발송으로 실제로 오는지 확인.
3. 테스트 번호가 꺼져 있는지 확인. 켜면 누구나 +99966… 번호로 로그인할 수 있습니다.
4. 필요하면 새 가입 허용을 끄고 시작해 초대할 사람만 먼저 받습니다.

9. 앱을 이 서버에 연결

앱은 서버 IP · 포트 · 공개키를 몸속에 넣고 빌드됩니다. 이 서버의 공개키로 다시 빌드해야 이 서버에 붙습니다. 맥에서:

# 1. 이 서버의 공개키 (비밀키가 아니라 공개키 — 문서 사이트에서 받아도 됩니다)
curl -s -o keys/production.pem.pub https://pabal.me/docs/server-key.pem

# 2. 앱 소스를 이 서버로 향하게 + 브랜드 적용
python3 scripts/tdesktop/point_to_server.py ~/Developer/tdesktop \
    --host 203.0.113.10 --port 8443 --key keys/production.pem.pub
python3 scripts/tdesktop/apply_branding.py ~/Developer/tdesktop

그다음 저장소의 docs/tdesktop-build-guide.md 5단계(configure)와 6단계(빌드)를 합니다. 결과 out/Debug/Pabal.app 은 다른 이름으로 복사해 두세요 — 같은 소스를 다른 서버용으로 다시 빌드하면 덮어써집니다.

안드로이드·아이폰·윈도우 앱은 저장소의 docs/mobile-apps-guide.md 에 같은 방식(서버 주소·공개키를 넣는 스크립트 → 빌드)이 있습니다. 안드로이드 앱에 푸시 알림을 넣으려면 빌드하기 전에 10단계의 Firebase 앱 설정이 있어야 합니다.

10. 안드로이드 푸시 알림 (선택)

안드로이드는 화면에서 벗어난 앱을 곧 재웁니다. 푸시를 켜지 않으면 앱을 열어 둔 동안에만 메시지가 뜨고 전화가 울립니다. 푸시는 Google 의 Firebase 클라우드 메시징(FCM)으로 보내고(무료), 알림 내용(보낸 사람 이름, 메시지 미리보기)은 서버가 그 휴대폰만 가진 키로 암호화하므로 Google 은 읽지 못합니다.

Firebase 프로젝트 만들기

1. Firebase 콘솔에서 프로젝트 추가. 이름은 아무것이나 괜찮고, Google 애널리틱스는 필요 없습니다.
2. 프로젝트 설정 → 일반 → 내 앱 → Android 앱 추가. 패키지 이름에 me.pabal.android(앱 빌드 스크립트가 앱에 붙이는 이름)를 넣습니다. 인증서 지문(SHA-1)은 푸시에 필요하지 않습니다.
3. 그 앱의 google-services.json 을 내려받습니다. 앱에 넣는 설정이며 비밀이 아닙니다.
4. 프로젝트 설정 → 서비스 계정 → 새 비공개 키 생성으로 JSON 파일을 받아 이름을 firebase-service-account.json 으로 바꿉니다. 이 파일은 비밀입니다 — 저장소·채팅·.env 에 내용을 넣지 마세요.
5. 프로젝트 설정 → 클라우드 메시징에서 Firebase Cloud Messaging API(V1) 가 사용 설정되어 있는지 봅니다(새 프로젝트는 보통 켜져 있습니다).

앱에 앱 설정 넣기

안드로이드 앱을 빌드하기 전에 google-services.json 을 빌드 스크립트가 찾는 곳에 둡니다. 스크립트는 파일을 검사한 뒤(me.pabal.android 가 등록된 프로젝트인지, 비밀 키를 잘못 준 것은 아닌지) 앱 소스에 넣습니다.

mkdir -p ~/.pabal/android
cp ~/Downloads/google-services.json ~/.pabal/android/     # 다른 곳에 두려면 apply_branding.py 에 --google-services 경로
python3 scripts/android/point_to_server.py <안드로이드 소스> \
    --host 203.0.113.10 --port 8443 --key keys/production.pem.pub
python3 scripts/android/apply_branding.py <안드로이드 소스>
# 끝에 "Firebase: project <프로젝트 ID>" 가 나와야 합니다. pabal-placeholder 가 보이면 푸시 없는 앱이 됩니다

그다음 빌드는 저장소의 docs/mobile-apps-guide.md "Android 앱" 절을 따릅니다. 푸시가 들어가기 전의 앱을 쓰던 휴대폰도 새로 빌드한 앱으로 업데이트해야 알림이 옵니다.

서버에 비밀 키 두기

sudo cp firebase-service-account.json /srv/pabal/pabal_server/keys/
sudo chown 1000:1000 /srv/pabal/pabal_server/keys/firebase-service-account.json    # 서버 컨테이너의 사용자
sudo chmod 600 /srv/pabal/pabal_server/keys/firebase-service-account.json

.env 에 한 줄을 넣습니다. 컨테이너 안에서 pabal_server/keys 는 /app/keys 입니다.

FCM_CREDENTIALS=/app/keys/firebase-service-account.json

docker compose up -d pabal-server
docker compose logs pabal-server | grep -i push

INFO  TelegramServer - Push notifications on: Firebase project <프로젝트 ID>, 0 device registrations, message text included (encrypted per device)

• 이 줄이 보이면 켜진 것입니다. 파일을 못 읽거나 형식이 틀리면 Push notifications are off: … 에 이유가 나옵니다(파일 내용은 로그에 나오지 않습니다).
• PUSH_PREVIEWS=false 면 줄 끝이 message text left out 이 되고, 알림에 메시지 내용 없이 보낸 사람만 보입니다.
• 컨테이너에서 oauth2.googleapis.com, fcm.googleapis.com(443)으로 나가는 연결이 열려 있어야 합니다.

확인

1. 휴대폰에 새로 빌드한 앱을 설치(또는 업데이트)하고 한 번 엽니다. 서버 로그에 Push device registered: user … type 2 token … (push key 256 bytes) 가 찍힙니다. 토큰은 지문으로만 남습니다.
2. 최근 앱 목록에서 앱을 밀어 닫습니다. 설정의 "강제 종료"는 쓰지 마세요 — 안드로이드가 앱을 다시 직접 열 때까지 푸시를 전하지 않습니다.
3. 다른 계정으로 메시지를 보내면 로그에 Push MESSAGE_TEXT to user …: sent 가 찍히고 휴대폰에 알림이 뜹니다.

• 개인정보 처리방침: 관리 화면 → 설정 → 운영자 정보의 처리 위탁과 국외 이전에 Google LLC(Firebase 클라우드 메시징, 미국)를 적어 넣으세요. 방침 본문에는 FCM 을 거친다는 문장이 이미 있습니다. Google Play 의 "데이터 보안" 양식에도 같은 내용을 적습니다.
• 키가 새어 나갔다면 Firebase 콘솔에서 그 키를 삭제하고 새로 받아 파일을 바꾼 뒤 서버를 다시 켭니다. 앱은 다시 빌드하지 않아도 됩니다.

11. 아이폰 푸시 알림 (선택)

아이폰도 화면에서 벗어난 앱을 곧 멈춥니다. 푸시를 켜지 않으면 앱을 열어 둔 동안에만 메시지와 전화를 받습니다. 푸시는 Apple 푸시 알림 서비스(APNs)로 보내고, 안드로이드와 같은 방식으로 알림 내용은 그 아이폰만 가진 키로 암호화합니다. Apple 이 볼 수 있는 알림 문구는 앱 이름과 "새 알림이 있습니다" 같은 내용 없는 말뿐이고, 아이폰 앱 속 알림 확장(Notification Service Extension)이 암호문을 풀어 보낸 사람과 메시지로 바꿔 보여 줍니다.

• 등록: 앱은 켜질 때마다 계정마다 두 가지를 등록합니다 — 알림용(type 1)과 전화용(VoIP, type 9). 서버는 등록과 함께 앱의 언어(겉 문구를 쓸 말)와 빌드 번호를 기억합니다.
• 메시지는 알림으로 갑니다. 알림을 끈 대화방에는 아무것도 보내지 않습니다. 다른 기기에서 읽거나 지운 것은 소리 없는 백그라운드 푸시로 알려, 떠 있던 알림을 앱이 치웁니다.
• 전화는 VoIP 로 보내면 잠긴 화면에서도 CallKit 전화 화면이 뜹니다. 다만 VoIP 를 받은 앱은 곧바로 CallKit 에 전화를 알려야 하고, 못 하면 iOS 가 앱을 죽이고 되풀이되면 VoIP 를 더 보내 주지 않습니다. 그래서 그렇게 만든 빌드부터만 APNS_VOIP_MIN_BUILD 로 켜고, 그 전에는 전화도 알림으로 갑니다.

APNs 키 만들기

1. Apple Developer → Certificates, IDs & Profiles → Keys → +. 앱에 서명한 팀의 계정이어야 합니다.
2. 이름을 적고 Apple Push Notifications service (APNs) 에 체크합니다. 환경은 Sandbox & Production, 범위는 팀 전체(Team Scoped)로 둡니다 — 알림과 VoIP 두 곳에 보내기 때문입니다.
3. Register → Download. AuthKey_<키 ID>.p8 은 한 번만 내려받을 수 있습니다. 이 파일은 비밀입니다 — 저장소·채팅·.env 에 내용을 넣지 마세요.

서버에 키 두기

sudo cp AuthKey_<키 ID>.p8 /srv/pabal/pabal_server/keys/
sudo chown 1000:1000 /srv/pabal/pabal_server/keys/AuthKey_<키 ID>.p8    # 서버 컨테이너의 사용자
sudo chmod 600 /srv/pabal/pabal_server/keys/AuthKey_<키 ID>.p8

.env 에 넣습니다. 컨테이너 안에서 pabal_server/keys 는 /app/keys 입니다.

APNS_KEY=/app/keys/AuthKey_<키 ID>.p8
APNS_TEAM_ID=4Z8R468M2D
APNS_TOPIC=me.pabal.ios
APNS_MIN_BUILD=4
APNS_VOIP_MIN_BUILD=

docker compose up -d pabal-server
docker compose logs pabal-server | grep -i push

INFO  TelegramServer - iPhone push notifications on: APNs key <키 ID> of team 4Z8R468M2D, topic me.pabal.ios, builds from 4, calls as alerts (TELEGRAM_APNS_VOIP_MIN_BUILD not set)

• 이 줄이 보이면 켜진 것입니다. 키 파일을 못 읽거나 형식이 틀리면 iPhone push notifications are off: … 에 이유가 나옵니다(파일 내용은 로그에 나오지 않습니다). 안드로이드(FCM)와는 따로 켜고 끕니다 — 한쪽만 켜도 됩니다.
• 컨테이너에서 api.push.apple.com(443, HTTP/2)으로 나가는 연결이 열려 있어야 합니다. Xcode 로 기기에 직접 설치한 디버그 빌드는 api.sandbox.push.apple.com 으로 갑니다(앱이 등록할 때 알려 줍니다).

확인

1. 실제 아이폰에서 앱을 한 번 열고 알림을 허용합니다. 서버 로그에 Push device registered: user … type 1 token … (push key 256 bytes, build …) 와 type 9 줄이 찍힙니다. 시뮬레이터로는 확인할 수 없습니다 — APNs 토큰도 CallKit 도 없습니다.
2. 앱을 위로 밀어 닫습니다.
3. 다른 계정으로 메시지를 보내면 로그에 Push MESSAGE_TEXT to user …: sent 가 찍히고 잠금 화면에 보낸 사람과 내용이 뜹니다.

• 개인정보 처리방침: 관리 화면 → 설정 → 운영자 정보의 처리 위탁과 국외 이전에 Apple Inc.(Apple 푸시 알림 서비스, 미국)를 적어 넣으세요. 방침 본문에는 APNs 를 거친다는 문장이 이미 있습니다. App Store Connect 의 앱 개인정보 설문에서 기기 ID(푸시 토큰) 항목도 확인합니다.
• 키가 새어 나갔다면 개발자 계정에서 그 키를 Revoke 하고 새로 만들어 파일을 바꾼 뒤 서버를 다시 켭니다. 앱은 다시 빌드하지 않아도 됩니다.

12. 음성 봇 (선택)

음성 봇은 사람이 앱에서 봇에게 전화를 걸면 AI 음성 모델이 받는 기능입니다(봇 주인을 위한 설명은 음성 봇). 서버에 부품 두 가지가 더 붙어야 하고, 법률 문서와 앱 빌드가 갖춰져야 켜집니다. 기본은 꺼져 있습니다.

켜지는 조건

시험 서버(TELEGRAM_TEST_NUMBERS=true)에서만 TELEGRAM_VOICE_NOTICE_CHECK=off 로 법률 절 확인을 건너뛸 수 있고, TELEGRAM_VOICE_BOTS(모든 봇 *)·TELEGRAM_VOICE_TESTERS=* 로 누구나 시험할 수 있습니다. 운영에서는 쓰지 마세요 — 운영 서버는 TELEGRAM_VOICE_BOTS 를 경고와 함께 무시합니다.

통화 중계 (coturn)

• 리눅스 서버라면 컴포즈의 pabal-turn(COMPOSE_PROFILES=turn)을 씁니다. .env 의 TURN_SECRET(openssl rand -hex 32)을 정하고, 공유기·방화벽에서 TURN_PORT(3478, udp·tcp)와 TURN_MIN_PORT~TURN_MAX_PORT(49160~49200, udp)를 엽니다. 범위를 늘리면 공유기·.env 를 함께 바꿉니다.
• macOS 의 Docker Desktop 에서는 coturn 을 컨테이너로 돌리지 마세요. 모든 발신자가 192.168.65.1 로 보여 중계 허락이 맞지 않고, 겉으로는 멀쩡한데 소리가 모두 버려집니다. 맥 서버에서는 coturn 을 직접 설치합니다(deploy/turnserver.conf.example, docs/turn-relay-guide.md).
• 게이트웨이에게 줄 중계 주소는 서버의 LAN 주소입니다: 서버의 TELEGRAM_VOICE_TURN_HOST 와 게이트웨이의 VOICE_TURN_HOST 에 같은 값을 둡니다. host.docker.internal 로는 닿지 않았고, 127.0.0.1 로는 할당이 끝나지 않았습니다. 앱에게는 공개 주소(TURN_HOST)가 그대로 갑니다.
• 바깥망에서 deploy/check_relay.py --data 로 소리가 실제로 건너가는지 확인합니다. STUN 이 답하고 할당이 돼도 소리가 안 가는 경우가 있습니다.

Vertex AI 키

1. Google Cloud 프로젝트에서 Agent Platform API(옛 이름 Vertex AI API, aiplatform.googleapis.com)를 켭니다. 결제 계정이 연결돼 있어야 합니다. Gemini Developer API(AI Studio 키)는 쓰지 않습니다.
2. 서비스 계정을 하나 만들고 역할은 roles/aiplatform.user 하나만 줍니다(더 좁히려면 aiplatform.endpoints.predict 권한 하나짜리 커스텀 역할). 운영용 키는 개발용과 따로 만듭니다.
3. JSON 키를 받아 저장소·.env 밖, 예를 들어 /srv/pabal/pabal_voice/secrets/vertex-sa.json 에 두고, 게이트웨이의 사용자만 읽게 합니다(리눅스: chown 10001:10001, chmod 400). 누구나 읽을 수 있으면 게이트웨이가 시작을 거부합니다.
4. 실시간 모델은 us-central1(미국 아이오와)에만 있습니다(2026-09-26 확인). 통화 소리가 미국으로 간다는 것을 개인정보처리방침과 확인 창이 말해야 하고, 앱의 확인 창에 적힌 지역과 게이트웨이의 지역(VOICE_VERTEX_REGION)이 같아야 서버가 그 게이트웨이에 통화를 줍니다.
5. 할 일: 예산 알림, 동시 세션 할당량(게이트웨이 용량의 두 배), 그리고 Vertex 의 데이터 캐시(켜져 있으면 입출력을 메모리에 최대 24시간 둡니다) — 확인 창은 "Google 은 대답을 만든 뒤 소리와 글을 보관하지 않는다"고 말하므로, 캐시를 끄기 전에는 그 말과 맞지 않습니다. 권장: 공개 전에 데이터 캐시를 끄고(저장소 docs/voice-bots/vertex-setup.md 9절), 키의 역할을 예측 권한 하나로 좁히세요(같은 문서 10절).

링크와 서버 설정

링크 비밀은 서버와 게이트웨이가 같은 값을 파일로 읽습니다. 링크는 암호화되지 않으므로 두 컨테이너만 붙는 전용 망에만 둡니다 — 다른 스택과 함께 쓰는 ssemiya-net 이나 LAN 에 두지 마세요. 포트는 공개하지 않습니다.

(umask 077; openssl rand -hex 32 > /tmp/voice-link.secret)
sudo install -m 400 -o 1000 /tmp/voice-link.secret /srv/pabal/pabal_server/keys/voice-link.secret   # 서버(uid 1000)의 것
sudo install -d -m 700 -o 10001 /srv/pabal/pabal_voice/secrets
sudo install -m 400 -o 10001 /tmp/voice-link.secret /srv/pabal/pabal_voice/secrets/voice-link.secret # 게이트웨이(uid 10001)의 것
shred -u /tmp/voice-link.secret

.env 에 넣는 값입니다. 덧붙이는 파일이 이 값으로 pabal-server 에 음성 설정(TELEGRAM_VOICE_*)과 링크 망을 더합니다.

COMPOSE_FILE=docker-compose.yml:docker-compose.voice.yml
COMPOSE_PROFILES=voice                              # 다른 프로파일(turn 등)이 있으면 쉼표로 함께
VOICE_LINK_SECRET_FILE=/app/keys/voice-link.secret  # 컨테이너 안 경로. 비우면 음성 꺼짐
VOICE_TURN_HOST=192.168.1.64                        # 서버의 LAN 주소 (coturn 이 듣는 곳)
VOICE_TESTERS=100001                                # 공개 전에 걸 수 있는 사람의 id (관리 화면에서도 넣음)

• 덧붙이는 파일은 서버를 내부 전용 망 pabal-voice-link(10.231.53.0/29 — 서버 .2, 게이트웨이 .3)에 붙이고, 서버는 그 망의 자기 주소에서만 듣습니다(0.0.0.0 이면 함께 붙은 공유 망에서도 열립니다). 이 범위가 LAN·VPN·다른 도커 망과 겹치면 VOICE_LINK_SUBNET·VOICE_LINK_SERVER_IP·VOICE_LINK_GATEWAY_IP 셋을 함께 바꿉니다.
• 루프백이 아닌 주소에 묶으려면 TELEGRAM_VOICE_LINK_ANY_ADDRESS=true 가 있어야 하고, 공인 주소에는 절대 묶이지 않습니다. 서버 로그가 링크가 보는 망을 알려 줍니다.
• 인증 전 연결은 업그레이드 3초·hello 3초, 한 주소에서 2개, 모두 16연결까지만 받습니다.
• 음성 관련 서버 설정 전체는 관리와 설정 — 음성 봇 환경 변수에 있습니다.

게이트웨이 (pabal-voice)

cd /opt/pabal
docker build -t pabal-voice:latest voice/                                       # 이 컴퓨터의 CPU 용
docker buildx build --platform linux/amd64 -t pabal-voice:latest --load voice/  # 인텔 서버용
cd deploy && docker compose up -d                                         # .env 의 COMPOSE_FILE·COMPOSE_PROFILES 대로

이미지는 해시로 고정한 파이썬 3.12, 컴파일러·pip 없음, uid 10001 로 돕니다. ntgcalls 는 리눅스 x86_64/aarch64 와 macOS arm64 만 있어 인텔 맥에서는 도커로만 돌립니다. 덧붙이는 파일의 pabal-voice 는 이 이미지를 빌드하지 않고 씁니다(image: pabal-voice:latest). 다른 컴퓨터에서 서버 CPU 용으로 만들어 보내려면 deploy/ship.sh <user@host> <폴더> --voice 를 씁니다(바로 전 이미지는 pabal-voice:previous 로 남습니다). 아래는 그 파일의 게이트웨이 서비스를 줄인 것입니다.

  pabal-voice:                             # deploy/docker-compose.voice.yml 에서 (줄임)
    image: pabal-voice:latest
    profiles: [voice]
    init: true
    stop_grace_period: 40s                 # VOICE_DRAIN_SECONDS(20) 보다 길게
    security_opt: ["no-new-privileges:true"]
    cap_drop: [ALL]
    mem_limit: ${VOICE_MEMORY:-1g}
    ulimits:
      core: 0
    environment:
      VOICE_LINK_URL: ws://${VOICE_LINK_SERVER_IP:-10.231.53.2}:8095/voice/link
      VOICE_LINK_SECRET_FILE: /run/secrets/voice-link.secret
      VOICE_ENGINE: gemini
      VOICE_VERTEX_KEY_FILE: /run/secrets/vertex-sa.json
      VOICE_VERTEX_REGION: us-central1
      VOICE_TURN_HOST: ${VOICE_TURN_HOST:-}  # 서버의 TELEGRAM_VOICE_TURN_HOST 와 같은 값
      VOICE_CAPACITY: ${VOICE_CAPACITY:-2}
      VOICE_DAILY_MODEL_MINUTES: ${VOICE_DAILY_MODEL_MINUTES:-60}
      VOICE_SAFETY_THRESHOLD: ${VOICE_SAFETY_THRESHOLD:-MEDIUM}   # 시험자 통화: 운영자가 확인할 가정(아래)
      VOICE_BYOK: "false"
      VOICE_STREAM: "false"
    volumes:
      - ${PABAL_HOME:-/srv/pabal}/pabal_voice/secrets:/run/secrets:ro   # 링크 비밀과 Vertex 키 — backup.sh 에 들어가지 않음
      - pabal_voice_state:/var/lib/pabal-voice
    networks:
      pabal-voice-link:                    # 서버와만 쓰는 링크 망 (internal)
        ipv4_address: ${VOICE_LINK_GATEWAY_IP:-10.231.53.3}
      pabal-voice-out: {}                  # 바깥(Google·중계)으로 나가는 자기 망

• 게이트웨이는 링크 말고도 바깥으로 나가는 길이 있어야 합니다: Google(us-central1-aiplatform.googleapis.com:443)과 통화 중계(UDP). 링크 망은 internal: true 라 바깥으로 나갈 수 없으므로, 위처럼 pabal-voice-out 망을 하나 더 붙입니다.
• Landlock: 모델이나 원음 모드를 쓰는 게이트웨이는 리눅스 커널의 Landlock(5.13 이상, 도커 기본 seccomp 에서 됨)이 없으면 시작을 거부합니다(종료 코드 2). 발신자가 보내는 것을 네이티브 코드로 다루는 미디어 작업 프로세스가 키 파일을 읽지 못하게 스스로 잠그기 때문입니다. 컨테이너 안에서 비밀 파일을 /app·/opt·/usr·/lib·/etc 아래로 마운트하지 마세요(/run/secrets 는 괜찮음 — 위 예처럼). VOICE_ALLOW_NO_LANDLOCK=true 는 개발용 맥 전용입니다. macOS Docker Desktop 에서 Landlock 이 되는지는 확인하지 않았습니다.
• 메모리: 통화 하나에 미디어 60~100 MB + 엔진 30~40 MB. 용량 8(VOICE_CAPACITY)과 예비 한 쌍이면 약 1.3 GB. 덧붙이는 파일의 기본은 용량 2·메모리 1 GB(VOICE_MEMORY)입니다.
• 안전 필터 VOICE_SAFETY_THRESHOLD 의 게이트웨이 기본은 LOW(가장 엄격)인데, 측정에서 멀쩡한 한국어 말 172개 중 13개를 영어 거절로 바꿨습니다(MEDIUM 은 69개 중 0개). 시험자 통화는 MEDIUM 을 명시하는 것이 저장소의 가정이며, 기본값을 바꾸기 전에는 레드팀 시험이 필요합니다.
• 한도: 게이트웨이의 기본은 한 통화 600초·40만 토큰·분당 30턴, 하루(UTC) 모델 300분·800만 토큰이고, 덧붙이는 파일은 하루를 60분·160만 토큰으로 정합니다(VOICE_DAILY_MODEL_*, 넘으면 새 통화는 통화 중). OpenAI 엔진은 가짜 서버로만 시험했고 꺼져 있으며, 엔진 사이의 자동 전환은 없습니다.
• 언어: 게이트웨이는 서버에 붙을 때 자기가 통화할 수 있는 봇 언어를 밝히고(0.7.0 부터 9개 모두), 서버는 봇의 언어로 통화하는 게이트웨이에만 그 봇의 통화를 줍니다 — 언어를 밝히지 않는 옛 게이트웨이(0.6.0)에는 한국어·영어 봇만 갑니다. 안내 녹음은 이미지의 assets/ 에 있고, 어느 녹음이 검토를 마쳤는지는 assets/assets.json 이 정합니다. 이 파일이 없으면 AI 안내를 싣지 못해 통화를 받지 못합니다(시작 로그에 ERROR). 검토를 마치지 않은 녹음(지금은 한국어·영어 밖의 모든 언어)은 틀지 않고, 그 언어의 발신자는 영어 안내를 듣습니다. VOICE_DRAFT_NOTICES=true 는 초안 녹음까지 트는 시험 서버 전용 스위치이고, VOICE_ALLOW_TEST_URLS=true 가 함께 없으면 게이트웨이가 시작하지 않습니다. VOICE_NOTICE_LANG(서버가 발신자의 언어를 알려 주지 않을 때의 안내 언어, 기본 ko)는 녹음 언어 10개(ko en ja zh fr es id vi km ar) 중 하나, VOICE_LANGUAGE(봇 주인 설정이 없는 통화의 봇 언어, 기본 ko-KR)는 봇 언어 목록의 id(음성 봇 — 목소리와 언어) 중 하나여야 합니다.
• 로그에는 링크 비밀·키·소리·대화 글·지시문이 남지 않습니다. SIGTERM 이면 새 통화를 받지 않고 진행 중 통화에 VOICE_DRAIN_SECONDS(기본 20초)를 준 뒤 끝냅니다.

확인

docker compose logs pabal-server | grep -E "Voice|voice"
docker compose logs pabal-voice | head -20

INFO  TelegramServer - Voice bots on: gateways connect to ws://10.231.53.2:8095/voice/link; bots 0 listed, 2 calls each at most
INFO  VoiceGatewayLink - Voice gateway link listening on ws://10.231.53.2:8095/voice/link (망)
INFO  TelegramServer - Voice bot callers: patched apps only (desktop pabal-bc1+, Android 62151+, iOS 5+), recipients google.vertex.gemini-live@us-central1, testers 0 listed + the admin page's
INFO  VoiceGatewayLink - Voice gateway pabal-voice-1 (boot 823c9600d05e811847ce95a8f1ba9efa) connected: new session, capacity 2, features […], audio to google.vertex.gemini-live@us-central1

• Voice bots are off: … 는 링크 비밀이 없거나 읽을 수 없거나 32바이트가 아닐 때, 줄 끝의 — but without a TURN relay every bot call is busy 는 중계가 없을 때입니다.
• ERROR Voice bots are on, but no bot is callable: the privacy policy … has no id="bot-calls" section 가 보이면 사이트의 방침에 봇 통화 절을 먼저 게시해야 합니다.
• 게이트웨이가 붙으면 서버 로그의 features 에 bot_settings·end_call·context·tools 와, 주인 키를 돌리는 게이트웨이면 byok, 대화 기록 안내 음성이 있으면 transcripts 가 보입니다(순서는 그때마다 다름). audio to 는 앱의 확인 창이 말하는 받는 곳과 같아야 합니다.
• 게이트웨이 쪽 첫 줄에 starting as pabal-voice-1 (capacity 2, … engine gemini, audio to google.vertex.gemini-live@us-central1), 모델 줄에 session resumption off; no failover, 그리고 media workers sandbox themselves with Landlock (ABI N) 이 나와야 합니다. recordings for the callers' notices in: Korean, English 는 발신자 안내를 틀 수 있는 언어입니다(초안까지 트는 시험 서버면 (drafts included: …) 가 붙음).
• 그다음 관리 화면의 음성 탭(관리와 설정 — 음성 탭)에서 게이트웨이가 붙었는지 보고, 시험자를 넣고, 봇을 허용합니다.

마스터 키 (자기 키 · 원음 모드)

봇 주인의 모델 키와 원음 모드의 비밀은 이 키로 감싸 저장합니다. 백업과 함께 복사되지 않는 곳에 둬야 합니다.

sudo install -d -m 700 -o 1000 -g 1000 /etc/pabal/voice                 # /srv/pabal 밖, 700
sudo sh -c 'umask 077; openssl rand -hex 32 > /etc/pabal/voice/voice-master.key'
sudo chown 1000:1000 /etc/pabal/voice/voice-master.key

      TELEGRAM_VOICE_KEYS_MASTER_FILE: /app/secrets/voice-master.key
    volumes:
      - /etc/pabal/voice:/app/secrets:ro

• 데이터 폴더·RSA 키 폴더 안이나 그 옆이면, 폴더가 다른 사용자에게 조금이라도 열려 있으면(700 이 아니면) 서버가 쓰지 않습니다(Voice keys off: …). 파일이 없으면 첫 키를 받을 때 서버가 만듭니다(읽기 전용 마운트면 위처럼 직접 만드세요).
• 백업에 넣지 말고, 오프라인 사본을 하나 따로 둡니다. 잃으면 모든 봇 주인이 키를 다시 정해야 합니다. 교체할 때는 TELEGRAM_VOICE_KEYS_PREVIOUS_MASTER_FILE 에 옛 키를 주고 켠 뒤 로그를 확인하고 옛 파일을 지웁니다.
• 마스터 키가 있어도 자기 키는 앱이 자기 키 봇의 확인 창(2판)을 보여 준 뒤 TELEGRAM_VOICE_OWN_KEYS_APPS_READY=true 를 줄 때까지 받지 않습니다. 원음 모드는 원음 확인 창이 든 앱 빌드를 TELEGRAM_VOICE_STREAM_MIN_BUILD_DESKTOP·_ANDROID·_IOS 로 알려야 걸 수 있고(기본 0 = 아무도 못 검), 게이트웨이에 VOICE_STREAM=true 와 이 배포의 공인 IP(VOICE_STREAM_DENY_ADDRESSES)가 있어야 합니다.

MCP 부품 (선택)

봇 주인이 등록한 MCP 서버를 통화 중에 부르는 부품입니다. 기본은 꺼져 있고, deploy/docker-compose.mcp.yml(프로파일 mcp)로 세 컨테이너를 더합니다.

docker compose -f docker-compose.yml -f docker-compose.mcp.yml --profile mcp up -d

• 켜려면 TELEGRAM_MCP_EGRESS_OWN_ADDRESSES(파발의 공인 주소들, 필수)와 키 파일들(링크 비밀, K_grant, 설치 키 — 모두 /srv/pabal 밖 700 폴더)이 있어야 하고, 사이트에 방침의 bot-calls-mcp 절과 약관의 봇 주인 절이 있어야 합니다. 한 번 할 설정은 docker-compose.mcp.yml 맨 위 주석에 순서대로 있습니다. 볼트와 서명 키는 백업에 넣지 않습니다.
• 앱이 확인 창에 봇의 MCP 받는 곳을 보여 주게 된 뒤 TELEGRAM_MCP_APPS_READY=true 를 줍니다. 그 전에는 등록만 되고 어떤 통화도 MCP 도구를 싣지 않습니다.
• MCP 요청이 나갈 전용 송신 주소를 따로 두는 것은 코드의 조건이 아니라 운영 결정입니다(발신자의 말이 제3자 서버로 가는 출구이므로).
• 켜지면 로그에 MCP tools on: pabal-mcp dials …; issuer …; ports …; own addresses N; clock by NTP …. deploy/ship.sh <서버> <폴더> --mcp 는 세 이미지를 만들어 싣고 override 파일을 복사할 뿐 아무것도 켜지 않습니다(리눅스 도커에서 돌려 본 적은 없음).

애플 워치 입구 (선택, 준비 중)

애플 워치 앱은 MTProto 대신 서버의 워치 API(HTTPS JSON, /api/watch/v1/)로 로그인하고 전화를 걸며, 통화 소리는 소리 입구(pabal-voice-edge, WSS)를 거쳐 게이트웨이에 닿습니다. 통화 중계(coturn)는 쓰지 않습니다. 기본은 꺼져 있습니다.

• 게이트웨이: VOICE_DIRECT=true 와 VOICE_EDGE_DIR(입구와 함께 쓰는 소켓 폴더, 기본 /run/pabal-voice-edge). 워치 통화는 16 kHz 엔진(Gemini)이나 에코로만 됩니다.
• 소리 입구: 같은 이미지의 두 번째 서비스로 python -m pabal_voice.edge 를 돌립니다(VOICE_EDGE_HOST·VOICE_EDGE_PORT, 기본 127.0.0.1·8096, VOICE_EDGE_DIR). 입구는 인터넷에서 온 것을 처음 푸는 곳이라 비밀을 하나도 붙이지 말고, 프록시와 게이트웨이 말고는 닿지 않는 내부 망에 둡니다.
• 리버스 프록시는 워치 두 경로만 넘깁니다 — /api/watch/v1/audio(WebSocket, 입구로)와 /api/watch/v1/(워치 API로). 워치 API 쪽은 접속자 주소를 X-Forwarded-For 의 마지막에 붙이게 둡니다(서버가 그 값으로 주소마다의 로그인 한도를 셉니다). 입구 쪽에서는 X-Forwarded-For·X-Real-IP 를 지웁니다.
• 워치에서는 가입할 수 없고, 도구·MCP·자기 키·원음 모드·봇 주인의 대화 기록을 쓰는 봇에는 걸 수 없습니다(WATCH_NOT_YET).

대화 남기기 (선택, 준비 중)

전화를 거는 사람이 확인 창에서 고르면 통화의 대화를 그 사람의 대화방에만 글로 남기는 기능입니다(앱 사용하기 — 음성 봇). 운영자 허용 스위치는 없고, 아래가 모두 있으면 켜집니다.

• 개인정보처리방침에 id="bot-calls-keep-text" 절(초안: 저장소의 docs/voice-bots/p0/privacy-*.draft.html). 이 절이 곧 켜는 스위치입니다. 앱은 help.getAppConfig 의 pabal_voice_keep_text 로 체크 상자를 보일지 압니다.
• 게이트웨이 0.9.0 의 VOICE_KEEP_TEXT: 모델 엔진이면 기본 true. 에코 엔진(원음 전용 게이트웨이 포함)에서 true 면 설정 오류로 시작하지 않습니다.
• 체크 상자가 든 앱 빌드. 체크 상자 문구는 법률 검토를 마쳐야 출시 빌드에 실립니다. 워치에는 검토 전 문구를 보이지 않고, TELEGRAM_VOICE_KEEP_TEXT_UNREVIEWED=true 는 검토 전 문구를 보이는 내부 시험 서버 전용 스위치입니다.
• 켜진 서버에서는 원음 모드가 아닌 모든 봇 통화의 voice_call ended 가 최대 10초 늦고, 통화 기록 뒤 메시지 번호 30개를 미리 잡습니다(발신자의 선택을 봇 주인이 알 수 없게).
• 통화가 끝난 뒤 쓰기를 기다리는 대화 글은 메모리에만 있어, 그사이 서버를 다시 켜면 그 통화의 글은 남지 않습니다.

봇이 거는 전화 (선택, 법률 검토 대기)

음성 봇이 그 봇에게 전화를 허락한 사람에게 먼저 전화를 거는 기능입니다(음성 봇 — 봇이 거는 전화). 받는 전화보다 조건이 많고, 법률 검토를 마치기 전에는 켜지 마세요. 켜는 순서:

1. 서버: 증거 키 폴더(TELEGRAM_VOICE_EVIDENCE_KEY_DIR — 700, 데이터·키 폴더처럼 백업되는 폴더 밖)를 scripts/voice-evidence-key.py 의 new 로 만들고(바꿀 때는 rotate, 점검은 check), 허락 창이 든 첫 앱 빌드를 TELEGRAM_VOICE_OUTBOUND_MIN_BUILD_ANDROID 같은 발신 최소 빌드로 정합니다(환경 변수). .env 에만 적은 TELEGRAM_VOICE_EVIDENCE_KEY_DIR 는 서버에 닿지 않습니다 — deploy/docker-compose.voice.yml 의 pabal-server 에 environment(컨테이너 안 경로)와 volumes(호스트의 그 폴더)로 더하세요.
2. 앱: 허락 창이 든 앱 빌드를 냅니다. 앱의 허락 링크 규칙은 pabal.me 만 알기 때문에, 다른 서버라면 앱 빌드의 링크 규칙에 그 서버의 호스트를 넣어야 봇이 보낸 링크로 창이 열립니다(메뉴와 설정 목록은 그대로 됩니다).
3. 법률: 개인정보처리방침의 id="bot-calls-outbound" 절과 이용약관의 id="voice-bot-owners-outbound" 절(봇 주인이 약관에 동의하려면 voice-bot-owners 절도)을 게시합니다. 초안은 저장소의 docs/voice-bots/p0/ 에 있습니다. 허락 창 글과 발신 안내 녹음(notice-out·apology-rule)의 검토와 승인도 이때입니다.
4. 스위치: 관리 화면 음성 탭의 봇이 거는 전화에서 나라와 한도를 정하고 확인 문구로 켭니다(관리 화면 — 음성 탭). 봇마다 운영자의 발신 검토가 따로 있습니다.

• 게이트웨이: VOICE_OUTBOUND=true 인 게이트웨이만 봇의 전화를 겁니다. 모델 엔진이면 발신 안내 녹음 넷이 승인되어 있어야 시작하고, 초안 녹음(VOICE_OUTBOUND_DRAFT_NOTICES)은 시험 서버 전용입니다.
• 운영 .env 에는 TELEGRAM_VOICE_CALLME_UNREVIEWED·TELEGRAM_VOICE_TEST_DIAL 같은 시험·개발 전용 이름을 두지 마세요.
• 봇이 거는 전화도 종단 간 암호화가 아닙니다 — 소리가 이 서버의 게이트웨이와 AI 제공자를 거칩니다.

13. 위치 메시지의 지도 그림 (선택)

위치를 보내면 안드로이드 앱과 데스크톱(맥·윈도우) 앱은 말풍선 속 지도를 스스로 그리지 않고 서버에 그 지점의 지도 그림을 달라고 합니다(upload.getWebFile). 서버는 그 그림을 Google 의 Maps Static API 에서 받아 전해 줍니다. 켜지 않으면 안드로이드는 자리표시 그림을, 데스크톱은 빈 칸에 핀만 보여 줍니다. 아이폰은 휴대폰에서 직접 그리므로 이 설정과 상관없고, 위치 보내기 자체와 위치를 누르면 열리는 큰 지도는 그대로 됩니다.

1. Google Cloud 콘솔에서 결제 계정이 연결된 프로젝트를 고르고 Maps Static API 를 사용 설정합니다.
2. API 키를 만들고, 애플리케이션 제한은 IP 주소(서버가 인터넷으로 나갈 때 쓰는 공인 IP), API 제한은 Maps Static API 하나로 둡니다. 이 키는 서버에만 있고 앱에는 들어가지 않습니다.
3. .env 에 넣고 docker compose up -d pabal-server 로 서버를 다시 켭니다.
4. 로그에서 확인합니다. 꺼져 있으면 Maps in location messages are off: … 와 그 이유가 나옵니다(키 값은 로그에 나오지 않습니다).

STATIC_MAPS_KEY=AIza…               # 키 값은 채팅·로그·저장소에 남기지 마세요
STATIC_MAPS_PER_DAY=300             # 하루에 새로 받는 그림 수 (0 = 제한 없음)
STATIC_MAPS_PER_USER_HOUR=120       # 한 사람이 한 시간에 새로 받게 할 수 있는 그림 수

INFO  TelegramServer - Maps in location messages from Google Static Maps (120 new per person an hour, 300 a day)

• 비용: Maps Static API 는 한 달 1만 건까지 무료입니다. 서버는 받은 그림을 하루 동안 기억해 같은 지도를 달라는 기기에 다시 주고, 다시 준 그림은 한도에 세지 않습니다. 기본 한도(하루 300건)면 한 달 약 9천 건이라 무료 범위 안입니다. 한도를 넘은 요청은 FLOOD_WAIT 로 거절되고, 앱은 그동안 자리표시 그림을 보여 줍니다.
• 개인정보 처리방침: 공유된 위치의 좌표(위도·경도)가 Google 로 갑니다 — 누가 보냈는지는 보내지 않습니다. 관리 화면 → 설정 → 운영자 정보의 처리 위탁과 국외 이전에 Google LLC(Maps Static API, 미국)를 적어 넣으세요.
• 로그에 Map picture not made: Google Static Maps answered 403: … 가 보이면 키의 제한(IP·API)이나 결제 계정을 확인합니다.

운영

상태·로그

cd /opt/pabal/deploy
docker compose ps
docker compose logs --since 1h pabal-server
tail -f /srv/pabal/pabal_server/logs/telegram-server.log

업데이트

cd /opt/pabal && git pull
cd deploy
./backup.sh                                     # 먼저 백업
docker compose up -d --build pabal-server             # 새 이미지로 서버만 교체
docker compose logs --since 5m pabal-server | grep -E "Website|ERROR"

서버가 다시 켜지는 수십 초 동안 앱은 끊겼다가 다시 로그인하지 않고 스스로 다시 붙습니다. 테이블 변경은 서버가 켜질 때 알아서 적용합니다. 바인드 디렉터리는 이미지와 상관없으므로 docker compose down 이나 이미지 삭제로 데이터가 지워지지 않습니다 — /srv/pabal 을 지우지만 마세요.

되돌리기: 바로 전 이미지로 돌아가도 새 판이 데이터베이스에 이미 쓴 것은 그대로입니다. 새 판의 기록을 옛 판이 읽지 못할 수 있으니(예: 음성 봇 코드가 든 판은 음성을 켜지 않아도 대화방의 통화 기록 같은 새 이벤트를 씁니다), 되돌릴 때는 업데이트 직전 백업의 DB 를 함께 되살립니다(복구).

백업

./backup.sh            # → /srv/pabal/backups/<날짜-시각>/{pabal.dump, server-keys-data.tar.gz}
crontab -e             # 매일 03:00:
# 0 3 * * * /opt/pabal/deploy/backup.sh >> /srv/pabal/backups/backup.log 2>&1

• 14일이 지난 백업은 스스로 지웁니다(KEEP_DAYS=30 ./backup.sh 처럼 바꿀 수 있음).
• 다른 곳에도 복사하세요. 같은 디스크의 백업은 디스크 고장을 이기지 못합니다.
• 백업에는 RSA 비밀키와 SMS·SMTP 비밀값이 들어 있습니다. 보관 장소도 서버만큼 지키세요.

복구

cd /opt/pabal/deploy
B=/srv/pabal/backups/20260920-030000            # 되살릴 백업
docker compose stop pabal-server pabal-caddy
docker compose exec -T pabal-postgres dropdb -U pabal pabal
docker compose exec -T pabal-postgres createdb -U pabal pabal
docker compose exec -T pabal-postgres pg_restore -U pabal -d pabal --no-owner < $B/pabal.dump
docker compose exec -T pabal-postgres psql -U pabal -d pabal -c "ALTER DATABASE pabal SET search_path = public"   # 데이터베이스의 기본 경로 — 복구로는 돌아오지 않아 다시 건다
sudo tar -C /srv/pabal/pabal_server -xzf $B/server-keys-data.tar.gz
sudo chown -R 1000:1000 /srv/pabal/pabal_server
docker compose up -d

새 서버로 옮길 때도 같습니다: 1~5단계를 한 뒤, 6단계 대신 위 복구를 하고 켭니다. 같은 키를 되살리면 앱을 다시 빌드할 필요가 없습니다(서버 IP 가 바뀌었다면 다시 빌드).

켜기·끄기

docker compose restart pabal-server       # 서버만 다시 켜기
docker compose stop                 # 모두 멈춤 (데이터 그대로)
docker compose up -d                # 다시 켬

서버를 재부팅해도 컨테이너는 restart: unless-stopped 라 스스로 다시 켜집니다.

보안 점검표

• .env 권한 600, POSTGRES_PASSWORD 는 무작위 값
• /srv/pabal/pabal_server/keys 권한 700, 비밀키가 백업 외 다른 곳에 없음
• (푸시를 켰다면) firebase-service-account.json 권한 600, 저장소·.env 에 내용이 들어가 있지 않음
• (아이폰 푸시를 켰다면) AuthKey_<키 ID>.p8 권한 600, 저장소·.env 에 내용이 들어가 있지 않음
• 방화벽: 22(가능하면 운영자 IP 만)·80·443·8443 만
• 바깥에서 https://도메인/admin/ 이 404
• 관리 화면: 테스트 번호 꺼짐, 코드 전달 방식 SMS/이메일, 테스트 발송 성공
• TELEGRAM_WEBHOOK_ALLOW_LOCAL 을 켜지 않음 (봇 웹훅이 내부망으로 가지 못하게)
• (음성 봇을 켰다면) 링크 비밀·Vertex 키·마스터 키가 각자 읽는 사용자만 읽을 수 있고(400/600), 마스터 키가 /srv/pabal 밖에 있어 백업에 들어가지 않음. 링크 포트는 공개하지 않았고 링크 망은 서버와 게이트웨이만 씀. 운영 서버에 TELEGRAM_VOICE_NOTICE_CHECK·TELEGRAM_VOICE_TESTERS=* 가 없음
• SSH: 비밀번호 로그인 끄기, 키로만
• 백업 cron 과 외부 복사 확인, 복구를 한 번 연습
• 서버 OS 자동 보안 업데이트(unattended-upgrades)

문제 해결

알려진 한계

• 서버 한 대 구성입니다. 켜질 때 모든 계정·대화·메시지를 메모리에 올려 둡니다. 여러 대로 나누는 수평 확장은 아직 안 되고, 데이터가 늘면 메모리를 늘려야 합니다.
• 기다리는 가입 코드, 봇의 가져가지 않은 업데이트, 쓰기를 기다리는 대화 남기기의 글은 메모리에 있어 서버를 다시 켜면 사라집니다.
• 가입 코드 요청에는 간격·하루 한도가 있지만, 그 밖의 요청 전체에 대한 속도 제한은 아직 없습니다. 공개 직후에는 로그와 대시보드를 자주 보세요.
• 푸시 알림은 휴대폰 앱에만 갑니다 — 안드로이드(10단계)와 아이폰(11단계). 아이폰은 APNS_MIN_BUILD 이상 빌드에만 가고(파발 1.0 (3) 은 빠짐), 전화의 CallKit 화면은 APNS_VOIP_MIN_BUILD 를 정한 뒤에야 켜집니다. 맥·윈도우 앱은 켜져 있는 동안 받습니다.
• 대화방별 "알림 끄기"는 서버 메모리에만 있습니다. 알림을 끈 대화방의 푸시는 안드로이드에는 급하지 않은 우선순위로 나가고(휴대폰이 스스로 걸러 냄) 아이폰에는 나가지 않다가, 서버를 다시 켜면 둘 다 평소처럼 나갑니다(앱은 설정을 바꿀 때만 서버에 다시 알려 줍니다). 꺼져 있던 앱이 깨어나 서버에 붙기까지 20초가 넘게 걸리면 전화는 거는 쪽에서 받지 않은 전화로 끝날 수 있습니다.
• 메시지 첨부는 사진과 파일이 되고, 앱 안에서 재생되는 동영상·음성 메시지는 아직입니다. 채널·슈퍼그룹, 그룹 통화, 2단계 인증도 아직입니다.
• 인증 키가 DB 에 평문으로 있습니다(서버가 복호화하려면 필요). DB 와 백업을 RSA 키만큼 지키세요.

파일