自动导出：加密备份

工作原理

• Pro 套餐：自动导出属于 Pro 套餐。使用一次性验证码的手动完整导出在所有级别中均保持免费。
• 两种方式：导出密钥允许你们那边的脚本（Windows 任务计划程序、Synology、Linux）取回导出。或者你们填写一个目标位置（WebDAV/Nextcloud、SFTP、S3），由我们按计划上传导出。
• 每个俱乐部每天最多一次自动导出——取回和上传合计。
• 始终加密：导出在我们这里保存之前就已加密。取回或上传后我们立即删除，否则在 24 小时后删除。
• 每次自动导出后，所有者都会收到一封包含时间、大小和地址的邮件——也可以改为每周摘要。
• 在管理后台（/admin）的“组织”→“基本资料”→“完整导出”→“自动”选项卡中设置，在 WebApp 或 App 中则通过“设置”→“管理区”→“基本资料”。

安装 age

1. age 是一个小巧的免费加密程序（age-encryption.org）。你们需要在生成密钥和打开备份的电脑上安装它——只负责取回的 NAS 不需要。
2. Windows：在命令提示符或 PowerShell 中输入“winget install FiloSottile.age”。
3. macOS：“brew install age”。Linux：通过包管理器，例如“sudo apt install age”。
4. 检查：“age --version”会显示已安装的版本。

生成密钥

age-keygen -o club-backup.key

Public key: age1…   ← 将这一行填入管理后台

设置加密——逐步说明

1. 打开完整导出的“自动”选项卡，点击“设置加密”。
2. 选择“公钥（推荐）”，粘贴以 age1 开头的那一行。
3. 点击“创建测试文件”。小文件 test-automatischer-export.txt.age 会被保存。
4. 在你们那边解密：“age -d -i club-backup.key test-automatischer-export.txt.age”。会显示一个校验词，例如 K7Q4-M2XD。
5. 输入校验词并点击“确认校验词”。我们会向所有者发送验证码；输入验证码后加密即生效。
6. 这样可以确保你们真的能打开备份——复制错误的密钥现在就会被发现，而不是等到紧急情况时。

用密码代替密钥

也可以不用密钥，而使用至少 12 个字符的密码。此时用“age -d 文件.zip.age”打开文件，age 会提示输入密码。

请注意：为了加密，我们的服务器必须知道密码。我们只以加密形式保存它，但运营方在技术上能够解密。使用公钥则不存在这种可能——因此我们推荐使用密钥。

为脚本创建导出密钥

1. 在“导出密钥”下输入名称，例如“俱乐部会所的 NAS”，并选择有效期（最长 12 个月）。
2. 可选：如果你们有固定 IP 地址，可将其填入“仅限以下 IP 地址”——密钥便只能从那里使用。
3. 点击“创建导出密钥”，并输入邮件中的验证码。
4. 密钥只显示一次。请立即将其保存到供脚本使用的安全位置——不要写在脚本里。
5. 到期前 30 天和 7 天我们会发邮件提醒。“更新”会生成新密钥；旧密钥仍可继续使用 7 天，方便你们从容地修改脚本。

Windows：任务计划程序脚本（PowerShell）

# backup-export.ps1 – 取回加密的完整导出
# Install-Module CredentialManager -Scope CurrentUser   (einmalig / once)
# New-StoredCredential -Target 'drinklist-export' -UserName export -Password '<Export-Schlüssel / export key>' -Persist LocalMachine
$key  = (Get-StoredCredential -Target 'drinklist-export').GetNetworkCredential().Password
$base = 'https://drinklist.app/api/v1'
$h    = @{ Authorization = "Bearer $key" }
$export = Invoke-RestMethod -Method Post -Uri "$base/exports" -Headers $h
do { Start-Sleep -Seconds 30; $state = Invoke-RestMethod -Uri "$base/exports/$($export.id)" -Headers $h } while ($state.status -in 'Waiting','Running')
if ($state.status -ne 'Ready') { throw "Export: $($state.status)" }
$file = "D:\Backup\Verein\komplettexport-$(Get-Date -Format yyyy-MM-dd).zip.age"
Invoke-WebRequest -Uri "$base/exports/$($export.id)/download" -Headers $h -OutFile $file
# 仅在需要时在可信的电脑上打开：age -d -i club-backup.key -o export.zip <文件>

设置 Windows 任务计划程序

1. 将脚本保存为 backup-export.ps1，例如放在 C:\Scripts。用 New-StoredCredential 将导出密钥一次性保存到 Windows 凭据管理器中（脚本第 2 和第 3 行）。
2. 打开任务计划程序 →“创建任务”→ 名称“俱乐部备份”，选择“不管用户是否登录都要运行”。
3. 触发器：每天，例如 03:30。操作：程序“powershell.exe”，参数“-NoProfile -ExecutionPolicy Bypass -File C:\Scripts\backup-export.ps1”。
4. 手动运行一次，检查备份文件夹中是否出现 *.zip.age 文件。

Synology/NAS 或 Linux：cron 脚本

#!/bin/sh
# backup-export.sh – 取回加密的完整导出
set -eu
KEY=$(cat /volume1/scripts/.drinklist-export-key)   # chmod 600
BASE=https://drinklist.app/api/v1
ID=$(curl -fsS -X POST -H "Authorization: Bearer $KEY" "$BASE/exports" | sed -n 's/.*"id":\([0-9]*\).*/\1/p')
while :; do
  STATUS=$(curl -fsS -H "Authorization: Bearer $KEY" "$BASE/exports/$ID" | sed -n 's/.*"status":"\([A-Za-z]*\)".*/\1/p')
  [ "$STATUS" = "Ready" ] && break
  case "$STATUS" in Waiting|Running) sleep 30 ;; *) echo "Export: $STATUS" >&2; exit 1 ;; esac
done
curl -fsS -H "Authorization: Bearer $KEY" -o "/volume1/backup/verein/export-$(date +%F).zip.age" "$BASE/exports/$ID/download"
# NAS 不需要 age——文件只在可信的电脑上打开

Synology：设置任务计划

1. 将导出密钥写入一个文件（例如 /volume1/scripts/.drinklist-export-key），并用“chmod 600”使其仅对备份用户可读。
2. 将脚本保存为 /volume1/scripts/backup-export.sh 并设为可执行（“chmod 700”）。
3. 控制面板 → 任务计划 → 新增 → 计划的任务 → 用户定义的脚本；用户：备份用户；计划：每天 03:30；命令：/volume1/scripts/backup-export.sh。
4. 在 Linux 上只需在 crontab 中添加一行：“30 3 * * * /volume1/scripts/backup-export.sh”。

无需脚本：由我们上传到你们的目标位置

1. 在“目标位置”下选择类型：WebDAV（Nextcloud、安装了 WebDAV Server 套件的 Synology，https 端口 5006）、SFTP 或 S3。
2. Nextcloud：使用文件夹地址，例如 https://cloud.club.org/remote.php/dav/files/backup/drinklist/，以及单独备份用户的应用密码。请先创建该文件夹。
3. SFTP：填写服务器、端口（22 或 2222）、文件夹、用户以及密码或 SSH 私钥。首次测试时我们会记住服务器的密钥——如果它发生变化，出于安全原因我们会中止。
4. S3：端点（留空 = Amazon）、区域、存储桶，以及只允许写入（PutObject）的访问凭据——它既不需要读取也不需要删除权限。
5. 选择频率（每天或每周）和时间——以俱乐部所在时区为准。
6. “测试连接并设置”：我们会写入一个小测试文件。成功后验证码会发送给所有者；输入验证码后目标位置即生效。
7. 如果上传失败，我们会重试三次并发送邮件。连续三次运行失败后，我们会暂停该目标位置，直到你们重新启用。

打开备份（解密）

age -d -i club-backup.key -o full-export.zip komplettexport-2026-10-07.zip.age

age -d -o full-export.zip komplettexport-2026-10-07.zip.age   # 密码方式

安全要点一览

• 导出密钥只能取回加密的导出——不能访问账户、记账或任何其他数据。
• 只有所有者可以创建，并需通过邮件验证码确认；管理员和支持团队都无法创建导出密钥。
• 来自新国家的访问或多次被拒绝的请求会暂停密钥；所有者会收到邮件，可以重新启用或撤销。
• 如果组织因违规被锁定，自动导出将暂停；管理后台中的手动导出仍可使用。
• 所有者变更时，密钥和目标位置保持不变。新所有者会收到邮件，可以撤销它们并重新设置加密。

遇到问题时

• 429“only one automatic export per day”：今天已经有过一次自动导出——明天再试。
• 403“export key paused”：滥用检测暂停了该密钥。所有者可在管理后台点击“重新启用”。
• 下载时出现 409：导出已被取回，或已在 24 小时后删除——请第二天重新请求。
• 423：组织已被锁定；请联系支持团队。
• 除了在脚本中轮询，也可以通过 Webhook 接收“export.ready”事件（管理后台 → 集成）。