네트워크 배포, Raspberry Pi, 프록시
LAN 바인딩, 폴링 vs 웹훅 채널, ARM 타깃, Raspberry Pi 임베디드 배포, 아웃바운드 프록시 라우팅.
이 페이지에서는 로컬 네트워크 또는 저전력 ARM 보드에서 Revka를 실행하는 방법과 아웃바운드 트래픽을 프록시를 통해 라우팅하는 방법을 다룹니다. Raspberry Pi 또는 홈 랩 호스트에 배포하거나, 폴링과 웹훅 채널 중 하나를 선택해야 하거나, Revka 트래픽을 기업 또는 에어갭 프록시를 통해 전송해야 할 때 이 문서를 참고하십시오.
단일 revka 바이너리는 어디서나 실행됩니다. 네이티브 vs. Docker 어댑터에 대한 내용은 런타임 모드, 어댑터 및 리소스 제한을, 재부팅 후에도 데몬을 유지하는 방법은 백그라운드 서비스로 실행을 참고하십시오.
인바운드 포트 요구사항에 따른 채널 선택
섹션 제목: “인바운드 포트 요구사항에 따른 채널 선택”가장 중요한 네트워크 결정은 채널이 인바운드 포트를 필요로 하는지 여부입니다. 폴링 방식 채널은 아웃바운드 연결만 사용하므로 NAT 뒤, Raspberry Pi, 또는 포트 포워딩이 없는 홈 랩 환경에서도 동작합니다. 웹훅 채널은 원격 서비스가 이벤트를 POST할 수 있도록 공개 HTTPS URL이 필요합니다.
| 모드 | 인바운드 포트 필요 여부 | 비고 |
|---|---|---|
| Telegram 폴링 | 불필요 | Revka가 Telegram API를 폴링하므로 어디서나 동작 |
| Matrix 동기화 (E2EE 포함) | 불필요 | Matrix 클라이언트 API를 통해 동기화; 웹훅 불필요 |
| Discord / Slack | 불필요 | 아웃바운드 전용 |
| Nostr | 불필요 | WebSocket을 통해 릴레이에 연결; 아웃바운드 전용 |
| Gateway 웹훅 | 필요 | POST /webhook, /whatsapp, /linq, /nextcloud-talk는 공개 URL 필요 |
| Gateway 페어링 | 필요 | Gateway를 통해 원격 클라이언트를 페어링하는 경우 |
네트워크 배포 모드 (바인드 주소)
섹션 제목: “네트워크 배포 모드 (바인드 주소)”Gateway는 다음 주소에 바인딩할 수 있습니다:
127.0.0.1— 로컬호스트 전용 (기본값; 다른 머신에서 접근 불가)0.0.0.0— 모든 IPv4 인터페이스 (LAN 접근)[::]— 모든 IPv6 인터페이스 (Docker 컨테이너 내부 기본값)
루프백이 아닌 주소 바인딩에는 보호 장치가 적용됩니다. CLI와 데몬은 allow_public_bind = true가 설정되거나 터널이 활성화되지 않는 한 루프백 이외의 주소 바인딩을 거부합니다.
[gateway]host = "0.0.0.0"port = 42617allow_public_bind = trueCLI에서 실행 시마다 바인드 주소를 오버라이드할 수 있습니다:
revka daemon --host 127.0.0.1 # localhost only (default)revka daemon --host 0.0.0.0 --port 42617 # LAN access| 설정 | 환경 변수 오버라이드 | 기본값 | 의미 |
|---|---|---|---|
gateway.host | REVKA_GATEWAY_HOST | 127.0.0.1 | 바인드 주소 |
gateway.port | REVKA_GATEWAY_PORT | 42617 | 리슨 포트 |
gateway.allow_public_bind | REVKA_ALLOW_PUBLIC_BIND | false | 루프백이 아닌 주소 바인딩 시 필요 |
Raspberry Pi 및 임베디드 배포
섹션 제목: “Raspberry Pi 및 임베디드 배포”Revka는 Raspberry Pi 3 / 4 / 5 (Raspberry Pi OS 포함)를 포함한 ARMv7 및 ARM64(aarch64) Linux에서 실행됩니다. Telegram 폴링에는 인바운드 포트가 필요 없으며, USB 연결 시리얼 주변기기(Arduino, STM32 Nucleo)는 네이티브 런타임을 통해 동작합니다.
ARMv7 / aarch64 사전 빌드 바이너리
섹션 제목: “ARMv7 / aarch64 사전 빌드 바이너리”두 가지 Raspberry Pi 아키텍처 모두에 대해 사전 빌드 바이너리가 제공되므로, 일반적으로 기기에서 직접 컴파일할 필요가 없습니다:
| 타깃 | 보드 |
|---|---|
aarch64-unknown-linux-gnu | Raspberry Pi 4 / 5 (64비트) |
armv7-unknown-linux-gnueabihf | Raspberry Pi 2 / 3 (ARMv7) |
arm-unknown-linux-gnueabihf | 구형 32비트 ARM |
하드웨어 지원으로 소스 빌드
섹션 제목: “하드웨어 지원으로 소스 빌드”GPIO 활성화 등의 이유로 로컬에서 빌드해야 하는 경우, 하드웨어 기능을 추가하십시오:
# USB / serial device supportcargo build --release --features hardware
# Native Raspberry Pi GPIO via rppalcargo build --release --features hardware,peripheral-rpi| Cargo 기능 | 활성화 내용 |
|---|---|
hardware | USB / 시리얼 디바이스 지원 |
peripheral-rpi | 네이티브 RPi GPIO (rppal 경유) |
GPIO, 시리얼 주변기기, Telegram 설정
섹션 제목: “GPIO, 시리얼 주변기기, Telegram 설정”[peripherals]enabled = true
# Native RPi GPIO[[peripherals.boards]]board = "rpi-gpio"transport = "native"
# Or an Arduino over USB-serial[[peripherals.boards]]board = "arduino-uno"transport = "serial"path = "/dev/ttyACM0"baud = 115200
[channels_config.telegram]bot_token = "YOUR_BOT_TOKEN"allowed_users = [] # deny-by-default; bind identities explicitly
[gateway]host = "127.0.0.1"port = 42617allow_public_bind = false데몬 실행
섹션 제목: “데몬 실행”-
로컬호스트에 바인딩된 데몬을 시작합니다. Telegram은 아웃바운드 폴링이므로 정상 동작합니다:
Terminal window revka daemon --host 127.0.0.1 --port 42617 -
런타임에서 Telegram 계정 하나를 승인합니다 (숫자 사용자 ID 또는
@없는 사용자명):Terminal window revka channel bind-telegram <IDENTITY> -
다른 LAN 기기에서 대시보드 접근이나 페어링을 허용하려면
0.0.0.0으로 전환하고allow_public_bind = true를 설정하십시오 (위의 바인드 주소 참고).
GPIO 도구, 보드 참조, Pi 전용 안내는 Raspberry Pi (셀프 호스팅), GPIO 도구, 지원 보드 참조를 참고하십시오. Alpine/OpenRC 보드에서는 sudo revka service install로 시스템 서비스를 설치하십시오. 자세한 내용은 백그라운드 서비스로 실행을 참고하십시오.
웹훅 채널 (공개 URL)
섹션 제목: “웹훅 채널 (공개 URL)”웹훅 채널인 WhatsApp Cloud API, Nextcloud Talk, 제네릭 인그레스는 공개 HTTPS 엔드포인트가 필요합니다. 권장 방식은 Gateway를 127.0.0.1에 유지하고 공개 바인딩 대신 터널을 통해 앞에 두는 것입니다:
[tunnel]provider = "tailscale" # or "ngrok", "cloudflare", "pinggy", "openvpn", "custom"웹훅 URL을 터널의 공개 호스트명으로 지정하십시오. 전체 프로바이더 목록, 토큰, 설정 키는 터널로 Gateway 노출하기를, 인그레스 엔드포인트는 웹훅 인그레스를 참고하십시오.
아웃바운드 프록시 라우팅 — [proxy]
섹션 제목: “아웃바운드 프록시 라우팅 — [proxy]”엔터프라이즈 및 에어갭 배포 환경에서는 Revka의 아웃바운드 HTTP/HTTPS/SOCKS5 트래픽을 프록시를 통해 라우팅해야 하는 경우가 많습니다. [proxy] 섹션에서 이를 제어하며, 특정 프로바이더, 채널, 또는 도구만 프록시를 경유하도록 서비스별 라우팅을 설정할 수 있습니다.
[proxy]enabled = truehttp_url = "http://proxy.example.com:8080"https_url = "http://proxy.example.com:8080"scope = "services"services = ["provider.anthropic", "channel.telegram"]| 키 | 환경 변수 오버라이드 | 기본값 | 의미 |
|---|---|---|---|
enabled | REVKA_PROXY_ENABLED | false | 마스터 스위치 |
http_url | REVKA_HTTP_PROXY | 미설정 | HTTP 프록시 URL |
https_url | REVKA_HTTPS_PROXY | 미설정 | HTTPS 프록시 URL |
all_proxy | REVKA_ALL_PROXY | 미설정 | 모든 프로토콜의 폴백 프록시 (SOCKS5) |
no_proxy | REVKA_NO_PROXY | 미설정 | 프록시를 우회하는 호스트 |
scope | REVKA_PROXY_SCOPE | "revka" | environment | revka | services |
services | REVKA_PROXY_SERVICES | [] | 쉼표로 구분된 서비스 키 (scope = "services" 시) |
허용되는 프록시 URL 스킴은 http, https, socks5, socks5h입니다.
스코프: environment / revka / services
섹션 제목: “스코프: environment / revka / services”scope 필드는 프록시가 적용되는 범위를 결정합니다:
| 스코프 | 적용 대상 | 환경 변수 내보내기 여부 | 사용 시점 |
|---|---|---|---|
revka | Revka의 자체 아웃바운드 HTTP 클라이언트 | 아니요 | 프로세스 수준 부작용 없이 일반 런타임 프록시 사용 시 |
services | 나열된 서비스 키/셀렉터만 | 아니요 | 특정 프로바이더, 채널, 도구에 대한 정밀 라우팅 시 |
environment | 런타임 및 프로세스 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY | 예 | 프록시 환경 변수를 읽는 사이드카 또는 서브프로세스가 있는 경우 |
scope = "services"인 경우, 정확한 키 또는 와일드카드로 대상을 선택합니다. 지원되는 키에는 provider.anthropic, provider.openai, provider.compatible, channel.telegram, channel.discord, tool.browser, tool.web_search, memory.embeddings, tunnel.custom, transcription.groq 등이 포함됩니다. provider.*, channel.*, tool.* 와일드카드도 지원됩니다.
[proxy]enabled = truehttp_url = "http://127.0.0.1:7890"scope = "services"services = ["provider.*", "channel.telegram"] # only LLM providers + Telegram런타임에서 프록시 관리 — proxy_config 도구
섹션 제목: “런타임에서 프록시 관리 — proxy_config 도구”에이전트는 proxy_config 도구를 통해 config.toml을 직접 편집하지 않고도 프록시 설정을 실시간으로 읽고 변경할 수 있습니다. 운영자가 에이전트에게 요청 시 프록시 동작을 전환해야 할 때 유용합니다.
액션: get, set, disable, list_services, apply_env, clear_env.
| 파라미터 | 타입 | 사용 액션 | 의미 |
|---|---|---|---|
action | string | 전체 | 위의 액션 중 하나 (기본값 get) |
enabled | bool | set | 프록시 활성화 또는 비활성화 |
scope | string | set | environment | revka | services |
http_proxy / https_proxy / all_proxy | string | set | 프록시 URL |
no_proxy | string or array | set | NO_PROXY 항목 |
services | string or array | set | 서비스 셀렉터 (scope = services 시) |
clear_env | bool | disable | 프로세스 프록시 환경 변수도 함께 초기화 |
프록시 에이전트 플레이북
섹션 제목: “프록시 에이전트 플레이북”모든 프록시 변경 시 이 표준적이고 되돌릴 수 있는 워크플로를 따르십시오: 검사 → 탐색 → 적용 → 확인 → 필요 시 롤백.
-
현재 상태를 검사하고 유효한 서비스 키를 탐색합니다.
{"action": "get"}{"action": "list_services"} -
필요한 스코프를 적용합니다.
프로세스 환경 변수를 내보내지 않고 Revka의 프로바이더/채널/도구 HTTP 트래픽을 라우팅합니다:
{"action": "set", "enabled": true, "scope": "revka","http_proxy": "http://127.0.0.1:7890","https_proxy": "http://127.0.0.1:7890","no_proxy": ["localhost", "127.0.0.1"]}특정 프로바이더/도구/채널만 프록시 처리합니다 (정확한 키 또는 셀렉터):
{"action": "set", "enabled": true, "scope": "services","services": ["provider.openai", "tool.http_request", "channel.telegram"],"all_proxy": "socks5h://127.0.0.1:1080","no_proxy": ["localhost", "127.0.0.1", ".internal"]}프록시 환경 변수를 읽는 서브프로세스를 위해 프로세스 전체 프록시 환경 변수를 내보낸 후 적용합니다:
{"action": "set", "enabled": true, "scope": "environment","http_proxy": "http://127.0.0.1:7890","https_proxy": "http://127.0.0.1:7890","no_proxy": "localhost,127.0.0.1,.internal"}{"action": "apply_env"} -
런타임 및 환경 스냅샷을 확인합니다.
{"action": "get"} -
예상과 다른 동작이 나타나면 롤백합니다.
{"action": "disable"} // disable proxy (safe default){"action": "disable", "clear_env": true} // also clear exported env vars{"action": "clear_env"} // keep proxy on, drop env exports only
RPi 배포 체크리스트
섹션 제목: “RPi 배포 체크리스트”- 사전 빌드된
aarch64/armv7바이너리를 사용하거나,--features hardware로 빌드합니다 (네이티브 GPIO가 필요한 경우peripheral-rpi추가). ~/.revka/config.toml에[peripherals]와[channels_config.telegram]을 설정합니다.revka daemon --host 127.0.0.1 --port 42617을 실행합니다. Telegram은 공개 바인딩 없이도 동작합니다.- LAN 접근이 필요한 경우
--host 0.0.0.0과allow_public_bind = true를 설정합니다. - 웹훅이 필요한 경우 Tailscale, ngrok, 또는 Cloudflare 터널로 Gateway를 앞에 둡니다.
- Telegram 봇 토큰당 폴러를 하나만 유지합니다.