ev-charging-backend/INSTALL_GUIDE.md

EV 충전 플랫폼 — 설치 / 복원 가이드

서버 정보

항목	값
서버	debian5825u (192.168.0.126)
도메인	s1.byunc.com (OCPP/대시보드), ecap.byunc.com (프록시)
프로젝트 경로	~/steve/ev-charging-backend
Steve 경로	~/steve/steve

포트 구성

서비스	포트	설명
FastAPI	8000	EV 충전 백엔드 API
Steve OCPP	8180	OCPP 서버
PostgreSQL	5432	충전 데이터 DB
Redis	6375	세션 캐시
MariaDB (Steve)	3307	Steve DB
OCPP 프록시	9002	충전기 WebSocket 프록시
프록시 관리웹	9003	프록시 관리 패널

신규 설치 순서

1. 코드 가져오기

cd ~/steve
git clone https://gitea.byunc.com/byun/ev-charging-backend.git
cd ev-charging-backend

2. 환경변수 설정

cp .env.example .env
nano .env

수정할 항목:

• POSTGRES_PASSWORD — DB 비밀번호
• REDIS_PORT=6375
• STEVE_API_PASSWORD=1234
• JWT_SECRET — 랜덤 문자열로 변경
• 토스페이먼츠 키 (있으면)

3. Docker 실행

docker compose build api
docker compose up -d

# 정상 확인
docker compose ps
curl http://localhost:8000/health

4. OCPP 프록시 설치

pip3 install websockets aiohttp

# 수동 실행 테스트
python3 ocpp_proxy_server.py
# Ctrl+C로 종료

# systemd 서비스 등록
sudo nano /etc/systemd/system/ocpp-proxy.service

[Unit]
Description=OCPP Proxy Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/steve/ev-charging-backend
ExecStart=/usr/bin/python3 ocpp_proxy_server.py
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable ocpp-proxy
sudo systemctl start ocpp-proxy
sudo systemctl status ocpp-proxy

5. Nginx 설정 (별도 서버인 경우)

s1.byunc.com — /api/ → :8000, /steve/ → :8180, /dashboard → :8000

ecap.byunc.com — / → :9003 (관리웹), /api/ → :9003, /ws/ → :9003, 나머지 → :9002 (프록시)

6. 테스트

# 전체 충전 흐름 테스트
python3 test_flow.py

# 대시보드 접속
# https://s1.byunc.com/dashboard  (admin / admin1234)

# 프록시 관리
# https://ecap.byunc.com  (admin / admin1234)

백업 순서

코드 백업 (Gitea)

cd ~/steve/ev-charging-backend
git add .
git commit -m "백업 메모"
git push

DB 백업

# PostgreSQL 덤프
docker exec ev-postgres pg_dump -U evuser ev_charging > backup_db_$(date +%Y%m%d).sql

# Steve MariaDB 덤프
docker exec steve-db-1 mariadb-dump -u root -p<비밀번호> stevedb > backup_steve_$(date +%Y%m%d).sql

설정 파일 백업 (Git에 포함 안 되는 것들)

# 한번에 묶기
tar czf backup_configs_$(date +%Y%m%d).tar.gz .env proxy_users.json proxy_config.json

복원 순서

1. 코드 복원

cd ~/steve
git clone https://gitea.byunc.com/byun/ev-charging-backend.git
cd ev-charging-backend

2. 설정 복원

# .env 파일 복원 (백업에서 복사 또는 .env.example에서 재작성)
cp .env.example .env
nano .env

# 프록시 설정 복원 (있으면)
# proxy_users.json, proxy_config.json 복사

3. Docker 실행

docker compose build api
docker compose up -d

4. DB 복원 (백업 파일이 있는 경우)

# PostgreSQL
cat backup_db_20260418.sql | docker exec -i ev-postgres psql -U evuser ev_charging

# Steve MariaDB
cat backup_steve_20260418.sql | docker exec -i steve-db-1 mariadb -u root -p<비밀번호> stevedb

5. 프록시 서비스 시작

sudo systemctl start ocpp-proxy

문제 해결

증상	확인	해결
API 502	docker compose ps	docker compose up -d
프록시 실패	sudo journalctl -u ocpp-proxy -n 20	포트 충돌 확인 ss -tlnp
대시보드 500	docker compose logs api --tail 20	docker compose restart api
bcrypt 에러	requirements.txt 확인	bcrypt==4.0.1 확인 후 docker compose build api
포트 충돌	ss -tlnp | grep 포트	sudo kill $(lsof -t -i:포트)
DB 연결 실패	docker compose logs postgres	.env의 비밀번호 확인

주요 파일 구조

ev-charging-backend/
├── docker-compose.yml       ← Docker 서비스 정의
├── Dockerfile               ← FastAPI 이미지
├── requirements.txt         ← Python 패키지
├── .env                     ← 환경변수 (Git 제외)
├── .gitignore
├── app/                     ← FastAPI 백엔드 코드
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── models/
│   ├── schemas/
│   ├── routers/
│   └── services/
├── dashboard.html           ← 관리 대시보드
├── simulator.html           ← 충전 시뮬레이터
├── ocpp_proxy_server.py     ← OCPP 프록시 (Docker 외부)
├── proxy_control.html       ← 프록시 관리 UI
├── test_flow.py             ← CLI 테스트 스크립트
├── ev_simulator.py          ← GUI 테스트 도구
├── nginx_fastapi.conf       ← Nginx 설정 참고
└── README.md