备份与恢复（WebDAV / 数据归档）

本指南面向面板使用者：如何配置 WebDAV 远端备份、设定定时与保留策略、手动上传与直接下载完整归档、从远端下载历史备份，以及换机恢复。

技术细节与 API 见运维手册。

两种备份的定位与区别

	配置 JSON	完整备份归档（WebDAV / 下载 .tar.gz）
入口	设置 → 数据管理 → 数据迁移与完整归档	设置 → 数据管理 → WebDAV 远端备份 / 下载备份包
任务配置	✅	✅（打包在 `.signer` 目录）
登录会话 `sessions/`	❌	✅
数据库 `db.sqlite`	❌	✅（SQLite 部署环境）
面板一键导入	✅	❌（需停止服务后解压覆盖）
敏感密钥	导出时自动脱敏；导入不覆盖服务器已有密钥	随文件原样打包，请妥善保管

仅迁移任务流程与系统参数 → 使用配置 JSON
整机迁移 / 灾难恢复 → 使用完整备份（本页指南）

完整备份不含 .admin_bootstrap_password（避免初始密码随备份文件外泄）。

1. 准备 WebDAV

任意支持 WebDAV 协议的网盘或服务端均可，例如坚果云、Nextcloud、ownCloud、InfiniCLOUD、Alist 或各类 NAS（群晖 Synology、TrueNAS 等）。

在面板填写的 WebDAV URL 一般为「用户文件根路径」，常见示例：

text

https://dav.jianguoyun.com/dav/
https://cloud.example.com/remote.php/dav/files/<你的用户名>
https://nas.your-domain.com:5006/

安全提示：服务端具备 SSRF 出站安全策略，WebDAV URL 必须为公网可解析且非保留私网/回环 IP 的地址。若使用私有 NAS，请配置合规的公网域名或反代解析。

字段	说明
WebDAV URL	须以 `http://` 或 `https://` 开头，支持一键点击快捷预设（坚果云 / Nextcloud / InfiniCLOUD / Alist）
用户名	WebDAV 登录账号（如坚果云应用密码对应邮箱）
密码	首次配置时必填（建议使用网盘生成的应用独立密码）；之后留空表示「保持已保存密码不变」
远端目录	相对路径，默认 `tg-signpulse-backups`；支持多级子目录如 `backups/tg`

密码与 Bot Token 在设置页 不会回显明文（仅提示「已保存」）。换浏览器或清理缓存后重新打开设置，密码框为空属于正常安全行为。

2. 备份目标策略（backup_target）

系统支持通过 备份目标策略 灵活控制备份落点：

策略选项	标识值	行为说明
智能选择 (默认)	`auto`	若配置了 WebDAV 优先上传 WebDAV；未配置 WebDAV 时，支持在面板直接点击「下载当前完整备份包」获取本地归档
仅 WebDAV	`webdav`	仅上传至 WebDAV 服务端；若 WebDAV 未配置则明确拦截并报错

3. 面板配置操作

进入面板设置 → 数据管理，区域划分为三个清晰的标签页：

WebDAV 远端备份：
- 支持点击预设按钮一键填入主流服务商模板（坚果云、Nextcloud、InfiniCLOUD、Alist）。
- 填写连接凭据与存储目录后，点击 测试连接 验证凭据有效性与网络连通性。
- 点击 一键备份至 WebDAV 触发实时全量打包与远端上传。
- 点击 列出远端备份 可查看已上传至网盘的历史备份，并支持逐条流式下载回本地。
- 提供 灾难恢复指引 弹窗，一键复制针对当前系统的解压恢复命令。
定时与保留策略：
- 打开 自动备份 开关。
- 设置 执行间隔（小时，1–168）与 保留份数（远端与本地保留的快照数，默认 3，最大 30）。
- 点击 保存备份设置。下方会实时展示本地自动备份历史及文件体积。
数据迁移与完整归档：
- 下载当前完整备份包：无需离开面板，一键打包并直接下载 .tar.gz 完整备份归档。
- 配置 JSON 迁移：轻量级导出与导入任务配置 JSON。

点 一键备份至 WebDAV、测试连接 或 列出远端备份 时，面板会自动先保存当前表单配置再发起服务端请求，避免表单未保存导致依然使用旧配置。

4. 自动备份工作机制

在「定时与保留策略」中开启自动备份后，调度器会在后台周期性执行任务：

到点后自动打包生成 auto-YYYYMMDD-HHMMSS.tar.gz。
WebDAV 备份场景：
- 上传成功 → 删除本地该副本（节省服务器磁盘空间），并按保留份数清理远端更旧的备份文件。
- 上传失败 → 保留本地文件 便于手动补传，并触发 Telegram Bot 失败告警。
未配置 WebDAV：仅在本地 data/backups/ 目录下按保留份数轮转。

备份失败通知

触发备份失败通知需同时满足：

系统设置 中 Telegram Bot 通知总开关 已开启；
已配置有效的 Bot Token 与 Chat ID。

备份失败通知与「任务失败通知」相互独立：关闭签到任务失败通知不会影响备份失败通知的发送。静默时段内通知会自动跳过。

5. 灾难恢复指南

为避免在线覆盖正在运行的 SQLite 数据库与 Telegram 连接会话导致数据损坏，面板不执行在线热恢复。

你可以直接在面板「设置 → 数据管理 → WebDAV 远端备份」中点击 灾难恢复指引 弹窗，复制针对 Docker 或宿主机环境的标准命令。

标准恢复步骤

获取备份包：从面板下载远端备份文件，或在「数据迁移与完整归档」下载当前完整备份包 tg-signpulse-backup-*.tar.gz。

停止服务：

bash

# Docker Compose 部署：
docker compose stop app
# 或 docker run 部署：
docker stop tg-signpulse

定位数据目录： Docker Compose 部署默认挂载宿主机的 ./data 目录到容器内 /data。

解压覆盖数据：

bash

# 将备份包解压覆盖到宿主机的数据目录 ./data
tar -xzf tg-signpulse-backup-YYYYMMDD-HHMMSS.tar.gz -C ./data

确认权限并启动：确保数据目录读写权限正确后启动容器：
bash
```
docker compose start app
```
1
验证状态：打开面板检查账号列表与任务列表。如个别账号会话失效，按提示重新登录。

PostgreSQL 部署说明

若配置了 APP_DATABASE_URL 使用外部 PostgreSQL 数据库：

备份包内的 db.sqlite 不包含 PostgreSQL 中的业务表数据；
数据库请通过 pg_dump 或云厂商快照独立备份恢复；
sessions/ 登录会话与 .signer 任务配置仍须从完整备份包中恢复。

6. 常见问题

为什么设置中的密码框显示为空？

出于安全合规要求，服务端不会向前端回传已保存的 WebDAV 密码。输入框占位符提示「已保存」即表示后台已持久化凭据；需要变更时直接输入新密码保存即可。

测试连接成功但上传备份失败？

检查账号在远端路径是否具备写入和创建目录的权限；
检查网络代理或网关反向代理是否对大文件上传限制了请求体大小（如 Nginx 的 client_max_body_size）。

自动备份没有在远端生成文件？

确认 自动备份 开关已勾选并点击了 保存备份设置；
检查远端配置是否完整有效；
检查本地 data/backups/ 目录下是否保留了 auto-*.tar.gz（上传失败时会自动保留）；
查看面板日志或 Telegram Bot 是否收到告警通知。

备份与恢复（WebDAV / 数据归档） ​

两种备份的定位与区别 ​

1. 准备 WebDAV ​

2. 备份目标策略（backup_target） ​

3. 面板配置操作 ​

4. 自动备份工作机制 ​

备份失败通知 ​

5. 灾难恢复指南 ​

标准恢复步骤 ​

PostgreSQL 部署说明 ​

6. 常见问题 ​

为什么设置中的密码框显示为空？ ​

测试连接成功但上传备份失败？ ​

自动备份没有在远端生成文件？ ​

相关文档 ​