oci-sync

README

oci-sync

将本地文件或目录同步到 OCI 兼容的镜像仓库中。支持文件/目录、可选加密，支持配置文件凭据和 Docker credential store 认证。

安装

使用 Go

go install github.com/tiramission/oci-sync@latest

或从源码构建：

git clone https://github.com/tiramission/oci-sync.git
cd oci-sync
go build -o oci-sync .

使用 Nix (Flake)

本项目已提供 flake.nix，Nix 用户可直接运行：

nix run github:tiramission/oci-sync -- --help

开发者也可直接进入开发环境：

nix develop github:tiramission/oci-sync

使用 Home Manager

在 flake.nix 中引用 home-manager 模块：

{
  inputs.home-manager.url = "github:nix-community/home-manager";
  inputs.oci-sync.url = "github:tiramission/oci-sync";

  outputs = { self, nixpkgs, home-manager, oci-sync }: {
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      modules = [
        home-manager.nixosModules.home-manager
        {
          home.username = "myuser";
          home.homeDirectory = "/home/myuser";
          programs.oci-sync = {
            enable = true;
            settings = {
              shortcuts = {
                x.repo = "registry.example.com/myteam/files";
              };
            };
          };
        }
        oci-sync.homeModules.oci-sync
      ];
    };
  };
}

前置条件

通过配置文件或 docker login 登录目标仓库。

使用

push — 推送到仓库

# 推送目录（不加密）
oci-sync push --local ./mydir --remote registry.example.com/myrepo:latest

# 推送文件（加密）
oci-sync push --local ./secret.txt --remote registry.example.com/myrepo:encrypted --passphrase mypassword

# 使用简写标志
oci-sync push -l ./mydir -r registry.example.com/myrepo:latest

pull — 从仓库拉取

# 拉取（不加密）
oci-sync pull --remote registry.example.com/myrepo:latest --local ./output

# 拉取并解密
oci-sync pull --remote registry.example.com/myrepo:encrypted --local ./output --passphrase mypassword

# 使用简写标志
oci-sync pull -r registry.example.com/myrepo:latest -l ./output

push / pull / list / delete — 动态快捷命令

动态命令通过配置文件 shortcuts.<name>.repo 定义，只需通过 --tag 指定标签：

# 推送目录
oci-sync x push --local ./mydir --tag latest

# 推送文件并加密
oci-sync x push --local ./secret.txt --tag encrypted --passphrase mypassword

# 拉取到本地目录
oci-sync x pull --tag latest --local ./output

# 拉取并解密
oci-sync x pull --tag encrypted --local ./output --passphrase mypassword

# 列出快捷仓库下的所有 tags
oci-sync x list

# 以 JSON 格式输出
oci-sync x list --format json

# 筛选包含特定标签的镜像
oci-sync x list --label app=myapp

# 删除快捷仓库中的指定 tag
oci-sync x delete --tag old-release

delete — 删除仓库中的文件

# 从远程仓库删除推送的文件
oci-sync delete --remote registry.example.com/myrepo:latest

# 使用简写标志
oci-sync delete -r registry.example.com/myrepo:latest

list — 列出仓库中的文件镜像

# 检索远程仓库中特定路径的文件镜像
oci-sync list --remote registry.example.com/myrepo

# 检索整个注册表下的所有由本工具上传的镜像记录
oci-sync list -r registry.example.com

# 以 JSON 格式输出
oci-sync list -r registry.example.com/myrepo --format json

# 以 YAML 格式输出
oci-sync list -r registry.example.com/myrepo -f yaml

# 筛选包含特定标签的镜像
oci-sync list -r registry.example.com/myrepo --label app=myapp

# 筛选包含特定标签 key 的镜像
oci-sync list -r registry.example.com/myrepo --label env

label — 管理标签

# 设置标签
oci-sync label set --remote registry.example.com/myrepo:tag key1=value1 key2=value2

# 设置空值标签
oci-sync label set --remote registry.example.com/myrepo:tag app=

# 删除标签
oci-sync label unset --remote registry.example.com/myrepo:tag key1 key2

alias — 管理 shortcuts

# 列出所有 shortcuts
oci-sync alias list

# 添加 shortcut
oci-sync alias add x --repo registry.example.com/myteam/files

# 删除 shortcut
oci-sync alias remove x

recent — 查看活动历史

查看 push/pull/delete/label 等操作的历史记录（存储在本地 cache）。

# 查看最近活动（默认 20 条）
oci-sync recent

# 指定数量
oci-sync recent --limit 10

# 指定格式
oci-sync recent --format json
oci-sync recent --format yaml

# 清空历史记录
oci-sync recent --clear

tui — 全屏交互式 TUI 管理

使用全屏分栏终端界面以极佳的视觉交互管理快捷仓库和 artifacts。

# 启动 TUI 界面
oci-sync tui

• 分栏结构：左侧 shortcuts 列表、右侧仓库 tags/artifacts 表格，顶部单行显示当前仓库与计数，底部按上下文显示快捷键提示；选中 artifact 按 Enter 查看完整元数据（Full Name、Digest、Version、Size、Encryption 状态和 Labels）。窄终端（<76 列）自动折叠为单栏。
• 拉取进度：pull 弹窗实时显示下载进度条（百分比 + 已下载/总大小）与当前阶段（解析 / 下载 / 解密 / 解包），进行中可随时 Esc 取消。
• 极简操作：Tab/1/2 切换分栏焦点，↑↓ 或 k/j 导航，Enter 加载/查看详情，/ 过滤 tags，p 拉取/解密（弹窗输入本地路径与密码），d 删除（弹窗确认，默认取消），r 刷新，? 查看全部快捷键，Esc 取消进行中的操作或逐级返回。

gui — 原生桌面 GUI

以原生桌面窗口浏览仓库、拉取、推送和删除 artifact，界面为中文。自 v0.8.0 起提供。

# 启动桌面 GUI
oci-sync gui

• 三栏结构：左侧仓库列表、中间 artifact 表格、右侧详情；底部固定操作栏，按钮始终贴窗口底边，窗口变窄时不会挤走。
• 选中即摘要：操作栏右侧实时显示当前选中项的标签、大小与加密状态，不必回看表格。
• 可撤销的顺序：操作按钮按 推送 / 拉取 / 删除 / 编辑标签 排列，删除夹在两个可撤销操作之间，避免误点。
• 与 CLI 共享实现：GUI 直接复用 CLI 的 push/pull/delete/label 命令，活动历史不会被重复记录，两边看到的是同一份数据。

GUI 使用 MyGo 原生 UI，需要系统图形环境；无图形环境（如纯 SSH 会话）请使用 oci-sync tui。

参数说明

参数	说明
--local, -l	本地文件或目录路径（push）或目标目录（pull）
--remote, -r	OCI 仓库引用 (push/pull/delete) 或注册表引用 (list)
--tag	快捷命令 x push / x pull / x delete 使用的标签
--passphrase	加密/解密口令（可选）
--format, -f	输出格式：table（默认）、json、yaml
--label	设置/筛选标签（格式：key=value，value 可为空；仅 key 时检查 key 是否存在）
--quiet, -q	开启静默模式，仅输出错误信息

配置文件

配置文件使用 YAML 格式，搜索路径如下：

1. 当前工作目录 ./oci-sync.yaml
2. 用户配置目录 ~/.config/oci-sync/oci-sync.yaml

配置文件格式：

shortcuts:
  x:
    repo: registry.example.com/myteam/files

auths:
  registry.example.com:
    username: myuser
    password: mytoken

可用配置项：

配置项	默认值	说明
shortcuts.<name>.repo	-	动态命令的默认仓库地址
auths.<registry>.username	-	该仓库的认证用户名
auths.<registry>.password	-	该仓库的认证密码或令牌

认证优先级：配置文件 auths > Docker credential store

工作原理

push：本地文件/目录 → tar.gz 打包 → [可选] AES-256-GCM 加密 → 推送至 OCI 仓库

pull：从 OCI 仓库检查加密状态 → 校验密码参数（若缺失则快速失败）→ 拉取数据 → [可选] 解密 → 解压 tar.gz → 写入本地

加密使用 scrypt 从口令派生密钥（N=32768），每次加密使用随机 salt 和 nonce，安全可靠。

认证支持配置文件 per-registry 凭据（auths.<registry>），也兼容 Docker credential store（~/.docker/config.json）。

详细设计

见 docs/design.md。