Back to Details

hosting-vaultwarden

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vaultwarden 비밀번호 관리자 관리

Vaultwarden密码管理器管理

Bitwarden 호환 셀프호스팅 비밀번호 관리자입니다. Podman 컨테이너로 실행되며, Caddy HTTPS 리버스 프록시(
https://vaultwarden.greenhead.dev
)를 통해 Tailscale VPN 내에서 접근합니다. Mac 브라우저 확장 + iPhone Bitwarden 앱에서 사용합니다.
这是一款兼容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
), 리소스 제한
文件作用
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
)
方式URL
网页密码库
https://vaultwarden.greenhead.dev
管理面板
https://vaultwarden.greenhead.dev/admin
内部访问（localhost）
http://127.0.0.1:8222
管理面板令牌：agenix密钥（
vaultwarden-admin-token.age
）

서비스 관리

服务管理

bash
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'  # 헬스 상태 상세
bash
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'  # 查看详细健康状态

백업

备份

bash
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/
bash
sudo systemctl start vaultwarden-backup.service  # 手动触发备份
systemctl list-timers | grep vaultwarden          # 查看定时器状态
sudo ls -la /mnt/data/backups/vaultwarden/        # 查看备份文件
journalctl -u vaultwarden-backup.service          # 查看备份日志
备份结构:
  • SQLite数据库: 
    sqlite3 .backup
    → gzip压缩 → 
    gunzip -t
    完整性验证
  • 其他文件: rsync同步（附件、RSA密钥、图标缓存等）
  • 保留期限: 30天（因是密码管理器，比其他服务的7天更长）
  • 执行时间: 每日04:30 KST（韩国标准时间）
  • 存储位置: 
    /mnt/data/backups/vaultwarden/YYYY-MM-DD/

클라이언트 설정

客户端设置

Mac (Bitwarden 브라우저 확장):
  1. 확장 프로그램 로그인 화면에서 Region → Self-hosted 선택
  2. Server URL: 
    https://vaultwarden.greenhead.dev
  3. 이메일 + Master Password로 로그인
iPhone (Bitwarden 앱):
  1. 로그인 화면에서 Region → Self-hosted 선택
  2. Server URL: 
    https://vaultwarden.greenhead.dev
  3. 이메일 + Master Password로 로그인
  4. Face ID 잠금 해제 활성화 권장
오프라인 사용: 클라이언트가 vault를 로컬 캐시하므로 Tailscale 없이도 비밀번호 조회 가능. 동기화만 VPN 필요.
Mac（Bitwarden浏览器扩展）:
  1. 在扩展登录界面选择Region → Self-hosted
  2. 输入Server URL: 
    https://vaultwarden.greenhead.dev
  3. 使用邮箱 + Master Password登录
iPhone（Bitwarden应用）:
  1. 在登录界面选择Region → Self-hosted
  2. 输入Server URL: 
    https://vaultwarden.greenhead.dev
  3. 使用邮箱 + Master Password登录
  4. 建议开启Face ID解锁
离线使用: 客户端会本地缓存密码库，无需Tailscale也可查看密码。仅同步操作需要VPN。

서비스 활성화/비활성화

服务启用/禁用

nix
undefined
nix
undefined

modules/nixos/configuration.nix

modules/nixos/configuration.nix

homeserver.vaultwarden.enable = true; # 활성화 homeserver.vaultwarden.port = 8222; # 포트 (기본값은 constants.nix) homeserver.vaultwardenUpdate.enable = true; # 버전 체크 + 업데이트 알림 (06:30)
undefined
homeserver.vaultwarden.enable = true; # 启用服务 homeserver.vaultwarden.port = 8222; # 端口配置（默认值在constants.nix中） homeserver.vaultwardenUpdate.enable = true; # 启用版本检查 + 更新通知（每日06:30执行）
undefined

보안 구성

安全配置

항목설정설명
회원가입
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
)		재부팅 시 자동 소멸
项目设置说明
注册功能
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
SSDSQLite DB + 첨부파일 + RSA 키 (0700)
/run/vaultwarden-env
tmpfsADMIN_TOKEN 환경변수 파일 (0400)
/mnt/data/backups/vaultwarden
HDD일별 백업 (30일 보존, 0700)
路径磁盘用途
/var/lib/docker-data/vaultwarden/data
SSDSQLite数据库 + 附件 + RSA密钥（权限0700）
/run/vaultwarden-env
tmpfsADMIN_TOKEN环境变量文件（权限0400）
/mnt/data/backups/vaultwarden
HDD每日备份（保留30天，权限0700）

Known Issues

已知问题

ADMIN_TOKEN 평문 경고
  • 관리자 패널에 "plain text ADMIN_TOKEN is insecure" 경고 표시
  • Argon2id 해싱으로 전환 가능하나, 초기 복잡도를 고려하여 v1에서는 평문 사용
  • Tailscale 전용 + root 권한 필수 환경에서 실질적 위험 낮음
  • 향후 개선: 컨테이너 내부에서 
    vaultwarden hash
    → agenix secret 교체
환경변수 파일 주입 방식 (caddy-env 패턴)
  • Vaultwarden은 
    _FILE
    접미사 환경변수 미지원
  • vaultwarden-env
    oneshot 서비스가 agenix secret → tmpfs 환경변수 파일 생성
  • environmentFiles
    로 컨테이너에 주입, 
    ConditionPathExists
    로 안전장치
  • 패턴 동일: 
    caddy-env
    (Cloudflare token), 
    copyparty-config
    (비밀번호)
SIGNUPS_ALLOWED=false에서 계정 생성
  • 로그인 페이지에 "Create Account" 버튼 미표시 (정상)
  • 관리자 패널(
    /admin
    ) → Users → Invite로 이메일 초대
  • 초대 후 
    /#/register
    에 직접 접속하여 계정 생성 (초대된 이메일만 허용)
WebSocket 실시간 동기화
  • Vaultwarden v1.29+에서 WebSocket이 동일 HTTP 포트로 통합
  • Caddy 
    reverse_proxy
    가 WebSocket 업그레이드를 자동 처리
  • 별도 설정 불필요 (별도 WebSocket 포트/경로 프록시 불필요)
헬스체크 시작 시 일시 실패 (exit code 4)
  • nrs
    적용 시 컨테이너 재시작 직후 헬스체크 transient 서비스가 start-period(30초) 내에 실행되면 exit code 4 발생 가능
  • nrs.sh
    가 exit code 4를 경고로 처리하므로 빌드 결과물 정리 등 후속 작업은 정상 진행
  • 30초 후 자동으로 
    healthy
    상태로 전환
  • 확인: 
    sudo podman inspect vaultwarden | jq '.[0].State.Health.Status'
이미지 버전 고정 + 업데이트 자동화
  • vaultwarden/server:1.35.2
    (
    :latest
    미사용)
  • 재부팅 시 예기치 않은 버전 변경 방지
  • homeserver.vaultwardenUpdate.enable = true
    로 매일 06:30 자동 버전 체크 + Pushover 알림
  • 수동 업데이트: 
    sudo vaultwarden-update
    (pinned tag pull → digest 비교 → 재시작 → 헬스체크)
  • 통합 업데이트 시스템 상세: 
    running-containers
    스킬의 service-update-system.md 참조
Master Password 복구 불가
  • Bitwarden은 클라이언트 측 암호화 (서버에 키 저장 안 함)
  • Master Password를 잊으면 서버 관리자도 vault 복구 불가능
  • 비상 대책: Master Password를 안전한 물리적 장소에 별도 보관
ADMIN_TOKEN明文警告
  • 管理面板会显示“plain text ADMIN_TOKEN is insecure”警告
  • 可切换为Argon2id哈希存储，但考虑到初始复杂度，v1版本暂使用明文
  • 在仅允许Tailscale访问 + 需root权限的环境中，实际风险较低
  • 后续优化方向：在容器内执行
    vaultwarden hash
    → 替换为agenix密钥
环境变量文件注入方式（caddy-env模式）
  • Vaultwarden不支持带
    _FILE
    后缀的环境变量
  • vaultwarden-env
    一次性服务将agenix密钥转换为tmpfs中的环境变量文件
  • 通过
    environmentFiles
    注入容器，使用
    ConditionPathExists
    作为安全防护
  • 相同模式：
    caddy-env
    （Cloudflare令牌）、
    copyparty-config
    （密码）
SIGNUPS_ALLOWED=false时的账号创建
  • 登录页面不显示“Create Account”按钮（正常现象）
  • 需通过管理面板(
    /admin
    ) → Users → Invite发送邮箱邀请
  • 受邀用户需直接访问
    /#/register
    页面创建账号（仅受邀邮箱可注册）
WebSocket实时同步
  • Vaultwarden v1.29+版本中，WebSocket已整合至同一HTTP端口
  • Caddy 
    reverse_proxy
    会自动处理WebSocket升级
  • 无需额外配置（无需单独代理WebSocket端口/路径）
健康检查启动时临时失败（exit code 4）
  • 应用
    nrs
    时，容器重启后健康检查临时服务若在start-period(30秒)内执行，可能会出现exit code 4
  • nrs.sh
    会将exit code 4视为警告，因此清理构建产物等后续操作仍会正常执行
  • 30秒后会自动切换为
    healthy
    状态
  • 状态确认：
    sudo podman inspect vaultwarden | jq '.[0].State.Health.Status'
镜像版本固定 + 更新自动化
  • 使用
    vaultwarden/server:1.35.2
    （不使用
    :latest
    ）
  • 避免重启时意外更新版本
  • 开启
    homeserver.vaultwardenUpdate.enable = true
    后，每日06:30自动检查版本并发送Pushover通知
  • 手动更新：执行
    sudo vaultwarden-update
    （拉取固定标签镜像 → 对比摘要 → 重启容器 → 健康检查）
  • 集成更新系统详情：参考running-containers技能中的service-update-system.md
Master Password无法恢复
  • Bitwarden采用客户端加密（服务器不存储密钥）
  • 若遗忘Master Password，即使服务器管理员也无法恢复密码库
  • 应急方案：将Master Password单独存储在安全的物理位置

자주 발생하는 문제

常见问题

  1. Bitwarden 클라이언트 로그인 실패: Region → Self-hosted → Server URL 설정 확인
  2. 관리자 패널 접근 불가: 
    cat /run/vaultwarden-env
    로 토큰 확인, 
    systemctl status vaultwarden-env
  3. 컨테이너 시작 실패: 
    journalctl -u podman-vaultwarden
    에서 원인 확인
  4. 백업 실패: 소스 디렉토리 비어있으면 안전하게 중단 (의도적 동작)
  5. 동기화 안 됨: Tailscale VPN 연결 확인, 
    curl -sf http://localhost:8222/alive
  6. admin token 변경: 
    agenix -e secrets/vaultwarden-admin-token.age
    → 
    nrs
    → 컨테이너 자동 재시작
  1. Bitwarden客户端登录失败: 检查Region是否选择Self-hosted，以及Server URL配置是否正确
  2. 无法访问管理面板: 通过
    cat /run/vaultwarden-env
    查看令牌，或检查
    systemctl status vaultwarden-env
    状态
  3. 容器启动失败: 通过
    journalctl -u podman-vaultwarden
    查看失败原因
  4. 备份失败: 若源目录为空，备份会安全终止（预期行为）
  5. 同步失败: 检查Tailscale VPN连接状态，或执行
    curl -sf http://localhost:8222/alive
    验证服务可用性
  6. 修改admin token: 执行
    agenix -e secrets/vaultwarden-admin-token.age
    → 运行
    nrs
    → 容器会自动重启

레퍼런스

参考资料

  • 설정/운영 상세: references/setup.md
  • 트러블슈팅: references/troubleshooting.md
  • 配置/运维详情: references/setup.md
  • 故障排查: references/troubleshooting.md