2026-10-26 (월) 개발일지
오늘은 게임 서버 연결 끊김과 Lepons Cockpit 설치·연결 장애라는 두 가지를 파고들었다. 겉보기엔 전혀 다른 문제였지만, 둘 다 앱이나 시스템이 조용히 실패하는 지점을 찾아내는 과정이었다. 하나는 Docker 설정 하나가 10일간 서버를 죽음으로 몰아넣었고, 다른 하나는 앱이 사용자를 올바른 경로로 안내하지 못해 발생한 권한 벽이었다.
게임 서버 10일 다운타임 — Mac 재부팅과 Docker auto-start 의 함정
게임 클라이언트가 서버 연결을 계속 끊는다는 보고가 들어왔다. docker ps를 실행하자 데몬 자체가 응답하지 않았다. 서버는 개발용 Mac이다.
첫 가설은 코드 회귀였다. 하지만 app/ 디렉토리의 마지막 커밋은 9/22. 코드는 1달 넘게 손대지 않았다. 그럼 Docker Desktop이 크래시 났거나 Mac이 절전 모드에 들어간 걸로 의심했다.
ps aux | grep docker로 프로세스를 확인했다. com.docker.vmnetd(권한 헬퍼)는 살아 있지만 핵심 엔진 프로세스가 보이지 않았다. Docker 로그를 뒤졌다. 마지막 로그 기록이 10/16 02:28. Mac 시스템 로그(log show --last boot)를 확인하니 10/16 02:09에 재부팅 로그가 찍혀 있었다. 재부팅 이후 Docker가 살아난 흔적이 전혀 없었다.
결정적 증거는 Docker Desktop 설정에서 찾았다.
auto start: false옵션이 체크되어 있었다. 재부팅 후 Docker가 자동으로 시작되지 않았고, 그 상태로 10일이 지난 거다.
Docker Desktop을 수동으로 실행하고 docker compose up -d로 스택을 복구했다. api 컨테이너는 8000번 포트에 정상 바인딩, app-db는 healthy. Alembic 헤드도 0009_blank_submission_mode로 밀린 마이그레이션이 없었다. /health/live와 /health/ready 모두 {"status":"ok"}와 {"status":"ready"}를 반환했다.
검증: 클라이언트 재연결 후 끊김 보고 중단. auto start를 true로 변경하고 마무리. 재부팅 원인은 아직 모르지만, 문제의 본질은 ‘OS 업데이트’가 아니라 ‘Docker가 다시 안 켜지게 설정된 상태’였다는 점이 교훈이다.
Lepons Cockpit — 설치·연결 첫 단계에서 막히는 권한 이슈 14건
비개발자 사용자로부터 Windows SmartScreen 차단, macOS 격리 경고, 호스트 키 변경 시 진행 불가 등 설치와 연결 첫 단계에서 막혔다는 피드백이 여러 건 들어왔다.
처음엔 각 케이스를 개별 버그로 접근했다. SmartScreen은 서명 문제니까 어쩔 수 없고, macOS 격리는 개발자만 겪는 문제라고 생각했다. 하지만 사용자 패턴을 분석하니 공통점이 보였다. 앱이 사용자에게 막다른 길을 안내하고 있었다. 예를 들어 호스트 키가 바뀌었을 때 ‘의도적으로 거부한 게 아니라면 연결하지 마세요’라는 메시지만 띄우고, 사용자가 직접 키를 갱신할 방법을 전혀 안내하지 않았다.
macOS 케이스를 공식 문서로 확인했다. app.isInApplicationsFolder()가 false인 상태로 실행되면 업데이트 실패와 이상 동작이 발생한다. 지금 앱은 이 상태를 무시하고 넘어가고 있었다. Windows SmartScreen은 앱이 회피할 수 없지만, ‘추가 정보 → 실행’ 경로를 앱 안에서 안내하면 사용자가 막히지 않는다.
14개의 권한·환경 이슈를
2026-10-26-permissions-audit.md에 표로 정리했다. 이 중 12개는 앱이 직접 처리할 수 있었고, 2개는 시스템 설정 자체라 가이드로만 제공하기로 했다.
바뀐 점
- macOS:
isInApplicationsFolder()가 false면 사용자에게 묻고 자동으로 Applications 폴더로 이동(moveToApplicationsFolder()) - Windows: SmartScreen 경고 화면에서 ‘추가 정보 → 실행’ 경로를 안내하는 인라인 도움말 추가
- 호스트 키 변경: 키 변경 시 사용자가 직접 수락/갱신할 수 있는 UI 흐름 추가
- 원격 에이전트 미설치: 감지 시 사용자에게 설치 팝업을 띄우는 로직으로 변경
검증: 수정 12건을 integrate-perm-fixes 브랜치에 합쳐 1.7.2 테스트 빌드를 만들었다. npm test는 465개 중 464개 통과, 실패 0. 남은 2건(방화벽 포트 허용, Tailscale 인증서)은 가이드 문서로 정리했다.
오늘의 한줄
조용히 실패하는 시스템은 코드 오류보다 설정 하나나 안내 부재에서 더 자주 발생한다.