CLI 명령어
Node Agent
| 명령어 |
설명 |
예시 |
python -m node.node_agent |
Node Agent 실행 (설정 파일 사용) |
python -m node.node_agent |
--slot-id <id> |
Slot ID 지정 (자동 등록) |
--slot-id slot_abc123 |
--token <token> |
Login Token 지정 (자동 등록) |
--token eyJhbGci... |
python request_slot.py |
Slot 발급 요청 |
python request_slot.py --email user@example.com |
Hub 관리 도구
| 명령어 |
설명 |
예시 |
python tools/admin_tool.py list-nodes |
전체 Node 목록 조회 |
python tools/admin_tool.py list-nodes |
python tools/admin_tool.py list-users |
전체 사용자 목록 조회 |
python tools/admin_tool.py list-users |
python tools/admin_tool.py node-status <node_id> |
특정 Node 상태 조회 |
python tools/admin_tool.py node-status node_abc123 |
python tools/admin_tool.py delete-node <node_id> |
Node 삭제 |
python tools/admin_tool.py delete-node node_abc123 |
주요 API 엔드포인트
Hub API
| 엔드포인트 |
메서드 |
설명 |
/admin/nodes |
GET |
전체 Node 목록 조회 |
/admin/nodes/{node_id} |
GET |
특정 Node 상세 정보 |
/admin/health |
GET |
관리용 헬스체크 |
/health |
GET |
시스템 헬스체크 |
/api/nodes/request-slot |
POST |
Slot 발급 요청 (이메일 기반) |
/api/nodes/register_by_slot |
POST |
Slot 기반 Node 등록 |
/ws/node |
WS |
Node Agent 연결 엔드포인트 (기존 방식) |
/tunnel/{node_id} |
WS |
Node Agent 연결 엔드포인트 (Nginx 프록시 환경) |
Reverse Proxy
모든 HTTP 요청은 Host 헤더 기반으로 Node로 라우팅됩니다:
# 예: https://node1.orbisync.com/api/data
# → Hub가 "node1" subdomain을 추출하여 해당 Node로 프록시
주요 설정값/환경 변수
Hub 설정
| 변수명 |
타입 |
기본값 |
설명 |
HUB_HOST |
string |
0.0.0.0 |
Hub 서버 바인딩 주소 |
HUB_PORT |
int |
8000 |
Hub 서버 포트 |
DB_URL |
string |
sqlite+aiosqlite:///./hub.db |
데이터베이스 연결 URL |
LOG_LEVEL |
string |
INFO |
로그 레벨 (DEBUG, INFO, WARNING, ERROR) |
HEARTBEAT_INTERVAL_SECONDS |
int |
10 |
Heartbeat 간격 (초) |
HEARTBEAT_TIMEOUT_SECONDS |
int |
30 |
Heartbeat 타임아웃 (초) |
Node 설정
| 변수명 |
타입 |
필수 |
설명 |
HUB_URL |
string |
예 |
Hub WebSocket URL |
NODE_ID |
string |
예* |
Node 식별자 (*Slot 기반 제외) |
AUTH_TOKEN |
string |
예* |
인증 토큰 (*Slot 기반 제외) |
SLOT_ID |
string |
선택 |
Slot ID (자동 등록용) |
LOGIN_TOKEN |
string |
선택 |
Login Token (자동 등록용) |
LOCAL_TARGET_URL |
string |
선택 |
로컬 타겟 URL |
HEARTBEAT_INTERVAL |
int |
선택 |
Heartbeat 간격 (초, 기본값: 10) |
RECONNECT_INTERVAL |
int |
선택 |
재연결 간격 (초, 기본값: 5) |
Sync 설정
| 변수명 |
타입 |
설명 |
sync_type |
string |
동기화 타입: "local" (클라이언트) 또는 "remote" (서버) |
local_root |
string |
로컬 루트 디렉토리 (클라이언트) |
remote_root |
string |
원격 루트 디렉토리 (서버) |
remote_base_url |
string |
원격 서버 URL (클라이언트) |
auth_token |
string |
인증 토큰 |
ignore_patterns |
array |
무시할 파일/폴더 패턴 |
server_host |
string |
서버 바인딩 주소 (서버) |
server_port |
int |
서버 포트 (서버) |
relay_enabled |
bool |
릴레이 모드 활성화 (서버) |
relay_url |
string |
릴레이 대상 URL (서버) |
로그/에러 코드
일반적인 로그 메시지
| 로그 레벨 |
메시지 |
의미 |
| INFO |
Registered successfully! Node ID: node_xyz789 |
Node 등록 성공 |
| INFO |
Tunnel connected: node_xyz789 |
터널 연결 성공 |
| WARNING |
Connection closed unexpectedly |
연결이 예기치 않게 종료됨 (자동 재연결 시도) |
| ERROR |
Hub server unreachable |
Hub 서버에 연결할 수 없음 |
| ERROR |
Registration failed: Invalid slot or token |
Slot 또는 Token이 유효하지 않음 |
에러 코드
| 에러 코드 |
설명 |
해결 방법 |
PLAN_EXPIRED |
플랜이 만료됨 |
플랜을 갱신하거나 새로운 플랜을 구매하세요 |
NODE_LIMIT_EXCEEDED |
Node 개수 제한 초과 |
기존 Node를 삭제하거나 플랜을 업그레이드하세요 |
INVALID_SLOT |
유효하지 않은 Slot |
새로운 Slot을 발급받아 다시 시도하세요 |
INVALID_TOKEN |
유효하지 않은 Token |
Token을 확인하고 다시 시도하세요 |
다음 단계
참고 자료를 확인했다면 다음 문서를 확인해보세요:
