Vaultwarden چیست و چرا آن را انتخاب کردیم؟

Vaultwarden پیاده‌سازی سبک Server API سازگار با Bitwarden است. یعنی به‌جای ساخت Password Manager از صفر، Server را روی VPS اجرا می‌کنیم و از برنامه‌ها و افزونه‌های رسمی Bitwarden برای استفاده روزمره بهره می‌بریم.

این انتخاب برای پروژه شخصی مناسب است چون یک VPS کوچک می‌تواند آن را اجرا کند، نصب Docker ساده است و لازم نیست خودمان رمزنگاری، Sync، Extension مرورگر و اپ موبایل را برنامه‌نویسی کنیم.

آیا برای این پروژه برنامه‌نویسی لازم است؟

خیر. هدف ما ساخت یک سرویس آماده و امن است، نه نوشتن Password Manager جدید. پیاده‌سازی رمزنگاری و Authentication از صفر می‌تواند خطرناک باشد؛ بنابراین به‌جای Python یا PHP از Vaultwarden آماده استفاده می‌کنیم و تمرکز را روی نصب امن، HTTPS و Backup می‌گذاریم.

چه سیستم‌عاملی مناسب است؟

پیشنهاد این آموزش Ubuntu Server 24.04 LTS است. دلیل انتخاب نسخه LTS، پشتیبانی طولانی، مستندات فراوان، سازگاری مناسب Docker و ساده بودن مدیریت Packageها برای کاربر تازه‌کار است.

مرحله اول: ورود به سرور با SSH

فرض می‌کنیم VPS تازه تحویل گرفته‌اید. از Windows Terminal، PowerShell، macOS Terminal یا Linux Terminal به Server متصل شوید:

ssh root@SERVER_IP

به‌جای SERVER_IP، IP واقعی VPS را قرار دهید. در اولین اتصال ممکن است SSH درباره Fingerprint سؤال کند؛ اگر IP را از پنل سرویس گرفته‌اید، پس از بررسی آن اتصال را تأیید کنید.

مرحله دوم: به‌روزرسانی سرور

apt update
apt upgrade -y

این مرحله Patchهای امنیتی و نسخه‌های جدید Packageها را نصب می‌کند. برای سرویسی که رمزهای شما را نگه می‌دارد، شروع کار با Server به‌روز ضروری است.

مرحله سوم: نصب Docker از Repository رسمی

apt install ca-certificates curl nginx certbot python3-certbot-nginx -y

install -m 0755 -d /etc/apt/keyrings

curl -fsSL 
https://download.docker.com/linux/ubuntu/gpg 
-o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: noble
Components: stable
Architectures: amd64
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update

apt install 
docker-ce 
docker-ce-cli 
containerd.io 
docker-buildx-plugin 
docker-compose-plugin 
-y

بررسی کنید Docker اجرا می‌شود:

docker --version
docker compose version

مرحله چهارم: آماده کردن دامنه

یک Subdomain مانند vault.example.com بسازید و رکورد A آن را روی IP سرور قرار دهید. بعد از انتشار DNS:

dig +short vault.example.com

خروجی باید IP VPS باشد. بدون DNS صحیح، گرفتن Certificate از Let’s Encrypt با خطا روبه‌رو می‌شود.

مرحله پنجم: ساخت Docker Compose

mkdir -p /opt/vaultwarden
cd /opt/vaultwarden

nano compose.yml

محتوای فایل:

services:
  vaultwarden:
    image: vaultwarden/server:1.37.3
    container_name: vaultwarden
    restart: unless-stopped

    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "true"

    volumes:
      - ./vw-data:/data

    ports:
      - "127.0.0.1:8080:80"

چرا Port را فقط روی 127.0.0.1 باز کردیم؟ چون نمی‌خواهیم Vaultwarden مستقیماً از اینترنت روی Port 8080 قابل دسترس باشد. Nginx روی همان Server درخواست HTTPS را دریافت می‌کند و به Container می‌فرستد.

مرحله ششم: اجرای Vaultwarden

docker compose up -d
docker compose ps
docker compose logs --tail=100

اگر وضعیت Container روی Up باشد، برنامه روی localhost:8080 در دسترس است.

مرحله هفتم: تنظیم Nginx

nano /etc/nginx/sites-available/vaultwarden

server {
    listen 80;
    server_name vault.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

فعال‌سازی:

ln -s \
/etc/nginx/sites-available/vaultwarden \
/etc/nginx/sites-enabled/vaultwarden

nginx -t
systemctl reload nginx

مرحله هشتم: فعال کردن HTTPS

certbot --nginx -d vault.example.com

بعد از پایان، آدرس زیر را باز کنید:

https://vault.example.com

Vaultwarden خودش توصیه می‌کند برای Server عمومی مقدار DOMAIN را روی URL HTTPS تنظیم کنید و TLS را از طریق Reverse Proxy پیاده کنید.

مرحله نهم: حساب اصلی را بسازید و ثبت‌نام را ببندید

در اولین ورود حساب شخصی خود را بسازید. بعد از اینکه مطمئن شدید Login کار می‌کند، compose.yml را ویرایش کنید:

SIGNUPS_ALLOWED: "false"

و Container را بازسازی کنید:

docker compose up -d

اتصال برنامه Bitwarden به Vaultwarden

در صفحه Login برنامه Bitwarden، گزینه Self-hosted یا Server URL را باز کنید و آدرس Server را روی دامنه خود قرار دهید:

https://vault.example.com

بعد با همان Email و Master Password وارد شوید. از این مرحله Vault شما میان کلاینت‌هایی که Login شده‌اند Sync می‌شود.

Master Password را چطور انتخاب کنیم؟

برای Master Password از رمز کوتاه و قابل حدس استفاده نکنید. یک Passphrase بلند و منحصربه‌فرد که در هیچ سرویس دیگری استفاده نشده باشد انتخاب بهتری است.

Master Password مهم‌ترین Credential این سیستم است؛ آن را داخل همان Vault ذخیره نکنید. یک نسخه Recovery امن و آفلاین داشته باشید.

2FA را فعال کنید

بعد از اطمینان از دسترسی، احراز هویت دومرحله‌ای را برای حساب اصلی فعال کنید. Recovery Code را خارج از Server و خارج از Vault نگه دارید.

Backup از Vaultwarden

تمام داده پایدار ما داخل مسیر زیر است:

/opt/vaultwarden/vw-data

برای Backup ساده و سازگار، ابتدا Container را متوقف کنید:

cd /opt/vaultwarden

docker compose stop

tar -czf 
/root/vaultwarden-backup-$(date +%F).tar.gz 
vw-data

docker compose start

نسخه Backup را روی همان VPS نگه ندارید؛ اگر Server حذف شود، Backup داخل همان Server هم از بین می‌رود.

آپدیت Vaultwarden

قبل از Update از Data Backup بگیرید. سپس Version جدید را بعد از بررسی Release Notes داخل compose.yml جایگزین کنید:

docker compose pull
docker compose up -d

خطاهای رایج Vaultwarden

502 Bad Gateway

ابتدا وضعیت Container را بررسی کنید:

docker compose ps
docker compose logs --tail=100

Certificate صادر نمی‌شود

DNS دامنه، باز بودن Portهای 80 و 443 و Server Name داخل Nginx را بررسی کنید.

اپ Bitwarden به Server وصل نمی‌شود

DOMAIN باید HTTPS صحیح باشد و Certificate نباید خطای Trust داشته باشد.

بعد از تغییر compose.yml تنظیمات اعمال نشد

فقط Restart کافی نیست؛ بعد از تغییر Environment بهتر است docker compose up -d اجرا شود تا Container با Configuration جدید بازسازی شود.

سؤالات متداول

Vaultwarden چیست؟

یک Server سبک و Self-hosted سازگار با کلاینت‌های Bitwarden برای نگهداری و Sync اطلاعات Vault است.

آیا Vaultwarden روی VPS کوچک اجرا می‌شود؟

بله. برای استفاده شخصی معمولاً یک VPS کوچک با ۱ تا ۲GB RAM کافی است.

آیا Vaultwarden بدون HTTPS کار می‌کند؟

برای استفاده واقعی اینترنتی HTTPS باید فعال باشد و خود پروژه نیز Reverse Proxy با TLS را توصیه می‌کند.

آیا باید ثبت‌نام را ببندیم؟

برای Server شخصی بهتر است بعد از ساخت حساب‌های مورد نیاز SIGNUPS_ALLOWED را غیرفعال کنید.

آیا Backup خود Vaultwarden کافی است؟

خیر. Backup باید از VPS اصلی خارج شود تا حذف یا خرابی Server هر دو نسخه را از بین نبرد.

Password Manager و Secrets Manager چه فرقی دارند؟

چرا OpenBao؟

OpenBao علاوه بر Secretهای ثابت Key/Value می‌تواند Policy، Token، AppRole و Secretهای پویا را مدیریت کند. برای این آموزش از KV Version 2 استفاده می‌کنیم تا Secretهای ساده مثل API Key و Password را Versioned نگه داریم.

آیا به زبان برنامه‌نویسی نیاز داریم؟

برای راه‌اندازی Server خیر. OpenBao سرویس آماده دارد و با CLI و HTTP API مدیریت می‌شود. در Application واقعی می‌توانید از SDK زبان خودتان استفاده کنید. برای شروع، CLI بهترین انتخاب است چون بدون نوشتن کد می‌توانیم تمام مفاهیم اصلی را ببینیم.

سیستم‌عامل پیشنهادی

Ubuntu Server 24.04 LTS را انتخاب می‌کنیم چون Docker، Nginx و ابزارهای امنیتی مورد نیاز به‌سادگی روی آن نصب می‌شوند و برای کاربر مبتدی مسیر مستقیمی دارد.

مرحله اول: ورود SSH و آپدیت Server

ssh root@SERVER_IP

apt update
apt upgrade -y

مرحله دوم: نصب Docker، Nginx و Certbot

apt install \
ca-certificates \
curl \
nginx \
certbot \
python3-certbot-nginx \
-y

install -m 0755 -d /etc/apt/keyrings

curl -fsSL 
https://download.docker.com/linux/ubuntu/gpg 
-o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: noble
Components: stable
Architectures: amd64
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update

apt install 
docker-ce 
docker-ce-cli 
containerd.io 
docker-buildx-plugin 
docker-compose-plugin 
-y

مرحله سوم: آماده کردن Domain

یک Subdomain مثل secrets.example.com را روی IP Server قرار دهید. این Domain بعداً Endpoint اصلی API خواهد بود.

مرحله چهارم: ساخت OpenBao Stack

mkdir -p /opt/openbao/config
cd /opt/openbao

nano config/config.hcl

Config تک‌Node:

ui = true

storage "raft" {
  path    = "/openbao/data"
  node_id = "bao-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 1
}

api_addr     = "https://secrets.example.com"
cluster_addr = "http://127.0.0.1:8201"

TLS داخل Container غیرفعال شده چون Port 8200 فقط روی localhost Host منتشر می‌شود و Nginx روی همان ماشین TLS را Terminate می‌کند. این مدل برای Single-node ساده است. برای Cluster یا محیط حساس‌تر بهتر است TLS خود OpenBao نیز فعال باشد.

Compose:

services:
  openbao:
    image: quay.io/openbao/openbao:2.7.1
    container_name: openbao
    restart: unless-stopped

    cap_add:
      - IPC_LOCK

    command:
      - server
      - -config=/openbao/config/config.hcl

    environment:
      BAO_ADDR: "http://127.0.0.1:8200"

    ports:
      - "127.0.0.1:8200:8200"

    volumes:
      - ./config:/openbao/config:ro
      - bao-data:/openbao/data

volumes:
  bao-data:

مرحله پنجم: اجرای OpenBao

docker compose up -d
docker compose logs -f

Server در این مرحله هنوز آماده استفاده نیست؛ OpenBao به‌صورت Sealed شروع می‌شود و باید Initialize و Unseal شود.

مرحله ششم: Nginx و HTTPS

nano /etc/nginx/sites-available/openbao

server {
    listen 80;
    server_name secrets.example.com;

    location / {
        proxy_pass http://127.0.0.1:8200;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 90s;
    }
}

ln -s \
/etc/nginx/sites-available/openbao \
/etc/nginx/sites-enabled/openbao

nginx -t
systemctl reload nginx

certbot --nginx 
-d secrets.example.com

مرحله هفتم: Initialize کردن OpenBao

docker compose exec openbao \
bao operator init \
-key-shares=5 \
-key-threshold=3

OpenBao پنج Unseal Key و یک Initial Root Token ایجاد می‌کند. برای باز کردن Vault بعد از Restart به حداقل سه Key نیاز داریم.

مرحله هشتم: Unseal

سه مرتبه دستور زیر را با سه Key متفاوت اجرا کنید:

docker compose exec openbao \
bao operator unseal

پس از Threshold لازم، وضعیت Sealed باید false شود.

مرحله نهم: Login اولیه

docker compose exec openbao \
bao login ROOT_TOKEN

Root Token برای Setup اولیه است؛ Applicationها نباید از Root Token استفاده کنند.

مرحله دهم: فعال کردن KV Version 2

docker compose exec openbao \
bao secrets enable \
-path=kv \
kv-v2

KV v2 تاریخچه نسخه Secret را نگه می‌دارد و برای Secretهای ثابت انتخاب مناسبی است.

ذخیره اولین Secret

docker compose exec openbao \
bao kv put kv/myapp/database \
username="appuser" \
password="CHANGE_ME"

خواندن:

docker compose exec openbao \
bao kv get kv/myapp/database

ساخت Policy فقط خواندنی برای Application

Application نباید Permission مدیریتی داشته باشد. یک Policy محدود می‌سازیم:

cat > /tmp/myapp-read.hcl <<'EOF'
path "kv/data/myapp/*" {
  capabilities = ["read"]
}
EOF

docker cp 
/tmp/myapp-read.hcl 
openbao:/tmp/myapp-read.hcl

docker compose exec openbao 
bao policy write 
myapp-read 
/tmp/myapp-read.hcl

AppRole؛ Login برای ماشین به‌جای User

AppRole برای Application و Workflow خودکار طراحی شده است. برنامه با Role ID و Secret ID Login می‌کند و Token محدود دریافت می‌کند.

docker compose exec openbao \
bao auth enable approle

docker compose exec openbao 
bao write auth/approle/role/myapp 
token_policies="myapp-read" 
token_ttl="20m" 
token_max_ttl="1h" 
secret_id_ttl="10m"

Role ID:

docker compose exec openbao \
bao read auth/approle/role/myapp/role-id

Secret ID:

docker compose exec openbao \
bao write -f auth/approle/role/myapp/secret-id

از این دو مقدار می‌توان برای Login ماشین استفاده کرد. Secret ID را مثل Password محافظت کنید و آن را داخل Git Commit نکنید.

OpenBao بعد از Reboot چرا Sealed می‌شود؟

در مدل Shamir استاندارد، بعد از Restart باید دوباره Threshold لازم از Unseal Keyها ارائه شود. این رفتار امنیتی است، نه خطا.

برای محیط‌های بزرگ‌تر می‌توان Auto Unseal با KMS یا HSM طراحی کرد، اما این موضوع پیچیدگی بیشتری دارد و برای آموزش پایه ضروری نیست.

Backup از OpenBao

فقط Backup گرفتن از Container کافی نیست. Storage Backend، Configuration و روش Unseal باید در Disaster Recovery دیده شوند. Unseal Keyها را جدا از Backup Data نگه دارید.

خطاهای رایج

Sealed: true

بعد از Restart طبیعی است. سه Unseal Key از پنج Key مثال ما لازم است.

Permission denied هنگام خواندن Secret

Path Policy و Policy متصل به Token یا AppRole را بررسی کنید. در KV v2 مسیر Policy شامل بخش data است.

502 از Nginx

وضعیت Container و Listener Port 8200 را بررسی کنید.

Root Token گم شده است

Root Token نباید Credential روزمره باشد. OpenBao روش Generate Root جدید با مجوزهای لازم دارد، اما نگهداری Recovery Material باید از ابتدا بخشی از Design باشد.

سؤالات متداول

OpenBao چیست؟

Secrets Manager متن‌باز برای ذخیره و توزیع Secret، کنترل دسترسی، Token و Secretهای پویا است.

Secret Manager با Password Manager فرق دارد؟

بله. Password Manager بیشتر برای Credentialهای انسان و Secrets Manager برای Application و Infrastructure طراحی شده است.

KV v2 چه مزیتی دارد؟

Secretهای Key/Value را به‌صورت Versioned نگه می‌دارد و امکان بازیابی نسخه‌های قبلی را فراهم می‌کند.

AppRole چیست؟

روش Authentication مناسب ماشین و سرویس است که Token محدود براساس Policy دریافت می‌کند.

آیا OpenBao بعد از Restart نیاز به Unseal دارد؟

در مدل Shamir معمولی بله. Auto Unseal نیازمند طراحی جداگانه است.