서버 운영
관리와 설정
관리 화면, 가입 코드 전달(SMS·이메일), 서버 설정 값, 백업과 보안 — 운영자를 위한 참조.
서버에는 브라우저로 여는 관리 화면이 들어 있습니다. 서버 상태를 보고, 가입·로그인 코드를 어떻게 전달할지 정하고, 사용자와 봇을 관리합니다. 이 문서는 관리 화면과 서버 설정 값을 한곳에 정리한 참조입니다. 설치가 먼저라면 서버 설치를 보세요.
관리 화면 열기
관리 화면은 관리 HTTP 포트(운영 구성에서 8080)의 /admin/ 이고, 서버 자신(127.0.0.1)에서만 열립니다. 운영자는 SSH 터널로 들어갑니다.
# 내 컴퓨터에서 (켜 둔 채로)
ssh -N -L 8080:127.0.0.1:8080 <사용자>@<서버>
# 브라우저: http://localhost:8080/admin/
# 토큰 (서버에서)
sudo cat /srv/pabal/pabal_server/data/admin-token토큰을 넣고 열기. 브라우저가 토큰을 기억하며, 오른쪽 위 토큰 지우기로 지웁니다. 토큰을 직접 정하려면 TELEGRAM_ADMIN_TOKEN(16자 이상)을 주세요 — 그러면 파일을 쓰지 않습니다.
탭별로 보이는 것
| 탭 | 내용 | 갱신 |
|---|---|---|
| 대시보드 | 지금 접속 중인 사람·세션·연결, 사람·봇·그룹·메시지·사진 수, 가동 시간·포트·DB, JVM, 상태 점검. 테스트 번호가 켜져 있으면 경고 띠 | 5초 |
| 가입 코드 | 기다리는 코드(번호·전달 방식·발송 상태·코드·남은 시간·틀린 입력 횟수)와 최근 기록. 코드 복사·취소 | 3초 |
| 사용자 | 모든 계정 — 전화번호, 로그인 이메일(편집), 접속 여부, 로그인 기기 수, 메시지 수. 모든 기기 로그아웃, 번호 차단 | 10초 |
| 봇 | BotFather 로 만든 봇 — 만든 사람, 명령어 메뉴, 연결 방식(MTProto · HTTP 폴링 · 웹훅 주소와 실패 이유), 기다리는 업데이트 수 | 10초 |
| 설정 | 가입·로그인 규칙, SMS, 이메일(SMTP), 전화번호 차단 | 직접 저장 |
| 저장소 | 데이터 디렉터리·DB 주소(비밀번호는 가림), 사진 개수·용량, 종류별 저장 스트림 수 | 10초 |
위험한 동작(로그아웃·차단·코드 취소)은 두 번 눌러야 실행됩니다.
가입·로그인 코드
사람이 앱에 전화번호를 넣으면 서버가 코드를 만들어 설정 탭에서 고른 방법으로 보냅니다.
| 전달 방식 | 코드가 가는 곳 | 앱 화면 |
|---|---|---|
| 관리 화면 | 가입 코드 탭. 운영자가 복사해 직접 알려 줌 | 번호 → "코드를 보냈습니다" → 코드 (새 번호면 이름) |
| SMS | Twilio · Solapi · 웹훅 중 하나로 문자 | 관리 화면과 같음 |
| 이메일 | SMTP 로 메일 | 번호 → 이메일 입력 → "이메일로 코드를 보냈습니다" → 코드 |
- 이메일 방식에서 새 가입은 아무 주소나 쓸 수 있고, 그 주소가 계정의 로그인 이메일이 됩니다. 기존 계정은 등록된 로그인 이메일로만 받습니다 — 남의 번호에 자기 주소를 넣어 들어오는 것을 막습니다. 로그인 이메일이 없는 기존 계정은 SMS(설정돼 있으면) 또는 관리 화면으로 대신 보냅니다. 사용자 탭에서 로그인 이메일을 넣어 줄 수 있습니다.
- 발송은 뒤에서 이루어져 앱은 바로 코드 화면으로 갑니다. 발송 결과(성공·실패와 이유)는 가입 코드 탭에 뜹니다.
- 가입(이름 입력)은 코드를 맞힌 뒤에만 됩니다. 틀린 코드는 허용 횟수만큼만 받고 그 뒤로는 맞는 코드도 거절합니다.
설정 — 가입·로그인
| 항목 | 뜻 | 기본 |
|---|---|---|
| 새 가입 허용 | 끄면 이미 있는 계정만 로그인. 새 번호는 "잘못된 번호"로 거절 | 켬 |
| 코드 전달 방식 | 관리 화면 / SMS / 이메일 | 관리 화면 |
| 관리 화면에 코드 표시 | SMS·이메일 방식에서도 가입 코드 탭에 코드를 보여 줌 (발송 실패 대비) | 켬 |
| 테스트 번호 (+99966…) | 서버 설정대로 / 켜기 / 끄기. 운영에서는 끄기 | 서버 설정대로 |
| 코드 자릿수 · 유효 시간 | 5~6자리 · 1~60분 | 5자리 · 5분 |
| 재요청 간격 · 하루 최대 | 같은 번호가 코드를 다시 받기까지 초(0~3600) · 24시간 안 최대 횟수(1~1000) | 60초 · 10회 |
| 틀린 입력 허용 횟수 | 넘으면 그 코드는 잠김 (1~20) | 5회 |
설정 — SMS
| 제공자 | 넣을 값 | 비고 |
|---|---|---|
| 웹훅 | 받을 주소(https://…), Authorization 헤더(선택) | 서버가 POST {"phone":"+8210…","code":"12345","text":"…"} 를 보냅니다. 2xx 면 성공. 자체 문자 서버나 다른 서비스에 연결할 때 |
| Twilio | Account SID, Auth Token, 발신 번호 또는 Messaging Service SID | 해외 번호 포함 전 세계 |
| Solapi (구 CoolSMS) | API Key, API Secret, 발신 번호 | 국내 문자. 발신 번호는 Solapi 에 사전 등록된 번호. +82 번호는 010… 형식으로 보냅니다 |
문구에는 {code}(코드)와 {minutes}(유효 시간)를 넣을 수 있습니다. 기본값: [파발] 인증 코드: {code}. 저장한 뒤 테스트 발송으로 확인하세요.
설정 — 이메일 (SMTP)
| 서비스 | 서버 · 포트 · 보안 | 사용자명 · 비밀번호 |
|---|---|---|
| Gmail | smtp.gmail.com · 587 · STARTTLS | Gmail 주소 · 앱 비밀번호 (Google 계정 → 보안 → 2단계 인증 → 앱 비밀번호) |
| 네이버 | smtp.naver.com · 587 · STARTTLS | 아이디 · 비밀번호 (메일 환경설정에서 POP3/SMTP 사용 켜기) |
| 사내 메일 릴레이 | 릴레이 주소 · 25 · 없음 | 비움 |
보내는 주소는 SMTP 계정이 보낼 수 있는 주소여야 합니다. 제목·본문에도 {code}, {minutes} 를 씁니다.
사용자 관리
- 모든 기기 로그아웃: 그 계정의 모든 로그인(인증 키)을 끊습니다. 기기를 잃어버린 사용자에게 씁니다.
- 번호 차단: 그 번호는 코드를 받을 수 없고, 그 번호의 계정은 모든 기기에서 즉시 로그아웃됩니다. 설정 탭의 전화번호 차단 목록과 같습니다.
- 로그인 이메일: 이메일 방식에서 기존 계정이 이메일로 로그인하려면 필요합니다.
- @BotFather 는 서버 안의 봇이라 로그아웃 대상이 아닙니다.
봇 관리
봇 탭에서 각 봇의 연결 방식을 봅니다 — MTProto 로 붙어 있는지, HTTP 로 최근 1분 안에 getUpdates 를 불렀는지, 웹훅 주소가 무엇이고 지금 실패 중인지(이유 포함). 기다리는 업데이트가 계속 늘면 봇 프로그램이 멈췄거나 웹훅이 실패하는 중입니다. 봇 삭제·토큰 재발급은 봇을 만든 사람이 @BotFather 에서 합니다.
환경 변수
서버는 설정 파일(server-config.json)을 읽은 뒤 환경 변수로 덮어씁니다. 운영 컴포즈 파일이 아래 값을 정해 주므로 보통은 .env 만 고치면 됩니다.
| 변수 | 뜻 | 운영 컴포즈 값 |
|---|---|---|
TELEGRAM_PORT | MTProto 포트 | MTPROTO_PORT (8443) |
TELEGRAM_HOST | MTProto 가 듣는 주소 | 0.0.0.0 |
TELEGRAM_PUBLIC_HOST | 앱에게 알려 줄 서버 주소 (help.getConfig) | PUBLIC_IP |
TELEGRAM_WEB_PORT | 웹사이트·문서·Bot API·관리 화면 포트 | 8080 |
TELEGRAM_WEB_HOST | 그 포트가 듣는 주소. 기본 127.0.0.1 | 0.0.0.0 (컨테이너 안. 호스트에는 127.0.0.1 로만 공개) |
TELEGRAM_PUBLIC_URL | 웹사이트 주소. 링크(me_url_prefix)·초대 링크·문서 예제·미리보기 이미지 | https://DOMAIN/ |
TELEGRAM_DATA_DIR | 사진·admin-token·operations.json 위치 | /app/data |
TELEGRAM_RSA_KEY | 서버 RSA 비밀키 경로 (없으면 처음에 만듦, 공개키는 .pub) | /app/keys/private.pem |
TELEGRAM_DC_ID | 이 서버의 DC 번호 | (이미지 기본 1) |
TELEGRAM_DB_TYPE | memory · h2 · postgresql | postgresql |
TELEGRAM_DB_URL, TELEGRAM_DB_USERNAME, TELEGRAM_DB_PASSWORD | JDBC 접속 | jdbc:postgresql://pabal-postgres:5432/pabal, pabal, POSTGRES_PASSWORD |
TELEGRAM_DB_MAX_POOL_SIZE | DB 연결 수 | 20 |
TELEGRAM_ADMIN_TOKEN | 관리 화면 토큰 (비우면 data/admin-token 에 만듦) | ADMIN_TOKEN |
TELEGRAM_TEST_NUMBERS | +99966… 테스트 번호. 개발 전용 | false |
TELEGRAM_WEBHOOK_ALLOW_LOCAL | 봇 웹훅이 http:// 와 내부 주소를 쓸 수 있게. 개발 전용 | (정하지 않음 = false) |
JAVA_OPTS | JVM 옵션 (메모리) | .env 의 값 |
데이터 파일
| 파일 | 내용 | 권한 |
|---|---|---|
keys/private.pem | 서버 RSA 비밀키. 절대 밖으로 내보내지 않음 | 600 |
keys/private.pem.pub | 공개키. 앱 빌드와 /docs/server-key.pem 에 쓰임 | — |
data/admin-token | 관리 화면 토큰 | 600 |
data/operations.json | 설정 탭의 값 — 가입 규칙, SMS·SMTP 비밀값, 차단 번호 | 600 |
data/media/ | 사진 원본 | — |
PostgreSQL events 테이블 | 계정·대화·메시지·로그인·봇·웹훅 설정 — 모든 변경의 기록 | — |
보안 메모
- 관리 포트를 인터넷에 직접 열지 마세요. 운영 구성의 Caddy 는
/admin,/health,/metrics같은 관리 경로를 404 로 막습니다. - 관리 데이터 요청은 모두
Authorization: Bearer <토큰>이 필요하고, 다른 사이트의 페이지는 읽을 수 없습니다. - SMS·SMTP 비밀값은
operations.json에만 있고, 화면과 API 는 "저장됨"만 알려 줍니다. 비밀값 칸을 비워 두고 저장하면 기존 값이 유지됩니다. - 토큰·비밀값은 로그에 찍히지 않고, 로그의 전화번호는 가려서 남깁니다. Bot API 주소(토큰 포함)도 로그에 남기지 않습니다.
- 인증 키가 DB 에 들어 있으므로, DB 에 접근할 수 있는 사람은 사용자 트래픽을 풀 수 있습니다. DB·백업을 RSA 키만큼 지키세요.
한계
- 기다리는 코드와 최근 기록은 메모리에 있어 서버를 다시 켜면 사라집니다(앱에서 다시 요청하면 됨).
- SMS 제공자의 실제 발송은 각 제공자 계정으로 확인해야 합니다. 서버는 각 제공자의 문서대로 요청을 만듭니다.
- 아직 없는 것: 계정 삭제, 봇 강제 삭제, 메시지 열람, 로그 보기, 그래프.