백업, 복원 및 데이터 정리

시스템 설정 → 유지보수에서는 fn-knock 설정을 자동 또는 수동으로 백업하고 가져오거나 현재 인스턴스의 데이터를 모두 지울 수 있습니다. .knock 아카이브는 마이그레이션과 설정 롤백에 적합하지만 전체 시스템, 컨테이너 볼륨 또는 업스트림 서비스 데이터의 백업을 대신하지는 않습니다.

백업에 포함되는 항목

내보내기는 fn-knock 네임스페이스에서 복원 가능한 설정과 자격 증명을 수집합니다. 예를 들면 다음과 같습니다.

• 인증 계정, TOTP, 패스키 및 외부 로그인 설정
• 서브도메인, 경로, 게이트웨이, WAF, 세션 정책 등의 fn-knock 설정
• 인증서와 개인 키, DDNS, 알림 및 터널 연결 설정
• fn-knock가 영구 저장하며 새 인스턴스에 다시 적용할 수 있는 기타 객체

런타임 로그, 이벤트, 세션, 임시 접근 권한, 로그인 재시도 제한, 잠금, 트래픽 통계, WAF 통계, 터널 실행 상태, DDNS의 마지막 주소 및 기타 단기 런타임 데이터는 제외됩니다. 다운로드한 FRP / Cloudflared / acme.sh 파일, 호스트 방화벽 상태, 외부 DNS 레코드 및 업스트림 서비스 데이터도 fn-knock 설정 백업에 포함되지 않습니다.

따라서 전체 환경을 마이그레이션할 때는 일반적으로 다음 두 종류의 백업이 모두 필요합니다.

1. 유지보수 페이지에서 내보낸 .knock 파일: fn-knock 설정 복원용
2. 플랫폼 데이터 디렉터리, Docker 볼륨 또는 시스템 스냅샷: SQLite, 다운로드한 리소스 및 플랫폼 런타임 데이터 보존용

보안 경계

.knock는 비밀번호가 설정된 ZIP 호환 형식을 사용합니다. 이 고정 아카이브 비밀번호는 업계에서 흔히 사용하는 저비용 애플리케이션 패키지 방식입니다. 프로그램이 fn-knock 백업 형식을 구분할 수 있게 하고, 실수나 가벼운 패키지 내용 변경의 장벽을 높이며, ZIP 압축으로 파일 크기를 줄입니다. 사용자 로그인 비밀번호를 저장하거나 암호화하는 방식이 아니며 사용자 비밀번호가 아카이브에 평문으로 기록된다는 뜻도 아닙니다. 고정 아카이브 비밀번호를 사용하는 것 자체는 “비밀번호 평문 저장” 보안 사고가 아닙니다.

아카이브 비밀번호는 애플리케이션과 함께 배포되므로 암호화나 기밀성 제공을 목적으로 하지 않습니다. 아카이브에는 인증서 개인 키, TOTP 시드, 계정 자격 증명 해시 및 OIDC / DDNS / 알림 / FRP처럼 바로 사용할 수 있는 민감한 설정이 포함될 수 있습니다. 따라서 파일 자체는 민감한 설정 백업으로 취급합니다.

• 암호화된 디스크, 신뢰할 수 있는 비밀번호 보관소 또는 통제된 오프라인 미디어에만 저장합니다.
• 클라우드 드라이브, 이메일 또는 메신저로 전송하기 전에 별도의 강력한 암호화를 적용합니다.
• 공개 이슈, 단체 채팅방, 공개 공유 디렉터리 또는 진단 첨부 파일에 업로드하지 않습니다.
• 오래된 사본을 정기적으로 정리하고 실제 유지보수 담당자만 백업을 읽을 수 있게 제한합니다.

자동 백업

시스템 설정 → 유지보수 → 자동 백업에서는 서버 데이터 디렉터리의 backups/automatic에 .knock를 정기적으로 저장할 수 있습니다. 기본값은 비활성화이며 기본 간격은 24시간, 보존 기간은 7일입니다. 간격은 1～8760시간, 보존 기간은 1～3650일로 설정할 수 있습니다.

처음 활성화하면 즉시 백업 하나를 만들고 이후 설정된 간격으로 실행합니다. 페이지에는 실제 디렉터리, 마지막 성공 시각, 다음 실행 시각 및 최근 오류가 표시됩니다. 실패하면 더 일찍 재시도하며 늦어도 약 1시간 안에 다시 실행합니다. 정리 작업은 자동 백업 디렉터리에서 보존 기간이 지난 .knock 아카이브만 삭제하며 다른 파일을 오래된 백업으로 간주하지 않습니다.

자동 백업과 수동 내보내기는 내용, 호환성 및 보안 경계가 같습니다. 자동 백업은 현재 서버의 데이터 디스크 또는 컨테이너 볼륨에 저장되므로 디스크 장애, 볼륨 손실 또는 호스트 전체 장애를 막지 못합니다. 중요한 사본은 다른 기기나 통제된 원격 저장소에 정기적으로 복사합니다.

복원할 때 자동 백업에서 선택을 사용하면 브라우저 기기에 먼저 다운로드하지 않고 서버 측 자동 백업 디렉터리에서 직접 선택할 수 있습니다. 복원은 현재 자동 백업 일정을 유지하므로 오래된 아카이브가 일정을 뜻하지 않게 덮어쓰지 않습니다. “모든 데이터 지우기” 후에도 기존 자동 백업 파일은 서버 디렉터리에 남지만 일정 설정은 비활성화로 초기화됩니다. 다시 활성화하기 전에 이전 파일의 보존 필요성을 확인합니다.

백업 내보내기

시스템 설정 → 유지보수 → 백업 내보내기로 이동합니다.

• 페이지에서 공유 디렉터리를 지원하면 fn-knock / backup에 저장하거나 현재 브라우저 기기로 다운로드할 수 있습니다.
• 그 밖의 배포 방식에서는 현재 기기로 바로 다운로드합니다.
• 파일 이름은 fn-knock-backup-으로 시작하고 .knock로 끝나며 내보낸 시각을 포함합니다.

공유 디렉터리 항목은 일반적으로 네이티브 fnOS FPK 또는 지원되는 공유 루트 디렉터리를 명시적으로 마운트한 환경에서만 표시됩니다. Docker와 OpenWrt에는 이 항목이 나타나지 않습니다. 공유 디렉터리가 본질적으로 안전한 것은 아니므로 접근 권한을 반드시 확인합니다.

다음 시점에 백업을 내보내는 것이 좋습니다.

• 인증, 라우팅 및 인증서의 초기 설정을 완료한 뒤
• 실행 모드, 루트 도메인, 인증 방식 또는 WAF를 변경하기 전
• fn-knock 업데이트, 마이그레이션, 재설치 또는 데이터 정리 전
• 자격 증명, 인증서, DDNS 또는 터널 설정을 중요하게 변경한 뒤

내보내기가 끝났다고 해서 백업을 실제로 사용할 수 있다는 뜻은 아닙니다. 최소한 파일이 비어 있지 않고 확장자가 올바른지 확인하고, 격리된 인스턴스나 롤백 가능한 인스턴스에서 정기적으로 가져와 복원할 수 있는지 테스트합니다.

가져오기 전 확인

가져오기는 병합이 아니라 현재 fn-knock 네임스페이스를 교체하는 작업입니다. 시작하기 전에 다음을 확인합니다.

1. 현재 인스턴스에서도 롤백용 백업을 하나 더 내보냅니다.
2. LAN, 데스크톱 진입점 또는 시스템 콘솔을 통해 관리 화면에 다시 들어갈 수 있는지 확인합니다.
3. 아카이브의 출처가 신뢰할 수 있고 신뢰할 수 없는 기기에서 압축을 풀거나 수정하지 않았는지 확인합니다.
4. 현재 버전, 실행 모드, 인증 Host, 게이트웨이 포트 및 핵심 서비스 매핑 하나를 기록합니다.
5. 플랫폼 간에 마이그레이션한다면 방화벽, 포트 공개, 공유 디렉터리 및 외부 DNS 상태도 따로 기록합니다.

현재 서버에서 허용하는 아카이브는 다음 조건을 모두 충족합니다.

• .knock 확장자를 사용합니다.
• 크기는 128 MiB를 초과할 수 없습니다.
• 현재 지원되는 백업 스키마를 사용하며 현재 스키마는 1입니다.
• 아카이브의 fn-knock 버전은 현재 코드에서 정의한 최소 호환 버전(현재 1.4.0) 이상만 허용합니다.
• 아카이브의 fn-knock 버전은 실행 중인 버전보다 높을 수 없습니다.

따라서 새 버전에서 내보낸 백업을 이전 버전에 바로 복원할 수 없습니다. 먼저 대상 인스턴스를 같거나 더 높은 버전으로 업그레이드한 뒤 가져옵니다. 정확한 지원 범위는 실패 메시지에 표시되는 버전 구간을 기준으로 판단합니다.

복원 실행

1. 유지보수 페이지에서 로컬 .knock 파일 또는 서버 측 자동 백업 디렉터리의 파일을 선택합니다. 공유 디렉터리를 지원하는 환경에서는 fn-knock / backup에서도 선택할 수 있습니다.
2. 파일 이름, 크기 및 출처를 확인하고 가져오기를 시작합니다.
3. 기존 데이터를 덮어쓴다는 경고를 읽고 확인합니다.
4. 가져오기 결과가 나올 때까지 기다립니다. 성공하면 페이지가 다시 로드됩니다.

서버는 기존 fn_knock: 데이터를 지우고 아카이브에서 복원이 허용된 항목을 기록한 뒤 다음 항목을 차례로 동기화합니다.

• 현재 실행 모드와 게이트웨이 라우트
• 직접 연결 모드의 허용 목록(해당하는 경우)
• 게이트웨이 로그, WAF 및 SSL 배포
• 오래된 인증 로그 정리 및 시스템 리소스 모니터링 상태

가져오기 결과에 ‘경고’가 표시되면 설정 항목은 이미 가져왔지만 하나 이상의 런타임 동기화 단계가 실패했다는 뜻입니다. 인스턴스 전체가 가져오기 전 상태로 자동 롤백되지는 않습니다. 경고 내용을 저장하고 관리 엔드포인트를 계속 사용할 수 있게 유지한 상태에서 다음 절에 따라 항목별로 처리합니다.

복원 후 점검

관리 화면부터 인터넷 접속 경로까지 다음 순서로 확인합니다.

1. 관리 화면에 다시 들어갈 수 있는지, 인증 계정, TOTP, 패스키 및 외부 로그인이 예상대로 구성되었는지 확인합니다.
2. 실행 모드, 루트 도메인, 인증 Host, 매핑 수 및 핵심 대상(타깃)이 올바른지 확인합니다.
3. 게이트웨이, WAF, 인증서 및 요청 로그가 정상인지 확인합니다. 경고가 있다면 해당 동기화 단계를 먼저 점검합니다.
4. FRP / Cloudflared 리소스가 설치되어 있고 다시 실행 중인지 확인합니다.
5. DDNS, 알림 제공자 및 외부 로그인 자격 증명의 테스트가 성공하는지 확인합니다.
6. 모바일 네트워크에서 인증 Host와 보호된 서비스 Host 하나 이상에 접속합니다.
7. 요청 로그의 실제 클라이언트 IP, 라우트 및 업스트림 상태가 올바른지 확인합니다.
8. 플랫폼 간에 마이그레이션했다면 포트 공개, 호스트 방화벽, Smart Connect 및 시스템 서비스를 다시 구성합니다.

복원된 설정이 이전 환경의 루프백 주소, LAN IP, 파일 경로 또는 도메인을 참조할 수 있습니다. 설정이 존재한다고 해서 이러한 외부 의존성도 새 플랫폼에 존재하는 것은 아닙니다.

자주 발생하는 실패

메시지 또는 증상	해결 방법
파일 확장자가 올바르지 않음	원본 .knock 파일을 선택합니다. 일반 ZIP 또는 JSON 파일의 확장자만 바꾸면 안 됩니다.
스키마 또는 버전이 지원되지 않음	대상 인스턴스를 메시지에 표시된 범위로 업그레이드합니다. 아카이브의 버전 필드를 수동으로 변조하면 안 됩니다.
아카이브가 너무 큼	파일이 손상되거나 다른 파일로 바뀌지 않았는지 확인합니다. 아카이브 하나의 최대 크기는 128 MiB입니다.
아카이브 읽기 실패	파일 무결성, 디스크 여유 공간 및 unzip 사용 가능 여부를 확인합니다. 일부 Linux / OpenWrt 환경에서는 시스템 패키지 관리자로 unzip 설치를 시도합니다.
공유 디렉터리를 사용할 수 없음	플랫폼이 공유 루트 디렉터리를 제공하는지, 디렉터리가 계속 마운트되어 있고 프로세스에서 읽고 쓸 수 있는지 확인합니다. 로컬 다운로드 및 업로드 방식으로 전환할 수도 있습니다.
가져오기는 성공했지만 경고가 표시됨	다시 가져오지 않습니다. 먼저 경고와 관련된 실행 모드, WAF, SSL 또는 게이트웨이 동기화를 확인한 뒤 필요에 따라 관련 설정을 수동으로 저장합니다.
페이지를 새로 고친 뒤 인터넷에서 로그인할 수 없음	남겨 둔 LAN 또는 플랫폼 진입점으로 접속하여 인증 Host, DNS, 인증서 및 외부 포트를 확인한 뒤 가져오기 전 백업을 복원할지 결정합니다.

모든 데이터 지우기

시스템 설정 → 유지보수 → 정리 → 모든 데이터 지우기는 게이트웨이를 초기화하고 서버 저장소의 설정, 계정, 세션, 로그 및 기타 fn-knock 데이터를 삭제한 뒤 현재 브라우저의 로컬 저장소를 지우고 페이지를 다시 불러옵니다.

작업을 실행하려면 페이지에 표시된 확인 문구를 입력합니다. 한국어 UI에서 현재 문구는 모든 데이터 지우기입니다. 이 작업은 되돌릴 수 없으며 내보낸 파일에서 내용을 자동으로 복원해 주지도 않습니다. 백업이 유효한지 검증하고 관리 엔드포인트와 배포 데이터 디렉터리에 문제가 없는지 확인했으며 인스턴스를 새로 초기화하려는 경우에만 실행합니다.

• 시스템 설정 및 유지보수
• 대시보드 및 시스템 업데이트
• 보안 경계 및 기준
• 배포 방식 선택