From 41a586b97b552c35b178e5d7c7f4d5da5b11867b Mon Sep 17 00:00:00 2001
From: Joywayer <joywayer@163.com>
Date: Tue, 7 Apr 2026 16:03:47 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20siyuan=20certd=20vaultward?=
 =?UTF-8?q?en?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                          | 197 ++++++++++++++
 base/.env.example                  |   4 +
 base/README.md                     |  72 ++++++
 base/setup.sh                      | 395 +++++++++++++++++++++++++++++
 certd/.env.example                 |  29 +++
 certd/README.md                    | 282 ++++++++++++++++++++
 certd/backup.sh                    |  68 +++++
 certd/deploy.sh                    | 178 +++++++++++++
 certd/docker-compose.yml           |  29 +++
 certd/nginx/certd.conf             |  55 ++++
 gitea/README.md                    | 158 ++++++++++--
 gitea/deploy.sh                    |  10 +-
 gitea/docker-compose.yml           |   2 +-
 siyuan/.env.example                |  31 +++
 siyuan/README.md                   | 277 ++++++++++++++++++++
 siyuan/backup.sh                   |  70 +++++
 siyuan/deploy.sh                   | 185 ++++++++++++++
 siyuan/docker-compose.yml          |  28 ++
 siyuan/nginx/siyuan.conf           |  70 +++++
 vaultwarden/.env.example           |  44 ++++
 vaultwarden/README.md              | 328 ++++++++++++++++++++++++
 vaultwarden/backup.sh              |  92 +++++++
 vaultwarden/deploy.sh              | 210 +++++++++++++++
 vaultwarden/docker-compose.yml     |  29 +++
 vaultwarden/nginx/vaultwarden.conf |  78 ++++++
 25 files changed, 2894 insertions(+), 27 deletions(-)
 create mode 100644 README.md
 create mode 100644 base/.env.example
 create mode 100644 base/README.md
 create mode 100644 base/setup.sh
 create mode 100644 certd/.env.example
 create mode 100644 certd/README.md
 create mode 100644 certd/backup.sh
 create mode 100644 certd/deploy.sh
 create mode 100644 certd/docker-compose.yml
 create mode 100644 certd/nginx/certd.conf
 create mode 100644 siyuan/.env.example
 create mode 100644 siyuan/README.md
 create mode 100644 siyuan/backup.sh
 create mode 100644 siyuan/deploy.sh
 create mode 100644 siyuan/docker-compose.yml
 create mode 100644 siyuan/nginx/siyuan.conf
 create mode 100644 vaultwarden/.env.example
 create mode 100644 vaultwarden/README.md
 create mode 100644 vaultwarden/backup.sh
 create mode 100644 vaultwarden/deploy.sh
 create mode 100644 vaultwarden/docker-compose.yml
 create mode 100644 vaultwarden/nginx/vaultwarden.conf

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78613e5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,197 @@
+# Docker 服务部署集合
+
+一套完整的自托管服务部署方案，适用于阿里云等国内服务器环境。
+
+## 服务列表
+
+| 服务 | 说明 | 端口 |
+|------|------|------|
+| [base/](base/) | 公共基础设施（Docker + Nginx + Certbot + 防火墙） | — |
+| [gitea/](gitea/) | Git 代码托管（Gitea + MySQL 8.4） | 443, 2222 |
+| [certd/](certd/) | SSL 证书自动化管理（Certd） | 443 |
+| [vaultwarden/](vaultwarden/) | 密码管理器（Vaultwarden / Bitwarden 兼容） | 443 |
+| [siyuan/](siyuan/) | 知识管理笔记（思源笔记 SiYuan） | 443 |
+
+## 架构概览
+
+```
+                    ┌─────────────┐
+                    │   Nginx     │ ← 统一 HTTPS 入口
+                    │  (系统包)    │ ← Let's Encrypt 证书
+                    └──────┬──────┘
+                           │
+            ┌──────────────┼──────────────┬──────────────┐
+            │              │              │              │
+     ┌──────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐ ┌────▼─────┐
+     │   Gitea     │ │  Certd   │ │ Vaultwarden │ │  SiYuan  │
+     │ :3000(内部)  │ │ :7001    │ │ :8080(内部)  │ │ :6806    │
+     │ + MySQL 8.4 │ │          │ │             │ │          │
+     └─────────────┘ └──────────┘ └─────────────┘ └──────────┘
+          Docker          Docker        Docker        Docker
+```
+
+所有服务通过 Nginx 反向代理提供 HTTPS 访问，容器端口仅监听 `127.0.0.1`。
+
+## 目录结构
+
+```
+docker/
+├── README.md                 # 本文件
+├── base/                     # 公共基础设施
+│   ├── setup.sh              #   安装脚本（Docker/Nginx/Certbot/防火墙）
+│   ├── .env.example          #   Docker 镜像加速配置
+│   └── README.md
+├── gitea/                    # Gitea 代码托管
+│   ├── docker-compose.yml    #   Gitea + MySQL 容器编排
+│   ├── deploy.sh             #   一键部署脚本（自包含）
+│   ├── backup.sh             #   备份脚本
+│   ├── upgrade.sh            #   升级脚本
+│   ├── migrate.sh            #   迁移脚本
+│   ├── nginx/gitea.conf      #   Nginx 配置模板
+│   └── README.md
+├── certd/                    # Certd 证书管理
+│   ├── docker-compose.yml
+│   ├── deploy.sh             #   部署脚本（依赖 base/）
+│   ├── backup.sh
+│   ├── nginx/certd.conf
+│   └── README.md
+├── vaultwarden/              # Vaultwarden 密码管理
+│   ├── docker-compose.yml
+│   ├── deploy.sh             #   部署脚本（依赖 base/）
+│   ├── backup.sh
+│   ├── nginx/vaultwarden.conf
+│   └── README.md
+└── siyuan/                   # SiYuan 思源笔记
+    ├── docker-compose.yml
+    ├── deploy.sh             #   部署脚本（依赖 base/）
+    ├── backup.sh
+    ├── nginx/siyuan.conf
+    └── README.md
+```
+
+## 快速开始
+
+### 场景一：全新服务器部署所有服务
+
+```bash
+# 1. 上传所有文件到服务器
+scp -r base/ gitea/ certd/ vaultwarden/ siyuan/ root@<IP>:/opt/
+
+# 2. 安装基础环境
+ssh root@<IP>
+cd /opt/base
+cp .env.example .env
+bash setup.sh
+
+# 3. 部署 Gitea
+cd /opt/gitea
+bash deploy.sh          # 首次生成 .env，修改配置后再次运行
+vi .env
+bash deploy.sh
+
+# 4. 部署 Certd
+cd /opt/certd
+bash deploy.sh
+vi .env
+bash deploy.sh
+
+# 5. 部署 Vaultwarden
+cd /opt/vaultwarden
+bash deploy.sh
+vi .env
+bash deploy.sh
+
+# 6. 部署 SiYuan
+cd /opt/siyuan
+bash deploy.sh
+vi .env
+bash deploy.sh
+```
+
+### 场景二：已有 Gitea 的服务器，追加部署 Certd
+
+```bash
+# 上传新服务文件（base 是新增的公共依赖）
+scp -r base/ certd/ root@<IP>:/opt/
+
+ssh root@<IP>
+
+# 安装 base（会检测已安装的组件并跳过）
+cd /opt/base
+cp .env.example .env
+bash setup.sh
+
+# 部署 Certd
+cd /opt/certd
+bash deploy.sh
+vi .env
+bash deploy.sh
+```
+
+### 场景三：只部署单个服务
+
+每个服务的 `deploy.sh` 会自动调用 `base/setup.sh` 安装缺失的基础环境，无需手动运行 base。
+
+```bash
+scp -r base/ vaultwarden/ root@<IP>:/opt/
+ssh root@<IP>
+cd /opt/vaultwarden
+bash deploy.sh
+vi .env
+bash deploy.sh
+```
+
+## 域名规划示例
+
+| 服务 | 域名 | DNS 记录 |
+|------|------|----------|
+| Gitea | `git.example.com` | A → 服务器 IP |
+| Certd | `cert.example.com` | A → 服务器 IP |
+| Vaultwarden | `vault.example.com` | A → 服务器 IP |
+| SiYuan | `note.example.com` | A → 服务器 IP |
+
+## 日常运维
+
+### 查看各服务状态
+
+```bash
+# Gitea
+cd /opt/gitea && docker compose ps
+
+# Certd
+cd /opt/certd && docker compose ps
+
+# Vaultwarden
+cd /opt/vaultwarden && docker compose ps
+
+# SiYuan
+cd /opt/siyuan && docker compose ps
+```
+
+### 备份所有服务
+
+```bash
+cd /opt/gitea && bash backup.sh
+cd /opt/certd && bash backup.sh
+cd /opt/vaultwarden && bash backup.sh
+cd /opt/siyuan && bash backup.sh
+```
+
+### SSL 证书续期
+
+所有服务共享 Certbot，证书自动续期（每天 03:00 检查）。
+
+```bash
+# 查看所有证书
+certbot certificates
+
+# 手动测试续期
+certbot renew --dry-run
+```
+
+## 注意事项
+
+- **Gitea 的 deploy.sh 是自包含的**，不依赖 base/（历史兼容）。Certd、Vaultwarden 和 SiYuan 依赖 base/。
+- 所有容器端口仅监听 `127.0.0.1`，通过 Nginx 反向代理对外提供 HTTPS 服务。
+- `.env` 文件包含敏感信息，不要提交到公开仓库。
+- 首次部署每个服务时需要运行两次 `deploy.sh`：第一次生成 `.env`，修改配置后第二次正式部署。
diff --git a/base/.env.example b/base/.env.example
new file mode 100644
index 0000000..d4a7ead
--- /dev/null
+++ b/base/.env.example
@@ -0,0 +1,4 @@
+# ===== 基础环境配置 =====
+
+# Docker 镜像加速（国内服务器推荐配置）
+DOCKER_REGISTRY_MIRRORS=https://docker.1ms.run,https://docker.m.daocloud.io,https://dockerpull.org,https://docker.rainbond.cc,https://docker.udayun.com,https://hub.rat.dev
diff --git a/base/README.md b/base/README.md
new file mode 100644
index 0000000..424c765
--- /dev/null
+++ b/base/README.md
@@ -0,0 +1,72 @@
+# 服务器基础环境
+
+公共基础设施脚本，提供以下功能：
+
+- **系统初始化**：安装常用工具、设置时区
+- **Docker 安装**：使用阿里云镜像源，配置国内加速
+- **Nginx 安装**：反向代理服务器，统一管理 HTTPS
+- **Certbot 安装**：Let's Encrypt SSL 证书自动申请与续期
+- **防火墙配置**：开放 SSH / HTTP / HTTPS 端口
+
+## 设计理念
+
+- **幂等性**：每个安装步骤都会先检查是否已安装，避免重复操作
+- **可复用**：既可以独立运行，也可以被其他服务的部署脚本 `source` 调用
+- **国内优化**：Docker 使用阿里云 APT 源安装，镜像拉取使用国内加速
+
+## 使用方式
+
+### 方式一：独立运行（安装全部基础环境）
+
+```bash
+# 上传到服务器
+scp -r base/ root@<服务器IP>:/opt/base
+
+# 登录服务器执行
+cd /opt/base
+cp .env.example .env
+# 编辑 .env 配置 Docker 镜像加速（可选）
+bash setup.sh
+```
+
+### 方式二：被其他服务脚本调用
+
+```bash
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BASE_DIR="$(cd "$SCRIPT_DIR/../base" && pwd)"
+source "$BASE_DIR/setup.sh"
+
+# 现在可以使用 base 提供的所有函数
+check_root
+init_system
+install_docker
+install_nginx
+# ...
+```
+
+## 提供的函数
+
+| 函数 | 说明 |
+|------|------|
+| `check_root` | 检查是否 root 用户 |
+| `init_system` | 系统初始化，安装基础工具 |
+| `install_docker` | 安装 Docker + Compose V2 |
+| `configure_docker_mirrors` | 配置 Docker 镜像加速 |
+| `install_nginx` | 安装配置 Nginx |
+| `install_certbot` | 安装 Certbot |
+| `setup_firewall_base` | 开放 22/80/443 端口 |
+| `firewall_allow_port <port> [desc]` | 开放额外端口 |
+| `setup_ssl_cert <domain> <email> [name]` | 申请 SSL 证书 |
+| `deploy_nginx_conf <template> <domain> <name>` | 部署 Nginx 反向代理配置 |
+| `load_base_env [dir]` | 加载 base/.env |
+
+## 目录结构
+
+```
+base/
+├── setup.sh          # 主脚本（函数库 + 独立运行入口）
+├── .env.example      # 配置模板
+├── .env              # 实际配置（从 .env.example 复制）
+└── README.md         # 本文件
+```
diff --git a/base/setup.sh b/base/setup.sh
new file mode 100644
index 0000000..0641852
--- /dev/null
+++ b/base/setup.sh
@@ -0,0 +1,395 @@
+#!/usr/bin/env bash
+
+# ============================================
+# 服务器基础环境安装脚本（公共依赖）
+# 安装: 系统工具 + Docker + Nginx + Certbot + 防火墙
+# 可独立运行，也可被其他部署脚本 source 调用
+# ============================================
+
+# 避免重复 source
+if [ -n "$_BASE_SETUP_LOADED" ]; then
+    return 0 2>/dev/null || true
+fi
+_BASE_SETUP_LOADED=1
+
+# ===== 终端颜色 =====
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+log()   { echo -e "${GREEN}[INFO]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[WARN]${NC} $*"; }
+error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+step()  { echo -e "\n${CYAN}========== $* ==========${NC}"; }
+
+# ===== 检查 root =====
+check_root() {
+    if [ "$(id -u)" -ne 0 ]; then
+        error "请使用 root 用户运行此脚本: sudo bash $0"
+        exit 1
+    fi
+}
+
+# ===== 检测包管理器 =====
+detect_pkg_mgr() {
+    if [ -n "${PKG_MGR:-}" ]; then
+        return
+    fi
+    if command -v apt-get &> /dev/null; then
+        PKG_MGR="apt"
+    elif command -v dnf &> /dev/null; then
+        PKG_MGR="dnf"
+    elif command -v yum &> /dev/null; then
+        PKG_MGR="yum"
+    else
+        error "不支持的系统，需要 apt/dnf/yum 包管理器"
+        exit 1
+    fi
+}
+
+# ===== 系统初始化 =====
+init_system() {
+    step "系统初始化"
+    detect_pkg_mgr
+    log "检测到包管理器: $PKG_MGR"
+    log "正在更新系统软件包..."
+
+    case "$PKG_MGR" in
+        apt)
+            export DEBIAN_FRONTEND=noninteractive
+            apt-get update -qq
+            apt-get upgrade -y -qq
+            apt-get install -y -qq curl wget git gnupg2 ca-certificates \
+                lsb-release software-properties-common openssl cron
+            ;;
+        dnf|yum)
+            $PKG_MGR update -y -q
+            $PKG_MGR install -y -q curl wget git gnupg2 ca-certificates openssl cronie
+            ;;
+    esac
+
+    if [ ! -f /etc/timezone ] || [ "$(cat /etc/timezone 2>/dev/null)" != "Asia/Shanghai" ]; then
+        timedatectl set-timezone Asia/Shanghai 2>/dev/null || true
+        log "时区已设置为 Asia/Shanghai"
+    fi
+
+    log "系统初始化完成"
+}
+
+# ===== 安装 Docker =====
+install_docker() {
+    step "安装 Docker"
+
+    if command -v docker &> /dev/null; then
+        log "Docker 已安装: $(docker --version)"
+    else
+        detect_pkg_mgr
+        log "正在安装 Docker (使用阿里云镜像)..."
+
+        case "$PKG_MGR" in
+            apt)
+                curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg \
+                    | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+                echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
+                    https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" \
+                    > /etc/apt/sources.list.d/docker.list
+                apt-get update -qq
+                apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-compose-plugin
+                ;;
+            dnf)
+                dnf config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
+                dnf install -y -q docker-ce docker-ce-cli containerd.io docker-compose-plugin
+                ;;
+            yum)
+                yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
+                yum install -y -q docker-ce docker-ce-cli containerd.io docker-compose-plugin
+                ;;
+        esac
+        log "Docker 安装完成: $(docker --version)"
+    fi
+
+    systemctl enable --now docker
+    log "Docker 服务已启动"
+
+    if ! docker compose version &> /dev/null; then
+        error "Docker Compose V2 不可用"
+        error "请手动安装: apt install docker-compose-plugin"
+        exit 1
+    fi
+    log "Docker Compose 已就绪: $(docker compose version --short)"
+}
+
+# ===== 配置 Docker 镜像加速 =====
+configure_docker_mirrors() {
+    local mirrors="${DOCKER_REGISTRY_MIRRORS:-}"
+    if [ -z "$mirrors" ]; then
+        log "未配置 DOCKER_REGISTRY_MIRRORS，跳过镜像加速"
+        return
+    fi
+
+    mkdir -p /etc/docker
+
+    local json_array
+    json_array=$(echo "$mirrors" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
+        | grep -v '^$' | awk '{printf "\"%s\",", $0}' | sed 's/,$//')
+
+    local need_restart=0
+    if [ -f /etc/docker/daemon.json ]; then
+        if ! grep -q "registry-mirrors" /etc/docker/daemon.json; then
+            need_restart=1
+        fi
+    else
+        need_restart=1
+    fi
+
+    if [ "$need_restart" -eq 1 ]; then
+        cat > /etc/docker/daemon.json <<EOF
+{
+    "registry-mirrors": [${json_array}],
+    "log-driver": "json-file",
+    "log-opts": {
+        "max-size": "10m",
+        "max-file": "3"
+    }
+}
+EOF
+        log "Docker 镜像加速已配置:"
+        echo "$mirrors" | tr ',' '\n' | sed 's/^/  → /'
+        systemctl restart docker
+        log "Docker 已重启以应用镜像加速"
+    else
+        log "Docker 镜像加速已存在，跳过"
+    fi
+}
+
+# ===== 安装 Nginx =====
+install_nginx() {
+    step "安装 Nginx"
+    detect_pkg_mgr
+
+    if command -v nginx &> /dev/null; then
+        log "Nginx 已安装: $(nginx -v 2>&1)"
+    else
+        log "正在安装 Nginx..."
+        case "$PKG_MGR" in
+            apt) apt-get install -y -qq nginx ;;
+            dnf|yum) $PKG_MGR install -y -q nginx ;;
+        esac
+        log "Nginx 安装完成"
+    fi
+
+    systemctl enable --now nginx
+
+    mkdir -p /etc/nginx/sites-available /etc/nginx/sites-enabled /var/www/certbot
+
+    if ! grep -q "sites-enabled" /etc/nginx/nginx.conf; then
+        sed -i '/^http {/a \    include /etc/nginx/sites-enabled/*;' /etc/nginx/nginx.conf
+    fi
+
+    log "Nginx 配置就绪"
+}
+
+# ===== 安装 Certbot =====
+install_certbot() {
+    detect_pkg_mgr
+
+    if command -v certbot &> /dev/null; then
+        log "Certbot 已安装: $(certbot --version 2>&1)"
+        return
+    fi
+
+    log "正在安装 Certbot..."
+    case "$PKG_MGR" in
+        apt) apt-get install -y -qq certbot python3-certbot-nginx ;;
+        dnf) dnf install -y -q certbot python3-certbot-nginx ;;
+        yum) yum install -y -q certbot python3-certbot-nginx ;;
+    esac
+    log "Certbot 安装完成"
+}
+
+# ===== 配置防火墙（基础端口）=====
+setup_firewall_base() {
+    step "配置防火墙（基础端口）"
+
+    if command -v ufw &> /dev/null; then
+        ufw --force enable 2>/dev/null || true
+        ufw allow ssh       comment "SSH"   2>/dev/null || true
+        ufw allow 80/tcp    comment "HTTP"  2>/dev/null || true
+        ufw allow 443/tcp   comment "HTTPS" 2>/dev/null || true
+        ufw reload 2>/dev/null || true
+        log "UFW 防火墙规则已添加 (22, 80, 443)"
+    elif command -v firewall-cmd &> /dev/null; then
+        systemctl enable --now firewalld 2>/dev/null || true
+        firewall-cmd --permanent --add-service=ssh   2>/dev/null || true
+        firewall-cmd --permanent --add-service=http  2>/dev/null || true
+        firewall-cmd --permanent --add-service=https 2>/dev/null || true
+        firewall-cmd --reload 2>/dev/null || true
+        log "Firewalld 规则已添加 (22, 80, 443)"
+    else
+        warn "未检测到防火墙工具，请手动开放端口: 22, 80, 443"
+    fi
+}
+
+# ===== 开放额外端口 =====
+# 用法: firewall_allow_port <端口> [描述]
+firewall_allow_port() {
+    local port="$1"
+    local comment="${2:-Custom}"
+
+    if command -v ufw &> /dev/null; then
+        ufw allow "$port"/tcp comment "$comment" 2>/dev/null || true
+        ufw reload 2>/dev/null || true
+    elif command -v firewall-cmd &> /dev/null; then
+        firewall-cmd --permanent --add-port="$port"/tcp 2>/dev/null || true
+        firewall-cmd --reload 2>/dev/null || true
+    fi
+    log "已开放端口: $port ($comment)"
+}
+
+# ===== 申请 SSL 证书 =====
+# 用法: setup_ssl_cert <域名> <邮箱> [站点名称]
+setup_ssl_cert() {
+    local domain="$1"
+    local email="$2"
+    local site_name="${3:-$domain}"
+
+    step "配置 SSL 证书: ${domain}"
+
+    install_certbot
+
+    # 部署临时 Nginx 配置（仅 HTTP，用于 ACME 验证）
+    cat > "/etc/nginx/sites-available/${site_name}" <<NGINX_TEMP
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${domain};
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 200 'Service is being configured...';
+        add_header Content-Type text/plain;
+    }
+}
+NGINX_TEMP
+
+    ln -sf "/etc/nginx/sites-available/${site_name}" "/etc/nginx/sites-enabled/${site_name}"
+    rm -f /etc/nginx/sites-enabled/default
+    nginx -t && systemctl reload nginx
+
+    # 申请证书
+    if [ ! -d "/etc/letsencrypt/live/${domain}" ]; then
+        log "正在申请 SSL 证书: ${domain} ..."
+        if ! certbot certonly --webroot \
+            -w /var/www/certbot \
+            -d "${domain}" \
+            --email "${email}" \
+            --agree-tos \
+            --non-interactive \
+            --no-eff-email; then
+            error "SSL 证书申请失败！"
+            error "请确认："
+            error "  1. 域名 ${domain} 已解析到本服务器 IP"
+            error "  2. 服务器 80 端口可从外网访问"
+            exit 1
+        fi
+        log "SSL 证书申请成功"
+    else
+        log "SSL 证书已存在，跳过申请"
+    fi
+
+    # 配置自动续期
+    if ! crontab -l 2>/dev/null | grep -q "certbot renew"; then
+        (crontab -l 2>/dev/null; echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload nginx'") | crontab -
+        log "已配置 SSL 证书自动续期 (每天 03:00 检查)"
+    fi
+}
+
+# ===== 部署 Nginx 配置 =====
+# 用法: deploy_nginx_conf <模板路径> <域名> <站点名称>
+# 模板中使用 __DOMAIN__ 作为域名占位符
+deploy_nginx_conf() {
+    local template="$1"
+    local domain="$2"
+    local site_name="$3"
+
+    if [ ! -f "$template" ]; then
+        error "Nginx 配置模板不存在: $template"
+        exit 1
+    fi
+
+    cp "$template" "/etc/nginx/sites-available/${site_name}"
+    sed -i "s/__DOMAIN__/${domain}/g" "/etc/nginx/sites-available/${site_name}"
+
+    ln -sf "/etc/nginx/sites-available/${site_name}" "/etc/nginx/sites-enabled/${site_name}"
+
+    nginx -t
+    systemctl reload nginx
+    log "Nginx 反向代理配置已部署: ${site_name} → ${domain}"
+}
+
+# ===== 加载 base .env =====
+load_base_env() {
+    local base_dir="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)}"
+    if [ -f "$base_dir/.env" ]; then
+        set -a
+        source "$base_dir/.env"
+        set +a
+    fi
+}
+
+# =============================================================
+#  独立运行模式：直接安装全部基础环境
+# =============================================================
+_base_main() {
+    echo -e "${CYAN}"
+    echo "  ____"
+    echo " | __ )  __ _ ___  ___"
+    echo " |  _ \\ / _\` / __|/ _ \\"
+    echo " | |_) | (_| \\__ \\  __/"
+    echo " |____/ \\__,_|___/\\___|  Server Base Setup"
+    echo -e "${NC}"
+    echo ""
+
+    check_root
+
+    local base_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+    # 加载 .env
+    if [ -f "$base_dir/.env" ]; then
+        set -a; source "$base_dir/.env"; set +a
+    elif [ -f "$base_dir/.env.example" ]; then
+        cp "$base_dir/.env.example" "$base_dir/.env"
+        set -a; source "$base_dir/.env"; set +a
+        log "已从 .env.example 生成 .env"
+    fi
+
+    init_system
+    install_docker
+    configure_docker_mirrors
+    install_nginx
+    install_certbot
+    setup_firewall_base
+
+    echo ""
+    log "===== 基础环境安装完成 ====="
+    log "已安装: Docker $(docker --version 2>/dev/null | grep -o '[0-9.]*' | head -1)"
+    log "已安装: Docker Compose $(docker compose version --short 2>/dev/null)"
+    log "已安装: Nginx $(nginx -v 2>&1 | grep -o '[0-9.]*')"
+    log "已安装: Certbot $(certbot --version 2>&1 | grep -o '[0-9.]*')"
+    echo ""
+    log "接下来可以部署各服务:"
+    log "  Gitea:       cd /opt/gitea && bash deploy.sh"
+    log "  Certd:       cd /opt/certd && bash deploy.sh"
+    log "  Vaultwarden: cd /opt/vaultwarden && bash deploy.sh"
+}
+
+# 仅直接运行时执行 main，被 source 时只加载函数
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    set -euo pipefail
+    _base_main "$@"
+fi
diff --git a/certd/.env.example b/certd/.env.example
new file mode 100644
index 0000000..29f4faf
--- /dev/null
+++ b/certd/.env.example
@@ -0,0 +1,29 @@
+# ===== Certd 基础配置 =====
+
+# Certd 访问域名（必须修改）
+CERTD_DOMAIN=cert.example.com
+
+# Let's Encrypt 邮箱（必须修改）
+CERTBOT_EMAIL=admin@example.com
+
+# ===== 镜像配置 =====
+
+# Certd 镜像（阿里云镜像，国内速度快）
+CERTD_IMAGE=registry.cn-shenzhen.aliyuncs.com/handsfree/certd:latest
+# 备选 Docker Hub 镜像：
+# CERTD_IMAGE=greper/certd:latest
+# 备选 GitHub Packages 镜像：
+# CERTD_IMAGE=ghcr.io/certd/certd:latest
+
+# ===== 目录配置 =====
+
+# Certd 数据目录（SQLite 数据库 + 证书文件）
+CERTD_DATA_DIR=/data/certd
+
+# 备份目录
+BACKUP_DIR=/var/backups/certd
+
+# ===== 高级设置 =====
+
+# 重置管理员密码（设为 true 重启后生效，然后改回 false）
+RESET_ADMIN_PASSWD=false
diff --git a/certd/README.md b/certd/README.md
new file mode 100644
index 0000000..53f4904
--- /dev/null
+++ b/certd/README.md
@@ -0,0 +1,282 @@
+# Certd 部署指南
+
+SSL 证书自动化管理工具，支持自动申请、部署和续期 Let's Encrypt / 各种商用证书。
+
+## 功能特性
+
+- 自动申请 Let's Encrypt 免费 SSL 证书
+- 支持阿里云、腾讯云、Cloudflare 等多种 DNS 提供商
+- 自动部署证书到 Nginx、CDN、OSS 等
+- 到期自动续期，无需人工干预
+- Web 管理界面，可视化操作
+
+## 技术栈
+
+| 组件 | 版本 | 说明 |
+|------|------|------|
+| Certd | latest | SSL 证书自动化工具 |
+| SQLite | 内置 | 轻量数据库，无需额外部署 |
+| Nginx | 系统包 | 反向代理 + HTTPS 接入 |
+| Docker | 最新版 | 容器运行环境 |
+
+## 前置条件
+
+1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
+2. 一个已解析到服务器的域名（如 `cert.example.com`）
+3. 服务器 80/443 端口可从外网访问
+
+## 目录结构
+
+```
+certd/
+├── docker-compose.yml    # 容器编排
+├── .env.example          # 配置模板
+├── deploy.sh             # 一键部署脚本
+├── backup.sh             # 备份脚本
+├── nginx/
+│   └── certd.conf        # Nginx 反向代理配置
+└── README.md             # 本文件
+```
+
+服务器上的数据目录：
+
+```
+/data/certd/              # Certd 数据（SQLite + 证书文件）
+/var/backups/certd/       # 备份文件
+```
+
+## 快速部署
+
+### 第一步：上传文件到服务器
+
+```bash
+# 在本地执行，上传 base 和 certd 目录
+scp -r base/ certd/ root@<服务器IP>:/opt/
+```
+
+### 第二步：登录服务器执行部署
+
+```bash
+ssh root@<服务器IP>
+
+# 如果是全新服务器，先安装基础环境
+cd /opt/base
+cp .env.example .env
+# 可选：编辑 .env 配置 Docker 镜像加速
+bash setup.sh
+
+# 部署 Certd
+cd /opt/certd
+bash deploy.sh
+# 首次运行会生成 .env，按提示修改配置后重新运行
+vi .env
+bash deploy.sh
+```
+
+### 第三步：配置域名解析
+
+在域名服务商（如阿里云 DNS）添加 A 记录：
+
+| 记录类型 | 主机记录 | 记录值 |
+|----------|----------|--------|
+| A | cert | `<服务器公网IP>` |
+
+### 第四步：登录管理后台
+
+1. 浏览器访问 `https://cert.yourdomain.com`
+2. 默认账号: `admin`
+3. 默认密码: `123456`
+
+> **⚠️ 安全提醒：请立即修改默认密码！**
+
+## 配置说明
+
+### .env 配置项
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CERTD_DOMAIN` | 访问域名 | 必填 |
+| `CERTBOT_EMAIL` | Let's Encrypt 邮箱 | 必填 |
+| `CERTD_IMAGE` | Docker 镜像 | 阿里云镜像 |
+| `CERTD_DATA_DIR` | 数据目录 | `/data/certd` |
+| `BACKUP_DIR` | 备份目录 | `/var/backups/certd` |
+| `RESET_ADMIN_PASSWD` | 重置管理员密码 | `false` |
+
+### 重置管理员密码
+
+如果忘记管理员密码：
+
+```bash
+cd /opt/certd
+
+# 1. 修改 .env，设置 RESET_ADMIN_PASSWD=true
+vi .env
+
+# 2. 重新创建容器（restart 不会重新读取 .env，必须用 up -d）
+docker compose up -d
+
+# 3. 查看日志确认重置完成（出现"重置1号管理员用户密码完成"即可）
+docker logs -f --tail 100 certd
+
+# 4. 用默认密码 123456 登录（用户名为原管理员账号，如修改过请查看上一步日志）
+
+# 5. 改回 RESET_ADMIN_PASSWD=false 并重新创建容器
+vi .env
+docker compose up -d
+```
+
+## 日常运维
+
+### 查看日志
+
+```bash
+cd /opt/certd
+docker compose logs -f
+docker compose logs --tail 100
+```
+
+### 备份
+
+```bash
+cd /opt/certd
+bash backup.sh
+```
+
+备份内容包括：
+- SQLite 数据库 + 证书文件（`/data/certd`）
+- 部署配置（`docker-compose.yml` + `.env` + `nginx/`）
+
+备份文件保存在 `/var/backups/certd/`，自动清理 30 天前的旧备份。
+
+> **提示**：Certd 还内置了自动备份流水线功能，可在管理界面中配置定时备份和失败通知，详见「安全加固建议」章节。
+
+### 恢复备份
+
+```bash
+# 查看可用备份
+ls /var/backups/certd/
+
+# 停止服务
+cd /opt/certd && docker compose down
+
+# 恢复数据
+tar xzf /var/backups/certd/<日期>/certd-data.tar.gz -C /data/
+
+# 重启服务
+cd /opt/certd && docker compose up -d
+```
+
+### 升级
+
+```bash
+cd /opt/certd
+
+# 1. 备份当前数据
+bash backup.sh
+
+# 2. 拉取新镜像
+docker compose pull
+
+# 3. 停止旧容器并启动新容器
+docker compose down
+docker compose up -d
+
+# 4. 检查运行状态
+docker compose ps
+docker compose logs --tail 20
+```
+
+### 停止 / 启动
+
+```bash
+cd /opt/certd
+docker compose down      # 停止
+docker compose up -d     # 启动
+docker compose restart   # 重启
+```
+
+## 使用 Certd 管理证书
+
+### 添加 DNS 授权
+
+1. 登录 Certd 管理后台
+2. 进入「授权管理」→「新增」
+3. 选择 DNS 提供商（如阿里云）
+4. 填入 AccessKey ID / Secret
+
+### 创建证书流水线
+
+1. 进入「证书管理」→「新增流水线」
+2. 选择「Let's Encrypt」证书颁发机构
+3. 填写要申请的域名（如 `*.example.com`）
+4. 选择 DNS 授权方式
+5. 配置部署目标（Nginx、CDN 等）
+6. 点击「运行」
+
+### 自动续期
+
+Certd 会自动检查证书过期时间，在到期前自动续期并部署。默认检查间隔为每天一次。
+
+## 安全加固建议
+
+### 1. 修改管理员用户名
+
+官方强烈建议修改默认的 `admin` 用户名。登录后前往「系统管理」→「用户管理」修改管理员账号的用户名，并建议注册一个名为 `admin` 的普通用户并设为禁用，防止被暴力破解。
+
+### 2. 开启站点隐藏
+
+Certd 设置好后日常很少需要访问，建议平时关闭站点访问入口，减少被攻击风险。前往「系统管理」→「系统设置」→「安全设置」→ 开启站点隐藏。
+
+### 3. 启用 2FA 双重验证
+
+Certd 支持 2FA 双重认证登录，建议在「个人设置」中开启。
+
+### 4. 配置自动备份流水线
+
+Certd 内置数据库自动备份功能。在管理界面中创建一个备份流水线，选择「数据库备份」任务，配置定时执行和失败通知，确保数据安全。详见[官方备份文档](https://certd.docmirror.cn/guide/use/backup/)。
+
+## 故障排查
+
+### 容器无法启动
+
+```bash
+# 查看容器状态
+docker compose ps
+
+# 查看详细日志
+docker compose logs --tail 50
+```
+
+### SSL 证书申请失败
+
+```bash
+# 检查域名解析是否正确
+dig cert.yourdomain.com
+
+# 检查 80 端口是否可访问
+curl -I http://cert.yourdomain.com
+
+# 查看 Certbot 日志
+cat /var/log/letsencrypt/letsencrypt.log
+```
+
+### 访问返回 502
+
+```bash
+# 检查 Certd 容器是否运行
+docker compose ps
+
+# 检查 7001 端口
+curl -I http://127.0.0.1:7001
+
+# 检查 Nginx 配置
+nginx -t
+```
+
+## 端口说明
+
+| 端口 | 协议 | 说明 |
+|------|------|------|
+| 80 | TCP | HTTP → HTTPS 重定向 |
+| 443 | TCP | HTTPS（Nginx 反向代理） |
+| 7001 | TCP | Certd HTTP（仅监听 127.0.0.1） |
diff --git a/certd/backup.sh b/certd/backup.sh
new file mode 100644
index 0000000..c04b3c6
--- /dev/null
+++ b/certd/backup.sh
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Certd 备份脚本
+# 备份 SQLite 数据库 + 配置文件
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# 加载配置
+if [ -f .env ]; then
+    set -a; source .env; set +a
+else
+    echo "[ERROR] .env 文件不存在，请先运行 deploy.sh" >&2
+    exit 1
+fi
+
+# ===== 配置 =====
+DATA_DIR="${CERTD_DATA_DIR:-/data/certd}"
+BACKUP_BASE="${BACKUP_DIR:-/var/backups/certd}"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR_FULL="${BACKUP_BASE}/${TIMESTAMP}"
+RETENTION_DAYS=30
+
+echo "========== Certd 备份 =========="
+echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+echo "数据目录: $DATA_DIR"
+echo "备份目录: $BACKUP_DIR_FULL"
+echo ""
+
+mkdir -p "$BACKUP_DIR_FULL"
+
+# ===== 备份数据目录（SQLite + 证书 + 配置）=====
+echo "[1/3] 备份 Certd 数据..."
+if [ -d "$DATA_DIR" ]; then
+    tar czf "$BACKUP_DIR_FULL/certd-data.tar.gz" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")"
+    echo "  ✓ 数据目录已备份"
+else
+    echo "  ⚠ 数据目录不存在: $DATA_DIR"
+fi
+
+# ===== 备份 docker-compose 和配置 =====
+echo "[2/3] 备份部署配置..."
+tar czf "$BACKUP_DIR_FULL/certd-config.tar.gz" \
+    -C "$SCRIPT_DIR" \
+    docker-compose.yml .env nginx/ 2>/dev/null || true
+echo "  ✓ 配置已备份"
+
+# ===== 清理旧备份 =====
+echo "[3/3] 清理 ${RETENTION_DAYS} 天前的旧备份..."
+find "$BACKUP_BASE" -maxdepth 1 -type d -mtime +${RETENTION_DAYS} -exec rm -rf {} \; 2>/dev/null || true
+echo "  ✓ 旧备份已清理"
+
+# ===== 汇总 =====
+echo ""
+echo "========== 备份完成 =========="
+TOTAL_SIZE=$(du -sh "$BACKUP_DIR_FULL" | cut -f1)
+echo "备份位置: $BACKUP_DIR_FULL"
+echo "备份大小: $TOTAL_SIZE"
+echo ""
+echo "备份内容:"
+ls -lh "$BACKUP_DIR_FULL/"
+echo ""
+echo "恢复方法:"
+echo "  tar xzf $BACKUP_DIR_FULL/certd-data.tar.gz -C $(dirname "$DATA_DIR")"
+echo "  cd $SCRIPT_DIR && docker compose restart"
diff --git a/certd/deploy.sh b/certd/deploy.sh
new file mode 100644
index 0000000..ff6acf0
--- /dev/null
+++ b/certd/deploy.sh
@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Certd 一键部署脚本
+# 自动安装 Docker + Nginx + SSL + Certd
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ===== 加载公共基础函数 =====
+BASE_DIR="$(cd "$SCRIPT_DIR/../base" 2>/dev/null && pwd)" || true
+if [ -z "$BASE_DIR" ] || [ ! -f "$BASE_DIR/setup.sh" ]; then
+    echo "[ERROR] base/setup.sh 未找到" >&2
+    echo "请确保目录结构如下:" >&2
+    echo "  /opt/base/setup.sh" >&2
+    echo "  /opt/certd/deploy.sh  (当前脚本)" >&2
+    exit 1
+fi
+source "$BASE_DIR/setup.sh"
+
+# =============================================================
+#  Certd 专用函数
+# =============================================================
+
+init_env() {
+    step "初始化 Certd 配置"
+
+    if [ ! -f .env ]; then
+        if [ ! -f .env.example ]; then
+            error "缺少 .env.example 模板文件"
+            exit 1
+        fi
+        cp .env.example .env
+        log "已生成 .env 文件"
+        echo ""
+        warn "┌─────────────────────────────────────────────────┐"
+        warn "│  请编辑 .env 文件，至少修改以下配置：              │"
+        warn "│                                                 │"
+        warn "│  CERTD_DOMAIN=cert.yourdomain.com               │"
+        warn "│  CERTBOT_EMAIL=you@yourdomain.com               │"
+        warn "│                                                 │"
+        warn "│  编辑命令: vi $SCRIPT_DIR/.env                  │"
+        warn "│  编辑完成后重新运行: bash deploy.sh              │"
+        warn "└─────────────────────────────────────────────────┘"
+        exit 0
+    fi
+
+    set -a; source .env; set +a
+
+    local has_error=0
+    if [[ -z "${CERTD_DOMAIN:-}" ]] || [[ "${CERTD_DOMAIN}" == "cert.example.com" ]]; then
+        error "请在 .env 中将 CERTD_DOMAIN 修改为你的实际域名"
+        has_error=1
+    fi
+    if [[ -z "${CERTBOT_EMAIL:-}" ]] || [[ "${CERTBOT_EMAIL}" == "admin@example.com" ]]; then
+        error "请在 .env 中将 CERTBOT_EMAIL 修改为你的实际邮箱"
+        has_error=1
+    fi
+    [ "$has_error" -eq 1 ] && { error "请修改 .env 后重新运行"; exit 1; }
+
+    log "配置检查通过"
+    log "  域名: ${CERTD_DOMAIN}"
+    log "  邮箱: ${CERTBOT_EMAIL}"
+}
+
+create_dirs() {
+    step "创建数据目录"
+    local data_dir="${CERTD_DATA_DIR:-/data/certd}"
+    local backup_dir="${BACKUP_DIR:-/var/backups/certd}"
+
+    mkdir -p "$data_dir" "$backup_dir"
+    log "数据目录: $data_dir"
+    log "备份目录: $backup_dir"
+}
+
+start_services() {
+    step "启动 Certd 服务"
+
+    log "正在拉取镜像..."
+    docker compose pull
+
+    log "正在启动容器..."
+    docker compose up -d
+
+    log "等待 Certd 就绪..."
+    local max_wait=30
+    for i in $(seq 1 "$max_wait"); do
+        if curl -sf http://127.0.0.1:7001/ &> /dev/null; then
+            log "Certd 启动成功！"
+            return
+        fi
+        sleep 2
+    done
+    warn "Certd 可能仍在启动中，请稍后检查: docker compose logs -f"
+}
+
+show_info() {
+    set -a; source .env; set +a
+
+    echo ""
+    echo -e "${GREEN}╔══════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${GREEN}║                Certd 部署完成！                          ║${NC}"
+    echo -e "${GREEN}╠══════════════════════════════════════════════════════════╣${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  Web 访问:  ${CYAN}https://${CERTD_DOMAIN}${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  默认账号:  ${CYAN}admin${NC}"
+    echo -e "${GREEN}║${NC}  默认密码:  ${CYAN}123456${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  数据目录:  ${CERTD_DATA_DIR:-/data/certd}"
+    echo -e "${GREEN}║${NC}  备份目录:  ${BACKUP_DIR:-/var/backups/certd}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  ${RED}⚠ 请立即登录并修改默认密码！${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}╚══════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    echo "常用命令:"
+    echo "  查看日志:    cd $SCRIPT_DIR && docker compose logs -f"
+    echo "  重启服务:    cd $SCRIPT_DIR && docker compose restart"
+    echo "  停止服务:    cd $SCRIPT_DIR && docker compose down"
+    echo "  备份数据:    cd $SCRIPT_DIR && bash backup.sh"
+    echo ""
+}
+
+# =============================================================
+#  主流程
+# =============================================================
+main() {
+    echo -e "${CYAN}"
+    echo "   ____          _      _"
+    echo "  / ___|___ _ __| |_ __| |"
+    echo " | |   / _ \\ '__| __/ _\` |"
+    echo " | |__|  __/ |  | || (_| |"
+    echo "  \\____\\___|_|   \\__\\__,_|  Deploy Script"
+    echo -e "${NC}"
+    echo ""
+
+    check_root
+    load_base_env "$BASE_DIR"
+
+    # Step 1: 系统初始化
+    init_system
+
+    # Step 2: 安装 Docker
+    install_docker
+
+    # Step 3: 安装 Nginx
+    install_nginx
+
+    # Step 4: 初始化配置
+    init_env
+
+    # Step 5: 配置 Docker 镜像加速
+    configure_docker_mirrors
+
+    # Step 6: 创建数据目录
+    create_dirs
+
+    # Step 7: 配置防火墙
+    setup_firewall_base
+
+    # Step 8: 配置 SSL 证书
+    setup_ssl_cert "${CERTD_DOMAIN}" "${CERTBOT_EMAIL}" "certd"
+
+    # Step 9: 部署 Nginx 反向代理
+    deploy_nginx_conf "$SCRIPT_DIR/nginx/certd.conf" "${CERTD_DOMAIN}" "certd"
+
+    # Step 10: 启动服务
+    start_services
+
+    # 显示部署信息
+    show_info
+    log "===== Certd 部署完成 ====="
+}
+
+main "$@"
diff --git a/certd/docker-compose.yml b/certd/docker-compose.yml
new file mode 100644
index 0000000..1b4a313
--- /dev/null
+++ b/certd/docker-compose.yml
@@ -0,0 +1,29 @@
+services:
+  certd:
+    image: ${CERTD_IMAGE:-registry.cn-shenzhen.aliyuncs.com/handsfree/certd:latest}
+    container_name: certd
+    restart: unless-stopped
+    environment:
+      - TZ=Asia/Shanghai
+      - certd_system_resetAdminPasswd=${RESET_ADMIN_PASSWD:-false}
+      - certd_koa_hostname=0.0.0.0
+    volumes:
+      # ⚠ 冒号后面的 /app/data 切记不要修改，只改冒号前面的宿主机路径
+      - ${CERTD_DATA_DIR:-/data/certd}:/app/data
+      - /etc/localtime:/etc/localtime:ro
+    ports:
+      - "127.0.0.1:7001:7001"
+    dns:
+      - 223.5.5.5
+      - 8.8.8.8
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:7001"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
diff --git a/certd/nginx/certd.conf b/certd/nginx/certd.conf
new file mode 100644
index 0000000..bf4a2d6
--- /dev/null
+++ b/certd/nginx/certd.conf
@@ -0,0 +1,55 @@
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __DOMAIN__;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name __DOMAIN__;
+
+    # SSL 证书
+    ssl_certificate     /etc/letsencrypt/live/__DOMAIN__/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/__DOMAIN__/privkey.pem;
+
+    # SSL 参数
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    # 安全头
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    # 反向代理到 Certd
+    location / {
+        proxy_pass http://127.0.0.1:7001;
+        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;
+
+        # WebSocket 支持
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        # 超时设置
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+}
diff --git a/gitea/README.md b/gitea/README.md
index 52e7d4a..99a816b 100644
--- a/gitea/README.md
+++ b/gitea/README.md
@@ -22,7 +22,7 @@
 | 组件 | 版本 | 说明 |
 |------|------|------|
 | Gitea | 1.25 | Git 托管服务（含内置 SSH 服务器） |
-| MySQL | 8.0 | 数据库（utf8mb4） |
+| MySQL | 8.4 LTS | 数据库（utf8mb4） |
 | Nginx | 系统包 | HTTPS 反向代理 |
 | Certbot | 系统包 | Let's Encrypt 自动 SSL 证书 |
 | Docker | 最新 | 容器运行时 |
@@ -158,29 +158,126 @@ git clone ssh://git@git.yourdomain.com:2222/用户名/仓库.git
 
 ### GPG 签名提交
 
+#### 步骤 1：确认 GPG 可用
+
+**macOS / Linux：**
+
 ```bash
-# 1. 生成 GPG 密钥
-gpg --full-generate-key
-# 选择 RSA and RSA → 4096 → 填写名字和邮箱
-
-# 2. 查看密钥 ID
-gpg --list-secret-keys --keyid-format=long
-# 输出中 sec 行的 XXXXXXXXXXXXXXXX 就是密钥 ID
-
-# 3. 导出公钥
-gpg --armor --export XXXXXXXXXXXXXXXX
-
-# 4. 在 Gitea 中添加
-#    → 头像 → 设置 → SSH/GPG 密钥 → 添加 GPG 密钥 → 粘贴公钥
-
-# 5. 配置 Git 使用 GPG 签名
-git config --global user.signingkey XXXXXXXXXXXXXXXX
-git config --global commit.gpgsign true
-
-# 6. 签名提交（之后所有 commit 自动签名）
-git commit -S -m "signed commit"
+gpg --version
 ```
 
+如未安装：
+- macOS: `brew install gnupg`
+- Ubuntu/Debian: `sudo apt-get install gnupg`
+
+**Windows：**
+
+Windows 系统默认**没有** `gpg` 命令。推荐使用 Git for Windows 自带的 GPG（无需额外安装）：
+
+```powershell
+# 确认 Git 自带的 GPG 可用
+& "C:\Program Files\Git\usr\bin\gpg.exe" --version
+# 输出类似: gpg (GnuPG) 2.4.x
+```
+
+**将 GPG 加入系统 PATH（推荐，这样可以直接使用 `gpg` 命令）：**
+
+```powershell
+# 将 Git 自带的 GPG 目录添加到用户 PATH（永久生效，需重启终端）
+$gpgDir = "C:\Program Files\Git\usr\bin"
+$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($userPath -notlike "*$gpgDir*") {
+    [Environment]::SetEnvironmentVariable("Path", "$userPath;$gpgDir", "User")
+    Write-Host "已添加到 PATH，请重启终端后生效"
+}
+
+# 重启终端后验证
+gpg --version
+```
+
+> 也可以通过 **系统设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 用户变量 → Path → 编辑**，手动添加 `C:\Program Files\Git\usr\bin`。
+
+**配置 Git 使用该 GPG（必须，否则 `git commit -S` 会报错）：**
+
+```powershell
+git config --global gpg.program "C:\Program Files\Git\usr\bin\gpg.exe"
+```
+
+> 也可以安装 [Gpg4win](https://www.gpg4win.org/)，安装后 `gpg` 会自动加入 PATH，无需上述配置。
+
+#### 步骤 2：生成 GPG 密钥
+
+> **Windows 用户注意**：必须在 **Git Bash** 中执行以下命令（不要在 PowerShell / CMD 中执行，因为交互式密钥生成在非 TTY 环境下会失败）。
+
+```bash
+gpg --full-generate-key
+```
+
+按提示依次操作：
+
+| 提示 | 推荐选择 |
+|------|----------|
+| 密钥类型 | `1`（RSA and RSA） |
+| 密钥长度 | `4096` |
+| 有效期 | `0`（永不过期），然后输入 `y` 确认 |
+| 真实姓名 | 你的名字（将显示在签名中） |
+| 电子邮箱 | **必须与 Git / Gitea 的提交邮箱一致** |
+| 注释 | 可留空，直接回车 |
+| 确认 | 输入 `O`（Okay） |
+| 密码 | 设置一个保护密码（每次签名提交时需要输入） |
+
+#### 步骤 3：获取密钥 ID
+
+```bash
+gpg --list-secret-keys --keyid-format=long
+```
+
+输出示例：
+
+```
+sec   rsa4096/ABCDEF1234567890 2026-04-07 [SC]
+      XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+uid                 [ultimate] Your Name <your@email.com>
+ssb   rsa4096/1234567890ABCDEF 2026-04-07 [E]
+```
+
+其中 `sec` 行 `rsa4096/` 后面的 **ABCDEF1234567890** 就是密钥 ID。
+
+#### 步骤 4：配置 Git 签名
+
+```bash
+# 设置签名密钥
+git config --global user.signingkey ABCDEF1234567890
+
+# 开启自动签名（之后所有 commit 自动签名，无需每次加 -S）
+git config --global commit.gpgsign true
+```
+
+#### 步骤 5：导出公钥并添加到 Gitea
+
+```bash
+# 导出 ASCII 格式公钥
+gpg --armor --export ABCDEF1234567890
+```
+
+复制输出的完整内容（从 `-----BEGIN PGP PUBLIC KEY BLOCK-----` 到 `-----END PGP PUBLIC KEY BLOCK-----`），然后：
+
+1. 登录 Gitea → 头像 → **设置** → **SSH / GPG 密钥**
+2. 点击 **添加密钥**（GPG 密钥区域）
+3. 粘贴公钥 → 确认添加
+
+#### 步骤 6：验证签名提交
+
+```bash
+# 测试签名提交
+git commit --allow-empty -m "test: GPG signed commit"
+
+# 验证签名
+git log --show-signature -1
+```
+
+push 到 Gitea 后，提交记录旁会显示绿色 **Verified** 徽标。
+
 ### Git LFS 大文件
 
 ```bash
@@ -604,6 +701,12 @@ docker compose exec -u git server \
 
 ## 六、常见问题
 
+**Q: 部署完成后访问显示 502 Bad Gateway？**
+- 这是正常现象，说明 Nginx 已就绪但 Gitea 容器尚未启动完成
+- 步骤 8 拉取 Docker 镜像较慢（首次需要下载约 300MB），等待脚本执行完毕即可
+- 如脚本已结束仍然 502，手动启动容器：`cd /opt/gitea && docker compose up -d`
+- 确认容器状态：`docker compose ps`，确认 Gitea 日志：`docker compose logs -f server`
+
 **Q: SSL 证书申请失败？**
 - 确认域名 A 记录已解析到服务器 IP（用 `dig git.yourdomain.com` 验证）
 - 确认 80 端口可从外网访问（云安全组 + 防火墙）
@@ -619,8 +722,17 @@ docker compose exec server gitea admin user change-password -u 管理员用户
 - 如仍超时，检查服务器带宽和磁盘空间
 
 **Q: GPG 签名的提交不显示 "Verified"？**
-- 确认 GPG 公钥已添加到 Gitea 用户设置
-- 确认 Git 提交邮箱与 GPG 密钥邮箱一致
+- 确认 GPG 公钥已添加到 Gitea 用户设置（头像 → 设置 → SSH/GPG 密钥）
+- 确认 Git 提交邮箱（`git config user.email`）与 GPG 密钥邮箱**完全一致**
+- 确认密钥未过期：`gpg --list-keys`
+
+**Q: Windows 上 `gpg` 命令找不到？**
+- Windows 默认不带 GPG，推荐使用 Git for Windows 自带的 GPG：
+  ```powershell
+  git config --global gpg.program "C:\Program Files\Git\usr\bin\gpg.exe"
+  ```
+- 或安装 [Gpg4win](https://www.gpg4win.org/)
+- 生成密钥时请在 **Git Bash** 中执行 `gpg --full-generate-key`（PowerShell/CMD 下交互式生成会失败）
 
 **Q: 如何迁移到新服务器？**
 使用迁移脚本一键完成，详见上方「迁移到新服务器」章节：
diff --git a/gitea/deploy.sh b/gitea/deploy.sh
index 530f3ac..b6d60b9 100644
--- a/gitea/deploy.sh
+++ b/gitea/deploy.sh
@@ -125,8 +125,12 @@ install_docker() {
     if command -v docker &> /dev/null; then
         log "Docker 已安装: $(docker --version)"
     else
-        log "正在安装 Docker..."
-        curl -fsSL https://get.docker.com | bash
+        log "正在安装 Docker (使用阿里云镜像)..."
+        curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" \
+            > /etc/apt/sources.list.d/docker.list
+        apt-get update -qq
+        apt-get install -y -qq docker-ce docker-ce-cli containerd.io docker-compose-plugin
         log "Docker 安装完成: $(docker --version)"
     fi
 
@@ -424,7 +428,7 @@ show_info() {
     echo -e "${GREEN}║${NC}    ✓ Git LFS 大文件存储"
     echo -e "${GREEN}║${NC}    ✓ SSH 密钥认证"
     echo -e "${GREEN}║${NC}    ✓ GPG 签名验证"
-    echo -e "${GREEN}║${NC}    ✓ MySQL 8.0 数据库"
+    echo -e "${GREEN}║${NC}    ✓ MySQL 8.4 LTS 数据库"
     echo -e "${GREEN}║${NC}"
     echo -e "${GREEN}║${NC}  首次访问说明:"
     echo -e "${GREEN}║${NC}    1. 浏览器打开 https://${GITEA_DOMAIN}"
diff --git a/gitea/docker-compose.yml b/gitea/docker-compose.yml
index aab80dd..c262e83 100644
--- a/gitea/docker-compose.yml
+++ b/gitea/docker-compose.yml
@@ -56,7 +56,7 @@ services:
         condition: service_healthy
 
   db:
-    image: mysql:8.0
+    image: mysql:8.4
     container_name: gitea-db
     restart: always
     environment:
diff --git a/siyuan/.env.example b/siyuan/.env.example
new file mode 100644
index 0000000..b72a93c
--- /dev/null
+++ b/siyuan/.env.example
@@ -0,0 +1,31 @@
+# ===== SiYuan 基础配置 =====
+
+# SiYuan 访问域名（必须修改）
+SIYUAN_DOMAIN=note.example.com
+
+# Let's Encrypt 邮箱（必须修改）
+CERTBOT_EMAIL=admin@example.com
+
+# 访问授权码（必须修改，否则任何人都能访问你的数据）
+SIYUAN_ACCESS_CODE=changeme
+
+# ===== 镜像配置 =====
+
+# SiYuan 镜像
+SIYUAN_IMAGE=b3log/siyuan:latest
+# 使用固定版本号（推荐生产环境）：
+# SIYUAN_IMAGE=b3log/siyuan:v3.6.3
+
+# ===== 目录配置 =====
+
+# SiYuan 工作空间目录
+SIYUAN_DATA_DIR=/data/siyuan/workspace
+
+# 备份目录
+BACKUP_DIR=/var/backups/siyuan
+
+# ===== 用户权限 =====
+
+# 容器内运行用户/组 ID（解决挂载目录权限问题）
+SIYUAN_PUID=1000
+SIYUAN_PGID=1000
diff --git a/siyuan/README.md b/siyuan/README.md
new file mode 100644
index 0000000..c817b3c
--- /dev/null
+++ b/siyuan/README.md
@@ -0,0 +1,277 @@
+# SiYuan 笔记部署指南
+
+隐私优先的个人知识管理系统，支持块级引用、Markdown 所见即所得编辑器、闪卡间隔重复等功能。
+
+## 功能特性
+
+- 块级引用和双向链接
+- Markdown 所见即所得编辑器
+- 数学公式、流程图、甘特图等
+- 闪卡间隔重复（Spaced Repetition）
+- AI 写作（基于 OpenAI API）
+- Web 剪藏（Chrome/Edge 扩展）
+- 社区插件市场
+
+## 技术栈
+
+| 组件 | 版本 | 说明 |
+|------|------|------|
+| SiYuan | latest | 知识管理系统 |
+| Nginx | 系统包 | 反向代理 + HTTPS 接入 |
+| Docker | 最新版 | 容器运行环境 |
+
+## Docker 版限制
+
+> **重要**：Docker 部署版与桌面版相比有以下限制：
+>
+> - **不支持**桌面和移动客户端连接，只能通过浏览器使用
+> - **不支持**导出 PDF、HTML、Word 格式
+> - **不支持**导入 Markdown 文件
+
+## 前置条件
+
+1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
+2. 一个已解析到服务器的域名（如 `note.example.com`）
+3. 服务器 80/443 端口可从外网访问
+
+## 目录结构
+
+```
+siyuan/
+├── docker-compose.yml    # 容器编排
+├── .env.example          # 配置模板
+├── deploy.sh             # 一键部署脚本
+├── backup.sh             # 备份脚本
+├── nginx/
+│   └── siyuan.conf       # Nginx 反向代理配置
+└── README.md             # 本文件
+```
+
+服务器上的数据目录：
+
+```
+/data/siyuan/workspace/   # SiYuan 工作空间（笔记 + 资源文件）
+/var/backups/siyuan/      # 备份文件
+```
+
+## 快速部署
+
+### 第一步：上传文件到服务器
+
+```bash
+# 在本地执行，上传 base 和 siyuan 目录
+scp -r base/ siyuan/ root@<服务器IP>:/opt/
+```
+
+### 第二步：登录服务器执行部署
+
+```bash
+ssh root@<服务器IP>
+
+# 如果是全新服务器，先安装基础环境
+cd /opt/base
+cp .env.example .env
+bash setup.sh
+
+# 部署 SiYuan
+cd /opt/siyuan
+bash deploy.sh
+# 首次运行会生成 .env，按提示修改配置后重新运行
+vi .env
+bash deploy.sh
+```
+
+### 第三步：配置域名解析
+
+在域名服务商（如阿里云 DNS）添加 A 记录：
+
+| 记录类型 | 主机记录 | 记录值 |
+|----------|----------|--------|
+| A | note | `<服务器公网IP>` |
+
+### 第四步：登录使用
+
+1. 浏览器访问 `https://note.yourdomain.com`
+2. 输入 `.env` 中配置的 `SIYUAN_ACCESS_CODE` 授权码
+
+## 配置说明
+
+### .env 配置项
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `SIYUAN_DOMAIN` | 访问域名 | 必填 |
+| `CERTBOT_EMAIL` | Let's Encrypt 邮箱 | 必填 |
+| `SIYUAN_ACCESS_CODE` | 访问授权码 | 必填 |
+| `SIYUAN_IMAGE` | Docker 镜像 | `b3log/siyuan:latest` |
+| `SIYUAN_DATA_DIR` | 工作空间目录 | `/data/siyuan/workspace` |
+| `BACKUP_DIR` | 备份目录 | `/var/backups/siyuan` |
+| `SIYUAN_PUID` | 容器用户 ID | `1000` |
+| `SIYUAN_PGID` | 容器组 ID | `1000` |
+
+### 修改访问授权码
+
+```bash
+cd /opt/siyuan
+
+# 修改 .env 中的 SIYUAN_ACCESS_CODE
+vi .env
+
+# 重新创建容器使新授权码生效
+docker compose up -d
+```
+
+### 用户权限说明
+
+SiYuan 容器通过 `PUID` 和 `PGID` 环境变量控制运行用户。部署脚本会自动设置数据目录的所有权。如需手动调整：
+
+```bash
+chown -R 1000:1000 /data/siyuan/workspace
+```
+
+## 日常运维
+
+### 查看日志
+
+```bash
+cd /opt/siyuan
+docker compose logs -f
+docker compose logs --tail 100
+```
+
+### 备份
+
+```bash
+cd /opt/siyuan
+bash backup.sh
+```
+
+备份内容包括：
+- 工作空间数据（笔记、资源文件、插件等）
+- 部署配置（`docker-compose.yml` + `.env` + `nginx/`）
+
+备份文件保存在 `/var/backups/siyuan/`，自动清理 30 天前的旧备份。
+
+### 恢复备份
+
+```bash
+# 查看可用备份
+ls /var/backups/siyuan/
+
+# 停止服务
+cd /opt/siyuan && docker compose down
+
+# 恢复数据
+tar xzf /var/backups/siyuan/<日期>/siyuan-workspace.tar.gz -C /data/siyuan/
+
+# 修复权限
+chown -R 1000:1000 /data/siyuan/workspace
+
+# 重启服务
+cd /opt/siyuan && docker compose up -d
+```
+
+### 升级
+
+```bash
+cd /opt/siyuan
+
+# 1. 备份当前数据
+bash backup.sh
+
+# 2. 拉取新镜像
+docker compose pull
+
+# 3. 停止旧容器并启动新容器
+docker compose down
+docker compose up -d
+
+# 4. 检查运行状态
+docker compose ps
+docker compose logs --tail 20
+```
+
+### 停止 / 启动
+
+```bash
+cd /opt/siyuan
+docker compose down      # 停止
+docker compose up -d     # 启动
+docker compose restart   # 重启
+```
+
+## 数据存储结构
+
+SiYuan 的数据存储在工作空间目录下：
+
+```
+workspace/
+└── data/
+    ├── assets/       # 插入的资源文件（图片等）
+    ├── emojis/       # 自定义 Emoji
+    ├── snippets/     # 代码片段
+    ├── storage/      # 查询条件、布局、闪卡等
+    ├── templates/    # 模板片段
+    ├── widgets/      # 挂件
+    ├── plugins/      # 插件
+    ├── public/       # 公共数据
+    └── <笔记本>/     # 用户创建的笔记本（.sy 格式 JSON 文件）
+```
+
+## 故障排查
+
+### 数据同步警告
+
+> **不要**使用第三方同步盘（Dropbox、OneDrive、坚果云等）同步工作空间目录，否则会导致数据损坏。如需多设备同步，请使用 SiYuan 官方云端同步（付费功能）或手动导出导入。
+
+### 容器无法启动
+
+```bash
+# 查看容器状态
+docker compose ps
+
+# 查看详细日志
+docker compose logs --tail 50
+```
+
+### 权限问题
+
+如果出现文件读写权限错误：
+
+```bash
+# 确认 PUID/PGID 与数据目录所有者一致
+ls -la /data/siyuan/
+chown -R 1000:1000 /data/siyuan/workspace
+```
+
+### 访问返回 502
+
+```bash
+# 检查 SiYuan 容器是否运行
+docker compose ps
+
+# 检查 6806 端口
+curl -I http://127.0.0.1:6806
+
+# 检查 Nginx 配置
+nginx -t
+```
+
+### WebSocket 连接失败
+
+确认 Nginx 配置中 `/ws` 路径已正确配置 WebSocket 反向代理（部署脚本已自动配置）。
+
+## 注意事项
+
+- **不要使用 URL 重写进行重定向**，否则可能导致认证出现问题。应当使用反向代理（部署脚本已正确配置）。
+- **不要通过第三方同步盘同步数据**（如 Dropbox、OneDrive、坚果云等），否则可能导致数据损坏。SiYuan 有自己的云端同步机制（付费功能）。
+- 确认挂载卷的路径正确，否则删除容器后数据会丢失。
+- 如果遇到权限问题，确认 `PUID`/`PGID` 环境变量与宿主机挂载目录的所有者一致。
+
+## 端口说明
+
+| 端口 | 协议 | 说明 |
+|------|------|------|
+| 80 | TCP | HTTP → HTTPS 重定向 |
+| 443 | TCP | HTTPS（Nginx 反向代理） |
+| 6806 | TCP | SiYuan HTTP（仅监听 127.0.0.1） |
diff --git a/siyuan/backup.sh b/siyuan/backup.sh
new file mode 100644
index 0000000..8fb9349
--- /dev/null
+++ b/siyuan/backup.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# SiYuan 备份脚本
+# 备份工作空间数据 + 配置文件
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# 加载配置
+if [ -f .env ]; then
+    set -a; source .env; set +a
+else
+    echo "[ERROR] .env 文件不存在，请先运行 deploy.sh" >&2
+    exit 1
+fi
+
+# ===== 配置 =====
+DATA_DIR="${SIYUAN_DATA_DIR:-/data/siyuan/workspace}"
+BACKUP_BASE="${BACKUP_DIR:-/var/backups/siyuan}"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR_FULL="${BACKUP_BASE}/${TIMESTAMP}"
+RETENTION_DAYS=30
+
+echo "========== SiYuan 备份 =========="
+echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+echo "数据目录: $DATA_DIR"
+echo "备份目录: $BACKUP_DIR_FULL"
+echo ""
+
+mkdir -p "$BACKUP_DIR_FULL"
+
+# ===== 备份工作空间数据 =====
+echo "[1/3] 备份 SiYuan 工作空间..."
+if [ -d "$DATA_DIR" ]; then
+    tar czf "$BACKUP_DIR_FULL/siyuan-workspace.tar.gz" -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")"
+    echo "  ✓ 工作空间已备份"
+else
+    echo "  ⚠ 数据目录不存在: $DATA_DIR"
+fi
+
+# ===== 备份 docker-compose 和配置 =====
+echo "[2/3] 备份部署配置..."
+tar czf "$BACKUP_DIR_FULL/siyuan-config.tar.gz" \
+    -C "$SCRIPT_DIR" \
+    docker-compose.yml .env nginx/ 2>/dev/null || true
+echo "  ✓ 配置已备份"
+
+# ===== 清理旧备份 =====
+echo "[3/3] 清理 ${RETENTION_DAYS} 天前的旧备份..."
+find "$BACKUP_BASE" -maxdepth 1 -type d -mtime +${RETENTION_DAYS} -exec rm -rf {} \; 2>/dev/null || true
+echo "  ✓ 旧备份已清理"
+
+# ===== 汇总 =====
+echo ""
+echo "========== 备份完成 =========="
+TOTAL_SIZE=$(du -sh "$BACKUP_DIR_FULL" | cut -f1)
+echo "备份位置: $BACKUP_DIR_FULL"
+echo "备份大小: $TOTAL_SIZE"
+echo ""
+echo "备份内容:"
+ls -lh "$BACKUP_DIR_FULL/"
+echo ""
+echo "恢复方法:"
+echo "  cd $SCRIPT_DIR && docker compose down"
+echo "  tar xzf $BACKUP_DIR_FULL/siyuan-workspace.tar.gz -C $(dirname "$DATA_DIR")"
+echo "  chown -R ${SIYUAN_PUID:-1000}:${SIYUAN_PGID:-1000} $DATA_DIR"
+echo "  cd $SCRIPT_DIR && docker compose up -d"
diff --git a/siyuan/deploy.sh b/siyuan/deploy.sh
new file mode 100644
index 0000000..a19a169
--- /dev/null
+++ b/siyuan/deploy.sh
@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# SiYuan 一键部署脚本
+# 自动安装 Docker + Nginx + SSL + SiYuan
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ===== 加载公共基础函数 =====
+BASE_DIR="$(cd "$SCRIPT_DIR/../base" 2>/dev/null && pwd)" || true
+if [ -z "$BASE_DIR" ] || [ ! -f "$BASE_DIR/setup.sh" ]; then
+    echo "[ERROR] base/setup.sh 未找到" >&2
+    echo "请确保目录结构如下:" >&2
+    echo "  /opt/base/setup.sh" >&2
+    echo "  /opt/siyuan/deploy.sh  (当前脚本)" >&2
+    exit 1
+fi
+source "$BASE_DIR/setup.sh"
+
+# =============================================================
+#  SiYuan 专用函数
+# =============================================================
+
+init_env() {
+    step "初始化 SiYuan 配置"
+
+    if [ ! -f .env ]; then
+        if [ ! -f .env.example ]; then
+            error "缺少 .env.example 模板文件"
+            exit 1
+        fi
+        cp .env.example .env
+        log "已生成 .env 文件"
+        echo ""
+        warn "┌─────────────────────────────────────────────────┐"
+        warn "│  请编辑 .env 文件，至少修改以下配置：              │"
+        warn "│                                                 │"
+        warn "│  SIYUAN_DOMAIN=note.yourdomain.com              │"
+        warn "│  CERTBOT_EMAIL=you@yourdomain.com               │"
+        warn "│  SIYUAN_ACCESS_CODE=你的访问授权码                │"
+        warn "│                                                 │"
+        warn "│  编辑命令: vi $SCRIPT_DIR/.env                  │"
+        warn "│  编辑完成后重新运行: bash deploy.sh              │"
+        warn "└─────────────────────────────────────────────────┘"
+        exit 0
+    fi
+
+    set -a; source .env; set +a
+
+    local has_error=0
+    if [[ -z "${SIYUAN_DOMAIN:-}" ]] || [[ "${SIYUAN_DOMAIN}" == "note.example.com" ]]; then
+        error "请在 .env 中将 SIYUAN_DOMAIN 修改为你的实际域名"
+        has_error=1
+    fi
+    if [[ -z "${CERTBOT_EMAIL:-}" ]] || [[ "${CERTBOT_EMAIL}" == "admin@example.com" ]]; then
+        error "请在 .env 中将 CERTBOT_EMAIL 修改为你的实际邮箱"
+        has_error=1
+    fi
+    if [[ -z "${SIYUAN_ACCESS_CODE:-}" ]] || [[ "${SIYUAN_ACCESS_CODE}" == "changeme" ]]; then
+        error "请在 .env 中将 SIYUAN_ACCESS_CODE 修改为一个安全的授权码"
+        has_error=1
+    fi
+    [ "$has_error" -eq 1 ] && { error "请修改 .env 后重新运行"; exit 1; }
+
+    log "配置检查通过"
+    log "  域名: ${SIYUAN_DOMAIN}"
+    log "  邮箱: ${CERTBOT_EMAIL}"
+}
+
+create_dirs() {
+    step "创建数据目录"
+    local data_dir="${SIYUAN_DATA_DIR:-/data/siyuan/workspace}"
+    local backup_dir="${BACKUP_DIR:-/var/backups/siyuan}"
+    local puid="${SIYUAN_PUID:-1000}"
+    local pgid="${SIYUAN_PGID:-1000}"
+
+    mkdir -p "$data_dir" "$backup_dir"
+    chown -R "$puid:$pgid" "$data_dir"
+    log "数据目录: $data_dir (所有者: $puid:$pgid)"
+    log "备份目录: $backup_dir"
+}
+
+start_services() {
+    step "启动 SiYuan 服务"
+
+    log "正在拉取镜像..."
+    docker compose pull
+
+    log "正在启动容器..."
+    docker compose up -d
+
+    log "等待 SiYuan 就绪..."
+    local max_wait=30
+    for i in $(seq 1 "$max_wait"); do
+        if curl -sf http://127.0.0.1:6806/ &> /dev/null; then
+            log "SiYuan 启动成功！"
+            return
+        fi
+        sleep 2
+    done
+    warn "SiYuan 可能仍在启动中，请稍后检查: docker compose logs -f"
+}
+
+show_info() {
+    set -a; source .env; set +a
+
+    echo ""
+    echo -e "${GREEN}╔══════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${GREEN}║              SiYuan 笔记部署完成！                       ║${NC}"
+    echo -e "${GREEN}╠══════════════════════════════════════════════════════════╣${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  Web 访问:  ${CYAN}https://${SIYUAN_DOMAIN}${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  访问授权码: 在 .env 中的 SIYUAN_ACCESS_CODE"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  数据目录:  ${SIYUAN_DATA_DIR:-/data/siyuan/workspace}"
+    echo -e "${GREEN}║${NC}  备份目录:  ${BACKUP_DIR:-/var/backups/siyuan}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  ${YELLOW}⚠ Docker 版不支持桌面/移动客户端连接${NC}"
+    echo -e "${GREEN}║${NC}  ${YELLOW}⚠ 不支持导出 PDF/Word/HTML 和导入 Markdown${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}╚══════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    echo "常用命令:"
+    echo "  查看日志:    cd $SCRIPT_DIR && docker compose logs -f"
+    echo "  重启服务:    cd $SCRIPT_DIR && docker compose restart"
+    echo "  停止服务:    cd $SCRIPT_DIR && docker compose down"
+    echo "  备份数据:    cd $SCRIPT_DIR && bash backup.sh"
+    echo ""
+}
+
+# =============================================================
+#  主流程
+# =============================================================
+main() {
+    echo -e "${CYAN}"
+    echo "   ____  _ __  __"
+    echo "  / ___|(_)\\ \\/ /   _ _ __ _ __"
+    echo "  \\___ \\| | \\  / | | | '_ \`_ \\"
+    echo "   ___) | | /  \\ |_| | | | | | |"
+    echo "  |____/|_|/_/\\_\\__,_|_| |_| |_|  Deploy Script"
+    echo -e "${NC}"
+    echo ""
+
+    check_root
+    load_base_env "$BASE_DIR"
+
+    # Step 1: 系统初始化
+    init_system
+
+    # Step 2: 安装 Docker
+    install_docker
+
+    # Step 3: 安装 Nginx
+    install_nginx
+
+    # Step 4: 初始化配置
+    init_env
+
+    # Step 5: 配置 Docker 镜像加速
+    configure_docker_mirrors
+
+    # Step 6: 创建数据目录
+    create_dirs
+
+    # Step 7: 配置防火墙
+    setup_firewall_base
+
+    # Step 8: 配置 SSL 证书
+    setup_ssl_cert "${SIYUAN_DOMAIN}" "${CERTBOT_EMAIL}" "siyuan"
+
+    # Step 9: 部署 Nginx 反向代理
+    deploy_nginx_conf "$SCRIPT_DIR/nginx/siyuan.conf" "${SIYUAN_DOMAIN}" "siyuan"
+
+    # Step 10: 启动服务
+    start_services
+
+    # 完成
+    show_info
+}
+
+main "$@"
diff --git a/siyuan/docker-compose.yml b/siyuan/docker-compose.yml
new file mode 100644
index 0000000..ccdb96a
--- /dev/null
+++ b/siyuan/docker-compose.yml
@@ -0,0 +1,28 @@
+services:
+  siyuan:
+    image: ${SIYUAN_IMAGE:-b3log/siyuan:latest}
+    container_name: siyuan
+    restart: unless-stopped
+    command:
+      - --workspace=/siyuan/workspace/
+      - --accessAuthCode=${SIYUAN_ACCESS_CODE:?请在 .env 中设置 SIYUAN_ACCESS_CODE}
+    environment:
+      - TZ=Asia/Shanghai
+      - PUID=${SIYUAN_PUID:-1000}
+      - PGID=${SIYUAN_PGID:-1000}
+    volumes:
+      - ${SIYUAN_DATA_DIR:-/data/siyuan/workspace}:/siyuan/workspace
+      - /etc/localtime:/etc/localtime:ro
+    ports:
+      - "127.0.0.1:6806:6806"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:6806"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
diff --git a/siyuan/nginx/siyuan.conf b/siyuan/nginx/siyuan.conf
new file mode 100644
index 0000000..fd2b8af
--- /dev/null
+++ b/siyuan/nginx/siyuan.conf
@@ -0,0 +1,70 @@
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __DOMAIN__;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name __DOMAIN__;
+
+    # SSL 证书
+    ssl_certificate     /etc/letsencrypt/live/__DOMAIN__/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/__DOMAIN__/privkey.pem;
+
+    # SSL 参数
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    # 安全头
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    # 上传大小限制（资源文件、图片等上传）
+    client_max_body_size 128M;
+
+    # 反向代理到 SiYuan
+    location / {
+        proxy_pass http://127.0.0.1:6806;
+        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_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+
+    # WebSocket 支持（官方要求 /ws 路径配置 WebSocket 反向代理）
+    location /ws {
+        proxy_pass http://127.0.0.1:6806;
+        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_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 300s;
+        proxy_read_timeout 300s;
+    }
+}
diff --git a/vaultwarden/.env.example b/vaultwarden/.env.example
new file mode 100644
index 0000000..6029f8e
--- /dev/null
+++ b/vaultwarden/.env.example
@@ -0,0 +1,44 @@
+# ===== Vaultwarden 基础配置 =====
+
+# Vaultwarden 访问域名（必须修改）
+VAULTWARDEN_DOMAIN=vault.example.com
+
+# Let's Encrypt 邮箱（必须修改）
+CERTBOT_EMAIL=admin@example.com
+
+# ===== 安全配置 =====
+
+# 管理员面板令牌（部署脚本自动生成随机字符串）
+# 如需更安全的 argon2id 哈希，运行: docker run --rm -it vaultwarden/server /vaultwarden hash
+# 将哈希值用单引号包裹填入，如: ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'
+ADMIN_TOKEN=
+
+# 是否允许新用户注册（部署完成注册好账号后建议关闭）
+SIGNUPS_ALLOWED=true
+
+# 是否显示密码提示
+SHOW_PASSWORD_HINT=false
+
+# 是否允许 Send 功能
+SENDS_ALLOWED=true
+
+# ===== 镜像配置 =====
+
+# Vaultwarden 镜像
+VAULTWARDEN_IMAGE=vaultwarden/server:latest
+
+# ===== 目录与端口 =====
+
+# 数据目录（SQLite 数据库 + 附件 + 密钥）
+VAULTWARDEN_DATA_DIR=/var/lib/vaultwarden
+
+# 本地监听端口（Nginx 反向代理目标）
+VAULTWARDEN_PORT=8080
+
+# 备份目录
+BACKUP_DIR=/var/backups/vaultwarden
+
+# ===== 日志 =====
+
+# 日志级别: trace, debug, info, warn, error
+LOG_LEVEL=info
diff --git a/vaultwarden/README.md b/vaultwarden/README.md
new file mode 100644
index 0000000..593291c
--- /dev/null
+++ b/vaultwarden/README.md
@@ -0,0 +1,328 @@
+# Vaultwarden 部署指南
+
+Bitwarden 兼容的自托管密码管理器，轻量、安全、功能完整。
+
+## 功能特性
+
+- 完全兼容 Bitwarden 官方客户端（浏览器插件、桌面端、移动端）
+- 密码、笔记、信用卡、身份信息安全存储
+- TOTP 两步验证码生成
+- 密码分享（Send 功能）
+- 组织与多用户协作
+- 管理员面板
+- 轻量级：使用 SQLite，单容器约 50MB 内存
+
+## 技术栈
+
+| 组件 | 版本 | 说明 |
+|------|------|------|
+| Vaultwarden | latest | Bitwarden 兼容服务端（Rust 实现） |
+| SQLite | 内置 | 轻量数据库，无需额外部署 |
+| Nginx | 系统包 | 反向代理 + HTTPS（Bitwarden 客户端必须 HTTPS） |
+| Docker | 最新版 | 容器运行环境 |
+
+## 前置条件
+
+1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
+2. 一个已解析到服务器的域名（如 `vault.example.com`）
+3. 服务器 80/443 端口可从外网访问
+4. **必须启用 HTTPS**（Bitwarden 客户端强制要求）
+
+## 目录结构
+
+```
+vaultwarden/
+├── docker-compose.yml    # 容器编排
+├── .env.example          # 配置模板
+├── deploy.sh             # 一键部署脚本
+├── backup.sh             # 备份脚本
+├── nginx/
+│   └── vaultwarden.conf  # Nginx 反向代理配置
+└── README.md             # 本文件
+```
+
+服务器上的数据目录：
+
+```
+/var/lib/vaultwarden/     # Vaultwarden 数据（SQLite + 附件 + RSA 密钥）
+/var/backups/vaultwarden/ # 备份文件
+```
+
+## 快速部署
+
+### 第一步：上传文件到服务器
+
+```bash
+# 在本地执行，上传 base 和 vaultwarden 目录
+scp -r base/ vaultwarden/ root@<服务器IP>:/opt/
+```
+
+### 第二步：登录服务器执行部署
+
+```bash
+ssh root@<服务器IP>
+
+# 如果是全新服务器，先安装基础环境
+cd /opt/base
+cp .env.example .env
+bash setup.sh
+
+# 部署 Vaultwarden
+cd /opt/vaultwarden
+bash deploy.sh
+# 首次运行会生成 .env（含自动生成的 ADMIN_TOKEN），按提示修改后重新运行
+vi .env
+bash deploy.sh
+```
+
+### 第三步：配置域名解析
+
+在域名服务商添加 A 记录：
+
+| 记录类型 | 主机记录 | 记录值 |
+|----------|----------|--------|
+| A | vault | `<服务器公网IP>` |
+
+### 第四步：注册账号
+
+1. 浏览器访问 `https://vault.yourdomain.com`
+2. 点击「创建账户」注册一个主账号
+3. 注册完成后，**强烈建议关闭注册功能**：
+
+```bash
+cd /opt/vaultwarden
+# 编辑 .env，将 SIGNUPS_ALLOWED 改为 false
+vi .env
+docker compose restart
+```
+
+### 第五步：安装客户端
+
+1. 下载 Bitwarden 客户端：https://bitwarden.com/download/
+2. 打开客户端，点击左上角齿轮图标
+3. 在「自托管服务器」中填入服务器 URL：`https://vault.yourdomain.com`
+4. 保存后使用注册的账号登录
+
+## 配置说明
+
+### .env 配置项
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `VAULTWARDEN_DOMAIN` | 访问域名 | 必填 |
+| `CERTBOT_EMAIL` | Let's Encrypt 邮箱 | 必填 |
+| `ADMIN_TOKEN` | 管理员面板令牌 | 自动生成 |
+| `SIGNUPS_ALLOWED` | 允许新用户注册 | `true` |
+| `SHOW_PASSWORD_HINT` | 显示密码提示 | `false` |
+| `SENDS_ALLOWED` | 允许 Send 功能 | `true` |
+| `VAULTWARDEN_IMAGE` | Docker 镜像 | `vaultwarden/server:latest` |
+| `VAULTWARDEN_DATA_DIR` | 数据目录 | `/var/lib/vaultwarden` |
+| `VAULTWARDEN_PORT` | 本地监听端口 | `8080` |
+| `BACKUP_DIR` | 备份目录 | `/var/backups/vaultwarden` |
+| `LOG_LEVEL` | 日志级别 | `info` |
+
+### 管理员面板
+
+访问 `https://vault.yourdomain.com/admin`，输入 `ADMIN_TOKEN` 中的明文令牌即可登录。
+
+管理员面板可以：
+- 查看所有用户
+- 邀请新用户（关闭注册后）
+- 删除用户
+- 查看系统诊断信息
+- 调整运行时配置
+
+> **安全提醒**：可在 Nginx 配置中限制 `/admin` 路径仅允许特定 IP 访问。
+
+### 使用 argon2id 加强 ADMIN_TOKEN 安全性
+
+部署脚本默认生成随机字符串作为 ADMIN_TOKEN。如需使用更安全的 argon2id 哈希：
+
+```bash
+# 生成 argon2id 哈希（使用 Bitwarden 默认参数: m=64MiB, t=3, p=4）
+docker run --rm -it vaultwarden/server /vaultwarden hash
+
+# 或使用 OWASP 推荐参数（m=19MiB, t=2, p=1，更节省内存）
+docker run --rm -it vaultwarden/server /vaultwarden hash --preset owasp
+```
+
+将生成的哈希值填入 `.env` 时，**必须用单引号包裹**（因为 argon2id 字符串包含 `$` 符号）：
+
+```bash
+# .env 中的写法（注意单引号）
+ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$MmeK......'
+```
+
+> **注意**：登录管理面板时输入的是你生成哈希时使用的**原始明文密码**，不是哈希值本身。
+
+## 日常运维
+
+### 查看日志
+
+```bash
+cd /opt/vaultwarden
+docker compose logs -f
+docker compose logs --tail 100
+```
+
+### 备份
+
+```bash
+cd /opt/vaultwarden
+bash backup.sh
+```
+
+备份内容包括：
+- SQLite 数据库（支持在线安全备份）
+- 附件和 RSA 密钥
+- 部署配置
+
+也可使用 Vaultwarden v1.32.1+ 内置备份命令：
+
+```bash
+docker exec -it vaultwarden /vaultwarden backup
+```
+
+备份文件保存在 `/var/backups/vaultwarden/`，自动清理 30 天前的旧备份。
+
+**建议配置定时备份：**
+
+```bash
+# 每天凌晨 2 点自动备份
+crontab -e
+# 添加：
+0 2 * * * cd /opt/vaultwarden && bash backup.sh >> /var/log/vaultwarden-backup.log 2>&1
+```
+
+### 恢复备份
+
+```bash
+cd /opt/vaultwarden
+docker compose down
+
+# 查看可用备份
+ls /var/backups/vaultwarden/
+
+# ⚠ 重要：先删除现有 WAL 文件，避免与恢复的数据库不匹配导致损坏
+rm -f /var/lib/vaultwarden/db.sqlite3-wal /var/lib/vaultwarden/db.sqlite3-shm
+
+# 恢复数据库
+cp /var/backups/vaultwarden/<日期>/db.sqlite3 /var/lib/vaultwarden/
+
+# 恢复附件
+tar xzf /var/backups/vaultwarden/<日期>/vaultwarden-data.tar.gz -C /var/lib/
+
+# 重启
+docker compose up -d
+```
+
+> **警告**：恢复通过 `.backup` 方式创建的备份时，**必须先删除**现有的 `db.sqlite3-wal` 文件，否则 SQLite 会尝试用旧的 WAL 文件恢复数据库，可能导致数据损坏。
+
+### 升级
+
+```bash
+cd /opt/vaultwarden
+
+# 1. 备份数据
+bash backup.sh
+
+# 2. 拉取新镜像
+docker compose pull
+
+# 3. 重启
+docker compose up -d
+
+# 4. 检查运行状态
+docker compose ps
+docker compose logs --tail 20
+```
+
+### 停止 / 启动
+
+```bash
+cd /opt/vaultwarden
+docker compose down      # 停止
+docker compose up -d     # 启动
+docker compose restart   # 重启
+```
+
+## 安全加固建议
+
+### 1. 关闭注册
+
+注册好所有需要的账号后：
+
+```bash
+# .env 中设置
+SIGNUPS_ALLOWED=false
+```
+
+### 2. 限制管理面板访问
+
+在 `nginx/vaultwarden.conf` 中取消注释 `/admin` 的 IP 限制部分，仅允许你的 IP 访问。
+
+### 3. 启用两步验证
+
+登录 Vaultwarden Web 界面 → 设置 → 两步登录 → 启用 TOTP 或其他验证方式。
+
+### 4. 定期备份
+
+配置定时任务，每天自动备份，并将备份文件同步到异地存储。
+
+## 故障排查
+
+### 客户端无法连接
+
+```bash
+# 检查 HTTPS 是否正常
+curl -I https://vault.yourdomain.com
+
+# 检查容器是否运行
+docker compose ps
+
+# 检查端口
+curl http://127.0.0.1:8080/alive
+```
+
+### 502 Bad Gateway
+
+```bash
+# 容器未运行
+docker compose up -d
+
+# 检查端口是否匹配
+grep VAULTWARDEN_PORT .env
+grep proxy_pass /etc/nginx/sites-available/vaultwarden
+```
+
+### 管理面板无法登录
+
+```bash
+# 确认 ADMIN_TOKEN 已设置
+grep ADMIN_TOKEN .env
+
+# 如果使用 argon2id 哈希，登录时输入的是原始明文密码
+# 检查容器日志中的错误
+docker compose logs --tail 20
+```
+
+### SSL 证书问题
+
+```bash
+# 检查证书状态
+certbot certificates
+
+# 手动续期
+certbot renew --dry-run
+
+# 检查域名解析
+dig vault.yourdomain.com
+```
+
+## 端口说明
+
+| 端口 | 协议 | 说明 |
+|------|------|------|
+| 80 | TCP | HTTP → HTTPS 重定向 |
+| 443 | TCP | HTTPS（Nginx 反向代理） |
+| 8080 | TCP | Vaultwarden HTTP（仅监听 127.0.0.1） |
diff --git a/vaultwarden/backup.sh b/vaultwarden/backup.sh
new file mode 100644
index 0000000..df9bcc2
--- /dev/null
+++ b/vaultwarden/backup.sh
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Vaultwarden 备份脚本
+# 备份 SQLite 数据库 + 附件 + 配置
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# 加载配置
+if [ -f .env ]; then
+    set -a; source .env; set +a
+else
+    echo "[ERROR] .env 文件不存在，请先运行 deploy.sh" >&2
+    exit 1
+fi
+
+# ===== 配置 =====
+DATA_DIR="${VAULTWARDEN_DATA_DIR:-/var/lib/vaultwarden}"
+BACKUP_BASE="${BACKUP_DIR:-/var/backups/vaultwarden}"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR_FULL="${BACKUP_BASE}/${TIMESTAMP}"
+RETENTION_DAYS=30
+
+echo "========== Vaultwarden 备份 =========="
+echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
+echo "数据目录: $DATA_DIR"
+echo "备份目录: $BACKUP_DIR_FULL"
+echo ""
+
+mkdir -p "$BACKUP_DIR_FULL"
+
+# ===== 备份 SQLite 数据库 =====
+echo "[1/4] 备份 SQLite 数据库..."
+DB_FILE="$DATA_DIR/db.sqlite3"
+if [ -f "$DB_FILE" ]; then
+    # 使用 sqlite3 .backup 命令进行在线安全备份
+    if command -v sqlite3 &> /dev/null; then
+        sqlite3 "$DB_FILE" ".backup '$BACKUP_DIR_FULL/db.sqlite3'"
+        echo "  ✓ 数据库已安全备份 (sqlite3 .backup)"
+    else
+        # 降级：直接复制（建议先停止容器）
+        cp "$DB_FILE" "$BACKUP_DIR_FULL/db.sqlite3"
+        cp "${DB_FILE}-wal" "$BACKUP_DIR_FULL/db.sqlite3-wal" 2>/dev/null || true
+        cp "${DB_FILE}-shm" "$BACKUP_DIR_FULL/db.sqlite3-shm" 2>/dev/null || true
+        echo "  ✓ 数据库已备份 (文件复制，建议安装 sqlite3 以支持在线备份)"
+    fi
+else
+    echo "  ⚠ 数据库文件不存在: $DB_FILE"
+fi
+
+# ===== 备份附件和密钥 =====
+echo "[2/4] 备份附件和密钥..."
+if [ -d "$DATA_DIR" ]; then
+    tar czf "$BACKUP_DIR_FULL/vaultwarden-data.tar.gz" \
+        -C "$(dirname "$DATA_DIR")" "$(basename "$DATA_DIR")" \
+        --exclude="db.sqlite3" --exclude="db.sqlite3-wal" --exclude="db.sqlite3-shm"
+    echo "  ✓ 附件和密钥已备份"
+else
+    echo "  ⚠ 数据目录不存在: $DATA_DIR"
+fi
+
+# ===== 备份部署配置 =====
+echo "[3/4] 备份部署配置..."
+tar czf "$BACKUP_DIR_FULL/vaultwarden-config.tar.gz" \
+    -C "$SCRIPT_DIR" \
+    docker-compose.yml .env nginx/ 2>/dev/null || true
+echo "  ✓ 配置已备份"
+
+# ===== 清理旧备份 =====
+echo "[4/4] 清理 ${RETENTION_DAYS} 天前的旧备份..."
+find "$BACKUP_BASE" -maxdepth 1 -type d -mtime +${RETENTION_DAYS} -exec rm -rf {} \; 2>/dev/null || true
+echo "  ✓ 旧备份已清理"
+
+# ===== 汇总 =====
+echo ""
+echo "========== 备份完成 =========="
+TOTAL_SIZE=$(du -sh "$BACKUP_DIR_FULL" | cut -f1)
+echo "备份位置: $BACKUP_DIR_FULL"
+echo "备份大小: $TOTAL_SIZE"
+echo ""
+echo "备份内容:"
+ls -lh "$BACKUP_DIR_FULL/"
+echo ""
+echo "恢复方法:"
+echo "  1. 停止服务:   cd $SCRIPT_DIR && docker compose down"
+echo "  2. 删除 WAL:   rm -f $DATA_DIR/db.sqlite3-wal $DATA_DIR/db.sqlite3-shm"
+echo "  3. 恢复数据库: cp $BACKUP_DIR_FULL/db.sqlite3 $DATA_DIR/"
+echo "  4. 恢复附件:   tar xzf $BACKUP_DIR_FULL/vaultwarden-data.tar.gz -C $(dirname "$DATA_DIR")"
+echo "  5. 启动服务:   cd $SCRIPT_DIR && docker compose up -d"
diff --git a/vaultwarden/deploy.sh b/vaultwarden/deploy.sh
new file mode 100644
index 0000000..28e90a0
--- /dev/null
+++ b/vaultwarden/deploy.sh
@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================
+# Vaultwarden 一键部署脚本
+# 自动安装 Docker + Nginx + SSL + Vaultwarden
+# ============================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# ===== 加载公共基础函数 =====
+BASE_DIR="$(cd "$SCRIPT_DIR/../base" 2>/dev/null && pwd)" || true
+if [ -z "$BASE_DIR" ] || [ ! -f "$BASE_DIR/setup.sh" ]; then
+    echo "[ERROR] base/setup.sh 未找到" >&2
+    echo "请确保目录结构如下:" >&2
+    echo "  /opt/base/setup.sh" >&2
+    echo "  /opt/vaultwarden/deploy.sh  (当前脚本)" >&2
+    exit 1
+fi
+source "$BASE_DIR/setup.sh"
+
+# =============================================================
+#  Vaultwarden 专用函数
+# =============================================================
+
+# 生成随机密码
+generate_password() {
+    openssl rand -base64 32 | tr -d '/+=' | head -c 32
+}
+
+init_env() {
+    step "初始化 Vaultwarden 配置"
+
+    if [ ! -f .env ]; then
+        if [ ! -f .env.example ]; then
+            error "缺少 .env.example 模板文件"
+            exit 1
+        fi
+        cp .env.example .env
+
+        # 自动生成 ADMIN_TOKEN
+        local admin_token
+        admin_token=$(generate_password)
+        sed -i "s/^ADMIN_TOKEN=$/ADMIN_TOKEN=${admin_token}/" .env
+        log "已自动生成 ADMIN_TOKEN"
+
+        log "已生成 .env 文件"
+        echo ""
+        warn "┌──────────────────────────────────────────────────────┐"
+        warn "│  请编辑 .env 文件，至少修改以下配置：                   │"
+        warn "│                                                      │"
+        warn "│  VAULTWARDEN_DOMAIN=vault.yourdomain.com             │"
+        warn "│  CERTBOT_EMAIL=you@yourdomain.com                    │"
+        warn "│                                                      │"
+        warn "│  ADMIN_TOKEN 已自动生成，请妥善保存                    │"
+        warn "│                                                      │"
+        warn "│  编辑命令: vi $SCRIPT_DIR/.env                       │"
+        warn "│  编辑完成后重新运行: bash deploy.sh                   │"
+        warn "└──────────────────────────────────────────────────────┘"
+        exit 0
+    fi
+
+    set -a; source .env; set +a
+
+    local has_error=0
+    if [[ -z "${VAULTWARDEN_DOMAIN:-}" ]] || [[ "${VAULTWARDEN_DOMAIN}" == "vault.example.com" ]]; then
+        error "请在 .env 中将 VAULTWARDEN_DOMAIN 修改为你的实际域名"
+        has_error=1
+    fi
+    if [[ -z "${CERTBOT_EMAIL:-}" ]] || [[ "${CERTBOT_EMAIL}" == "admin@example.com" ]]; then
+        error "请在 .env 中将 CERTBOT_EMAIL 修改为你的实际邮箱"
+        has_error=1
+    fi
+    if [[ -z "${ADMIN_TOKEN:-}" ]]; then
+        error "ADMIN_TOKEN 未设置"
+        has_error=1
+    fi
+    [ "$has_error" -eq 1 ] && { error "请修改 .env 后重新运行"; exit 1; }
+
+    log "配置检查通过"
+    log "  域名: ${VAULTWARDEN_DOMAIN}"
+    log "  邮箱: ${CERTBOT_EMAIL}"
+    log "  注册: ${SIGNUPS_ALLOWED:-true}"
+}
+
+create_dirs() {
+    step "创建数据目录"
+    local data_dir="${VAULTWARDEN_DATA_DIR:-/var/lib/vaultwarden}"
+    local backup_dir="${BACKUP_DIR:-/var/backups/vaultwarden}"
+
+    mkdir -p "$data_dir" "$backup_dir"
+    log "数据目录: $data_dir"
+    log "备份目录: $backup_dir"
+}
+
+start_services() {
+    step "启动 Vaultwarden 服务"
+
+    log "正在拉取镜像..."
+    docker compose pull
+
+    log "正在启动容器..."
+    docker compose up -d
+
+    local port="${VAULTWARDEN_PORT:-8080}"
+    log "等待 Vaultwarden 就绪..."
+    local max_wait=30
+    for i in $(seq 1 "$max_wait"); do
+        if curl -sf "http://127.0.0.1:${port}/alive" &> /dev/null; then
+            log "Vaultwarden 启动成功！"
+            return
+        fi
+        sleep 2
+    done
+    warn "Vaultwarden 可能仍在启动中，请稍后检查: docker compose logs -f"
+}
+
+show_info() {
+    set -a; source .env; set +a
+
+    echo ""
+    echo -e "${GREEN}╔══════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${GREEN}║            Vaultwarden 部署完成！                        ║${NC}"
+    echo -e "${GREEN}╠══════════════════════════════════════════════════════════╣${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  Web 访问:     ${CYAN}https://${VAULTWARDEN_DOMAIN}${NC}"
+    echo -e "${GREEN}║${NC}  管理后台:     ${CYAN}https://${VAULTWARDEN_DOMAIN}/admin${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  数据目录:     ${VAULTWARDEN_DATA_DIR:-/var/lib/vaultwarden}"
+    echo -e "${GREEN}║${NC}  备份目录:     ${BACKUP_DIR:-/var/backups/vaultwarden}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  ${YELLOW}管理员令牌保存在 .env 文件的 ADMIN_TOKEN 中${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  客户端下载:"
+    echo -e "${GREEN}║${NC}    浏览器插件:  ${CYAN}https://bitwarden.com/download/${NC}"
+    echo -e "${GREEN}║${NC}    桌面客户端:  ${CYAN}https://bitwarden.com/download/${NC}"
+    echo -e "${GREEN}║${NC}    移动端:      ${CYAN}https://bitwarden.com/download/${NC}"
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}║${NC}  ${RED}⚠ 客户端连接时，服务器 URL 填写:${NC}"
+    echo -e "${GREEN}║${NC}  ${CYAN}  https://${VAULTWARDEN_DOMAIN}${NC}"
+    echo -e "${GREEN}║${NC}"
+    if [[ "${SIGNUPS_ALLOWED:-true}" == "true" ]]; then
+        echo -e "${GREEN}║${NC}  ${YELLOW}⚠ 注册功能已开启，注册完账号后建议关闭：${NC}"
+        echo -e "${GREEN}║${NC}  ${YELLOW}  修改 .env 中 SIGNUPS_ALLOWED=false${NC}"
+        echo -e "${GREEN}║${NC}  ${YELLOW}  然后 docker compose restart${NC}"
+    fi
+    echo -e "${GREEN}║${NC}"
+    echo -e "${GREEN}╚══════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    echo "常用命令:"
+    echo "  查看日志:    cd $SCRIPT_DIR && docker compose logs -f"
+    echo "  重启服务:    cd $SCRIPT_DIR && docker compose restart"
+    echo "  停止服务:    cd $SCRIPT_DIR && docker compose down"
+    echo "  备份数据:    cd $SCRIPT_DIR && bash backup.sh"
+    echo ""
+}
+
+# =============================================================
+#  主流程
+# =============================================================
+main() {
+    echo -e "${CYAN}"
+    echo " __     __          _ _"
+    echo " \\ \\   / /_ _ _   _| | |___      ____ _ _ __ ____| | ___ _ __"
+    echo "  \\ \\ / / _\` | | | | | __\\ \\ /\\ / / _\` | '__/ _  | |/ _ \\ '_ \\"
+    echo "   \\ V / (_| | |_| | | |_ \\ V  V / (_| | | | (_| |  __/ | | |"
+    echo "    \\_/ \\__,_|\\__,_|_|\\__| \\_/\\_/ \\__,_|_|  \\__,_|\\___|_| |_|"
+    echo -e "${NC}"
+    echo ""
+
+    check_root
+    load_base_env "$BASE_DIR"
+
+    # Step 1: 系统初始化
+    init_system
+
+    # Step 2: 安装 Docker
+    install_docker
+
+    # Step 3: 安装 Nginx
+    install_nginx
+
+    # Step 4: 初始化配置
+    init_env
+
+    # Step 5: 配置 Docker 镜像加速
+    configure_docker_mirrors
+
+    # Step 6: 创建数据目录
+    create_dirs
+
+    # Step 7: 配置防火墙
+    setup_firewall_base
+
+    # Step 8: 配置 SSL 证书
+    setup_ssl_cert "${VAULTWARDEN_DOMAIN}" "${CERTBOT_EMAIL}" "vaultwarden"
+
+    # Step 9: 部署 Nginx 反向代理
+    deploy_nginx_conf "$SCRIPT_DIR/nginx/vaultwarden.conf" "${VAULTWARDEN_DOMAIN}" "vaultwarden"
+
+    # Step 10: 启动服务
+    start_services
+
+    # 显示部署信息
+    show_info
+    log "===== Vaultwarden 部署完成 ====="
+}
+
+main "$@"
diff --git a/vaultwarden/docker-compose.yml b/vaultwarden/docker-compose.yml
new file mode 100644
index 0000000..d4e452d
--- /dev/null
+++ b/vaultwarden/docker-compose.yml
@@ -0,0 +1,29 @@
+services:
+  vaultwarden:
+    image: ${VAULTWARDEN_IMAGE:-vaultwarden/server:latest}
+    container_name: vaultwarden
+    restart: unless-stopped
+    environment:
+      - DOMAIN=https://${VAULTWARDEN_DOMAIN}
+      - SIGNUPS_ALLOWED=${SIGNUPS_ALLOWED:-true}
+      - ADMIN_TOKEN=${ADMIN_TOKEN}
+      - LOG_LEVEL=${LOG_LEVEL:-info}
+      - TZ=Asia/Shanghai
+      - SHOW_PASSWORD_HINT=${SHOW_PASSWORD_HINT:-false}
+      - SENDS_ALLOWED=${SENDS_ALLOWED:-true}
+    volumes:
+      - ${VAULTWARDEN_DATA_DIR:-/var/lib/vaultwarden}:/data
+      - /etc/localtime:/etc/localtime:ro
+    ports:
+      - "127.0.0.1:${VAULTWARDEN_PORT:-8080}:80"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://127.0.0.1:80/alive"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
diff --git a/vaultwarden/nginx/vaultwarden.conf b/vaultwarden/nginx/vaultwarden.conf
new file mode 100644
index 0000000..64962f3
--- /dev/null
+++ b/vaultwarden/nginx/vaultwarden.conf
@@ -0,0 +1,78 @@
+# WebSocket 连接升级映射
+# 有 Upgrade 头时发送 "upgrade"，否则发送空字符串（保持 keepalive）
+# 参考: https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      "";
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name __DOMAIN__;
+
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name __DOMAIN__;
+
+    # SSL 证书
+    ssl_certificate     /etc/letsencrypt/live/__DOMAIN__/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/__DOMAIN__/privkey.pem;
+
+    # SSL 参数
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 10m;
+
+    # 安全头
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header Referrer-Policy "same-origin" always;
+
+    # 上传大小限制（附件上传）
+    client_max_body_size 525M;
+
+    # 反向代理到 Vaultwarden
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        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;
+
+        # WebSocket 支持（Vaultwarden 1.29+ 在同一端口）
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        # 超时设置
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+
+    # 管理员面板（可选：限制访问 IP）
+    # location /admin {
+    #     allow 你的IP;
+    #     deny all;
+    #     proxy_pass http://127.0.0.1:8080;
+    #     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;
+    # }
+}