Fix exclude list matching and document usage

backup.sh

@@ -316,10 +316,10 @@ pack() {
 
   log "INFO" "开始打包（支持 exclude.list），pigz=${USE_PIGZ}"
   if $USE_PIGZ; then
-    tar --warning=no-file-changed --exclude-ignore="$EXCLUDE_FILE" --exclude-from="$EXCLUDE_FILE" \
+    tar --warning=no-file-changed --exclude-from="$EXCLUDE_FILE" \
       -c "${tar_args[@]}" | pigz > "$ARCHIVE_PATH"
   else
-    tar --warning=no-file-changed --exclude-ignore="$EXCLUDE_FILE" --exclude-from="$EXCLUDE_FILE" \
+    tar --warning=no-file-changed --exclude-from="$EXCLUDE_FILE" \
       -czf "$ARCHIVE_PATH" "${tar_args[@]}"
   fi
   local end; end=$(date +%s)

exclude.list

@@ -1,24 +1,116 @@
-# 常见不需要纳入备份的临时/缓存/日志等
+# ============================================================
+# exclude.list
+# ============================================================
+# 说明：
+# 1. 本文件由 tar --exclude-from 读取，匹配的是“归档内相对路径”，不是绝对路径。
+# 2. 排除目录时，建议同时写：
+#    */dir
+#    */dir/*
+# 3. 如果要排除单个业务文件或业务目录，请优先追加到下面“用户自定义规则”区域。
+
+# ============================================================
+# 用户自定义规则
+# 在下面追加你自己的业务排除项
+#
+# 示例：排除单个文件
+# */project/src/main.js
+#
+# 示例：排除一个目录
+# */project/cache
+# */project/cache/*
+# ============================================================
+
+# ============================================================
+# 默认排除：日志、临时文件、运行时文件
+# ============================================================
 *.log
 *.log.*
 *.tmp
-*.swp
-*.swo
-.cache/
-.npm/_cacache/
-node_modules/
-tmp/
-temp/
-__pycache__/
-.DS_Store
-Thumbs.db
 *.pid
 *.sock
 *.lock
-.idea/
+*.swp
-.vscode/
+*.swo
+.DS_Store
+Thumbs.db
+
+# ============================================================
+# 默认排除：本备份工具可能生成的归档和校验文件
+# 避免把旧备份再次打进新备份包
+# ============================================================
+backup_*.tar.gz
+backup_*.tar.gz.*
+*.sha256
+*.gpg
+
+# ============================================================
+# 默认排除：通用缓存和临时目录
+# ============================================================
+*/.cache
+*/.cache/*
+*/tmp
+*/tmp/*
+*/temp
+*/temp/*
+
+# ============================================================
+# 默认排除：Node.js / 前端相关
+# ============================================================
+*/node_modules
+*/node_modules/*
+*/.npm/_cacache
+*/.npm/_cacache/*
+*/.next
+*/.next/*
+*/.nuxt
+*/.nuxt/*
+
+# ============================================================
+# 默认排除：Python 相关
+# ============================================================
+*/__pycache__
+*/__pycache__/*
+*/.pytest_cache
+*/.pytest_cache/*
+*/.mypy_cache
+*/.mypy_cache/*
+*/.tox
+*/.tox/*
+*/.venv
+*/.venv/*
+*/venv
+*/venv/*
+.coverage
+.coverage.*
+*/coverage
+*/coverage/*
+
+# ============================================================
+# 默认排除：Java / JVM / 通用编译产物
+# ============================================================
 *.o
 *.class
-target/
+*/target
-build/
+*/target/*
-dist/
+*/build
+*/build/*
+*/dist
+*/dist/*
+*/.gradle
+*/.gradle/*
+
+# ============================================================
+# 默认排除：编辑器 / IDE
+# ============================================================
+*/.idea
+*/.idea/*
+*/.vscode
+*/.vscode/*
+
+# ============================================================
+# 默认排除：Terraform / 基础设施缓存
+# ============================================================
+*/.terraform
+*/.terraform/*
+*.tfstate
+*.tfstate.*

readme.md

@@ -1 +1,95 @@
+# backup_OBS
 
+基于 `bash + obsutil` 的 OBS 备份脚本，包含备份上传和历史清理两个入口：
+
+- `backup.sh`：打包目录、生成 `sha256`、上传到 OBS、下载远端校验文件做一致性校验
+- `clean_backups.sh`：按文件名日期清理旧备份
+
+## 配置
+
+先复制模板并填写实际配置：
+
+```bash
+cp env.conf.example env.conf
+```
+
+重点配置项：
+
+- `OBS_BUCKET`：OBS 桶名
+- `LABEL`：机器或业务标识
+- `BACKUP_DIR`：要备份的目录，当前格式为以空格分隔的路径列表
+- `TG_BOT_TOKEN` / `TG_USER_ID`：Telegram 通知配置，可留空
+
+## 使用方式
+
+备份：
+
+```bash
+./backup.sh
+```
+
+仅做打包自检，不上传：
+
+```bash
+./backup.sh --dry-run
+```
+
+检查远端前缀是否可访问：
+
+```bash
+./backup.sh --verify
+```
+
+清理旧备份：
+
+```bash
+./clean_backups.sh --retain-days=5
+```
+
+## exclude.list 规则
+
+`exclude.list` 由 `tar --exclude-from` 读取，匹配的是归档内的相对路径，不是磁盘上的绝对路径。
+
+不要写：
+
+```text
+/root/data/project/src/main.js
+cache/
+```
+
+应该写相对路径或通配规则。
+
+排除单个文件：
+
+```text
+project/src/main.js
+```
+
+或者：
+
+```text
+*/project/src/main.js
+```
+
+排除某类文件：
+
+```text
+*.log
+*.tmp
+```
+
+排除一个目录，建议写两行：
+
+```text
+*/node_modules
+*/node_modules/*
+```
+
+例如排除 `project/cache`：
+
+```text
+*/project/cache
+*/project/cache/*
+```
+
+当前自带的 `exclude.list` 已对常见目录采用这种写法，避免 `.cache/`、`node_modules/` 这类规则匹配不到的问题。