워커 패키징
지원되는 런타임, 고정된 종속성 및 서비스 관리자 또는 컨테이너를 사용하세요. 재시작 제한과 전용 서비스 사용자를 구성하세요. 비공개 제공업체 자격 증명을 애플리케이션의 공개 파일 외부에 있는 보호된 구성에 보관하세요.
중요한 작업 전에 진행 상황 저장
작업에는 내구성 있는 큐나 데이터베이스를 사용하세요. 고유한 작업 식별자를 할당하고, 외부 요청을 기록하며, 불확실한 결과를 조정하세요. 재시작 시 두 번째 이메일을 보내거나, 두 번째 주문을 생성하거나, 이중으로 청구해서는 안 됩니다.
유용한 관측 가능성 추가
프로세스 존재 여부만 확인하지 말고 작업 완료, 대기열 경과 시간, 오류율 및 비용을 모니터링하세요. 검토할 수 있을 만큼 로그를 작게 유지하고 보관할 필요가 없는 토큰, 프롬프트 및 문서는 삭제하세요.
명확한 상한 설정
모델 지출, 브라우저 동시성, 런타임 및 재시도 횟수를 제한하세요. 간편한 일시 중지 스위치와 중대한 작업에 대한 사람 검토 경로를 유지하세요. 잘 관찰되는 작은 워커가 제한 없는 워커보다 신뢰하기 쉽습니다.
슈퍼바이저와 신중한 일정을 사용하십시오
Systemd와 Docker는 터미널 연결이 끊겨도 프로세스가 유지되도록 하는 일반적인 방법입니다. systemd 서비스의 경우 Type=exec는 단순한 백그라운드 실행보다 실행 실패를 더 직접적으로 보고할 수 있으며, Restart=on-failure는 제한된 정책으로 실패 시 재시작할 수 있습니다. 예약 작업은 실행이 겹치지 않도록 해야 합니다. 작업 디렉터리, 서비스 사용자 및 환경을 명시적으로 지정하세요. 이 예시는 koala-agent 사용자, 가상 환경, 워커 모듈 및 비공개 환경 파일이 이미 존재한다고 가정합니다. 유닛을 설치하기 전에 이에 맞게 조정하세요.
- 전용 서비스 계정을 사용하세요
- 재시작 지연 및 실패 한도 설정
- 예약된 실행을 시작하기 전에 이전 작업 상태를 확인하세요
[Unit]
Description=Example agent worker
After=network-online.target
[Service]
Type=exec
User=koala-agent
WorkingDirectory=/opt/koala-agent
EnvironmentFile=/etc/koala-agent.env
ExecStart=/opt/koala-agent/.venv/bin/python -m worker
Restart=on-failure
RestartSec=10
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target공식 문서: Systemd 서비스 의미론
일일 예산과 중복 경계를 설정하세요
워커에 최대 요청 수, 지출 한도 및 실행 시간 제한을 설정하세요. 외부 세계에 영향을 미치는 작업에는 내구성 있는 멱등성 기록을 사용하세요. 프로세스가 응답을 받기 전에 브라우저 클릭이 성공할 수 있으므로 다시 시도하기 전에 외부 상태를 확인하세요. Docker Compose 시크릿 마운트는 시크릿을 이미지 외부에 유지할 수 있지만 권한과 소비 애플리케이션은 여전히 검토해야 합니다.
공식 문서: Docker Compose 시크릿
주기적 작업에 명시적인 따라잡기 정책을 부여하세요
지속적인 큐 워커에는 장기 실행 서비스를, 제한된 예약 작업에는 타이머로 트리거되는 원샷 서비스를 사용하세요. systemd 캘린더 타이머에서 Persistent=true는 다운타임 후 놓친 활성화를 한 번 트리거할 수 있지만, 전체 업무 백로그를 재현하지는 않습니다. 이러한 따라잡기가 바람직한지 결정하세요. RandomizedDelaySec는 시작을 분산할 수 있으며, 애플리케이션 수준 임대는 두 복제본이 동일한 예약 작업을 처리하지 못하게 합니다.
- 의도한 시간대를 기록하고 일정을 활성화하기 전에 다음 실행 시간을 확인하세요.
- 작업의 실행 기한을 겹치면 안 되는 간격보다 짧게 유지하거나, 만료와 소유권이 있는 내구성 있는 리스를 사용하세요.
- 이전의 모든 타이머 이벤트가 실행되었다고 가정하지 말고, 작업이 저장된 상태에서 미처리 작업을 선택하도록 하세요.
- 최신 매뉴얼의 지시문을 사용하기 전에 설치된 systemd 버전을 확인하세요.
# Read-only checks after creating your own matching units.
systemctl list-timers --all
systemctl status koala-agent.service
journalctl -u koala-agent.service --since today --no-pager공식 문서: systemd: 타이머 스케줄링
크래시 루프와 정체된 워커 구분하기
재시작 정책은 실패한 프로세스를 복구할 수 있지만, 잘못된 자격 증명이나 깨진 마이그레이션을 몇 초마다 반복하면 장애가 더 시끄러워집니다. 서비스 시작 횟수를 제한하고 반복 실패 시 알림을 설정하세요. 실행 중인 프로세스도 멈출 수 있습니다. 가장 오래된 작업의 경과 시간과 마지막으로 완료된 작업을 측정하세요. 일회용 작업으로 API 중단, 디스크 가득 참 및 프로세스 정지를 테스트한 다음, 영구 상태가 중복 외부 작업을 방지하는지 확인하세요.
- 애플리케이션에 제공자 예산과 요청 타임아웃을 설정하고, 런타임에 CPU/메모리 경계도 설정하세요.
- Docker 컨테이너라고 해서 워크로드별 메모리 제한이 자동으로 유용해지는 것은 아닙니다. 제한을 의도적으로 구성하고 테스트하세요.
- 이미지와 공개 트리 외부에 시크릿을 저장한 다음, 크래시 로그와 진단 정보에서 해당 시크릿이 마스킹되는지 테스트하세요.
- 수동 중지 경로를 유지하고 지출, 프로덕션 쓰기 또는 외부 메시지에 적절한 검토를 요구하세요.
공식 문서: systemd: 서비스 감독 · Docker: 컨테이너 리소스 제약