핫 리로드
PRX는 대부분의 설정 변경을 핫 리로드하는 것을 지원합니다. config.toml(또는 config.d/의 프래그먼트)을 편집하면 변경 사항이 수초 내에 감지되어 적용됩니다 -- 재시작이 필요하지 않습니다.
작동 방식
PRX는 라이브 설정 업데이트를 위해 3계층 메커니즘을 사용합니다:
파일 감시자 --
notify파일 시스템 감시자가 설정 디렉터리(config.toml과 전체config.d/트리 모두)에서 쓰기 이벤트를 모니터링합니다.디바운스 -- 이벤트는 빠르게 연속되는 쓰기(예: 쓰기 후 이름 변경하는 에디터)를 통합하기 위해 1초 창으로 디바운스됩니다.
원자적 교체 -- 변경 감지 시 PRX는:
- 새 설정의 SHA-256 지문을 계산합니다
- 마지막 알려진 지문과 비교합니다 (동일하면 건너뜀)
- 새 TOML을
Config구조체로 파싱합니다 - 성공 시:
ArcSwap를 통해 새 설정을 원자적으로 게시합니다 (락 프리) - 실패 시: 이전 설정을 유지하고 경고를 기록합니다
SharedConfig 타입(Arc<ArcSwap<Config>>)은 설정을 읽는 모든 컴포넌트가 경합 없이 일관된 스냅샷을 얻도록 보장합니다. 리더는 .load_full()을 호출하여 사용 중 설정이 교체되더라도 유효한 Arc<Config> 스냅샷을 얻습니다.
핫 리로드 가능한 항목
다음 변경 사항은 즉시 적용됩니다 (약 1초 이내):
| 범주 | 예시 |
|---|---|
| 프로바이더 설정 | default_provider, default_model, default_temperature, api_key, api_url |
| 채널 설정 | Telegram allowed_users, Discord mention_only, Slack channel_id 등 |
| 메모리 설정 | backend, auto_save, embedding_provider, 보존 기간 |
| 라우터 설정 | enabled, 가중치(alpha/beta/gamma/delta/epsilon), Automix 임계값 |
| 보안 설정 | 샌드박스 백엔드, 리소스 제한, 감사 설정 |
| 자율성 설정 | 범위 규칙, 자율성 수준 |
| MCP 설정 | 서버 정의, 타임아웃, 도구 허용 목록 |
| 웹 검색 설정 | enabled, provider, max_results |
| 브라우저 설정 | enabled, allowed_domains |
| Xin 설정 | enabled, interval_minutes, 작업 제한 |
| 비용 설정 | daily_limit_usd, monthly_limit_usd, 가격 |
| 안정성 설정 | max_retries, fallback_providers |
| 관측성 설정 | backend, OTLP 엔드포인트 |
| 프록시 설정 | 프록시 URL, no-proxy 목록, 범위 |
재시작이 필요한 항목
소수의 설정은 시작 시 바인딩되며 런타임에 변경할 수 없습니다:
| 설정 | 이유 |
|---|---|
[gateway] host | TCP 리스너가 시작 시 한 번 바인딩됨 |
[gateway] port | TCP 리스너가 시작 시 한 번 바인딩됨 |
[tunnel] 설정 | 터널 연결이 시작 시 수립됨 |
| 채널 봇 토큰 | 봇 연결(Telegram 롱 폴링, Discord 게이트웨이, Slack 소켓)이 한 번 초기화됨 |
이러한 설정의 경우 PRX 데몬을 재시작해야 합니다:
# systemd 서비스로 실행 중인 경우
sudo systemctl restart openprx
# 포그라운드에서 실행 중인 경우
# Ctrl+C로 중지한 다음 다시 시작
prxCLI 다시 로드 명령
파일을 편집하지 않고 수동으로 설정 다시 로드를 트리거할 수 있습니다:
prx config reload이는 파일 감시자가 변경을 감지하는 것과 동일합니다. 설정 파일을 다시 읽고 파싱한 다음 라이브 설정을 원자적으로 교체합니다. 다음과 같은 경우에 유용합니다:
- 파일을 수정했지만 감시자가 이벤트를 놓친 경우 (드물게 발생)
- 환경 변수 업데이트 후 강제 다시 로드하려는 경우
- 설정 변경을 스크립팅하는 경우
오류 처리
새 설정 파일에 오류가 있는 경우:
- TOML 구문 오류 -- 파서가 파일을 거부합니다. 이전 설정이 유지됩니다. 파싱 오류 세부 사항과 함께 경고가 기록됩니다.
- 잘못된 필드 값 -- Automix가 활성화된 상태에서
confidence_threshold > 1.0이나 빈premium_model_id와 같은 문제를 유효성 검사에서 포착합니다. 이전 설정이 유지됩니다. - 파일 누락 --
config.toml이 삭제되면 감시자가 오류를 기록하지만 메모리 내 설정은 계속 작동합니다.
모든 오류 경우에서 PRX는 마지막으로 알려진 양호한 설정으로 계속 작동합니다. 데이터 손실이 없고 서비스 중단이 발생하지 않습니다.
다시 로드 모니터링
HotReloadManager는 성공적인 다시 로드마다 증가하는 단조 reload_version 카운터를 유지합니다. 게이트웨이 상태 엔드포인트를 통해 현재 버전을 확인할 수 있습니다:
curl http://localhost:16830/api/status응답에는 현재 다시 로드 횟수가 포함되어 변경 사항이 적용되었는지 확인하는 데 도움이 됩니다.
분할 파일 다시 로드
분할 설정 파일(config.d/*.toml)을 사용할 때 감시자는 전체 config.d/ 디렉터리를 재귀적으로 모니터링합니다. .toml 프래그먼트에 대한 변경은 모든 설정의 전체 재병합 및 다시 로드를 트리거합니다. 이는 다음을 의미합니다:
config.d/channels.toml을 편집하면 전체 설정이 다시 로드됩니다 (채널만이 아님)- 프래그먼트 파일을 추가하거나 제거하면 다시 로드가 트리거됩니다
- 병합 순서는 파일 이름의 알파벳순이며, 프래그먼트가
config.toml보다 우선합니다