포트 충돌·CORS 문제 해결

서버는 떴는데 접속이 안 되거나, 브라우저(connect-web)에서 CORS 오류가 나나요? 포트 설정과 출처(origin) 구성을 함께 짚어보면 대부분 풀립니다.

증상

• 서버 기동 시 포트가 이미 사용 중이라는 오류가 납니다.
• 클라이언트가 서버에 접속하지 못합니다.
• 브라우저 콘솔에 CORS(Cross-Origin) 오류가 보입니다.

원인

먼저 바른의 포트 구성을 정리해봐요.

해결

1. 포트 충돌부터 확인하세요. 기동 오류가 "포트 사용 중"이라면, 같은 포트를 쓰는 다른 프로세스가 있는 것입니다. bareun.json의 address.port(기본 5656)를 비어 있는 포트로 바꾸고 서버를 다시 실행하세요.

   복사

   {
     "address": { "ipAddr": "0.0.0.0", "port": 5656 },
     "staticAddress": { "ipAddr": "0.0.0.0", "port": 5656 }
   }
   

   포트를 바꾸면 재시작이 필요해요

   포트 변경은 서버를 다시 실행해야 적용됩니다. 클라이언트가 요청하는 포트도 함께 맞추세요.

2. 클라이언트가 맞는 포트로 접속하는지 보세요. 네이티브 설치본과 도커 배포본 모두 기본 5656 포트를 사용합니다(네이티브는 5658도 함께 쓸 수 있습니다). 환경에 맞는 포트로 요청하고 있는지 확인하세요.

3. 브라우저(connect-web)는 CORS를 점검하세요. 바른 서버(connect-go)는 connect-web 요청을 직접 받으며 CORS도 서버가 직접 처리합니다. 별도의 프록시는 필요하지 않습니다. 웹 프런트엔드가 서버와 다른 출처(origin)에서 요청한다면, 서버가 그 출처를 허용하도록 구성돼 있는지와 클라이언트가 올바른 주소·포트로 요청하는지 확인하세요.

예방·팁

• 한 호스트에 여러 인스턴스를 띄운다면 포트가 겹치지 않게 미리 계획하세요.
• 브라우저에서 붙는 구성이라면 connect-web으로 서버를 직접 호출하면 됩니다. 같은 출처로 서빙하거나 서버의 허용 출처 설정을 맞추면 CORS 문제를 피할 수 있어요.

자주 묻는 질문

Q. 포트가 충돌하면 어떻게 바꾸나요?

bareun.json의 address.port(기본 5656)를 비어 있는 포트로 변경하고 서버를 다시 실행하세요. 정적 자원을 같은 포트로 서빙한다면 staticAddress.port도 함께 맞추는 게 좋습니다.

Q. 브라우저에서 CORS 오류가 나요.

connect-web으로 다른 출처에서 요청하면 CORS 처리가 필요합니다. 바른 서버가 connect-web과 CORS를 직접 처리하므로, 서버가 해당 출처를 허용하도록 구성돼 있는지 확인하고 클라이언트가 올바른 주소·포트로 요청하는지 점검하세요. 같은 출처에서 서빙하면 CORS 문제 자체가 생기지 않습니다.

Q. 네이티브와 도커의 포트는 같나요?

네. 둘 다 기본 5656 포트를 사용합니다. 네이티브 설치본은 gRPC/Connect와 정적 자원을 같은 포트 (또는 5658)에서 서빙하고, 도커 배포본도 5656으로 직접 서비스합니다. 바른 서버(connect-go)가 한 포트에서 gRPC·connect-web·HTTP+JSON을 모두 처리하고 CORS도 직접 담당하므로, 별도의 Envoy 프런트(과거 5757)나 관리 포트 9902는 쓰지 않습니다.

Q. REST(HTTP+JSON)로 호출할 때 경로는 무엇인가요?

바른은 Connect 경로를 사용합니다. POST /bareun.<Service>/<Method> 형식으로 호출하세요(예: POST /bareun.LanguageService/AnalyzeSyntax). 옛 게이트웨이 경로(/bareun/api/v1/...)는 쓰지 않습니다. 같은 5656 포트로 gRPC·connect-web과 함께 처리됩니다.