阿里云OSS异地备份适配与门禁

1. 目标

本能力把platform-backup.service生成并校验过的加密归档复制到阿里云OSS，上传后重新下载到受控临时目录并复算SHA-256，只有源归档、远端回读文件和远端摘要文件三者一致才记录verified。

本地备份已经加密，OSS仍应使用私有Bucket、最小权限RAM角色、服务端加密、版本控制、生命周期和必要的跨区域复制。仓库不保存AccessKey、STS令牌或ossutil配置正文。

2. 当前环境状态

目标ECS已安装并校验ossutil 2.3.0，客户端压缩包使用阿里云文档公布的Linux x86_64 SHA-256验证。当前实例没有绑定RAM角色，也没有配置OSS Bucket，因此：

OFFSITE_BACKUP_ENABLED=false；
定时器已安装并保持活动，但任务只记录disabled/not_enabled；
健康监测记录offsite_backup=healthy/not_required；
不把当前状态声明为异地备份完成。

3. 上传与验证流程

选择最新本机加密归档
  → 验证本机外层SHA-256
  → 上传归档到OSS私有路径
  → 上传SHA-256旁路文件
  → 从OSS重新下载归档与摘要
  → 重新计算下载文件SHA-256
  → 三方摘要一致
  → 原子写入platform-offsite-backup-v1状态

上传和下载均固定为单任务、单文件并发，避免在当前2核小规格服务器上争抢资源。大于ossutil阈值的文件使用断点续传，检查点保存在/var/lib/data-terminal-cloud-offsite/checkpoints。

状态文件位于/var/lib/data-terminal-cloud-offsite/status.json，只包含源文件名、OSS对象引用、SHA-256、大小、验证时间和稳定原因，不包含凭据。

4. 安装

cd /opt/data-terminal-cloud/current
chmod 0755 deploy/server/install-ossutil.sh \
  deploy/server/install-offsite-backup.sh \
  deploy/server/sync-backup-offsite.sh
deploy/server/install-offsite-backup.sh
systemctl list-timers platform-offsite-backup.timer --no-pager

安装器固定下载ossutil 2.3.0并校验官方SHA-256；已有同版本时不会重复下载。若服务器没有unzip，使用Python标准库解压。

5. OSS准备

业务方或云管理员需要在阿里云控制台完成：

创建私有OSS Bucket，确定地域、版本控制、服务端加密和生命周期策略；
优先给ECS绑定最小权限实例RAM角色，避免长期AccessKey落盘；
授权该角色仅能向指定Bucket前缀上传、读取和查询备份对象；
如需地域级灾备，为目标Bucket配置跨区域复制；
使用ossutil交互配置或RAM角色模式生成/etc/data-terminal-cloud/ossutilconfig，权限必须为0600 root:root。

当前脚本需要上传后回读，因此至少要具备指定前缀的写入和读取权限。Bucket创建、RAM授权和跨区域复制属于云资源变更，不能通过服务器root账号替代完成。

6. 启用

编辑/etc/data-terminal-cloud/offsite-backup.env：

OFFSITE_BACKUP_ENABLED=true
OFFSITE_BACKUP_REQUIRED=true
OFFSITE_OSS_BUCKET=your-private-backup-bucket
OFFSITE_OSS_PREFIX=data-terminal-cloud/121.41.46.238
OFFSITE_OSS_CONFIG_FILE=/etc/data-terminal-cloud/ossutilconfig

然后执行：

systemctl start platform-offsite-backup.service
systemctl show platform-offsite-backup.service -p Result -p ExecMainStatus
python3 -m json.tool /var/lib/data-terminal-cloud-offsite/status.json
systemctl start platform-health-monitor.service

期望异地状态为verified，健康状态中的offsite_backup为healthy。启用或设为必需后，缺状态、上传失败、回读失败、摘要不一致、源归档不匹配或超过36小时都会令健康检查进入critical。

7. 定时与保留

本机备份默认在02:40执行并带最多45分钟随机延迟；OSS同步默认在04:10执行并带最多30分钟随机延迟。OSS侧历史保留应由Bucket生命周期和版本控制管理，脚本不会主动删除远端对象，避免错误配置扩大为批量删除。

8. 失败语义

原因	含义
`ossutil_missing`	官方客户端未安装
`oss_config_missing`	身份配置不可读
`local_backup_missing`	没有本机加密备份
`local_checksum_failed`	本机归档已损坏
`archive_upload_failed`	OSS归档上传失败
`checksum_upload_failed`	OSS摘要上传失败
`archive_download_verification_failed`	远端归档无法回读
`checksum_download_verification_failed`	远端摘要无法回读
`remote_checksum_mismatch`	回读内容与源归档不一致

失败状态会原子写入状态文件并使systemd任务失败；本机已验证备份不会被删除。

9. 已执行验证

禁用状态：任务成功记录disabled/not_enabled，不访问OSS；
隔离兼容目标：上传归档和摘要、回读并复算，状态为verified且远端有2个文件；
缺身份配置：退出4并记录failed/oss_config_missing；
健康门禁：设为必需但缺远端状态时退出1并记录offsite_backup=critical/status_missing。

隔离兼容目标只验证脚本控制流与摘要闭环，不是阿里云真实Bucket证据。真实门禁必须在配置RAM角色和私有Bucket后重新执行。

5.2 KiB Raw Blame History Unescape Escape