백업, 복원 및 데이터 정리
시스템 설정 → 유지보수에서는 fn-knock 설정을 자동 또는 수동으로 백업하고 가져오거나 현재 인스턴스의 데이터를 모두 지울 수 있습니다. .knock 아카이브는 마이그레이션과 설정 롤백에 적합하지만 전체 시스템, 컨테이너 볼륨 또는 업스트림 서비스 데이터의 백업을 대신하지는 않습니다.
백업에 포함되는 항목
내보내기는 fn-knock 네임스페이스에서 복원 가능한 설정과 자격 증명을 수집합니다. 예를 들면 다음과 같습니다.
- 인증 계정, TOTP, 패스키 및 외부 로그인 설정
- 서브도메인, 경로, 게이트웨이, WAF, 세션 정책 등의 fn-knock 설정
- 인증서와 개인 키, DDNS, 알림 및 터널 연결 설정
- 원격 SSH 대상과 보호된 비밀번호, 개인 키 및 키 암호
- 정적 Host의 응답 유형, 서버 경로, 기본 문서 및 디렉터리 목록 설정
- fn-knock가 영구 저장하며 새 인스턴스에 다시 적용할 수 있는 기타 객체
런타임 로그, 이벤트, 로그인 세션, 활성 터미널 세션, 로컬 터미널 활성화 설정, 임시 접근 권한, 로그인 재시도 제한, 잠금, 트래픽 통계, WAF 통계, 터널 실행 상태, WOL 온라인 상태, DDNS의 마지막 주소 및 기타 단기 또는 호스트 전용 런타임 데이터는 제외됩니다. 다운로드한 FRP / Cloudflared / acme.sh 파일, Cloudflare API Token과 Tunnel Token, WOL Relay PSK, Blinker 장치 키, Bemfa 개인 키, 호스트 방화벽 상태, 외부 DNS 레코드, 정적 매핑의 실제 파일 및 업스트림 서비스 데이터도 포함되지 않습니다. 복원 뒤에는 Cloudflare API를 다시 연결하고 수동 Tunnel Token을 다시 입력하며 WOL Relay를 다시 페어링하거나 외부 플랫폼 자격 증명을 다시 입력합니다. 백업을 가져와도 원격 Cloudflare 리소스가 자동으로 삭제되거나 다시 생성되지 않습니다.
가져오기는 원격 SSH 대상과 자격 증명을 복원하지만 내보낼 때 실행 중이던 Shell을 되살리지는 않습니다. 로컬 터미널 설정은 현재 호스트에서 별도로 판단해야 하는 보안 선택이므로 복원 뒤에도 비활성화된 상태로 유지됩니다. 사용하려면 새 환경에서 실행 계정, Shell 및 초기 디렉터리를 다시 확인하고 위험을 승인한 뒤 수동으로 활성화합니다.
따라서 전체 환경을 마이그레이션할 때는 일반적으로 다음 두 종류의 백업이 모두 필요합니다.
- 유지보수 페이지에서 내보낸
.knock파일: fn-knock 설정 복원용 - 플랫폼 데이터 디렉터리, Docker 볼륨 또는 시스템 스냅샷: SQLite, 다운로드한 리소스 및 플랫폼 런타임 데이터 보존용
보안 경계
.knock는 비밀번호가 설정된 ZIP 호환 형식을 사용합니다. 이 고정 아카이브 비밀번호는 업계에서 흔히 사용하는 저비용 애플리케이션 패키지 방식입니다. 프로그램이 fn-knock 백업 형식을 구분할 수 있게 하고, 실수나 가벼운 패키지 내용 변경의 장벽을 높이며, ZIP 압축으로 파일 크기를 줄입니다. 사용자 로그인 비밀번호를 저장하거나 암호화하는 방식이 아니며 사용자 비밀번호가 아카이브에 평문으로 기록된다는 뜻도 아닙니다. 고정 아카이브 비밀번호를 사용하는 것 자체는 “비밀번호 평문 저장” 보안 사고가 아닙니다.
아카이브 비밀번호는 애플리케이션과 함께 배포되므로 암호화나 기밀성 제공을 목적으로 하지 않습니다. 아카이브에는 인증서 개인 키, TOTP 시드, 계정 자격 증명 해시 및 OIDC / LDAP / DDNS / 알림 / FRP처럼 바로 사용할 수 있는 민감한 설정이 포함될 수 있습니다. 따라서 파일 자체는 민감한 설정 백업으로 취급합니다.
- 암호화된 디스크, 신뢰할 수 있는 비밀번호 보관소 또는 통제된 오프라인 미디어에만 저장합니다.
- 클라우드 드라이브, 이메일 또는 메신저로 전송하기 전에 별도의 강력한 암호화를 적용합니다.
- 공개 이슈, 단체 채팅방, 공개 공유 디렉터리 또는 진단 첨부 파일에 업로드하지 않습니다.
- 오래된 사본을 정기적으로 정리하고 실제 유지보수 담당자만 백업을 읽을 수 있게 제한합니다.
자동 백업
시스템 설정 → 유지보수 → 자동 백업에서는 서버 데이터 디렉터리의 backups/automatic에 .knock를 정기적으로 저장할 수 있습니다. 기본값은 비활성화이며 기본 간격은 24시간, 보존 기간은 7일입니다. 간격은 1～8760시간, 보존 기간은 1～3650일로 설정할 수 있습니다.
처음 활성화하면 즉시 백업 하나를 만들고 이후 설정된 간격으로 실행합니다. 페이지에는 실제 디렉터리, 마지막 성공 시각, 다음 실행 시각 및 최근 오류가 표시됩니다. 실패하면 더 일찍 재시도하며 늦어도 약 1시간 안에 다시 실행합니다. 정리 작업은 자동 백업 디렉터리에서 보존 기간이 지난 .knock 아카이브만 삭제하며 다른 파일을 오래된 백업으로 간주하지 않습니다.
자동 백업과 수동 내보내기는 내용, 호환성 및 보안 경계가 같습니다. 자동 백업은 현재 서버의 데이터 디스크 또는 컨테이너 볼륨에 저장되므로 디스크 장애, 볼륨 손실 또는 호스트 전체 장애를 막지 못합니다. 중요한 사본은 다른 기기나 통제된 원격 저장소에 정기적으로 복사합니다.
복원할 때 자동 백업에서 선택을 사용하면 브라우저 기기에 먼저 다운로드하지 않고 서버 측 자동 백업 디렉터리에서 직접 선택할 수 있습니다. 복원은 현재 자동 백업 일정을 유지하므로 오래된 아카이브가 일정을 뜻하지 않게 덮어쓰지 않습니다. “모든 데이터 지우기” 후에도 기존 자동 백업 파일은 서버 디렉터리에 남지만 일정 설정은 비활성화로 초기화됩니다. 다시 활성화하기 전에 이전 파일의 보존 필요성을 확인합니다.
백업 이메일
시스템 설정 → 유지 관리 → 자동 백업에서 백업 이메일을 열고 전송을 활성화한 뒤 SMTP, 발신자, 수신자를 설정하고 저장합니다. 알림 센터의 이메일 제공자와 독립된 설정입니다. 로컬 실행 주기와 보관 기간은 유지 관리 페이지에서 관리합니다.
전송은 기본적으로 꺼져 있습니다. 연결 기본값은 포트 465, TLS, 제한 시간 30초이며 첨부 제한은 20 MiB(설정 범위 1–100 MiB)입니다. 테스트 이메일 보내기는 현재 양식과 저장된 비밀번호로 작은 테스트 첨부를 보냅니다. 양식을 저장하거나 백업을 생성하지 않습니다. 테스트 후 저장하고 로컬 백업과 이메일 전송 상태를 각각 확인합니다.
- 로컬 백업 성공 후 같은
.knock파일을 백그라운드에서 전송합니다. 전송 실패는 로컬 사본에 영향을 주지 않습니다. - 일시적 오류는
1, 5, 30분 후 재시도하며 최대4회 시도합니다. 인증 실패, 영구 거부, 잘못된 주소, 파일 누락, 첨부 크기 초과는 재시도하지 않습니다. - 제한은 원본 파일 크기 기준이며 이메일 인코딩 후 제공자의 제한을 넘을 수 있습니다. 초과 시 첨부 없는 안내 메일을 시도하지만 첨부 전송은 실패로 기록합니다.
- 대기 작업은 최대
24시간 유지하고 해당 첨부의 만료 정리를 보류합니다. 재시작 후 미완료 작업을 재개합니다. SMTP 수락 후 로컬 성공 기록 전에 중단되면 중복 메일이 발생할 수 있습니다. - 자동 백업이나 이메일을 끄거나 이메일 설정을 변경하면 시작 전인 이전 작업을 취소합니다. 이미 제출한 메일은 회수할 수 없습니다.
이메일 설정, SMTP 자격 증명, 작업은 .knock에 포함되지 않습니다. 복원 시 대상 인스턴스의 이메일 설정과 상태를 유지하며 새 기기에서는 다시 설정해야 합니다. 전체 데이터 삭제 시 이메일 자격 증명도 지워집니다. 첨부는 민감한 설정 아카이브이며 내장 전송은 별도의 강력한 암호화를 추가하지 않습니다. 관리되는 메일함을 사용하고 첨부 접근을 제한합니다.
백업 내보내기
시스템 설정 → 유지보수 → 백업 내보내기로 이동합니다.
- 페이지에서 공유 디렉터리를 지원하면
fn-knock / backup에 저장하거나 현재 브라우저 기기로 다운로드할 수 있습니다. - 그 밖의 배포 방식에서는 현재 기기로 바로 다운로드합니다.
- 파일 이름은
fn-knock-backup-으로 시작하고.knock로 끝나며 내보낸 시각을 포함합니다.
공유 디렉터리 항목은 일반적으로 네이티브 fnOS FPK 또는 지원되는 공유 루트 디렉터리를 명시적으로 마운트한 환경에서만 표시됩니다. Docker와 OpenWrt에는 이 항목이 나타나지 않습니다. 공유 디렉터리가 본질적으로 안전한 것은 아니므로 접근 권한을 반드시 확인합니다.
다음 시점에 백업을 내보내는 것이 좋습니다.
- 인증, 라우팅 및 인증서의 초기 설정을 완료한 뒤
- 실행 모드, 루트 도메인, 인증 방식 또는 WAF를 변경하기 전
- fn-knock 업데이트, 마이그레이션, 재설치 또는 데이터 정리 전
- 자격 증명, 인증서, DDNS 또는 터널 설정을 중요하게 변경한 뒤
내보내기가 끝났다고 해서 백업을 실제로 사용할 수 있다는 뜻은 아닙니다. 최소한 파일이 비어 있지 않고 확장자가 올바른지 확인하고, 격리된 인스턴스나 롤백 가능한 인스턴스에서 정기적으로 가져와 복원할 수 있는지 테스트합니다.
가져오기 전 확인
가져오기는 병합이 아니라 현재 fn-knock 네임스페이스를 교체하는 작업입니다. 시작하기 전에 다음을 확인합니다.
- 현재 인스턴스에서도 롤백용 백업을 하나 더 내보냅니다.
- LAN, 데스크톱 진입점 또는 시스템 콘솔을 통해 관리 화면에 다시 들어갈 수 있는지 확인합니다.
- 아카이브의 출처가 신뢰할 수 있고 신뢰할 수 없는 기기에서 압축을 풀거나 수정하지 않았는지 확인합니다.
- 현재 버전, 실행 모드, 인증 Host, 게이트웨이 포트 및 핵심 서비스 매핑 하나를 기록합니다.
- 플랫폼 간에 마이그레이션한다면 방화벽, 포트 공개, 공유 디렉터리, 정적 콘텐츠 디렉터리 또는 Docker 읽기 전용 마운트, 외부 DNS 상태도 따로 기록합니다.
현재 서버에서 허용하는 아카이브는 다음 조건을 모두 충족합니다.
.knock확장자를 사용합니다.- 크기는
128 MiB를 초과할 수 없습니다. - 현재 지원되는 백업 스키마를 사용하며 현재 스키마는
1입니다. - 아카이브의 fn-knock 버전은 현재 코드에서 정의한 최소 호환 요구 사항을 충족해야 합니다.
- 아카이브의 fn-knock 버전은 실행 중인 버전보다 높을 수 없습니다.
따라서 새 버전에서 내보낸 백업을 이전 버전에 바로 복원할 수 없습니다. 먼저 대상 인스턴스를 같거나 더 높은 버전으로 업그레이드한 뒤 가져옵니다. 정확한 지원 범위는 실패 메시지에 표시되는 버전 구간을 기준으로 판단합니다.
복원 실행
- 유지보수 페이지에서 로컬
.knock파일 또는 서버 측 자동 백업 디렉터리의 파일을 선택합니다. 공유 디렉터리를 지원하는 환경에서는fn-knock / backup에서도 선택할 수 있습니다. - 파일 이름, 크기 및 출처를 확인하고 가져오기를 시작합니다.
- 기존 데이터를 덮어쓴다는 경고를 읽고 확인합니다.
- 가져오기 결과가 나올 때까지 기다립니다. 성공하면 페이지가 다시 로드됩니다.
서버는 먼저 전체 아카이브를 검증하고 현재 복원 대상 데이터의 트랜잭션 스냅샷을 만든 뒤 fn_knock: 애플리케이션 데이터를 교체합니다. 유효 기간이 있는 항목은 내보내기부터 가져오기까지 지난 시간을 차감하며 이미 만료된 항목은 복원하지 않습니다.
Schema, 버전, 항목 형식, 중복 키, 설정 마이그레이션 또는 Cloudflared 자격 증명 정리와 같은 치명적 단계가 실패하면 서버는 가져오기 전 저장소 스냅샷으로 복구를 시도합니다. 오류에는 저장소 또는 런타임 롤백 실패 여부도 표시됩니다. 이 단계를 통과한 뒤 다음 항목을 동기화합니다.
- 현재 실행 모드와 게이트웨이 라우트
- 게이트웨이 신뢰 클라이언트 IP, 요청 로그, WAF 및 SSL 배포
- 자동 HTTPS, Smart Connect, fnOS 포트 아이콘 인계 및 네트워크 튜닝(해당하는 경우)
- 언어 설정
- 오래된 인증 로그 정리 및 시스템 리소스 모니터링 상태
가져오기 결과의 ‘경고’는 설정을 가져온 뒤 치명적이지 않은 런타임 동기화 또는 트랜잭션 마무리 단계가 실패했다는 뜻입니다. 경고만으로 가져온 설정이 자동 롤백되지는 않습니다. 경고 내용을 저장하고 관리 엔드포인트를 계속 사용할 수 있게 유지한 상태에서 다음 절을 확인합니다.
복원 후 점검
관리 화면부터 인터넷 접속 경로까지 다음 순서로 확인합니다.
- 관리 화면에 다시 들어갈 수 있는지, 인증 계정, TOTP, 패스키 및 외부 로그인이 예상대로 구성되었는지 확인합니다.
- 실행 모드, 루트 도메인, 인증 Host, 매핑 수, 핵심 Target 및 정적 서버 경로가 올바른지 확인합니다.
- 게이트웨이, WAF, 인증서 및 요청 로그가 정상인지 확인합니다. 경고가 있다면 해당 동기화 단계를 먼저 점검합니다.
- FRP / Cloudflared 리소스가 설치되어 있고 다시 실행 중인지 확인합니다. Cloudflare 관리 모드는 API Token을 다시 연결하고 수동 모드는 Tunnel Token을 다시 입력합니다.
- DDNS, 알림 제공자 및 외부 로그인 자격 증명의 테스트가 성공하는지 확인합니다.
- 원격 SSH 대상을 확인하고 지문과 연결을 다시 테스트합니다. 로컬 터미널이 필요하면 실행 계정, Shell 및 초기 디렉터리를 다시 확인한 뒤 활성화합니다.
- Wake-on-LAN을 사용한다면 Relay를 다시 페어링하고 Blinker 또는 Bemfa 자격 증명을 입력한 뒤 장치 IP, 브로드캐스트 주소 및 온라인 확인을 검증합니다.
- 모바일 네트워크에서 인증 Host와 보호된 서비스 Host 하나 이상에 접속합니다.
- 요청 로그의 실제 클라이언트 IP, 라우트 및 업스트림 상태가 올바른지 확인합니다.
- 플랫폼 간에 마이그레이션했다면 포트 공개, 호스트 방화벽, Smart Connect, 시스템 서비스 및 정적 콘텐츠 디렉터리를 다시 구성합니다. Docker에서는 읽기 전용 마운트도 다시 만들어야 합니다.
복원된 설정이 이전 환경의 루프백 주소, LAN IP, 파일 경로 또는 도메인을 참조할 수 있습니다. 설정이 존재한다고 해서 이러한 외부 의존성도 새 플랫폼에 존재하는 것은 아닙니다. 정적 매핑을 복원한 뒤에는 각 항목에서 찾아보기를 열어 파일 또는 디렉터리를 다시 찾고 선택한 뒤 매핑을 저장해야 합니다. .knock는 경로와 옵션만 복원하며 디렉터리의 파일은 복사하지 않습니다. 전체 경계는 정적 파일 및 디렉터리 응답을 참고합니다.
자주 발생하는 실패
| 메시지 또는 증상 | 해결 방법 |
|---|---|
| 파일 확장자가 올바르지 않음 | 원본 .knock 파일을 선택합니다. 일반 ZIP 또는 JSON 파일의 확장자만 바꾸면 안 됩니다. |
| 스키마 또는 버전이 지원되지 않음 | 대상 인스턴스를 메시지에 표시된 범위로 업그레이드합니다. 아카이브의 버전 필드를 수동으로 변조하면 안 됩니다. |
| 아카이브가 너무 큼 | 파일이 손상되거나 다른 파일로 바뀌지 않았는지 확인합니다. 아카이브 하나의 최대 크기는 128 MiB입니다. |
| 아카이브 읽기 실패 | 파일 무결성, 아카이브 비밀번호, 내부 fn-knock-backup.json 및 디스크 여유 공간을 확인합니다. fn-knock는 ZIP을 직접 읽으며 시스템 unzip 명령에 의존하지 않습니다. |
| 가져오기 실패와 롤백 메시지 | 일반적으로 가져오기 전 스냅샷에서 기존 설정을 복원한 상태입니다. 저장소 또는 런타임 롤백 실패도 함께 표시되면 반복 가져오기를 중단하고 전체 오류를 보존한 뒤 플랫폼 진입점에서 인스턴스를 확인합니다. |
| 공유 디렉터리를 사용할 수 없음 | 플랫폼이 공유 루트 디렉터리를 제공하는지, 디렉터리가 계속 마운트되어 있고 프로세스에서 읽고 쓸 수 있는지 확인합니다. 로컬 다운로드 및 업로드 방식으로 전환할 수도 있습니다. |
| 가져오기는 성공했지만 경고가 표시됨 | 다시 가져오지 않습니다. 먼저 경고와 관련된 실행 모드, WAF, SSL 또는 게이트웨이 동기화를 확인한 뒤 필요에 따라 관련 설정을 수동으로 저장합니다. |
| 페이지를 새로 고친 뒤 인터넷에서 로그인할 수 없음 | 남겨 둔 LAN 또는 플랫폼 진입점으로 접속하여 인증 Host, DNS, 인증서 및 외부 포트를 확인한 뒤 가져오기 전 백업을 복원할지 결정합니다. |
모든 데이터 지우기
시스템 설정 → 유지보수 → 정리 → 모든 데이터 지우기는 게이트웨이를 초기화하고 서버 저장소의 설정, 계정, 세션, 로그 및 기타 fn-knock 데이터를 삭제한 뒤 현재 브라우저의 로컬 저장소를 지우고 페이지를 다시 불러옵니다.
작업을 실행하려면 페이지에 표시된 확인 문구를 입력합니다. 한국어 UI에서 현재 문구는 모든 데이터 지우기입니다. 이 작업은 되돌릴 수 없으며 내보낸 파일에서 내용을 자동으로 복원해 주지도 않습니다. 백업이 유효한지 검증하고 관리 엔드포인트와 배포 데이터 디렉터리에 문제가 없는지 확인했으며 인스턴스를 새로 초기화하려는 경우에만 실행합니다.