Files

T

CI / Frontend - type-check & test (push) Canceled after 0s

Details

aaPanel 프록시와 공용 인증서 적용 결과를 운영 문서에 남겼다.`nHTTP의 HTTPS 전환과 공개 주소 응답 검증 및 .com 별칭 동작을 기록했다.

2026-10-03 08:37:26 +09:00

4.5 KiB

Raw Blame History

ITOSM 피아노 학습실 - Bach to Basics 설치 및 운영

운영 정보

항목	값
설치 위치	`/home/syskiller/piano/bach-to-basics`
Gitea 저장소	`syskiller/ITOSMPiano-BachToBasics`
프론트엔드 컨테이너	`piano-bach-frontend`
백엔드 컨테이너	`piano-bach-backend`
호스트 포트	`127.0.0.1:18102`
백엔드 내부 포트	`8000`
기본 주소	`https://learn.itosm.co.kr`
별칭 주소	`https://learn.itosm.com`
MusicXML 보관 폴더	`/home/syskiller/piano/music/musicxml`

백엔드는 호스트 포트를 열지 않는다. 프론트엔드 nginx만 Docker 내부 네트워크에서 백엔드에 접근한다. 외부 요청은 aaPanel nginx와 프론트엔드 nginx를 차례로 거친다.

aaPanel의 프록시 프로젝트에는 learn.itosm.co.kr을 등록했다. 공용 *.itosm.co.kr 인증서를 적용했으며 HTTP 요청은 HTTPS로 강제 전환한다. 2026-10-03 공개 주소에서 HTTPS 200 응답과 인증서의 대상 도메인을 확인했다. learn.itosm.com은 기본 주소로 이동한다.

실행과 관리

cd /home/syskiller/piano/bach-to-basics
docker compose up -d --build
docker compose ps
docker compose logs -f --tail=200
docker compose restart
docker compose down

프론트엔드 내부 확인은 curl http://127.0.0.1:18102/로 한다. 백엔드 확인은 프론트엔드 프록시를 통해 curl http://127.0.0.1:18102/api/openapi.json을 사용한다.

비밀 파일과 환경 변수

백엔드 API 키는 secrets/backend_api_key에 저장한다. 파일 권한은 600을 유지하고 Git에 넣지 않는다. Compose는 다음 값을 사용한다.

BACKEND_API_KEY_FILE=/run/secrets/backend_api_key
REQUIRE_AUTH=1
ALLOWED_ORIGINS=https://learn.itosm.co.kr,https://learn.itosm.com
RATE_LIMIT_PER_MIN=60

프론트엔드 컨테이너가 비밀 파일을 읽어 백엔드로 보내는 내부 요청에만 인증 헤더를 추가한다.

업데이트

git status --short --branch로 로컬 변경을 확인한다.
공식 origin의 변경을 가져온다.
한국어판과 운영 보안 커밋의 충돌 여부를 확인한다.
docker compose build를 실행한다.
docker compose up -d로 두 전용 컨테이너만 교체한다.
MIDI와 MusicXML 가져오기 및 악보와 내려오는 음표 화면을 다시 검사한다.

한국어판 변경 파일

frontend/src/i18n/ko.ts
frontend/src/main.tsx
frontend/index.html
frontend/vite.config.ts
frontend/src/index.css
frontend/src/views/PracticeView.tsx
frontend/src/components/Transport/TransportControls.tsx
backend/main.py
backend/routers/transcribe.py
frontend/nginx.conf
frontend/docker-entrypoint.d/20-backend-api-key.sh
frontend/Dockerfile
docker-compose.yml

한국어 번역 리소스와 모바일 화면 보완 및 서버 내부 API 키 처리를 추가했다. 공식 CI와 같은 pnpm 9를 사용하도록 고정해 잠금 파일 기반 빌드를 유지한다. MIDI와 MusicXML 및 악보와 내려오는 음표와 따라치기 기능은 원본 구조를 유지한다. 표준 .musicxml 확장자도 파일 선택과 백엔드 변환에서 지원한다.

데이터와 한글 파일명

MIDI와 MusicXML은 브라우저 파일 선택이나 끌어 놓기로 불러온다. 공용 보관 폴더는 /home/syskiller/piano/music/midi와 /home/syskiller/piano/music/musicxml이다. 프론트엔드는 파일명을 유니코드 문자열로 처리하며 백엔드 전송 제목에는 UTF-8 URL 인코딩을 사용한다.

원본으로 되돌리기

공식 원본 커밋을 별도 작업 트리에 복원해 빌드한다. 현재 운영 폴더의 기록은 강제로 다시 쓰지 않는다. /home/syskiller/piano/backup에 보관한 Git 번들과 설치 백업을 사용해 별도 복제본에서 먼저 검증한다. 백엔드 키를 복원할 때는 비밀 백업을 일반 소스와 분리하고 권한 600을 유지한다.

선택 기능과 제한 사항

초기 운영에서는 Audiveris PDF OMR과 Basic Pitch 오디오 변환을 별도로 구성하지 않는다.
MusicXML과 MIDI 및 기본 악보 변환 기능은 설치되어 있다.
실제 USB MIDI 입력과 따라치기 동작은 안드로이드 Chrome과 실제 전자피아노에서 최종 확인해야 한다.
iPhone과 iPad의 Safari는 Web MIDI를 지원하지 않는다.
관리자 곡 업로드와 사용자 곡 목록 선택은 기본 운영 안정화 뒤 진행할 후속 기능이다.

4.5 KiB Raw Blame History