웹 터미널
웹 터미널은 관리 패널에서 제어 가능한 호스트 셸 세션을 제공합니다. 상태 확인, 짧은 명령 실행 및 긴급 문제 해결에 적합합니다. 일상적인 개발 환경이 아니며 SSH 키, 감사 및 최소 권한 관리를 대신해서도 안 됩니다.
이 기능은 복구 가능한 세션을 유지하기 위해 tmux를 사용합니다. 현재 fnOS FPK와 일반 Linux를 지원하며 Docker, OpenWrt, Synology DSM 7 SPK 및 Windows x86_64에는 웹 터미널 진입점이 없습니다.
권한 경계
터미널 명령은 fn-knock 서비스 프로세스의 시스템 권한으로 실행됩니다. 서비스가 root로 실행되면 터미널에도 root 권한이 있을 수 있으며 잘못된 명령으로 시스템, 서비스 데이터 및 네트워크 설정이 바로 변경될 수 있습니다.
- 신뢰할 수 있는 관리자에게만 관리 패널을 공개합니다.
- 관리 패널에 별도의 접근 범위와 강력한 인증을 설정합니다.
- 브라우저 기록, 클립보드 또는 화면 녹화에 남을 수 있는 장기 키를 터미널에 입력하지 않습니다.
- 설정 파일, 패키지 또는 방화벽을 변경하기 전에 백업합니다.
- 웹 터미널을 인터넷 SSH의 대체 진입점으로 사용하지 않습니다.
tmux 환경
시스템 설정 → 터미널에서 tmux 상태와 버전을 확인합니다. 상태는 설치되지 않음, 설치 중, 설치됨 및 오류로 나뉩니다.
- 설치되지 않았으면 페이지에서 설치를 시작할 수 있습니다.
- 설치 중에는 진행 상황이 표시되고 완료되면 상태를 새로 고칩니다.
- 설치에 실패하면 오류를 확인하고 다시 설치할 수 있습니다.
- tmux가 준비되지 않으면 터미널 세션을 만들 수 없습니다.
해당 패키지 관리 기능과 네트워크를 사용할 수 있는 배포 환경에서만 설치할 수 있습니다. 페이지가 계속 설치 중에 머물거나 오류를 표시하면 백엔드 로그, 패키지 저장소 및 디스크 공간을 확인합니다.
터미널 설정
| 설정 | 기본값 및 범위 | 설명 |
|---|---|---|
| 웹 터미널 사용 | 기본값은 꺼짐 | 켜면 측면 탐색에 표시되고 세션을 만들 수 있음 |
| 최대 세션 | 기본값 3, 범위 1~12 | 상한에 도달하면 새 세션을 만들 수 없음 |
| 유휴 정리 시간 | 기본값 86400초, 범위 60~604800초 | 1분에서 7일까지이며 시간이 지난 유휴 세션은 백엔드에서 정리 |
유휴 정리 시간은 서버의 tmux 세션에 적용되며 브라우저 로그인 세션의 유효 시간이 아닙니다. 설정을 저장한 뒤 웹 터미널 페이지로 돌아가 탐색 메뉴와 실행 상태를 확인합니다.
세션 동작
페이지를 처음 열면 시스템이 기존 세션을 읽고 현재 브라우저에서 최근에 사용한 세션을 우선 복구합니다. 세션이 없으면 기본 세션 생성을 시도합니다. 페이지에서 제공하는 기능은 다음과 같습니다.
- 새 세션 생성
- 여러 세션 탭 사이 전환
- 현재 세션 이름 바꾸기
- 연결이 끊긴 세션에 다시 연결
- 텍스트를 터미널에 그대로 전송
- 현재 세션을 종료하고 영구 삭제
- 최대화, 글꼴 크기 조정, 복사, 붙여넣기 및 모두 선택
브라우저는 HTTP 긴 폴링으로 터미널 출력을 받습니다. 네트워크가 잠시 끊긴 뒤 다시 연결할 수 있습니다. 페이지를 새로 고치거나 브라우저를 닫으면 현재 연결만 해제되며 하위 tmux 세션이 즉시 끝나지는 않습니다. 프로세스를 완전히 중지하고 세션을 삭제하려면 셸에서 종료하거나 “세션 종료”를 클릭합니다.
종료한 세션은 복구할 수 없습니다. 세션에서 실행 중인 명령도 해당 tmux 세션과 함께 종료됩니다.
모바일 조작
화면이 좁은 기기에서는 자주 사용하는 제어 키, 보조 키, 방향 및 탐색 키와 글꼴 크기 조절 기능을 갖춘 빠른 도구 모음이 표시됩니다. 브라우저에서 클립보드를 직접 읽을 수 없으면 페이지가 “터미널로 보내기” 대화상자를 열며 사용자가 직접 붙여넣은 뒤 전송할 수 있습니다.
모바일 브라우저는 짧은 문제 해결에 적합합니다. 긴 명령, 대화형 편집, 장기 실행 작업 및 파일 전송에는 로컬 SSH 클라이언트를 사용하는 편이 좋습니다.
문제 해결
진입점이 표시되지 않음
배포 플랫폼에서 터미널 기능을 지원하는지, tmux가 설치되었는지, 기능이 활성화된 상태로 저장되었는지 확인한 뒤 관리 패널 설정을 다시 불러옵니다.
현재 사용할 수 없다는 메시지가 표시됨
실행 상태에 사용할 수 없는 이유가 표시됩니다. 일반적인 원인은 기능이 꺼져 있거나 tmux가 설치 중이거나 누락되었거나 설치 오류가 발생한 경우입니다. 먼저 시스템 설정 → 터미널에서 실행 환경을 복구합니다.
새 세션을 만들 수 없음
현재 세션 수가 상한에 도달했는지와 이전 세션이 계속 실행 중인지 확인합니다. 필요하면 더 이상 사용하지 않는 세션을 종료합니다.
세션을 복구할 수 없음
세션이 유휴 정리 시간을 넘겼거나 다른 관리자가 종료했거나 호스트 재부팅으로 사라졌거나 fn-knock가 tmux에 다시 연결하지 못했을 수 있습니다. 실행 상태를 새로 고친 뒤 새 세션을 만듭니다.
연결되었지만 출력이 없음
“다시 연결”을 사용해 세션에 다시 연결합니다. 그래도 출력이 없으면 브라우저 네트워크 요청과 백엔드 로그를 확인합니다. 리버스 프록시의 긴 폴링 제한 시간이 너무 짧아도 연결이 반복해서 끊길 수 있습니다.