CLI 로 실행하는 서버
iosignal-cli는 코드를 작성하지 않고 IOSignal 서버를 실행하는 프로그램입니다.
설치
Node.js 22.16.0 이상이 필요하며 Windows, macOS, Linux에서 설치할 수 있습니다.
npm install -g iosignal-cli
서버 실행
io-server와 별칭 ios를 사용할 수 있습니다. -l 또는 -L 중 하나 이상이 필요하며, 없으면 오류로 종료합니다.
io-server -l 7777 # WebSocket 서버
io-server -L 8888 # CongSocket(TCP) 서버
io-server -l 7777 -L 8888 # 두 전송 방식 함께 사용
io-server --help # 옵션과 실행 예제
io-server --version # CLI 및 IOSignal 버전
브라우저와 Node.js는 ws://localhost:7777, TCP 클라이언트는 cong://localhost:8888, Arduino는 서버 호스트와 TCP 포트로 연결합니다. 다른 장치에서는 localhost 대신 서버의 IP나 도메인을 씁니다. 서버는 Ctrl+C로 종료합니다.
서버 옵션
| 옵션 | 설명 |
|---|---|
-l, --listen <port> | WebSocket 포트 |
-L, --listen-congport <port> | CongSocket(TCP) 포트 |
-d, --auth-file <path> | JSON 또는 JavaScript 인증 파일 |
-e, --auth-param <id.key.cid[.role[.quota]]> | 인증 정보, 여러 항목은 쉼표로 구분. 역할은 device(기본)·service·admin |
-r, --auth-redis | Redis 인증 사용 |
-i, --id-key | 로컬 테스트: 키가 ID와 같은 모든 ID 로그인 (CID = ID) |
-k, --shared-key <key> | 로컬 테스트: 공통 키를 가진 모든 ID 로그인 (CID = ID) |
-M, --members-only | 인증하지 않은 연결의 시그널 차단 |
-t, --heartbeat-interval <milliseconds> | 연결 확인 주기, 기본 50000ms, 범위 1000~2147483647 |
-m, --log-stats <milliseconds> | N ms마다 한 줄 집계 출력. 0은 끔, 그 외 1000~2147483647 |
-s, --log-messages | 받은 메시지의 종류와 태그 로그(내용은 남기지 않음) |
-q, --anonymous-quota <profile> | 미인증 연결의 쿼터 프로필: anonymous(기본), basic, pro, unlimited |
-f, --file-logger | 현재 작업 디렉터리에 connection.log, auth.log, attack.log 기록 |
-a, --attach-services [list...] | reply, sudo, redis 중 공백으로 구분하여 등록; 기본은 없음 |
-o, --show-options | 초기 설정과 등록된 서비스 이름 출력 |
-V, --version / -h, --help | 버전 / 도움말 |
포트 범위는 0~65535이며, 0은 운영체제가 사용 가능한 포트를 선택하도록 합니다. --auth-env와 --api-list는 지원하지 않습니다.
인증
io-server -l 7777 --auth-file ./auth_file.json
io-server -l 7777 --auth-param 'uno.uno-key.uno,admin.admin-key.admin.admin'
쿼터를 생략하면 device는 basic, service·admin은 unlimited 프로필을 씁니다. 파일 형식은 인증 문서를 참고하세요. 인증 옵션을 함께 지정하면 --auth-file → --auth-param → --auth-redis 순서로 하나만 선택됩니다. 지정하지 않으면 인증 제공자를 설정하지 않습니다.
로컬 테스트 로그인
iosignal-cli 8.1.0부터 --id-key나 --shared-key로 키 목록 없이 인증을 켤 수 있습니다. 로그인 ID가 그대로 CID가 됩니다.
io-server -l 7777 -L 8888 --id-key # 키가 ID와 같으면 로그인
io-client -i dev1 -k dev1
io-server -l 7777 -k lab2026 -M # 아무 ID + 공통 키, 익명 시그널 차단
io-client -i dev1 -k lab2026
- 익명 연결은
-M없이도 계속 접속할 수 있습니다.-M은 다른 인증 옵션과도 함께 쓸 수 있습니다. --id-key와--shared-key는 서로, 또는 다른 인증 옵션과 함께 쓰면 오류로 종료합니다.- 시작 화면의
Authentication에 인증 방식이 표시되며 공통 키는 출력하지 않습니다. - 규칙을 아는 누구나 임의 ID로 로그인할 수 있으므로 신뢰하는 로컬 네트워크의 테스트에만 사용하세요. 자세한 내용은 로컬 테스트 로그인을 참고하세요.
쿼터
모든 연결은 쿼터 프로필(메시지 크기, 발행 한 건의 전달 수, 초당 메시지·바이트, 계정당 연결 수)을 따르며 서버가 항상 적용합니다. 미인증 연결은 anonymous 프로필을 씁니다. 로컬 테스트에서 큰 메시지를 보내려면 -q unlimited처럼 다른 프로필을 지정합니다.
io-server -l 7777 -q unlimited -m 10000 # 익명 연결 제한 없음, 10초마다 집계
Redis와 내장 서비스
Redis 기본 주소는 localhost:6379이며 REDIS_HOST, REDIS_PORT로 바꿉니다(아래는 macOS·Linux 셸 구문). 인증과 Redis 서비스는 같은 연결을 씁니다.
REDIS_HOST=127.0.0.1 REDIS_PORT=6379 io-server -l 7777 --auth-redis
io-server -l 7777 --auth-redis --attach-services reply redis
서버는 Redis 연결 후 시작하며, 5초 안에 연결하지 못하면 종료 코드 1로 끝납니다(자동 재접속 없음).
서비스 호출을 체험하려면 다음 서버를 실행한 뒤 클라이언트에서 call reply echo hello를 입력합니다.
io-server -l 7777 --attach-services reply
sudo 서비스는 별도로 등록해야 합니다. sudo는 admin 역할로, redis 서비스는 service 이상의 역할로 로그인한 연결만 호출할 수 있으므로 인증 옵션과 함께 사용하세요. 중복 로그인 정책은 아직 CLI 옵션으로 지정할 수 없으며 라이브러리 기본값을 따릅니다. 다음 단계는 CLI 클라이언트 사용법을 참고하세요.