SPipe/SERVER_SETUP.md

SPipe 사내 서버 설치 안내

다른 Windows PC를 SPipe 서버로 쓰기 위한 절차입니다. 사내 사용자는 브라우저에서 http://<서버 IP>:8080 으로 접속합니다.

• 웹 화면: 서버의 8080 포트 (사내망에 공개)
• 해석 API: 서버 내부 127.0.0.1:8000 (외부 비공개, 웹 서버가 /api 요청만 전달)

1. 준비물

항목	버전 / 비고
Windows x64 PC	해석 엔진 64bit/epanet2.dll 사용
Node.js	24.x (검증 버전 24.14.1)
Python	3.12 64비트 (검증 버전 3.12.10), Python Launcher(py) 포함
인터넷	최초 패키지 설치, 배경지도·주소 검색

2. 설치 (최초 1회)

전달받은 SPipe_server_*.zip을 C:\SPipe에 압축 해제한 뒤 PowerShell에서 실행합니다. 경로는 원하는 위치로 바꿔도 됩니다.

cd C:\SPipe

npm.cmd ci
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
.\.venv\Scripts\python.exe -m pip check

Copy-Item .env.example .env.local
notepad .env.local

npm.cmd test
npm.cmd run build

.env.local에는 브이월드 API 키와 카카오 JavaScript 키를 넣습니다. 키는 저장소·압축 파일에 들어 있지 않으니 담당자에게 따로 받습니다. 키를 넣지 않으면 브이월드 배경지도와 주소 검색만 동작하지 않고, 키를 바꾼 뒤에는 다시 빌드(npm.cmd run build 또는 start-lan.ps1 -Rebuild)해야 반영됩니다.

npm test가 모두 통과하고 빌드가 성공하면 다음 단계로 넘어갑니다.

3. 방화벽 (관리자 PowerShell, 최초 1회)

같은 사내 서브넷에서만 8080 포트 접속을 허용합니다. 회사 네트워크가 "공용"으로 잡혀 있어도 적용되도록 세 프로필을 모두 지정합니다.

New-NetFirewallRule -DisplayName "SPipe 8080" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow -Profile Domain,Private,Public -RemoteAddress LocalSubnet

다른 층·지사 등 서브넷이 다른 곳에서도 접속해야 하면 LocalSubnet 대신 사내 IP 대역(예: 10.0.0.0/8)을 넣습니다. 8000 포트는 열지 않습니다.

4. 실행

cd C:\SPipe
powershell -ExecutionPolicy Bypass -File .\start-lan.ps1

화면에 표시되는 http://<서버 IP>:8080 주소를 사내에 공유합니다. 창을 닫거나 Ctrl+C를 누르면 웹·API 서버가 함께 종료됩니다.

재부팅 후 자동으로 켜려면 작업 스케줄러에 "로그온 시" 트리거로 위 명령을 등록합니다.

5. 카카오 주소 검색 도메인 등록

주소 검색은 카카오 JavaScript 키를 쓰며, 등록된 주소에서만 동작합니다. 카카오 개발자 콘솔 → 앱 → 플랫폼 키 → JavaScript 키 → "JavaScript SDK 도메인"에 서버 주소를 추가합니다.

• 예: http://10.12.30.5:8080 (서버의 실제 IP)
• 서버 PC에서 직접 열 경우: http://localhost:8080

서버 IP가 바뀌면 이 등록도 바꿔야 하므로, 서버 PC는 고정 IP를 받아 두는 것을 권장합니다.

6. 업데이트

새 zip을 받으면 서버를 끄고(Ctrl+C), C:\SPipe에 덮어써 압축을 푼 뒤 실행합니다. .venv, node_modules 폴더는 지우지 않아도 됩니다.

cd C:\SPipe
npm.cmd ci
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
powershell -ExecutionPolicy Bypass -File .\start-lan.ps1 -Rebuild

start-lan.ps1은 dist 폴더가 있으면 기존 빌드를 그대로 씁니다. 코드를 받은 뒤에는 반드시 -Rebuild를 붙입니다.

7. 사용자 안내 사항

• 작업 내용 자동 저장은 각자의 브라우저에만 남습니다. 서버에 저장되지 않으므로 INP와 결과물은 파일로 보관합니다.
• 배경지도·주소 검색·표고 조회는 외부 인터넷이 필요합니다.
• .net 내보내기는 지원하지 않습니다. .inp로 저장합니다.
• 로그인 기능이 없어 사내망의 누구나 접속할 수 있습니다.

8. 알려진 보류 항목 (2026-10-15 점검)

• vite preview는 상시 운영용 서버가 아닙니다. 사용자가 늘면 nginx 구성(deploy/)으로 옮깁니다.
• API 업로드 의존성(python-multipart 0.0.20, Starlette 0.47.3)에 알려진 보안 문제가 있어 수정 버전으로 갱신이 예정되어 있습니다. 갱신 전까지는 사내망에서만 운영합니다.