Initial intranet dashboard app

README.md

@@ -0,0 +1,205 @@
+# 인트라넷 게시판 초보자 가이드
+
+이 프로젝트는 `WSL2 Ubuntu + VS Code` 환경에서 실행하는 사내 게시판입니다.
+중요한 점은, `WSL2`에서는 앱을 `0.0.0.0:8010`으로 띄워도 다른 PC가 곧바로 WSL 주소로 접속되지 않을 수 있다는 점입니다.
+
+즉, 내부망 공유를 하려면 아래 2가지가 모두 필요합니다.
+
+1. WSL 안에서 FastAPI 서버 실행
+2. Windows가 `8010` 요청을 받아 WSL의 `8010`으로 전달하도록 설정
+
+## 1. 이번에 정리된 내용
+
+- 앱은 [main.py](/home/b17301/my-intranet-app/main.py) 에서 `0.0.0.0:8010`으로 실행됨
+- 데이터는 `data.db`에 저장됨
+- WSL2 내부망 공유용 보조 스크립트를 `scripts/` 폴더에 추가함
+- Windows `portproxy`와 방화벽 규칙 설정용 PowerShell 스크립트를 추가함
+
+## 2. 폴더 구조
+
+```text
+my-intranet-app/
+├── main.py
+├── requirements.txt
+├── data.db
+├── static/
+├── templates/
+│   └── index.html
+└── scripts/
+    ├── run_server.sh
+    ├── show_access_info.sh
+    ├── setup_windows_portproxy.ps1
+    └── remove_windows_portproxy.ps1
+```
+
+## 3. 왜 다른 PC에서 접속이 안 되었는가
+
+당신의 현재 환경은 `WSL2`입니다.
+
+WSL2는 Windows 안에 있는 별도 가상 네트워크를 사용합니다.
+그래서 아래처럼 동작할 수 있습니다.
+
+- 내 PC 브라우저에서 `http://127.0.0.1:8010` 접속: 됨
+- 다른 PC에서 `http://WSL-IP:8010` 접속: 안 될 수 있음
+
+이럴 때는 다른 PC가 `Windows 호스트 IP:8010` 으로 접속하고,
+Windows가 그 요청을 WSL 앱으로 넘겨줘야 합니다.
+
+## 4. 처음 한 번만 할 설정
+
+프로젝트 폴더로 이동:
+
+```bash
+cd /home/b17301/my-intranet-app
+```
+
+가상환경 생성:
+
+```bash
+python3 -m venv .venv
+```
+
+가상환경 활성화:
+
+```bash
+source .venv/bin/activate
+```
+
+라이브러리 설치:
+
+```bash
+pip install -r requirements.txt
+```
+
+## 5. WSL에서 서버 실행
+
+아래 명령으로 실행:
+
+```bash
+./scripts/run_server.sh
+```
+
+또는 기존처럼:
+
+```bash
+source .venv/bin/activate
+python main.py
+```
+
+내 PC 테스트 주소:
+
+```text
+http://127.0.0.1:8010
+```
+
+중요:
+
+- 이제 서버는 `reload=False`로 실행되므로, 예전처럼 자동 재시작 로그가 반복해서 나오지 않습니다.
+- 코드를 수정한 뒤 반영하려면 서버를 `Ctrl + C`로 끄고 다시 `./scripts/run_server.sh`를 실행하면 됩니다.
+
+## 6. 현재 WSL 쪽 주소 확인
+
+아래 명령 실행:
+
+```bash
+./scripts/show_access_info.sh
+```
+
+현재 값은 실행 시점마다 달라질 수 있습니다.
+
+- WSL 내부 IP: `./scripts/show_access_info.sh` 실행 결과를 확인
+- Windows와 연결된 주소 추정값: `./scripts/show_access_info.sh` 실행 결과를 확인
+
+하지만 다른 PC가 접속할 때는 보통 `WSL 내부 IP`가 아니라 `Windows 호스트 IP`를 사용해야 합니다.
+
+## 7. 가장 중요한 설정: Windows 포트 전달
+
+다음 작업은 `Windows PowerShell을 관리자 권한`으로 열어서 실행해야 합니다.
+
+가장 쉬운 방법은 `PowerShell`에서 아래 명령을 실행하는 것입니다.
+
+```powershell
+& "\\wsl$\Ubuntu\home\b17301\my-intranet-app\scripts\setup_windows_portproxy.ps1" -Port 8010
+```
+
+만약 `CMD` 창만 사용하고 있다면 아래 명령을 그대로 실행하면 됩니다.
+
+```cmd
+"\\wsl$\Ubuntu\home\b17301\my-intranet-app\scripts\setup_windows_portproxy.cmd"
+```
+
+이 스크립트가 하는 일:
+
+- Windows의 `0.0.0.0:8010` 수신
+- 들어온 요청을 `현재 WSL IP:8010` 으로 전달
+- Windows 방화벽에서 TCP `8010` 허용
+
+## 8. 다른 PC에서 접속할 주소
+
+다른 PC 브라우저에서는 아래처럼 접속합니다.
+
+```text
+http://Windows호스트IP:8010
+```
+
+예를 들어 Windows PC의 실제 사내 IP가 `192.168.0.25` 라면:
+
+```text
+http://192.168.0.25:8010
+```
+
+여기서 중요한 점:
+
+- WSL 주소를 다른 PC에 알려주면 안 될 수 있음
+- 다른 PC에는 반드시 `Windows IP`를 알려주는 쪽이 안전함
+
+## 9. WSL IP가 바뀌면 어떻게 하나
+
+WSL을 재시작하면 내부 IP가 바뀔 수 있습니다.
+그럴 때는 아래 순서로 다시 맞추면 됩니다.
+
+1. WSL에서 `./scripts/show_access_info.sh` 실행
+2. 새 WSL IP 확인
+3. 관리자 PowerShell에서 다시 실행
+
+```powershell
+.\setup_windows_portproxy.ps1 -Port 8010
+```
+
+## 10. 접속 확인 순서
+
+1. WSL에서 `./scripts/run_server.sh` 실행
+2. 내 PC 브라우저에서 `http://127.0.0.1:8010` 확인
+3. Windows 관리자 PowerShell에서 `setup_windows_portproxy.ps1` 실행
+4. 다른 PC에서 `http://Windows호스트IP:8010` 접속
+
+## 11. 안 되면 확인할 것
+
+1. 서버가 실제로 실행 중인지 확인
+
+```bash
+lsof -i :8010
+```
+
+2. 다른 프로그램이 `8010`을 이미 사용 중인지 확인
+3. Windows 방화벽 규칙이 생겼는지 확인
+4. 회사 네트워크에서 사설 포트 접근이 막히지 않았는지 확인
+5. WSL IP가 바뀌었는지 확인
+
+## 12. 제거가 필요할 때
+
+관리자 PowerShell에서:
+
+```powershell
+& "\\wsl$\Ubuntu\home\b17301\my-intranet-app\scripts\remove_windows_portproxy.ps1" -Port 8010
+```
+
+또는 `CMD`에서는:
+
+```cmd
+"\\wsl$\Ubuntu\home\b17301\my-intranet-app\scripts\remove_windows_portproxy.cmd" 8010
+```
+
+## 13. 초보자용 한 줄 요약
+
+이 프로젝트는 이제 코드 문제는 해결되어 있고, 내부망 공유의 핵심은 `Windows IP:8010 -> WSL 8010` 연결을 Windows에서 열어주는 것입니다.