포트 충돌·CORS

Q: 바른 서버에서 포트 충돌이 날 때 어떻게 해결하나요?

bareun.json의 address.port(기본 5656)를 비어 있는 포트로 변경하고 서버를 다시 실행하세요. 정적 자원을 같은 포트로 서빙한다면 staticAddress.port도 함께 맞추고, 클라이언트가 요청하는 포트도 동일하게 변경해야 합니다.

Q: 브라우저에서 CORS 오류가 나는 이유는 무엇인가요?

connect-web 클라이언트가 서버와 다른 출처에서 요청하면 CORS 처리가 필요합니다. 바른 서버(connect-go)가 connect-web과 CORS를 직접 처리하므로 별도 프록시 없이, 서버가 해당 출처를 허용하도록 구성하거나 같은 출처에서 서빙하면 해결됩니다.

Q: 바른은 Envoy 프록시나 관리 포트가 필요한가요?

필요하지 않습니다. 바른 서버는 connect-go로 gRPC·connect-web·HTTP+JSON을 한 포트(기본 5656)에서 처리하고 CORS도 직접 담당합니다. 도커에서도 5656을 직접 노출하며, 과거의 Envoy 프런트(5757)나 관리 포트 9902는 사용하지 않습니다.

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

Connect 경로를 사용합니다. POST /bareun. / 형식으로 호출하며, 예를 들어 POST /bareun.LanguageService/AnalyzeSyntax 입니다. 옛 게이트웨이 경로(/bareun/api/v1/...)는 쓰지 않고, 같은 5656 포트에서 gRPC·connect-web과 함께 처리됩니다.

포트 충돌·CORS 문제 해결

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

증상

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

원인

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

환경	포트	용도
네이티브 설치본	5656	gRPC/Connect + 정적 자원(동일 포트 서빙 가능)
도커 배포본	5656	gRPC/Connect + 정적 자원
클라우드	443	TLS, API 키 필요

원인	설명
포트 충돌	다른 프로세스가 같은 포트를 이미 점유
잘못된 포트로 접속	클라이언트가 다른 포트로 요청
CORS 미허용	브라우저에서 다른 출처로 요청했는데 허용되지 않음

해결

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

포트 변경은 서버를 다시 실행해야 적용됩니다. 클라이언트가 요청하는 포트도 함께 맞추세요.
클라이언트가 맞는 포트로 접속하는지 보세요. 네이티브 설치본과 도커 배포본 모두 기본 5656 포트를 사용합니다(네이티브는 5658도 함께 쓸 수 있습니다). 환경에 맞는 포트로 요청하고 있는지 확인하세요.
브라우저(connect-web)는 CORS를 점검하세요. 바른 서버(connect-go)는 connect-web 요청을 직접 받으며 CORS도 서버가 직접 처리합니다. 별도의 프록시는 필요하지 않습니다. 웹 프런트엔드가 서버와 다른 출처(origin)에서 요청한다면, 서버가 그 출처를 허용하도록 구성돼 있는지와 클라이언트가 올바른 주소·포트로 요청하는지 확인하세요.

0.0.0.0 vs 특정 인터페이스

address.ipAddr의 기본값은 0.0.0.0으로 모든 인터페이스에서 받습니다. 특정 네트워크 인터페이스만 열려면 그 호스트 주소로 바꿀 수 있어요. 접속이 안 될 때 바인딩 주소도 확인 대상입니다.

예방·팁

한 호스트에 여러 인스턴스를 띄운다면 포트가 겹치지 않게 미리 계획하세요.
브라우저에서 붙는 구성이라면 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과 함께 처리됩니다.

아직 충분히 검증되지 않은 문서입니다

이 문서의 포트·CORS 관련 설명은 아직 충분히 검증되지 않았습니다. 실제 환경·버전에 따라 동작이 다를 수 있으니 참고용으로만 활용해 주세요. 정확한 동작은 운영 환경에서 직접 확인하시거나 지원 요청 채널로 문의해 주세요.

도움이 되었나요?