云原生开发环境数据持久化工具 - 为 CNB 环境提供多程序数据备份和恢复能力

• 多任务支持: 同时监控多个工具的数据（Claude Code、VS Code、Git 配置等）
• 层级化存储: 基于 CNB 环境变量构建 {repo}/{branch}/{user}/{task} 路径结构，完全隔离
• 实时同步: 自动监听文件变化，实时上传到腾讯云 COS
• 智能恢复: 容器重启时自动从云端恢复数据，保留最新版本
• 灵活配置: 支持 YAML 配置文件和环境变量两种配置方式
• 可靠性保证: 自动重试、防抖动、并发控制，确保数据安全
• 后台运行: 不阻塞前台进程，静默运行

1. 创建配置文件：

# 复制示例配置
cp config.example.yaml ~/.config/cnb-keep-toolkit/config.yaml

# 或使用 CNB 环境配置
cp configs/cnb-config.yaml /opt/cnb/config/config.yaml

2. 配置 COS 认证（环境变量）：

export COS_SECRET_ID=AKIDxxxxx
export COS_SECRET_KEY=xxxxx
export COS_BUCKET_URL=https://your-bucket-1234567890.cos.ap-guangzhou.myqcloud.com
# 格式：https://{bucket-name}-{appid}.cos.{region}.myqcloud.com
# 注意：URL 中已包含 region 信息，无需单独配置 region

3. 运行：

./cnb-keep-toolkit

配置文件支持：

• 多任务定义
• 每个任务独立的监控目录和规则
• 基于 CNB 环境变量的自动路径构建
• 详细配置请参考 配置指南

# 必需配置
export COS_SECRET_ID=AKIDxxxxx
export COS_SECRET_KEY=xxxxx
export COS_BUCKET_URL=https://your-bucket-1234567890.cos.ap-guangzhou.myqcloud.com
# 格式：https://{bucket-name}-{appid}.cos.{region}.myqcloud.com
# 注意：URL 中已包含 region，无需额外配置

# 可选配置
export WATCH_BASE_DIR=~/.claude/
export LOG_LEVEL=info

实时监听文件变化并上传：

export RUN_MODE=sync
./cnb-keep-toolkit

从云端恢复数据：

export RUN_MODE=restore
./cnb-keep-toolkit

在 CNB 环境中，数据会自动恢复和同步：

# 执行恢复脚本（在容器启动时运行）
bash /opt/cnb/scripts/cnb-restore.sh

# 构建当前平台
./build.sh

# 构建所有平台
./build.sh --all

docker build -t cnb-keep-toolkit:latest .

支持多任务、灵活的文件规则、层级化存储。配置文件位置（按优先级）：

1. $CONFIG_FILE 环境变量指定
2. /etc/cnb-keep-toolkit/config.yaml
3. /opt/cnb/config/config.yaml
4. ./config.yaml
5. ~/.config/cnb-keep-toolkit/config.yaml

示例配置：

version: "1.0"
global:
  storage:
    type: cos
    cos:
      secret_id: ${COS_SECRET_ID}
      secret_key: ${COS_SECRET_KEY}
      bucket_url: ${COS_BUCKET_URL}

  base_path: "cnb-toolkit"  # 基础路径，用于环境隔离
  path_template: "${CNB_REPO_SLUG}/${CNB_BRANCH}/${CNB_BUILD_USER}"

tasks:
  - name: claude-code
    enabled: true
    watch_dir: ~/.claude/
    globs: ["**/*"]
    exclude: ["*.tmp", "*.log"]

  - name: vscode-settings
    enabled: true
    watch_dir: ~/.vscode-server/data/User/
    globs: ["settings.json", "keybindings.json"]

完整配置说明请参考：配置文档

环境变量	必需	默认值	说明
COS 配置
COS_SECRET_ID	是	-	腾讯云 SecretId
COS_SECRET_KEY	是	-	腾讯云 SecretKey
COS_BUCKET_URL	是	-	COS Bucket 完整 URL 格式：https://{bucket}-{appid}.cos.{region}.myqcloud.com 示例：https://mybucket-1234567890.cos.ap-guangzhou.myqcloud.com
CNB 环境变量（自动提供）
CNB_REPO_SLUG	-	-	仓库路径 (自动)
CNB_BRANCH	-	-	分支名 (自动)
CNB_BUILD_USER	-	-	构建用户 (自动)
其他配置
CONFIG_FILE	否	-	配置文件路径
LOG_LEVEL	否	info	日志级别
LOG_FORMAT	否	json	日志格式

基于 CNB 环境变量自动构建层级化路径：

{base_path}/{CNB_REPO_SLUG}/{CNB_BRANCH}/{CNB_BUILD_USER}/{task_name}/

路径组成：

• base_path: 环境前缀（dev/prod/cnb-toolkit 等）
• CNB_REPO_SLUG: 仓库路径（自动）
• CNB_BRANCH: 分支名（自动）
• CNB_BUILD_USER: 用户名（自动）
• task_name: 任务名称（配置）

示例（开发环境）：

dev/
└── debug.icu/my-project/
    ├── main/
    │   ├── zhangsan/
    │   │   ├── claude-code/
    │   │   └── vscode-settings/
    │   └── lisi/
    │       └── claude-code/
    └── feature-x/
        └── zhangsan/
            └── claude-code/

多环境隔离：

├── dev/debug.icu/...      # 开发环境
├── test/debug.icu/...     # 测试环境
└── prod/debug.icu/...     # 生产环境

cnb-keep-toolkit/
├── cmd/
│   └── cnb-keep-toolkit/     # 应用入口
├── internal/
│   ├── config/               # 配置管理
│   ├── storage/              # 存储接口和 COS 实现
│   ├── watcher/              # 文件监听器
│   ├── sync/                 # 同步引擎
│   └── logger/               # 日志封装
├── pkg/
│   └── retry/                # 重试机制
└── scripts/
    └── cnb-restore.sh        # CNB 环境恢复脚本

• Config: YAML 配置文件 + 环境变量加载和验证
• Storage: COS 存储抽象接口
• Watcher: 文件监听和防抖动（支持多实例）
• Sync Engine: 同步引擎（管理多个 TaskRunner）
• TaskRunner: 任务运行器（每个任务独立的 Watcher + Uploader + Downloader）
• Retry: 指数退避重试机制

Engine
├── TaskRunner (claude-code)
│   ├── Watcher → ~/.claude/
│   ├── Uploader → COS:/repo/branch/user/claude-code/
│   └── Downloader
├── TaskRunner (vscode-settings)
│   ├── Watcher → ~/.vscode-server/
│   ├── Uploader → COS:/repo/branch/user/vscode-settings/
│   └── Downloader
└── TaskRunner (custom-task)
    ├── Watcher → ~/custom/
    ├── Uploader → COS:/repo/branch/user/custom-task/
    └── Downloader

Task 1: 文件变化 → Watcher → Debouncer → Uploader → COS (path1)
                                                 ↓
                                            SyncState

Task 2: 文件变化 → Watcher → Debouncer → Uploader → COS (path2)
                                                 ↓
                                            SyncState

/{base_path}/
├── debug.icu/my-project/
│   ├── main/zhangsan/
│   │   ├── claude-code/
│   │   │   ├── .claude/
│   │   │   │   ├── sessions/
│   │   │   │   └── config.json
│   │   │   └── .claude-code-workspace
│   │   └── vscode-settings/
│   │       ├── settings.json
│   │       └── keybindings.json
│   └── dev/lisi/
│       └── claude-code/

实际示例（base_path=cnb-toolkit）：

/cnb-toolkit/debug.icu/my-project/main/zhangsan/claude-code/.claude/config.json

# 运行所有测试
go test ./...

# 测试覆盖率
go test -cover ./... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# 运行特定模块测试
go test ./internal/config/...
go test ./internal/watcher/...
go test ./internal/sync/...

# 同步模式日志
tail -f /var/log/cnb-keep-toolkit.log

# 设置详细日志
export LOG_LEVEL=debug
export LOG_FORMAT=text

1. COS 连接失败

   • 检查 COS_SECRET_ID 和 COS_SECRET_KEY 是否正确
   • 检查 COS_BUCKET_URL 格式是否正确
   • 检查网络连接

2. 文件未上传

   • 检查文件是否在监听目录内
   • 检查文件是否匹配排除模式
   • 查看日志确认错误信息

3. 恢复失败

   • 检查 COS 中是否存在数据
   • 检查本地目录权限
   • 查看日志确认错误信息

go mod download
go mod tidy

go fmt ./...
go vet ./...

go get github.com/example/package

MIT License

• Issue: https://github.com/debug-icu/cnb-keep-toolkit/issues