提拉米线

使用指南 ​

安装 ​

使用 Go ​

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

或从源码构建：

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

使用 Nix (Flake) ​

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

开发者进入开发环境：

bash
nix develop github:tiramission/oci-sync

使用 Home Manager ​

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

nix
{
  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 登录目标仓库，或在配置文件中配置凭据：

bash
docker login registry.example.com

配置文件 ​

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

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

配置文件格式：

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 — 推送到仓库 ​

bash
# 推送目录（不加密）
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

# 推送并设置标签
oci-sync push -l ./mydir -r registry.example.com/myrepo:latest --label app=myapp --label env=prod

# 推送并设置空值标签
oci-sync push -l ./mydir -r registry.example.com/myrepo:latest --label app=

pull — 从仓库拉取 ​

bash
# 拉取（不加密）
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

<name> push / pull / list / delete — 动态快捷命令 ​

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

bash
# 推送目录
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

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

delete — 删除仓库中的文件 ​

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

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

label — 管理标签 ​

bash
# 设置标签
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 ​

bash
# 列出所有 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）。

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

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

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

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

gui — 图形化管理界面 ​

启动基于 gogpu/ui 的桌面图形界面（GUI），以可视化方式管理快捷仓库和 artifacts。

bash
# 启动 GUI 界面
oci-sync gui
  • 分栏布局：左侧 快捷键列表、右侧 artifacts 列表，底部详情面板展示选中 artifact 的完整信息（状态、Tag、Size、Version 等）。
  • 操作按钮：Upload 上传（弹窗输入本地路径、Tag、可选口令加密）、Download 下载（弹窗输入路径，加密内容需口令）、Delete 删除（确认弹窗）、Refresh 刷新列表。
  • 快捷列表：点击左侧 shortcut 加载对应仓库的 artifacts；[E] 前缀标识加密 artifact。

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

bash
# 检索远程仓库中特定路径的文件镜像
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

参数说明 ​

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

工作原理 ​

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）。

label：通过更新 OCI manifest annotations 实现标签管理，支持设置、更新和删除标签。

recent：所有 push/pull/delete/label 操作自动记录到本地 activity cache（~/.cache/oci-sync/activity.json），支持查看和清空历史记录。

gui：基于 gogpu/ui 的桌面图形界面，左侧 shortcuts 列表、右侧 artifacts 列表、底部详情面板，提供 Upload / Download / Delete / Refresh 按钮操作。