更新readme

README.md

@@ -1,23 +1,101 @@
-# OCIFLAB备份脚本
+# OCIFLAB 备份脚本
 
 ## 功能
-每天从https://git.ociflab.icu/Laplace/backup-list拉取whitelist.md
-如果没拉取到，则使用前一天拉取并保存的whitelist文件。
-如果超过三分之一的仓库都拉取错误，则给脚本中设置的server酱3 Pushkey推送警告信息。
-然后根据whitelist.md拉取对应的仓库到backup文件夹进行备份
-压缩成zip，每天定时备份一次，保留7天。
-使用bash。
 
-## whitelist.md文件结构：
+每天从 `指定的网址` 拉取 `whitelist.md`：
 
-~~~
+- 拉取不到时，自动使用前一天保存的白名单缓存作为兜底。
+- 超过 **1/3** 的仓库拉取/更新失败时，通过 **server酱3** 推送告警通知。
+- 白名单第一次拉取失败且无前一天缓存时，同样推送告警。
+- 对白名单中的仓库执行 `git pull --ff-only`（已有）或 `git clone --depth 1`（新仓库），失败后自动重试一次重新克隆。
+- 将所有仓库打包为 `ociflab-backup-YYYYMMDD.zip`，保留最近 **7 天**，过期自动清理。
+
+## 依赖
+
+| 工具 | 用途 |
+|------|------|
+| `bash` | 脚本运行环境 |
+| `git` | 仓库克隆与更新 |
+| `curl` | 拉取白名单 & server酱推送 |
+| `zip` | 打包压缩 |
+
+## 配置
+
+编辑脚本顶部的配置变量：
+
+```bash
+# server酱3 配置（不填则跳过推送）
+SERVERCHAN_UID=""          # 填写你的 UID
+SERVERCHAN_SENDKEY=""      # 填写你的 SendKey
+
+# 白名单地址
+WHITELIST_URL=""
+
+# 保留天数（默认 7 天）
+RETENTION_DAYS=7
+```
+
+## whitelist.md 文件结构
+
+```
 https://git.ociflab.icu/userA/projectA
 https://git.ociflab.icu/userB/projectB
-~~~
+```
 
+每行一个完整的仓库 HTTPS 地址。
 
-## server酱3参考
-~~~bash
-# 一行代码即可调用，中文参数需要UrlEncode，长内容建议使用POST
+## 使用
+
+### 手动执行
+
+```bash
+chmod +x ociflab-backup.sh
+./ociflab-backup.sh
+```
+
+### 定时执行（crontab）
+
+每天凌晨 3 点自动运行，日志输出到文件：
+
+```bash
+crontab -e
+```
+
+添加：
+
+```
+0 3 * * * /bin/bash /path/to/ociflab-backup/ociflab-backup.sh >> /path/to/ociflab-backup/backup.log 2>&1
+```
+
+## 目录结构
+
+```
+ociflab-backup/
+├── ociflab-backup.sh              # 主脚本
+├── whitelist_cache.md             # 当天拉取的白名单缓存
+├── whitelist_cache.md.yesterday   # 前一天缓存（兜底）
+├── work/                          # 仓库克隆工作目录
+├── archives/                      # zip 归档（保留 7 天）
+│   ├── ociflab-backup-20260501.zip
+│   └── ociflab-backup-20260502.zip
+└── README.md
+```
+
+## server酱3 告警
+
+配置 `SERVERCHAN_UID` 和 `SERVERCHAN_SENDKEY` 后，以下场景会推送告警：
+
+| 场景 | 标题示例 |
+|------|----------|
+| 白名单拉取失败且无缓存 | `OCIFLAB备份失败` |
+| 白名单为空 | `OCIFLAB备份失败` |
+| 超 1/3 仓库失败 | `OCIFLAB备份异常 - 5/10 仓库失败` |
+
+未配置 server酱 则仅输出日志，不推送。
+
+## server酱3 参考
+
+```bash
+# 一行代码即可调用，中文参数需要 UrlEncode，长内容建议使用 POST
 curl "https://<uid>.push.ft07.com/send/<sendkey>.send?title=<title>&desp=<desp>"
-~~~
+```