데이터베이스 암호화
Libre WebUI에는 민감한 값을 스토리지에 쓰기 전에 보호하는 애플리케이션 수준 암호화 서비스가 포함되어 있습니다.
암호화 방식
백엔드는 Node.js crypto를 통해 AES-256-GCM을 사용합니다. 암호화 키는 32바이트이며 64자의 16진수 문자열로 표현해야 합니다.
ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
키 생성:
openssl rand -hex 32
키 저장
Libre WebUI는 다음 순서로 키를 불러옵니다.
- 환경의
ENCRYPTION_KEY. - 선택한
DATA_DIR아래에 저장된.encryption_key파일. - 새 스토리지에서만 새 키를 생성해 데이터베이스 시작 전에
DATA_DIR/.encryption_key에 영구 기록.
환경과 영구 파일에 모두 키가 있으면 서로 일치해야 하며, 그렇지 않으면 시작이 실패합니다. 기존 암호화 상태에 원래 키가 없어도 안전하게 실패합니다. Libre는 기존 스토리지용 대체 키를 생성하지 않습니다.
중요한 키 규칙
- 데이터베이스와 함께
ENCRYPTION_KEY를 백업하세요. - 암호화된 값을 위한 마이그레이션 계획이 없다면 키를 교체하지 마세요.
- 키를 잃으면 암호화된 값을 복구할 수 없습니다.
- 데이터를 다시 암호화하지 않고 키를 바꾸면 기존 암호화 값을 읽을 수 없습니다.
보호 대상
암호화 서비스 또는 암호화 스토리지 도우미를 사용하는 코드 경로에 암호화가 적용됩니다. 해당 도우미가 처리하는 자격 증명, 비공개 사용자 데이터 같은 민감한 애플리케이션 값을 보호하기 위한 기능입니다.
전체 디스크 암호화, SQLite 페이지 암호화, 사용자와 브라우저 사이의 종단 간 암호화는 아닙니다. 해당 계층에는 디스크 암호화와 HTTPS를 사용하세요.
Work 데이터
애플리케이션 수준 암호화는 Work 작업 전체를 암호화하지 않습니다. Work 소스 파일과 프로젝트 종속성은 작업 범위 Docker 이름 있는 볼륨의 일반 파일입니다. Work 대화, 도구 결과, 명령 출력, 작업 메타데이터는 SQLite에 저장되며, 일부 자격 증명 저장 경로가 암호화 서비스를 사용한다고 해서 자동으로 암호화되지는 않습니다.
필요하면 Docker 데이터 루트와 DATA_DIR를 접근 제어 및 디스크 암호화로 보호하세요. 데이터베이스, ENCRYPTION_KEY, 관리 대상 Work 볼륨을 함께 백업하세요. Work 작업을 원격 모델에 보내면 대화 문맥과 요청된 파일 또는 명령 출력이 해당 제공자에게 공개될 수도 있습니다. 스토리지 암호화는 이 네트워크 경계를 바꾸지 않습니다.
Docker 및 Kubernetes
프로덕션에서는 안정된 키를 명시적으로 설정합니다.
ENCRYPTION_KEY=replace-with-64-hex-characters
DATA_DIR=/data
DATA_DIR를 영구 스토리지에 마운트하세요. Kubernetes에서는 키를 Secret에 저장하고 데이터를 PersistentVolume에 마운트합니다.
문제 해결
잘못된 키 길이
키는 정확히 64자의 16진수여야 합니다. 다음 명령으로 새로 생성합니다.
openssl rand -hex 32
재배포 후 데이터를 복호화할 수 없음
동일한 ENCRYPTION_KEY를 사용하며 동일한 DATA_DIR 볼륨이 마운트되었는지 확인하세요.
개발 환경에서 새 키가 생성됨
데이터베이스와 함께 DATA_DIR/.encryption_key를 보관하세요. 대신 동일한 값을 ENCRYPTION_KEY로 설정할 수도 있습니다. 두 소스가 모두 있으면 서로 일치해야 합니다.