재배포 직후 몇 초 동안 봇이 조용했다

재배포할 때마다 봇이 한동안 답을 하지 않았다. 그 길이는 컨테이너 기동 시간에 초기 동기화 시간을 더한 만큼이었고, 2026년 6월에 이걸 기동 시간만큼으로 줄였다. 사고가 나서 고친 건 아니다. 작은 변경인데 그 뒤의 배포 관련 수정들이 이 위에 올라탔기 때문에 따로 적어 둔다.

바꾼 것부터 적는다. 동기화는 백그라운드 task로 보내서 폴링이 바로 시작되게 했고, 동기화가 끝나기 전에 들어온 update는 asyncio.Event가 켜질 때까지 맨 앞 핸들러에서 기다리게 했다.

_ready = asyncio.Event()

async def _gate_until_ready(update: object, context: object) -> None:
    # group=-1: 모든 핸들러보다 먼저 돈다.
    await _ready.wait()

async def _startup_sync(app):
    try:
        await sync_all()
    except Exception:
        logging.exception("initial sync failed")
    finally:
        _ready.set()     # 실패해도 풀어 준다

app.add_handler(TypeHandler(Update, _gate_until_ready), group=-1)

동기화가 끝나야 폴링이 시작됐다

커뮤니티용 텔레그램 봇을 python-telegram-bot(이하 PTB)으로 만들어 Docker 컨테이너로 돌린다. 봇은 시작할 때 구글 시트에서 권한 목록을 읽어 메모리에 올리고, 누가 관리자 명령을 쓸 수 있는지를 이 목록으로 정한다. 네트워크를 타는 작업이라 몇 초가 걸린다.

이 동기화를 PTB의 post_init 훅 안에서 await하고 있었다. post_init은 폴링이 시작되기 전에 불리고, 훅이 끝나야 폴링이 시작된다. 컨테이너가 떠도 동기화가 끝날 때까지는 update를 받지 않았고, 사용자는 재배포 때마다 그 시간만큼 조용한 봇을 봤다.

그냥 뒤로 미루면 관리자가 거절당한다

폴링을 빨리 시작하는 것만 보면 쉽다. 동기화를 백그라운드 task로 보내고 post_init을 바로 끝내면 된다.

그러면 폴링은 시작됐는데 권한 목록은 아직 비어 있는 구간이 생긴다. 재배포 직후 1초 안에 관리자가 명령을 보내면 봇은 빈 목록과 대조해서 “권한 없음”으로 거절한다. 조용한 것보다 나쁘다. 응답이 늦는 건 기다리면 되지만, 틀린 답을 받은 사용자는 다시 시도해야 한다는 사실조차 알기 어렵다.

그래서 받는 것은 바로 받고, 처리는 준비된 뒤에 하게 했다. 위 코드의 게이트 핸들러가 그 역할이다.

PTB에서 핸들러는 그룹 번호 순서로 처리되고, update 하나는 각 그룹에서 맞는 핸들러를 하나씩 거친다. TypeHandler(Update, ...)는 종류를 가리지 않고 모든 update에 맞으니, 이것을 group=-1에 두면 기본 그룹(0)의 명령·메시지 핸들러보다 먼저 실행된다. 게이트 핸들러가 await에서 멈춰 있는 동안 그 update는 뒤 그룹으로 넘어가지 않는다.

이벤트가 켜진 뒤에는 wait()가 즉시 돌아와서 평상시 비용은 없다. 핸들러 본문마다 조건문을 넣을 필요도 없었다.

이 봇은 concurrent_updates(True)로 update를 동시에 처리한다(True는 동시 256개까지다). 한 update가 게이트에서 기다려도 다른 처리는 막히지 않고, 기다리던 update들은 이벤트가 켜지면 각자 이어서 진행한다.

_ready.set()은 finally에 있다

이 설계에서 위치가 가장 중요한 한 줄이다. 동기화가 성공했을 때만 켜면, 시트 API가 오류를 낸 날에는 게이트가 영원히 닫혀 있다. 봇은 떠 있고 폴링도 하는데 아무것도 처리하지 않는다. 로그에는 동기화 실패 한 줄만 남고, 겉으로는 봇이 그냥 멈춘 것처럼 보인다.

finally에서 켜면 동기화가 실패해도 핸들러들이 그때 메모리에 있는 목록으로 판정한다. 완전하지 않을 수 있다. 그래도 무한 정지보다 낫고, 관리자가 동기화 명령으로 다시 시도할 수 있다.

못 막는 경우가 하나 있다. finally는 예외는 막아 주지만 끝나지 않는 대기는 막지 못한다. 동기화 안의 네트워크 호출이 응답 없이 매달리면 finally에 도달하지 않고 게이트도 열리지 않는다. 동기화가 성공이든 실패든 유한한 시간 안에 끝난다는 전제 위에 있는 게이트다.

app.create_task는 몇 분 만에 바꿨다

처음에는 동기화 task를 PTB의 app.create_task()로 띄웠고, 경고가 나왔다. post_init 시점에는 애플리케이션이 아직 running 상태가 아니고, 이때 app.create_task()로 만든 task는 종료 시 자동으로 await되지 않는다는 PTBUserWarning이다.

몇 분 뒤 커밋에서 asyncio.create_task()로 바꿨다. 이 task는 예외를 스스로 처리하므로 PTB의 오류 처리 경로가 필요하지 않았다. 대신 직접 챙길 것이 하나 생겼다. asyncio 이벤트 루프는 task에 대해 약한 참조만 가져서, 참조를 어디에도 보관하지 않으면 실행 도중에 가비지 컬렉션될 수 있다. 모듈 수준 변수에 담아 뒀다.

_startup_task: asyncio.Task | None = None

async def _post_init(app) -> None:
    global _startup_task
    # 폴링은 바로 시작되고, 동기화는 뒤에서 돈다.
    _startup_task = asyncio.create_task(_startup_sync(app))

배포 스크립트도 둘로 나눴다

배포 스크립트는 docker compose up -d --build 한 줄이었다. 빌드와 교체가 한 명령에 묶여 있던 것을 두 단계로 나눴다.

echo "→ Building new image (old container keeps running)..."
docker compose build

echo "→ Swapping in the new container..."
docker compose up -d --remove-orphans

docker compose build는 옛 컨테이너가 서비스하는 동안 돌고, 새 이미지가 완전히 준비된 뒤에 up -d가 컨테이너 교체만 한다. 솔직히 적으면 up -d --build도 동작은 같다. 빌드가 끝난 뒤에 교체하기 때문이다. 나눠서 얻은 것은 두 단계 사이에 끼어들 자리다. 미리 빌드해 두고 조용한 시점에 교체만 실행할 수 있고, 나중에 “교체 직전에 진행 중인 작업이 있는지 확인”하는 단계를 넣을 때 바로 이 자리를 썼다.

--remove-orphans는 다른 문제 때문에 넣었다. 이 구성에는 텔레그램 로컬 Bot API 서버 컨테이너가 같이 있는데, 낡은 컨테이너가 남아 있으면 같은 데이터 볼륨의 락을 두고 새 컨테이너와 다투면서 재시작 루프에 빠진다. compose 파일에 더 이상 없는 서비스의 컨테이너는 교체할 때 같이 치우게 했다.

얼마나 줄었는지는 재지 않았다

재배포 공백은 “기동 + 동기화”에서 “기동”으로 줄었다. 몇 초에서 몇 초로 줄었는지는 재지 않았다. 동기화가 네트워크를 타는 몇 초짜리 작업이라는 것이 아는 전부다.

게이트 핸들러는 그 뒤에 다른 용도로도 썼다. 모든 update가 가장 먼저 지나는 자리이기 때문이다. 8월에는 여기에 “누가 방금 봇을 썼는가”를 기록하는 한 줄을 얹었고, 배포 스크립트가 그 기록을 보고 다른 사용자의 입력 중에는 교체를 미룬다. 모든 update마다 실행되는 자리라, 여기 얹는 코드는 절대 예외를 던지지 않게 하고 실패는 삼킨다.