轻量级用户数据同步工具，支持「压缩包上传/下载」与「Git 隐藏引用快照」两种模式，一份二进制即可切换。

---

• 压缩模式：将目录打包为 tar.gz，通过预签名 URL 上传/下载。
• Git 模式：像 chat-cache.sh save/restore 一样，把目录内容存到隐藏 ref（如 refs/cache/userdata），可选推送远端或本地保存。
• 零外部依赖：纯 Go 实现，无需系统 git、tar。
• 双配置入口：命令行参数优先，环境变量兜底，开箱即用。

编译：go build -o userdata ./cmd/userdata 或 go install cnb.cool/zishuo/userdata/cmd/userdata@latest

PLUGIN_TYPE=upload \
CNB_TOKEN=xxx \
CNB_API_ENDPOINT=https://api.cnb.cool \
CNB_REPO_SLUG=zishuo/userdata \
userdata --dir /run/.userdata

PLUGIN_TYPE=download \
CNB_TOKEN=xxx CNB_API_ENDPOINT=... CNB_REPO_SLUG=... \
userdata --dir /run/.userdata

PLUGIN_TYPE=git-save \               # 或 --type backup
GIT_DATA_DIR=/opt/chat/data \        # 要保存的目录
GIT_REPO_DIR=/workspace \            # 仓库所在目录（包含 .git）
CACHE_REF=refs/cache/userdata \     # 隐藏引用
GIT_HTTP_USER=token GIT_HTTP_PASS=xxx \  # 或用 SSH：GIT_SSH_KEY=~/.ssh/id_rsa
userdata

userdata --type git-restore --git-data /opt/chat/data --git-repo /workspace --git-cache-ref refs/cache/userdata

• 通用：

  • --type / PLUGIN_TYPE：upload | download | git-save | git-restore | 别名 backup/restore
  • --timeout / PLUGIN_TIMEOUT：HTTP/Git 操作超时，默认 30s

• 压缩模式（仅在 upload/download 生效）：

  • --dir / PLUGIN_USERDATA_DIR：目标目录（默认当前工作目录）
  • --archive / GZ_FILE_PATH：压缩包路径，默认 /tmp/userdata.tar.gz
  • --use-put / PLUGIN_USE_PUT_OBJECT：true 使用 PUT，默认 POST 表单
  • --size-limit / PLUGIN_UPLOAD_SIZE_LIMIT：字节数上限
  • CNB_TOKEN、CNB_API_ENDPOINT、CNB_REPO_SLUG、PLUGIN_AUTH_TYPE（默认 Bearer）

• Git 模式（仅在 git-save/git-restore 生效）：

  • --git-repo / GIT_REPO_DIR：含 .git 的仓库目录，默认 /workspace
  • --git-data / GIT_DATA_DIR：需要保存/恢复的目录，默认 /opt/chat/data
  • --git-cache-ref / CACHE_REF：隐藏引用名，默认 refs/cache/userdata
  • --git-remote / CACHE_REMOTE：远端名，可留空表示只写本地 ref
  • 认证（任选其一）：
    • HTTP：--git-http-user / GIT_HTTP_USER，--git-http-pass / GIT_HTTP_PASS
    • SSH：--git-ssh-key / GIT_SSH_KEY，--git-ssh-pass / GIT_SSH_PASS
  • 作者信息：--git-author-name / GIT_AUTHOR_NAME，--git-author-email / GIT_AUTHOR_EMAIL

规则：参数优先于环境变量；仅在对应模式校验必要项，互不干扰。

• 压缩模式
  • 打包前会删除旧的 archive 文件；解压与写入时做路径穿越检查。
  • 支持 PUT 与表单 POST 直传，上传大小可选限制。
• Git 模式
  • 构建纯对象树并写入 commit（无父提交，保持脚本行为）；更新 ref 后可选推送 +ref:ref。
  • 恢复时可先 fetch；再将目标目录 RemoveAll 后还原，保证一致性。
  • 支持符号链接、可执行位；不支持设备文件等特殊类型（跳过）。

# 构建
cd /workspace && go build -o userdata ./cmd/userdata

# 假设有一个本地 git 仓库和数据目录
CACHE_REF=refs/cache/test GIT_REPO_DIR=/workspace GIT_DATA_DIR=/tmp/demo-data userdata --type backup
CACHE_REF=refs/cache/test GIT_REPO_DIR=/workspace GIT_DATA_DIR=/tmp/demo-restore userdata --type restore

• 提示缺少 CNB_TOKEN：仅在 upload/download 校验，切换到 git 模式无需此变量。
• Git push 认证失败：确认选择的认证方式（HTTP/SSH）与远端匹配；SSH 密钥需有拉取/推送权限。
• 恢复后目录为空：检查 CACHE_REF 是否存在；可先执行 git-show-ref 或在命令中设置 --git-remote 以 fetch。
• 大目录打包慢：可提前排除不必要目录（当前版本未内置 ignore，可手动临时移除后再上传）。

cmd/userdata         # CLI 入口
internal/app         # 业务编排
internal/config      # 配置解析与校验
internal/archive     # tar.gz 打包/解压
internal/api         # 预签名 HTTP 交互
internal/gitcache    # 隐藏 ref 快照存取（纯 go-git）
docs/                # 需求与设计文档

• 单枚举多模式，避免多可执行文件；参数/环境变量双入口。
• 纯 Go Git（go-git），写对象树+update-ref，跳过工作区操作，性能接近 shell 版本。
• 路径安全与幂等：解压/恢复前清理，防穿越；无父提交，始终覆盖当前 snapshot。

---

欢迎在 Issue 中反馈问题或提 PR 改进。