Copy & Run

Vaultwarden으로 비밀번호 관리 서버 띄우기: 도커 실행, 상태 확인, 데이터 백업

Bitwarden과 호환되는 오픈소스 서버 Vaultwarden을 도커로 localhost에만 열어 띄우고, 상태 확인 주소와 데이터 파일을 살펴봅니다. 컨테이너를 멈추고 데이터베이스를 복사해 백업한 뒤 다시 시작해도 서버가 살아나는지 확인합니다.

실습 노트 · 2026-10-28 발행 · 12분 · 2026-10 확인
실습 코드 내려받기: 전체 받기(zip)GitHubvw_test.py

비밀번호를 브라우저나 메모장에 흩어 두면 유출과 분실 위험이 큽니다. Vaultwarden은 Bitwarden 클라이언트와 호환되는 가벼운 오픈소스 서버입니다. 이 글에서는 Vaultwarden을 도커로 띄워 서버가 정상인지 확인하고, 가장 중요한 데이터 백업까지 해 봅니다. 비밀번호 보관에 쓰는 서버이므로 실습용으로만 띄웠습니다. 처음 판에서는 계정을 만들지 않았는데, 그래서 백업이 정말 쓸 만한지 확인하지 못했습니다. 이번에 계정을 하나 만들어 백업과 복원까지 해 보니 처음 판의 백업 방법에 문제가 있었습니다(아래 4절).

준비물

항목 확인한 값
Docker 29.5.3 (Windows 11)
이미지 vaultwarden/server:latest (이미지 라벨 버전 1.37.4)

1. 실행

docker run -d --name osk-vw -p 127.0.0.1:3902:80 -v osk_vw:/data -e SIGNUPS_ALLOWED=false vaultwarden/server:1.37.4
  • 127.0.0.1:3902:80: 이 PC 안에서만 접속됩니다.
  • -v osk_vw:/data: 모든 데이터가 이 볼륨에 저장됩니다.
  • SIGNUPS_ALLOWED=false: 자유 가입을 끄는 설정입니다. 실제로 가입이 막히는지는 아래 5절에서 확인했습니다.

로그에 Rocket has launched from http://0.0.0.0:80이 찍혔습니다.

2. 상태 확인

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3902/alive
# 기대 출력
200

/api/config는 서버 정보를 JSON으로 돌려주며, 이 서버는 Vaultwarden이라는 이름과 API 버전 2026.6.0을 알려 주었습니다. 모니터링 도구에서 /alive를 감시 대상으로 쓸 수 있습니다(앞 글의 Uptime Kuma가 이 주소를 감시했습니다).

브라우저로 http://127.0.0.1:3902/를 열면 웹 보관함 로그인 화면이 나옵니다.

Vaultwarden 웹 보관함의 로그인 화면에 이메일 입력칸, 계속 버튼, 계정 만들기 링크가 보이고 아래쪽에 Vaultwarden Web 2026.7.0 버전이 적힌 것을 확인합니다.
Vaultwarden 웹 보관함의 로그인 화면에 이메일 입력칸, 계속 버튼, 계정 만들기 링크가 보이고 아래쪽에 Vaultwarden Web 2026.7.0 버전이 적힌 것을 확인합니다.

SIGNUPS_ALLOWED=false로 띄웠는데도 화면에는 계정 만들기 링크가 그대로 보였습니다. 화면에 링크가 보이는 것과 가입이 되는 것은 다릅니다. 실제 가입 요청이 막히는지는 5절에서 요청을 직접 보내 확인했습니다.

3. 데이터는 어디에 있나

docker exec osk-vw ls /data
# 기대 출력
db.sqlite3  db.sqlite3-shm  db.sqlite3-wal  rsa_key.pem  tmp

db.sqlite3(278,528바이트)가 계정과 보관함 데이터베이스이고 rsa_key.pem은 서버의 서명 키입니다. 백업 때는 이 둘이 모두 필요하다고 보는 것이 안전하지만, 키 없이 복원이 되는지는 시험하지 않았습니다.

/alive 호출이 200을 돌려주고 docker exec로 본 /data 폴더에 db.sqlite3, db.sqlite3-shm, db.sqlite3-wal, rsa_key.pem, tmp가 있는 것을 확인합니다.
/alive 호출이 200을 돌려주고 docker exec로 본 /data 폴더에 db.sqlite3, db.sqlite3-shm, db.sqlite3-wal, rsa_key.pem, tmp가 있는 것을 확인합니다.

4. 백업과 재시작(처음 판의 방법)

SQLite 파일은 쓰는 도중에 복사하면 깨질 수 있어서, 컨테이너를 먼저 멈춘 뒤 볼륨에서 파일을 복사했습니다.

docker stop osk-vw
docker run --rm -v osk_vw:/data -v "$PWD:/bk" alpine cp /data/db.sqlite3 /bk/vw-backup.sqlite3
docker start osk-vw
# 기대 출력(이 PC)
-rw-r--r--  278528  vw-backup.sqlite3
after restart alive 200

복사본은 원본과 같은 278,528바이트였고, 파이썬 sqlite3로 열어 보니 테이블 등 63개 객체가 있었으며 users 행은 0이었습니다(계정을 만들지 않았기 때문입니다). 6초 뒤 /alive가 다시 200을 돌려주었습니다.

이 방법은 계정이 있으면 부족합니다. 아래 5절에서 계정을 만든 뒤 확인했더니, db.sqlite3 한 개만 복사한 백업으로는 복원 뒤 로그인이 되지 않았습니다.

5. 계정을 만들고 백업을 복원해 보기

Vaultwarden은 SQLite의 WAL 방식을 써서, 최근 변경이 db.sqlite3가 아니라 db.sqlite3-wal 파일에 먼저 쌓입니다. 계정을 만든 뒤 /data를 보면 db.sqlite3는 278,528바이트 그대로이고 db.sqlite3-wal이 24,752바이트가 되어 있었습니다. 계정 정보가 아직 WAL에 있다는 뜻입니다. 이 상태에서 db.sqlite3만 복사하면 계정이 빠집니다.

실험은 네 단계입니다. 모두 같은 PC에서 했고, 계정은 실습용으로 하나만 만들었습니다.

  1. SIGNUPS_ALLOWED=false로 띄우고 가입을 시도합니다.
  2. SIGNUPS_ALLOWED=true로 다시 띄워 계정 하나를 만들고 로그인합니다.
  3. 컨테이너를 멈추고 세 가지로 백업합니다: 볼륨 전체, 키 파일(rsa_key.pem)만 뺀 것(db.sqlite3와 -shm, -wal), db.sqlite3 한 개.
  4. 원본 컨테이너와 볼륨을 지우고 백업마다 복원해, 같은 계정으로 로그인합니다.
단계 결과
SIGNUPS_ALLOWED=false 가입 시도 400 Registration not allowed or user already exists. 설정이 가입을 막았습니다
SIGNUPS_ALLOWED=true 가입과 로그인 가입 200, 로그인 200과 access_token
볼륨 전체 백업을 복원 로그인 200
키 파일만 뺀 백업을 복원 로그인 200. 백업에 없던 rsa_key.pem을 서버가 새로 만들었습니다
db.sqlite3 한 개만 복원 로그인 400, 계정이 없음
  • 가장 중요한 결과: 데이터베이스 파일 세 개(db.sqlite3, -shm, -wal)를 함께 복사해야 합니다. 한 개만 복사하면 계정이 없는 빈 서버가 됩니다.
  • 키 파일 없이도 로그인은 됐습니다. 이 파일은 서버가 로그인 토큰에 서명하는 키입니다. 없으면 서버가 새로 만들고, 이미 로그인해 둔 기기의 토큰은 무효가 되어 다시 로그인해야 할 것으로 추정합니다. 이 부분(기존 기기의 토큰)은 확인하지 않았습니다. 그래도 키 파일까지 같이 백업하는 것이 안전합니다.
  • 가입을 막는 설정이 실제로 동작합니다. 화면에는 계정 만들기가 보였지만 요청은 400으로 거부되었습니다.
  • 새 가입 방식은 3단계(이메일 확인 토큰 요청, 키 만들기, 가입 완료)입니다. 이 서버에서 예전 주소(/identity/accounts/register)는 404였는데, 처음 판에서 "가입 주소 404"를 증거로 쓰지 않은 것은 맞는 판단이었습니다.

vw_test.py 실행 결과에서 SIGNUPS_ALLOWED=false는 가입이 400으로 거부되고, true는 가입과 로그인이 200이며, 전체 백업과 키 파일을 뺀 백업은 복원 뒤 로그인이 200이고, db.sqlite3 한 개만 복원하면 400인 것을 확인합니다.
vw_test.py 실행 결과에서 SIGNUPS_ALLOWED=false는 가입이 400으로 거부되고, true는 가입과 로그인이 200이며, 전체 백업과 키 파일을 뺀 백업은 복원 뒤 로그인이 200이고, db.sqlite3 한 개만 복원하면 400인 것을 확인합니다.

이 단계의 파일 내려받기:vw_test.py

전체 코드

위 실험을 한 번에 하는 파일입니다. 이 파일은 비밀번호 관리자 서버가 쓰는 Bitwarden 방식 암호화(마스터 키, 비밀번호 해시, 사용자 키 암호화)를 직접 구현해 계정을 만듭니다. vw_test.py로 저장하고 pip install requests cryptography를 한 뒤 python -X utf8 vw_test.py로 실행합니다. 이 PC에서는 약 1분 걸렸습니다. 컨테이너 osk-vw와 볼륨 osk_vw, osk_vw_bk를 만들고 끝에서 지웁니다. 비밀번호(Lab-Only-Pass-1)와 이메일은 실습용 값입니다. 이 코드는 실험용이며 실제 계정 생성에 쓰지 않습니다.

"""Vaultwarden 을 도커로 띄워 가입 차단, 계정 만들기와 로그인, 정지 후 백업, 복원 뒤 로그인, 키 파일 없이 복원까지 확인한다.

준비: Docker, pip install requests cryptography
주의: osk-vw 컨테이너와 osk_vw, osk_vw_bk 볼륨을 만들고 끝에서 지운다. 같은 이름이 있으면 먼저 지운다.
      127.0.0.1:3902 에만 열고, 만드는 계정은 실습용(lab@example.com)이다. 실제 비밀번호를 넣지 않는다.
실행: python -X utf8 vw_test.py   (약 1분)
"""
import base64
import hashlib
import hmac
import os
import subprocess
import time
import uuid

import requests
from cryptography.hazmat.primitives import padding, serialization
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

PORT = 3902
URL = f"http://127.0.0.1:{PORT}"
NAME, VOL, BK = "osk-vw", "osk_vw", "osk_vw_bk"
IMAGE = "vaultwarden/server:1.37.4"
EMAIL, PW, ITER = "lab@example.com", "Lab-Only-Pass-1", 100000


def sh(*a, check=True):
    r = subprocess.run(a, capture_output=True, text=True)
    if check and r.returncode:
        raise RuntimeError(f"{a}: {r.stderr.strip()}")
    return r.stdout.strip()


def cleanup():
    sh("docker", "rm", "-f", NAME, check=False)
    sh("docker", "volume", "rm", VOL, BK, check=False)


def start(signups):
    sh("docker", "rm", "-f", NAME, check=False)
    sh("docker", "run", "-d", "--name", NAME, "-p", f"127.0.0.1:{PORT}:80", "-v", f"{VOL}:/data",
       "-e", f"SIGNUPS_ALLOWED={signups}", IMAGE)
    for _ in range(60):
        try:
            if requests.get(URL + "/alive", timeout=2).status_code == 200:
                return
        except requests.RequestException:
            pass
        time.sleep(1)
    raise RuntimeError("Vaultwarden 이 시작되지 않았다")


def b64(b):
    return base64.b64encode(b).decode()


def hkdf_expand(key, info):
    return hmac.new(key, info + b"\x01", hashlib.sha256).digest()


def enc_string(enc_key, mac_key, data):
    """Bitwarden 의 '2.iv|암호문|mac' 형식(AES-256-CBC + HMAC-SHA256)으로 암호화한다."""
    iv = os.urandom(16)
    padder = padding.PKCS7(128).padder()
    c = Cipher(algorithms.AES(enc_key), modes.CBC(iv)).encryptor()
    ct = c.update(padder.update(data) + padder.finalize()) + c.finalize()
    return f"2.{b64(iv)}|{b64(ct)}|{b64(hmac.new(mac_key, iv + ct, hashlib.sha256).digest())}"


def pw_hash():
    master = hashlib.pbkdf2_hmac("sha256", PW.encode(), EMAIL.encode(), ITER, 32)
    return master, b64(hashlib.pbkdf2_hmac("sha256", master, PW.encode(), 1, 32))


def register():
    """가입 3단계: 이메일 확인 토큰 받기(메일을 쓰지 않으면 응답에 토큰이 들어 있다) -> 키 만들기 -> 가입 완료."""
    r = requests.post(URL + "/identity/accounts/register/send-verification-email",
                      json={"email": EMAIL, "name": "lab", "receiveMarketingEmails": False}, timeout=20)
    if r.status_code != 200:
        return r
    token = r.text.strip('"')
    master, h = pw_hash()
    stretched_enc, stretched_mac = hkdf_expand(master, b"enc"), hkdf_expand(master, b"mac")
    user_key = os.urandom(64)
    priv = rsa.generate_private_key(public_exponent=65537, key_size=2048)
    pub_der = priv.public_key().public_bytes(serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo)
    priv_der = priv.private_bytes(serialization.Encoding.DER, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())
    return requests.post(URL + "/identity/accounts/register/finish", json={
        "email": EMAIL, "emailVerificationToken": token, "masterPasswordHash": h, "masterPasswordHint": "",
        "userSymmetricKey": enc_string(stretched_enc, stretched_mac, user_key),
        "userAsymmetricKeys": {"publicKey": b64(pub_der),
                               "encryptedPrivateKey": enc_string(user_key[:32], user_key[32:], priv_der)},
        "kdf": 0, "kdfIterations": ITER}, timeout=30)


def login():
    _, h = pw_hash()
    return requests.post(URL + "/identity/connect/token", data={
        "grant_type": "password", "username": EMAIL, "password": h, "scope": "api offline_access",
        "client_id": "web", "deviceType": 9, "deviceIdentifier": str(uuid.uuid4()), "deviceName": "lab"}, timeout=20)


def users():
    out = sh("docker", "run", "--rm", "-v", f"{VOL}:/data", "alpine", "sh", "-c", "ls -l /data | tr -s ' ' | cut -d' ' -f5,9")
    return out.replace("\n", " | ")


cleanup()
print("## 1. SIGNUPS_ALLOWED=false 로 띄우고 가입 시도")
start("false")
r = register()
print("가입 응답:", r.status_code, r.text[:90].replace("\n", " "))

print("## 2. SIGNUPS_ALLOWED=true 로 다시 띄워 계정 하나 만들고 로그인")
start("true")
r = register()
print("가입 응답:", r.status_code)
r = login()
print("로그인 응답:", r.status_code, "access_token 받음:", "access_token" in r.json())
print("/data 내용(크기 | 이름):", users())

print("## 3. 정지 후 백업(세 가지: 볼륨 전체 / 키 파일만 뺀 것 / db.sqlite3 한 개)")
sh("docker", "stop", NAME)
sh("docker", "run", "--rm", "-v", f"{VOL}:/data", "-v", f"{BK}:/bk", "alpine", "sh", "-c",
   "mkdir -p /bk/full /bk/nokey /bk/dbfile && cp -a /data/. /bk/full/ && cp /data/db.sqlite3* /bk/nokey/ && cp /data/db.sqlite3 /bk/dbfile/")
for d in ("full", "nokey", "dbfile"):
    print(f"{d:<7}:", sh("docker", "run", "--rm", "-v", f"{BK}:/bk", "alpine", "ls", f"/bk/{d}").replace("\n", " "))


def restore(d):
    sh("docker", "rm", "-f", NAME)
    sh("docker", "volume", "rm", VOL)
    sh("docker", "run", "--rm", "-v", f"{VOL}:/data", "-v", f"{BK}:/bk", "alpine", "sh", "-c", f"cp -a /bk/{d}/. /data/")
    start("false")
    r = login()
    return r.status_code, "access_token" in r.json()


print("## 4. 원본을 지우고 전체 백업으로 복원 -> 같은 계정으로 로그인")
print("전체 복원 뒤 로그인:", restore("full"))
print("## 5. 원본을 지우고 키 파일(rsa_key.pem)만 뺀 백업으로 복원 -> 로그인")
print("키 파일 없이 복원 뒤 로그인:", restore("nokey"))
print("새로 만들어진 /data(크기 | 이름):", users())
print("## 6. 원본을 지우고 db.sqlite3 한 개만으로 복원 -> 로그인")
print("db.sqlite3 한 개만 복원 뒤 로그인:", restore("dbfile"))

print("## 7. 정리")
cleanup()
print("남은 osk-vw 컨테이너:", len(sh("docker", "ps", "-a", "--filter", f"name={NAME}", "--format", "{{.Names}}").split()))
이 단계의 파일 내려받기:vw_test.py

6. 운영 전에 정할 것

항목 내용
HTTPS 외부에 열 때는 HTTPS 프록시가 필요합니다. 이 글은 HTTP로 localhost에서만 확인했습니다
백업 주기와 보관 위치 백업 파일 자체가 민감 정보이므로 접근을 제한하고 암호화해 보관합니다. 컨테이너를 멈춘 뒤 /data 전체를 복사합니다
가입 정책 가입을 끈 상태에서 사용자를 추가하는 방법(초대 등)은 확인하지 않았습니다. 가입을 끄는 설정은 실제로 가입을 막았습니다
관리자 페이지 관리자 토큰 설정은 하지 않았습니다

자주 막히는 곳

증상 원인과 해결
/alive가 바로 안 열립니다 시작 직후에는 health: starting 상태입니다. 몇 초 기다립니다
컨테이너 안에 sqlite3 명령이 없습니다 이 이미지에는 없었습니다. 위처럼 볼륨을 다른 컨테이너에 연결해 파일을 복사합니다
가입 주소를 호출했더니 404입니다 이 버전은 예전 /identity/accounts/register가 아니라 3단계 방식입니다. 5절의 코드를 봅니다
복원했는데 계정이 없습니다 db.sqlite3만 복사한 경우입니다. -shm, -wal까지 함께 복사합니다

확인 범위

  • 해 본 것: 2026-10-28, Windows 11 · Docker 29.5.3 · Vaultwarden 1.37.4에서 실행, /alive와 /api/config 호출, 데이터 파일 확인, 정지 후 복사 백업, 재시작 후 상태 확인. 29일에 계정을 하나 만들고(API로 가입과 로그인), 세 가지 백업을 각각 복원해 로그인되는지, 가입 차단 설정이 실제로 막는지 확인했습니다. 이미지는 vaultwarden/server:1.37.4로 고정했습니다.
  • 해 보지 않은 것: Bitwarden 앱이나 브라우저 확장으로 로그인, 보관함에 항목을 넣은 뒤의 복원, 복원 뒤 기존 기기의 토큰 상태, HTTPS, 관리자 페이지, 업데이트 절차.
  • 읽을 때 주의: 비밀번호를 실제로 맡기는 서버는 이 글의 범위를 넘습니다. 운영 전에 공식 문서의 보안 권고를 직접 확인합니다.

이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.

이 글의 다음 단계

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글