Vaultwarden 비밀번호 관리자 관리

Bitwarden 호환 셀프호스팅 비밀번호 관리자입니다. Podman 컨테이너로 실행되며, Caddy HTTPS 리버스 프록시(https://vaultwarden.greenhead.dev)를 통해 Tailscale VPN 내에서 접근합니다. Mac 브라우저 확장 + iPhone Bitwarden 앱에서 사용합니다.

모듈 구조

파일	역할
`modules/nixos/options/homeserver.nix`	`vaultwarden` + `vaultwardenUpdate` mkOption 정의
`modules/nixos/programs/docker/vaultwarden.nix`	Podman 컨테이너 + 시크릿 주입
`modules/nixos/programs/docker/vaultwarden-backup.nix`	매일 SQLite 안전 백업 (SSD -> HDD)
`modules/nixos/programs/vaultwarden-update/`	버전 체크 + 수동 업데이트 자동화
`modules/nixos/programs/caddy.nix`	Caddy HTTPS 리버스 프록시 (Vaultwarden 포함)
`secrets/vaultwarden-admin-token.age`	agenix 암호화 관리자 토큰
`libraries/constants.nix`	포트 (`vaultwarden = 8222`), 리소스 제한

빠른 참조

접근 방법

방식	URL
웹 볼트	`https://vaultwarden.greenhead.dev`
관리자 패널	`https://vaultwarden.greenhead.dev/admin`
내부 (localhost)	`http://127.0.0.1:8222`

관리자 패널 토큰: agenix secret (vaultwarden-admin-token.age)

서비스 관리

sudo podman ps | grep vaultwarden              # 컨테이너 상태
sudo podman logs vaultwarden                   # 로그 확인
systemctl status podman-vaultwarden            # systemd 서비스 상태
systemctl status vaultwarden-env               # 환경변수 생성 서비스 상태
journalctl -u podman-vaultwarden -f            # 로그 실시간
sudo ss -tlnp | grep 8222                      # 포트 리스닝 확인
curl -sf http://localhost:8222/alive           # 헬스체크
sudo podman inspect vaultwarden | jq '.[0].State.Health'  # 헬스 상태 상세

백업

sudo systemctl start vaultwarden-backup.service  # 수동 백업
systemctl list-timers | grep vaultwarden          # 타이머 확인
sudo ls -la /mnt/data/backups/vaultwarden/        # 백업 파일 확인
journalctl -u vaultwarden-backup.service          # 백업 로그

백업 구조:

SQLite DB: sqlite3 .backup → gzip 압축 → gunzip -t 무결성 검증
기타 파일: rsync (첨부파일, RSA 키, icon cache 등)
보존: 30일 (비밀번호 관리자이므로 다른 서비스 7일보다 길게)
스케줄: 매일 04:30 KST
위치: /mnt/data/backups/vaultwarden/YYYY-MM-DD/

클라이언트 설정

Mac (Bitwarden 브라우저 확장):

확장 프로그램 로그인 화면에서 Region → Self-hosted 선택
Server URL: https://vaultwarden.greenhead.dev
이메일 + Master Password로 로그인

iPhone (Bitwarden 앱):

로그인 화면에서 Region → Self-hosted 선택
Server URL: https://vaultwarden.greenhead.dev
이메일 + Master Password로 로그인
Face ID 잠금 해제 활성화 권장

오프라인 사용: 클라이언트가 vault를 로컬 캐시하므로 Tailscale 없이도 비밀번호 조회 가능. 동기화만 VPN 필요.

서비스 활성화/비활성화

# modules/nixos/configuration.nix
homeserver.vaultwarden.enable = true;          # 활성화
homeserver.vaultwarden.port = 8222;            # 포트 (기본값은 constants.nix)
homeserver.vaultwardenUpdate.enable = true;    # 버전 체크 + 업데이트 알림 (06:30)

보안 구성

항목	설정	설명
회원가입	`SIGNUPS_ALLOWED=false`	공개 회원가입 차단
초대	`INVITATIONS_ALLOWED=false`	사용자 간 초대 차단
비밀번호 힌트	`SHOW_PASSWORD_HINT=false`	힌트 노출 방지
로그인 제한	`LOGIN_RATELIMIT=5/60`	60초당 5회
관리자 제한	`ADMIN_RATELIMIT=3/60`	60초당 3회
포트 바인딩	`127.0.0.1:8222`	localhost 전용
데이터 권한	`0700`	root만 접근
시크릿	tmpfs (`/run/vaultwarden-env`)	재부팅 시 자동 소멸

스토리지 구조

경로	디스크	용도
`/var/lib/docker-data/vaultwarden/data`	SSD	SQLite DB + 첨부파일 + RSA 키 (0700)
`/run/vaultwarden-env`	tmpfs	ADMIN_TOKEN 환경변수 파일 (0400)
`/mnt/data/backups/vaultwarden`	HDD	일별 백업 (30일 보존, 0700)

Known Issues

ADMIN_TOKEN 평문 경고 (Argon2id 전환 미적용)
환경변수 파일 주입 방식 (caddy-env 패턴)
SIGNUPS_ALLOWED=false에서 계정 생성 절차
헬스체크 start-period 내 exit code 4
이미지 버전 고정 + 수동 업데이트 (sudo vaultwarden-update)
Master Password 복구 불가

상세: references/known-issues.md

자주 발생하는 문제

Bitwarden 클라이언트 로그인 실패: Region → Self-hosted → Server URL 설정 확인
관리자 패널 접근 불가: cat /run/vaultwarden-env로 토큰 확인, systemctl status vaultwarden-env
컨테이너 시작 실패: journalctl -u podman-vaultwarden에서 원인 확인
백업 실패: 소스 디렉토리 비어있으면 안전하게 중단 (의도적 동작)
동기화 안 됨: Tailscale VPN 연결 확인, curl -sf http://localhost:8222/alive
admin token 변경: agenix -e secrets/vaultwarden-admin-token.age → nrs → 컨테이너 자동 재시작

레퍼런스

설정/운영 상세: references/setup.md
Known Issues 상세: references/known-issues.md
트러블슈팅: references/troubleshooting.md

hosting-vaultwarden