onesystems/bookstackbackup

📚 BookStack Backup Docker

本项目为BookStack提供轻量级容器化备份解决方案，支持导出为PDF格式、上传至Nextcloud WebDAV文件夹（可选），并可通过Nextcloud Talk和邮件发送告警通知（可选）。

🚀 核心功能特性

• 将BookStack书籍导出为PDF格式（默认）
• 支持将备份上传至Nextcloud WebDAV
• 清理旧备份（本地和远程）
• 通过cron实现定时备份
• 多渠道错误通知：
  • 📧 电子邮件通知
  • 💬 Nextcloud Talk机器人通知
• 支持Docker健康检查

🐳 使用方法（Docker Compose）

yaml
version: "3.9"

services:
  bookstack-backup:
    image: docker.xuanyuan.run/bookstack-backup:latest
    container_name: bookstack-backup
    volumes:
      - /etc/timezone:/etc/timezone:ro  # 挂载时区配置，确保时间同步
      - /etc/localtime:/etc/localtime:ro  # 挂载本地时间，确保时间同步
      - ./logs:/logs  # 日志存储目录
      - ./backup:/backup  # 备份文件存储目录
    environment:
      CRON_SCHEDULE: "0 0 * * *"  # cron调度表达式，默认每天凌晨执行
      EXPORT_FORMAT: "pdf"  # 导出格式，目前仅支持pdf
      RETENTION_DAYS: 30  # 备份保留天数，超过自动清理
      BACKUP_DIR: "/backup"  # 本地备份目录
      LOG_DIR: "/logs"  # 日志目录

      # 配置BookStack服务器列表，每行一个服务器，格式：服务器名称|URL|token_id|token_secret
      BOOKSTACK_SERVERS: |
        server1|https://bookstack1.example.com|token_id_1|token_secret_1
        server2|https://bookstack2.example.com|token_id_2|token_secret_2

      NC_WEBDAV_UPLOAD: "off"  # 是否启用Nextcloud WebDAV上传，on/off
      NC_WEBDAV_URL: "https://cloud.example.com/remote.php/dav/files/USERNAME/BookStackBackups"  # WebDAV地址
      NC_USER: "USERNAME"  # Nextcloud用户名
      NC_PASSWORD: "APP_PASSWORD"  # Nextcloud应用密码

      NC_TALK_NOTIFY: "off"  # 是否启用Nextcloud Talk通知，on/off
      NC_TALK_URL: "https://cloud.example.com"  # Nextcloud服务器地址
      NC_TALK_BOT_CHANNEL: "channel_id"  # Talk通知频道ID
      NC_TALK_BOT_SECRET: "secret"  # Talk机器人密钥

      EMAIL_NOTIFY: "off"  # 是否启用邮件通知，on/off
      EMAIL_TO: "admin@example.com"  # 收件人邮箱
      EMAIL_FROM: "bookstack-backup@example.com"  # 发件人邮箱
      SMTP_SERVER: "smtp.example.com"  # SMTP服务器
      SMTP_PORT: 587  # SMTP端口
      SMTP_USER: "smtp-user"  # SMTP用户名
      SMTP_PASS: "smtp-pass"  # SMTP密码
      SMTP_TLS: "on"  # 是否启用TLS，on/off

    healthcheck:
      test: ["CMD", "/app/healthcheck.sh"]  # 健康检查命令
      interval: 5m  # 检查间隔
      timeout: 10s  # 超时时间
      retries: 3  # 重试次数
      start_period: 30s  # 启动等待时间

✅ 配置步骤

1. 配置BookStack API

• 在BookStack管理面板的 设置 > API令牌 中创建令牌
• 确保令牌具有访问 /api/books 和 /api/books/:id/export/pdf 端点的权限

2. 启用WebDAV上传（可选）

• 设置 NC_WEBDAV_UPLOAD=on
• 提供有效的凭据和 NC_WEBDAV_URL（格式示例：https://cloud.example.com/remote.php/dav/files/USERNAME/BookStackBackups）

3. 启用Nextcloud Talk通知（可选）

• 设置 NC_TALK_NOTIFY=on
• 填写 NC_TALK_URL（Nextcloud服务器地址）、NC_TALK_BOT_CHANNEL（目标频道ID）和 NC_TALK_BOT_SECRET（机器人密钥）

4. 启用邮件告警（可选）

• 设置 EMAIL_NOTIFY=on
• 配置SMTP参数：SMTP_SERVER、SMTP_PORT、SMTP_USER、SMTP_PASS 等，以及发件人（EMAIL_FROM）和收件人（EMAIL_TO）***

🤖 创建Nextcloud Talk机器人

如需启用Nextcloud Talk通知，需先创建机器人：

bash
# 配置参数
BOT_NAME="BookStack"  # 机器人显示名称
BOT_SECRET=$(openssl rand -hex 40)  # 生成随机密钥
BOT_BASE_URL="https://cloud.example.com/ocs/v2.php/apps/spreed/api/v1/bot"  # 机器人API基础URL

# 处理名称（小写，移除空格）
BOT_NAME_LOWER=$(echo "$BOT_NAME" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_-')
BOT_URL="${BOT_BASE_URL}/${BOT_NAME_LOWER}"  # 完整机器人URL

# 注册机器人
php occ talk:bot:install \
  --feature message \
  "$BOT_NAME" \
  "$BOT_SECRET" \
  "$BOT_URL" \
  && echo "✅ 机器人安装成功"
echo "🔑 机器人密钥: $BOT_SECRET"
echo "🌐 机器人URL:    $BOT_URL"

将 NC_TALK_BOT_SECRET 环境变量设置为上述命令中生成的 $BOT_SECRET 值。

📁 输出内容

• 日志文件：保存至 /logs/backup_YYYY-MM-DD.log（按日期命名）
• 导出文件：本地存储于 /backup/<server_name>/YYYY-MM-DD/*.pdf（按服务器名称和日期组织）
• 远程备份：若启用WebDAV上传，文件将按相同目录结构存储于Nextcloud中

🧑‍💻 作者

• Michael Kleger
  OneSystems GmbH

  ---

📝 许可证

MIT许可证 - 允许商业和私人免费使用。