외부 접속 설정¶
Backend.AI GO는 기본적으로 OpenAI 호환 Continuum Router를 127.0.0.1에 바인드합니다. 외부 접속을 명시적으로 켜기 전에는 다른 장치에서 접근할 수 없습니다.
이 문서는 OpenAI 호환 클라이언트가 사용하는 Router(기본 포트 39080)를 다룹니다. REST API, MCP 엔드포인트, 데스크톱 앱 자체를 제공하는 관리 API 서버(기본 포트 8001)는 설정 > API 서버 > 관리 API에 별도의 다른 기기에서 접근 허용 스위치를 두고 있습니다. 보안 유의 사항은 MCP 엔드포인트 문서를 참고하세요.
외부 접속 구성¶
- 설정 > API 서버를 엽니다.
- TCP 서버가 꺼져 있으면 켭니다.
- Router 포트를 확인합니다. 현재 기본값은 39080입니다.
- 외부 액세스 허용을 켜고 경고를 확인합니다. Router는 loopback 대신
0.0.0.0에 바인드합니다. - 설정 > API 서버 > 보안에서 인증 정책을 검토합니다.
- 설정 > API 서버 > 액세스 키에서 원격 클라이언트용 access key를 만듭니다.
- 선택한 포트를 호스트 방화벽에서 의도한 사설 네트워크에만 허용합니다.
포트 변경은 Router를 활성화하거나 다시 시작할 때 적용됩니다. External access 토글은 Router가 사용할 bind 주소를 바꿉니다.
다른 장치에서 연결¶
호스트의 LAN 주소와 구성한 Router 포트를 사용합니다.
OpenAI 호환 클라이언트에는 다음 base URL을 사용합니다.
보안 점검 목록¶
- 필요하지 않을 때는 external access를 끕니다.
- Router를 공용 인터넷에 직접 노출하지 않습니다.
- 원격 클라이언트에 access key를 요구합니다.
- 방화벽 규칙을 신뢰할 수 있는 subnet 또는 특정 장치로 제한합니다.
- 신뢰할 수 없는 네트워크를 건너야 하면 VPN이나 인증된 reverse proxy를 사용합니다.
- 키가 노출되면 즉시 교체합니다.
0.0.0.0은 모든 네트워크 인터페이스에서 요청을 받습니다. API 키가 네트워크 수준 제한을 대신하지는 않습니다.
문제 해결¶
원격 요청이 실패하면 다음을 확인합니다.
- 설정 > API 서버에서 Router가 실행 중인지 확인합니다.
- 클라이언트가 Management API 포트가 아니라 구성한 Router 포트를 쓰는지 확인합니다.
- 외부 액세스 허용이 켜져 있는지 확인합니다.
- 방화벽 규칙과 LAN routing을 확인합니다.
- 설정 > API 서버 > 액세스 키의 키를 확인합니다.
- 먼저 호스트에서
http://127.0.0.1:39080/v1/models를 시험합니다.
게시된 에이전트, 모델 검색, 앱 안의 채팅처럼 앱 자체 기능이 실패한다면 Router가 앱이 자체 호출에 쓰는 키를 거부하고 있는 것입니다. 이때 설정 > API 서버에 원인을 알려 주는 배너가 표시됩니다. 앱이 키를 읽지 못했거나, Router가 다른 키로 시작되었거나, Router가 시작할 때 받은 키를 거부하는 경우입니다. Router와 앱이 키에 대해 서로 다르게 알고 있으면 앱이 Router를 한 번 스스로 재시작합니다. 그 밖의 경우에는 배너의 재시작을 선택합니다. 앱 로그에도 같은 진단이 기록되며, 호출한 위치와 두 키의 지문을 남기고 키 자체는 남기지 않습니다.
게시된 에이전트¶
게시된 에이전트의 Chat Completions와 Responses는 라우터를, A2A는 Management API를 사용합니다. 클라이언트에 필요한 인터페이스만 노출하고 각 리스너에 도달할 수 있는 주소와 키를 사용하세요. A2A에는 agent_invoke 권한이 필요하며 게시 설정 관리에는 agent_read와 agent_write를 사용합니다. Management API 터널만으로는 라우터 포트에 접속할 수 없습니다. 연결 정보와 예제는 에이전트 엔드포인트를 참고하세요.