remote-docker-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{remote_docker_cli-0.2.0 → remote_docker_cli-0.3.1}/.gitignore

@@ -150,4 +150,8 @@ cython_debug/
 /.hatch/
 /build_artifacts/
 
-uv.lock
+.opencode
+uv.lock
+
+# rdocker kaggle notebook staging dir (created by `rdocker kaggle upload`)
+.kaggle/

{remote_docker_cli-0.2.0 → remote_docker_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: remote-docker-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: A CLI tool for managing remote Docker hosts
 Project-URL: Homepage, https://gitee.com/kzhuo/remote-docker
 Project-URL: Issues, https://gitee.com/kzhuo/remote-docker/issues
@@ -24,8 +24,8 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Requires-Dist: click
 Requires-Dist: pyyaml
-Provides-Extra: all
-Requires-Dist: paramiko>=3.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: ssh
 Requires-Dist: paramiko>=3.0; extra == 'ssh'
 Description-Content-Type: text/markdown
@@ -64,6 +64,29 @@ Description-Content-Type: text/markdown
 
 `skopeo copy` 会带上 `--override-arch` 选项，自动按本地机器架构 (`amd64` / `arm64` / ...) 拉取对应镜像清单。
 
+### 可选通道：Kaggle（无需 SSH 跳板机）
+
+```
+本地机器                                    Kaggle (Notebook)
+┌────────────────────┐                     ┌──────────────────────────────┐
+│ docker-compose.yml │                     │  /kaggle/working/<name>/     │
+└────────┬───────────┘                     │   ├── nginx_latest.tar       │
+         │ 解析 + 自动补 :latest            │   ├── redis_7-alpine.tar     │
+         ▼                                 │   └── ...                    │
+   镜像列表  ──`kaggle kernels push`───▶  │  skopeo copy --override-arch │
+   (在 .kaggle/<name>/ 暂存)               │                              │
+                                          │  tar -czf <name>.tar.gz .    │
+                                          └──────────────┬───────────────┘
+                                                         │ output
+                                                         ▼
+                                          ./<name>.tar.gz  ← 本地产物
+                                                         │ docker load
+                                                         ▼
+                                          本地 Docker 引擎
+```
+
+详见 [Kaggle 通道](#kaggle-通道) 一节。
+
 ---
 
 ## 安装
@@ -73,16 +96,16 @@ Description-Content-Type: text/markdown
 ### 使用 pip
 
 ```bash
-pip install remote-docker
+pip install remote-docker-cli
 
 # 可选：启用 paramiko 后端（当前版本使用系统 ssh，可不装）
-pip install "remote-docker[ssh]"
+pip install "remote-docker-cli[ssh]"
 ```
 
 ### 从源码安装（推荐使用 uv）
 
 ```bash
-git clone https://github.com/kzhuo/remote-docker.git
+git clone https://gitee.com/kzhuo/remote-docker.git
 cd remote-docker
 uv sync
 uv pip install -e .
@@ -92,6 +115,7 @@ uv pip install -e .
 
 ```bash
 rdocker --help
+rdocker version          # 查看版本
 ```
 
 ### 远端机器前置条件
@@ -211,7 +235,20 @@ $ rdocker_HOST=override.host rdocker config show
 
 所有动作命令均支持 `--try` 干跑：仅打印将要执行的 ssh / scp / skopeo 命令，不实际执行。
 
-`--name` 缺省规则：
+### `rdocker version`
+
+打印当前安装的 rdocker 版本：
+
+```bash
+$ rdocker version
+rdocker 0.3.1
+```
+
+### 通用选项
+
+- `--host / --user / --port / --key` — 可在任意子命令上直接覆盖 SSH 连接参数（默认从配置文件/环境变量读取），优先级与配置一致。
+
+### `--name` 缺省规则：
 - **compose 模式**（`pull` / `all` / `save` / `fetch` / `cleanup`） → 当前目录最后一级目录名
 - **image 模式**（`spull`） → 镜像去除 tag 后的最后一段（如 `nginx:1.25-alpine` → `nginx`，`registry:5000/myapp:v1` → `myapp`）
 
@@ -285,18 +322,18 @@ rdocker fetch --name mybundle --output-dir ./dist --try
 - `--output-dir, -o` — 本地输出目录（默认：`.`）
 - `--try` — 干跑模式
 
-### `rdocker load [--name <bundle> | --file <tar.gz>] [--try]`
-解压本地 `.tar.gz` 并依次 `docker load` 每个镜像；如果本地文件不存在且指定了 `--name`，会自动从远端 fetch。
+### `rdocker load <tar.gz> [--try]`
+解压本地 `.tar.gz` 并依次 `docker load` 每个镜像。`FILE` 是必填的位置参数；不再支持 `--name`/`--file` 选项，也不再自动从远端 fetch —— 需要远端文件时请显式 `rdocker fetch` / `rdocker kaggle fetch` 之后再 `rdocker load`。
 
 ```bash
-rdocker load --name mybundle
-rdocker load --file ./mybundle.tar.gz
-rdocker load --name mybundle --try                    # 本地无文件时打印会触发的 scp + load
+rdocker load ./mybundle.tar.gz
+rdocker load ./myapp.tar.gz --try                     # 打印将要执行的 tar 解压 + docker load 命令
 ```
 
+参数：
+- `FILE` — 本地 `.tar.gz` 文件路径（必填，必须存在）
+
 选项：
-- `--name, -n` — Bundle 名称（与 `--file` 二选一）
-- `--file, -f` — 本地 `.tar.gz` 文件路径
 - `--try` — 干跑模式
 
 ### `rdocker cleanup [--name <bundle>] [--try]`
@@ -313,6 +350,84 @@ rdocker cleanup --name mybundle --try
 
 ---
 
+## Kaggle 通道
+
+无 SSH 跳板机时，可把镜像拉取与打包放到 Kaggle 的一次性 notebook 上跑，产出的 `.tar.gz` 走 `kaggle kernels output` 下载到本地，再被 `rdocker load` 直接消费。
+
+### 前置条件
+
+1. Kaggle 账号（任意注册方式都可）。
+2. `pip install kaggle`（Python ≥ 3.10）。
+3. 配置 Kaggle 凭据，使 `kaggle config view` 能输出非空 `username`：
+   - 首次会引导你把 API token 放到 `~/.kaggle/credentials.json`，**或**
+   - 设置环境变量 `KAGGLE_USERNAME` / `KAGGLE_KEY`。
+4. 验证：`kaggle config view` 应当看到一行 `- username: <你的名字>`。
+
+### 三步工作流
+
+```bash
+# 1. 解析 compose 并推送一个 notebook 到 Kaggle
+rdocker kaggle upload docker-compose.yml --name myapp
+
+# 2. 等待 kernel 在 Kaggle 网站跑完（通常几分钟）
+#    可在 https://www.kaggle.com/<username>/rdocker-myapp 看日志
+
+# 3. 下载产出的 .tar.gz 到本地
+rdocker kaggle fetch --name myapp
+
+# 4. 加载到本地 Docker
+rdocker load ./myapp.tar.gz
+```
+
+### `rdocker kaggle upload <compose_file> [--name <bundle>] [--try]`
+
+解析 `docker-compose.yml`、在 `.kaggle/<bundle>/` 暂存一个 `rdocker.py` 与 `kernel-metadata.json`、调用 `kaggle kernels push` 推上去。`--try` 模式下不写盘也不推送，只在 stdout 打印将要上传的 notebook 完整内容（含 skopeo 安装段、镜像循环、最终 tar 打包），方便审核。
+
+```bash
+rdocker kaggle upload docker-compose.yml                       # --name 缺省 = cwd 短名
+rdocker kaggle upload docker-compose.yml --name prod --registry-auth admin:pass
+rdocker kaggle upload docker-compose.yml --arch arm64          # 覆盖镜像架构
+rdocker kaggle upload docker-compose.yml --try                 # 只打印不推送
+```
+
+选项：
+- `--name, -n` — Bundle 名称（缺省 = cwd 短名）
+- `--registry-auth, -a` — 镜像仓库认证 `user:pass`
+- `--arch` — 覆盖镜像架构（如 `amd64`、`arm64`、`ppc64le`、`s390x`、`386`、`arm`；缺省 = 本地自动探测）
+- `--try` — 干跑：只打印 notebook 内容
+
+### `rdocker kaggle fetch [--name <bundle>] [--output-dir <dir>] [--try]`
+
+从 Kaggle 下载 `<bundle>.tar.gz` 到本地。下载后可被 `rdocker load <bundle>.tar.gz` 直接消费。
+
+```bash
+rdocker kaggle fetch --name myapp                              # 下载到 cwd
+rdocker kaggle fetch --name myapp --output-dir ./dist           # 下载到 ./dist
+rdocker kaggle fetch --name myapp --try                        # 只打印命令
+```
+
+选项：
+- `--name, -n` — Bundle 名称（缺省 = cwd 短名）
+- `--output-dir, -o` — 本地输出目录（默认：`.`）
+- `--try` — 干跑：只打印 `kaggle kernels output` 命令
+
+### 内部机制
+
+- **username 解析**：`rdocker` 不直接读 `~/.kaggle/credentials.json`，而是 `subprocess.run(["kaggle", "config", "view"])` 并解析 `- username: <name>` 行 —— 自动跟随 Kaggle CLI 自身的配置源优先级（环境变量 > `~/.kaggle/` > `/etc/kaggle.json`）。
+- **kernel 命名**：固定为 `<username>/rdocker-<bundle>`，私有（`is_private: true`），便于 `fetch` 端稳定定位。
+- **架构**：`skopeo --override-arch <local_arch>` 的 arch 在本地计算后注入 notebook，确保拉到的镜像清单与本地 Docker 引擎匹配。
+- **skopeo 兜底**：notebook 第一段是 `which skopeo || apt-get install -y skopeo || pip install skopeo`（Kaggle 基础镜像通常自带，但本工具不依赖此假设）。
+
+### 常见问题
+
+- **kaggle CLI 缺失 / 未配置** → `pip install kaggle` 后 `kaggle config view` 验证。`rdocker` 会把错误指向这两步。
+- **kernel 跑失败** → 在 https://www.kaggle.com/<username>/rdocker-<bundle> 看 stderr；常因镜像仓库私有需 `--registry-auth`，或 compose 中含 Kaggle 网络策略拉不到的镜像。
+- **arch 不匹配** → `rdocker` 默认按本地 `platform.machine()` 注入 `--override-arch`；如需拉取其他架构的镜像，使用 `rdocker kaggle upload --arch <arch>` 覆盖（如 `amd64`、`arm64`）。
+- **output 还没生成** → `kaggle kernels output` 报错时直接看返回的 stderr；常见原因是 kernel 仍在排队（免费版 CPU 偶尔排队几分钟）或已失败。
+- **`.kaggle/` 目录膨胀** → 该目录在 CWD 下，是 `kaggle kernels push` 的暂存区，可随时 `rm -rf .kaggle`。
+
+---
+
 ## 环境变量
 
 | 变量 | 对应配置 | 说明 |
@@ -361,7 +476,9 @@ remote-docker/
 │   └── remote_docker/
 │       ├── __init__.py        # 包元信息 (__version__)
 │       ├── __main__.py        # python -m remote_docker 入口
-│       └── cli.py             # Click CLI 主体
+│       ├── cli.py             # Click CLI 主体
+│       └── tests/             # pytest 测试
+├── openspec/                  # OpenSpec 变更规格（如 add-kaggle-support）
 ├── pyproject.toml             # 项目与依赖配置（hatchling 构建）
 ├── uv.lock                    # uv 锁定文件
 └── README.md

{remote_docker_cli-0.2.0 → remote_docker_cli-0.3.1}/README.md

@@ -32,6 +32,29 @@
 
 `skopeo copy` 会带上 `--override-arch` 选项，自动按本地机器架构 (`amd64` / `arm64` / ...) 拉取对应镜像清单。
 
+### 可选通道：Kaggle（无需 SSH 跳板机）
+
+```
+本地机器                                    Kaggle (Notebook)
+┌────────────────────┐                     ┌──────────────────────────────┐
+│ docker-compose.yml │                     │  /kaggle/working/<name>/     │
+└────────┬───────────┘                     │   ├── nginx_latest.tar       │
+         │ 解析 + 自动补 :latest            │   ├── redis_7-alpine.tar     │
+         ▼                                 │   └── ...                    │
+   镜像列表  ──`kaggle kernels push`───▶  │  skopeo copy --override-arch │
+   (在 .kaggle/<name>/ 暂存)               │                              │
+                                          │  tar -czf <name>.tar.gz .    │
+                                          └──────────────┬───────────────┘
+                                                         │ output
+                                                         ▼
+                                          ./<name>.tar.gz  ← 本地产物
+                                                         │ docker load
+                                                         ▼
+                                          本地 Docker 引擎
+```
+
+详见 [Kaggle 通道](#kaggle-通道) 一节。
+
 ---
 
 ## 安装
@@ -41,16 +64,16 @@
 ### 使用 pip
 
 ```bash
-pip install remote-docker
+pip install remote-docker-cli
 
 # 可选：启用 paramiko 后端（当前版本使用系统 ssh，可不装）
-pip install "remote-docker[ssh]"
+pip install "remote-docker-cli[ssh]"
 ```
 
 ### 从源码安装（推荐使用 uv）
 
 ```bash
-git clone https://github.com/kzhuo/remote-docker.git
+git clone https://gitee.com/kzhuo/remote-docker.git
 cd remote-docker
 uv sync
 uv pip install -e .
@@ -60,6 +83,7 @@ uv pip install -e .
 
 ```bash
 rdocker --help
+rdocker version          # 查看版本
 ```
 
 ### 远端机器前置条件
@@ -179,7 +203,20 @@ $ rdocker_HOST=override.host rdocker config show
 
 所有动作命令均支持 `--try` 干跑：仅打印将要执行的 ssh / scp / skopeo 命令，不实际执行。
 
-`--name` 缺省规则：
+### `rdocker version`
+
+打印当前安装的 rdocker 版本：
+
+```bash
+$ rdocker version
+rdocker 0.3.1
+```
+
+### 通用选项
+
+- `--host / --user / --port / --key` — 可在任意子命令上直接覆盖 SSH 连接参数（默认从配置文件/环境变量读取），优先级与配置一致。
+
+### `--name` 缺省规则：
 - **compose 模式**（`pull` / `all` / `save` / `fetch` / `cleanup`） → 当前目录最后一级目录名
 - **image 模式**（`spull`） → 镜像去除 tag 后的最后一段（如 `nginx:1.25-alpine` → `nginx`，`registry:5000/myapp:v1` → `myapp`）
 
@@ -253,18 +290,18 @@ rdocker fetch --name mybundle --output-dir ./dist --try
 - `--output-dir, -o` — 本地输出目录（默认：`.`）
 - `--try` — 干跑模式
 
-### `rdocker load [--name <bundle> | --file <tar.gz>] [--try]`
-解压本地 `.tar.gz` 并依次 `docker load` 每个镜像；如果本地文件不存在且指定了 `--name`，会自动从远端 fetch。
+### `rdocker load <tar.gz> [--try]`
+解压本地 `.tar.gz` 并依次 `docker load` 每个镜像。`FILE` 是必填的位置参数；不再支持 `--name`/`--file` 选项，也不再自动从远端 fetch —— 需要远端文件时请显式 `rdocker fetch` / `rdocker kaggle fetch` 之后再 `rdocker load`。
 
 ```bash
-rdocker load --name mybundle
-rdocker load --file ./mybundle.tar.gz
-rdocker load --name mybundle --try                    # 本地无文件时打印会触发的 scp + load
+rdocker load ./mybundle.tar.gz
+rdocker load ./myapp.tar.gz --try                     # 打印将要执行的 tar 解压 + docker load 命令
 ```
 
+参数：
+- `FILE` — 本地 `.tar.gz` 文件路径（必填，必须存在）
+
 选项：
-- `--name, -n` — Bundle 名称（与 `--file` 二选一）
-- `--file, -f` — 本地 `.tar.gz` 文件路径
 - `--try` — 干跑模式
 
 ### `rdocker cleanup [--name <bundle>] [--try]`
@@ -281,6 +318,84 @@ rdocker cleanup --name mybundle --try
 
 ---
 
+## Kaggle 通道
+
+无 SSH 跳板机时，可把镜像拉取与打包放到 Kaggle 的一次性 notebook 上跑，产出的 `.tar.gz` 走 `kaggle kernels output` 下载到本地，再被 `rdocker load` 直接消费。
+
+### 前置条件
+
+1. Kaggle 账号（任意注册方式都可）。
+2. `pip install kaggle`（Python ≥ 3.10）。
+3. 配置 Kaggle 凭据，使 `kaggle config view` 能输出非空 `username`：
+   - 首次会引导你把 API token 放到 `~/.kaggle/credentials.json`，**或**
+   - 设置环境变量 `KAGGLE_USERNAME` / `KAGGLE_KEY`。
+4. 验证：`kaggle config view` 应当看到一行 `- username: <你的名字>`。
+
+### 三步工作流
+
+```bash
+# 1. 解析 compose 并推送一个 notebook 到 Kaggle
+rdocker kaggle upload docker-compose.yml --name myapp
+
+# 2. 等待 kernel 在 Kaggle 网站跑完（通常几分钟）
+#    可在 https://www.kaggle.com/<username>/rdocker-myapp 看日志
+
+# 3. 下载产出的 .tar.gz 到本地
+rdocker kaggle fetch --name myapp
+
+# 4. 加载到本地 Docker
+rdocker load ./myapp.tar.gz
+```
+
+### `rdocker kaggle upload <compose_file> [--name <bundle>] [--try]`
+
+解析 `docker-compose.yml`、在 `.kaggle/<bundle>/` 暂存一个 `rdocker.py` 与 `kernel-metadata.json`、调用 `kaggle kernels push` 推上去。`--try` 模式下不写盘也不推送，只在 stdout 打印将要上传的 notebook 完整内容（含 skopeo 安装段、镜像循环、最终 tar 打包），方便审核。
+
+```bash
+rdocker kaggle upload docker-compose.yml                       # --name 缺省 = cwd 短名
+rdocker kaggle upload docker-compose.yml --name prod --registry-auth admin:pass
+rdocker kaggle upload docker-compose.yml --arch arm64          # 覆盖镜像架构
+rdocker kaggle upload docker-compose.yml --try                 # 只打印不推送
+```
+
+选项：
+- `--name, -n` — Bundle 名称（缺省 = cwd 短名）
+- `--registry-auth, -a` — 镜像仓库认证 `user:pass`
+- `--arch` — 覆盖镜像架构（如 `amd64`、`arm64`、`ppc64le`、`s390x`、`386`、`arm`；缺省 = 本地自动探测）
+- `--try` — 干跑：只打印 notebook 内容
+
+### `rdocker kaggle fetch [--name <bundle>] [--output-dir <dir>] [--try]`
+
+从 Kaggle 下载 `<bundle>.tar.gz` 到本地。下载后可被 `rdocker load <bundle>.tar.gz` 直接消费。
+
+```bash
+rdocker kaggle fetch --name myapp                              # 下载到 cwd
+rdocker kaggle fetch --name myapp --output-dir ./dist           # 下载到 ./dist
+rdocker kaggle fetch --name myapp --try                        # 只打印命令
+```
+
+选项：
+- `--name, -n` — Bundle 名称（缺省 = cwd 短名）
+- `--output-dir, -o` — 本地输出目录（默认：`.`）
+- `--try` — 干跑：只打印 `kaggle kernels output` 命令
+
+### 内部机制
+
+- **username 解析**：`rdocker` 不直接读 `~/.kaggle/credentials.json`，而是 `subprocess.run(["kaggle", "config", "view"])` 并解析 `- username: <name>` 行 —— 自动跟随 Kaggle CLI 自身的配置源优先级（环境变量 > `~/.kaggle/` > `/etc/kaggle.json`）。
+- **kernel 命名**：固定为 `<username>/rdocker-<bundle>`，私有（`is_private: true`），便于 `fetch` 端稳定定位。
+- **架构**：`skopeo --override-arch <local_arch>` 的 arch 在本地计算后注入 notebook，确保拉到的镜像清单与本地 Docker 引擎匹配。
+- **skopeo 兜底**：notebook 第一段是 `which skopeo || apt-get install -y skopeo || pip install skopeo`（Kaggle 基础镜像通常自带，但本工具不依赖此假设）。
+
+### 常见问题
+
+- **kaggle CLI 缺失 / 未配置** → `pip install kaggle` 后 `kaggle config view` 验证。`rdocker` 会把错误指向这两步。
+- **kernel 跑失败** → 在 https://www.kaggle.com/<username>/rdocker-<bundle> 看 stderr；常因镜像仓库私有需 `--registry-auth`，或 compose 中含 Kaggle 网络策略拉不到的镜像。
+- **arch 不匹配** → `rdocker` 默认按本地 `platform.machine()` 注入 `--override-arch`；如需拉取其他架构的镜像，使用 `rdocker kaggle upload --arch <arch>` 覆盖（如 `amd64`、`arm64`）。
+- **output 还没生成** → `kaggle kernels output` 报错时直接看返回的 stderr；常见原因是 kernel 仍在排队（免费版 CPU 偶尔排队几分钟）或已失败。
+- **`.kaggle/` 目录膨胀** → 该目录在 CWD 下，是 `kaggle kernels push` 的暂存区，可随时 `rm -rf .kaggle`。
+
+---
+
 ## 环境变量
 
 | 变量 | 对应配置 | 说明 |
@@ -329,7 +444,9 @@ remote-docker/
 │   └── remote_docker/
 │       ├── __init__.py        # 包元信息 (__version__)
 │       ├── __main__.py        # python -m remote_docker 入口
-│       └── cli.py             # Click CLI 主体
+│       ├── cli.py             # Click CLI 主体
+│       └── tests/             # pytest 测试
+├── openspec/                  # OpenSpec 变更规格（如 add-kaggle-support）
 ├── pyproject.toml             # 项目与依赖配置（hatchling 构建）
 ├── uv.lock                    # uv 锁定文件
 └── README.md

{remote_docker_cli-0.2.0 → remote_docker_cli-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "remote-docker-cli"
-version = "0.2.0"
+dynamic = ["version"]
 description = "A CLI tool for managing remote Docker hosts"
 readme = "README.md"
 license = "MIT"
@@ -37,8 +37,8 @@ dependencies = [
 ssh = [
     "paramiko>=3.0",
 ]
-all = [
-    "remote-docker-cli[ssh]",
+dev = [
+    "pytest>=7.0",
 ]
 
 [project.scripts]
@@ -49,13 +49,15 @@ Homepage = "https://gitee.com/kzhuo/remote-docker"
 Issues = "https://gitee.com/kzhuo/remote-docker/issues"
 Repository = "https://gitee.com/kzhuo/remote-docker"
 
+[tool.hatch.version]
+path = "src/remote_docker/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/remote_docker"]
 
 [tool.hatch.build.targets.sdist]
 include = [
     "src/remote_docker",
-    "tests",
     "README.md",
     "LICENSE",
     "pyproject.toml",
@@ -65,4 +67,8 @@ exclude = [
     ".venv",
     "venv",
     "__pycache__",
-]
+]
+
+[tool.pytest.ini_options]
+testpaths = ["src"]
+pythonpath = ["src"]

{remote_docker_cli-0.2.0 → remote_docker_cli-0.3.1}/src/remote_docker/__init__.py

@@ -1,3 +1,3 @@
 """remote-docker: A CLI tool for managing remote Docker hosts."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"