instance-repo 1.3.0.dev0__tar.gz → 1.3.1__tar.gz

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.0.dev0
+Version: 1.3.1
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -58,6 +58,12 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 `profile_overrides={"acr_namespace": ...}`；默认 namespace 由 repo-config 返回，但**必须由部署方
 在 ACR 企业版实例中预建**，SDK 不会创建）。
 
+**公网 ACR registry（runner 不在 VPC 内网时）**：默认使用 repo-config 返回的 `registry`
+（VPC 内网域名）。runner 不在对应 VPC 内时，设环境变量 `IR_ACR_PREFER_PUBLIC=1`（或
+`Repo(profile_overrides={"prefer_public_registry": True})`），SDK 会改走 `public_registry`
+（公网域名）；公网值缺失时静默回落到 VPC 值。也可用 `IR_ACR_PUBLIC_HOST` /
+`profile_overrides={"acr_public_host": ...}` 显式指定公网 registry。
+
 兼容别名表：
 
 | 旧名 | 新名或状态 | 优先级 | 告警 |

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/README.md

@@ -44,6 +44,12 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 `profile_overrides={"acr_namespace": ...}`；默认 namespace 由 repo-config 返回，但**必须由部署方
 在 ACR 企业版实例中预建**，SDK 不会创建）。
 
+**公网 ACR registry（runner 不在 VPC 内网时）**：默认使用 repo-config 返回的 `registry`
+（VPC 内网域名）。runner 不在对应 VPC 内时，设环境变量 `IR_ACR_PREFER_PUBLIC=1`（或
+`Repo(profile_overrides={"prefer_public_registry": True})`），SDK 会改走 `public_registry`
+（公网域名）；公网值缺失时静默回落到 VPC 值。也可用 `IR_ACR_PUBLIC_HOST` /
+`profile_overrides={"acr_public_host": ...}` 显式指定公网 registry。
+
 兼容别名表：
 
 | 旧名 | 新名或状态 | 优先级 | 告警 |

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/__init__.py

@@ -18,7 +18,7 @@ from .errors import (
     TransportError,
 )
 
-__version__ = "1.3.0.dev0"
+__version__ = "1.3.1"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/bootstrap.py

@@ -36,7 +36,8 @@ _logger = logging.getLogger(__name__)
 DISCOVERY_TTL_SECONDS = 3600.0
 
 #: 由自动发现填充的字段（scaffold 两项不在 repo-config 返回范围内，仍须显式提供）。
-DISCOVERABLE_FIELDS = ("oss_bucket", "oss_prefix", "acr_host", "acr_namespace")
+DISCOVERABLE_FIELDS = ("oss_bucket", "oss_prefix", "acr_host",
+                       "acr_public_host", "acr_namespace")
 
 _cache = TTLCache(safety=0.0)
 _lock = threading.Lock()

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/clients/config.py

@@ -76,6 +76,11 @@ ENV_OSS_PREFIX = "IR_OSS_PREFIX"
 ENV_SCAFFOLD_BUCKET = "IR_SCAFFOLD_BUCKET"
 ENV_SCAFFOLD_ROOT = "IR_SCAFFOLD_ROOT"
 
+# 公网 ACR registry：runner 不在 VPC 内网时，可显式切换使用公网 registry。
+ENV_ACR_PUBLIC_HOST = "IR_ACR_PUBLIC_HOST"
+# 是否优先使用公网 registry（"1"/"true"/"on"，大小写不敏感）。
+ENV_ACR_PREFER_PUBLIC = "IR_ACR_PREFER_PUBLIC"
+
 #: v0.8 弃用的手工寻址环境变量 → 建议替代。scaffold 两项不在其中：scaffold 包不在
 #: repo-config 的返回范围内，仍须显式提供。
 DEPRECATED_ADDRESS_ENVS = {
@@ -179,6 +184,7 @@ class Profile:
     name: str
     oss_bucket: str = ""
     acr_host: str = ""
+    acr_public_host: str = ""
     acr_namespace: str = ""
     oss_prefix: str = DEFAULT_OSS_PREFIX
     scaffold_bucket: str = ""
@@ -197,6 +203,21 @@ class Profile:
     #: ``bootstrap.discover()`` 捕获异常时写入；``require()`` 据此在报错消息里
     #: 透传根因，避免"返回里没有 acr_host"这类误导性口径。
     discovery_error: str = ""
+    #: 优先使用公网 ACR registry（默认 False=走 VPC 内网）。runner 不在 VPC
+    #: 内网时置 True，配合 ``acr_public_host``（repo-config 的 public_registry）
+    #: 生效；公网值缺失时静默回落到 ``acr_host``。
+    prefer_public_registry: bool = False
+
+    @property
+    def effective_acr_host(self) -> str:
+        """ACR 操作实际使用的 registry host。
+
+        默认返回 ``acr_host``（repo-config 的 registry，通常是 VPC 内网域名）；
+        ``prefer_public_registry=True`` 且 ``acr_public_host`` 非空时返回公网域名。
+        """
+        if self.prefer_public_registry and self.acr_public_host:
+            return self.acr_public_host
+        return self.acr_host
 
     @property
     def dataset_environment(self) -> str:
@@ -240,12 +261,14 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         storage_env, ENV_STORAGE_ENV, LEGACY_ENV_STORAGE_ENV)
     env_values = {k: os.environ.get(k, "") for k in
                   (ENV_OSS_BUCKET, ENV_ACR_HOST, ENV_ACR_NAMESPACE,
+                   ENV_ACR_PUBLIC_HOST,
                    ENV_OSS_PREFIX, ENV_SCAFFOLD_BUCKET, ENV_SCAFFOLD_ROOT)}
     _warn_deprecated_envs(env_values)
     cfg = {
         "oss_bucket": env_values[ENV_OSS_BUCKET],
         "acr_host": env_values[ENV_ACR_HOST],
         "acr_namespace": env_values[ENV_ACR_NAMESPACE],
+        "acr_public_host": env_values[ENV_ACR_PUBLIC_HOST],
         "oss_prefix": env_values[ENV_OSS_PREFIX] or DEFAULT_OSS_PREFIX,
         "scaffold_bucket": env_values[ENV_SCAFFOLD_BUCKET],
         "scaffold_root": env_values[ENV_SCAFFOLD_ROOT],
@@ -259,19 +282,28 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         sources["api_env"] = "env"
     else:
         sources["api_env"] = ""
+    prefer_public = False
     if overrides:
-        # 只接受已知字段，避免把 api_env 之类误当数据面字段
-        for k in ("oss_bucket", "acr_host", "acr_namespace", "oss_prefix",
-                  "scaffold_bucket", "scaffold_root", "api_base"):
+        # 只接受已知字段，避免把 api_env 之类误当数据面字段；
+        # prefer_public_registry 单独取（非寻址字段，不进 **cfg 传 Profile）。
+        for k in ("oss_bucket", "acr_host", "acr_namespace", "acr_public_host",
+                  "oss_prefix", "scaffold_bucket", "scaffold_root", "api_base"):
             if k in overrides and overrides[k] is not None:
                 cfg[k] = overrides[k]
                 sources[k] = "explicit"
+        if overrides.get("prefer_public_registry") is not None:
+            prefer_public = bool(overrides["prefer_public_registry"])
     if cfg["api_base"]:
         cfg["api_base"] = str(cfg["api_base"]).rstrip("/")
+    if not prefer_public:
+        # 环境变量开关：IR_ACR_PREFER_PUBLIC=1/true/on（大小写不敏感）
+        prefer_public = os.environ.get(ENV_ACR_PREFER_PUBLIC, "").strip().lower() \
+            in ("1", "true", "on")
     return Profile(name=name, api_env=env,
                    cluster=str(cluster_value).strip(),
                    storage_env=normalize_storage_env(storage_value),
                    metadata_model=(metadata_model or "").strip(),
+                   prefer_public_registry=bool(prefer_public),
                    sources=sources, **cfg)
 
 
@@ -323,6 +355,8 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
     if acr := data.get("acr"):
         if acr.get("registry"):
             result["acr_host"] = acr["registry"]
+        if acr.get("public_registry"):
+            result["acr_public_host"] = acr["public_registry"]
         if acr.get("namespace"):
             result["acr_namespace"] = acr["namespace"]
     # api_env 由 apiserver 在 repo-config 响应中下发（omitempty，旧版不返回）。

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/clients/images.py

@@ -48,7 +48,7 @@ class ImageClient:
         计算**目标环境**的引用，配合 :meth:`copy` 做跨环境搬运。
         """
         host = acr_host or bootstrap.require(
-            self._p, "acr_host", action="拼 ACR 镜像引用")
+            self._p, "effective_acr_host", action="拼 ACR 镜像引用")
         ns = namespace or bootstrap.require(
             self._p, "acr_namespace", action="拼 ACR 镜像引用")
         return self._layout(metadata_model).image_ref(

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/clients/instances.py

@@ -377,7 +377,7 @@ class InstancesClient:
             if push_image:
                 # 自带 tar 且会推 ACR：docker_image 记它将被推到的 ACR 目标地址。
                 # 仅在 push_image 时记——否则该 ACR 地址指向从未推送过的镜像，是假的。
-                docker_ref = lay.image_ref(self._p.acr_host, self._p.acr_namespace,
+                docker_ref = lay.image_ref(self._p.effective_acr_host, self._p.acr_namespace,
                                            dataset, instance_id,
                                            version=version, split=split)
         else:
@@ -399,7 +399,7 @@ class InstancesClient:
         if image_release_dst_acr:
             from .. import release as _R  # 局部导入避免循环依赖
             extend_meta = _R.image_release_meta(
-                docker_ref, self._p.acr_host, image_release_dst_acr)
+                docker_ref, self._p.effective_acr_host, image_release_dst_acr)
 
         # ② 写元数据(pending) → 拿稳定 id（register=False 时跳过，用本地 id）
         meta = DatasetInstance(
@@ -702,6 +702,8 @@ class InstancesClient:
                 warm(sts_prefix)
         # 推镜像时同样预热 ACR 凭据缓存（否则首轮各 worker 会并发重复签同一 host）
         if push_image and getattr(self._p, "acr_host", None):
+            # 签名恒用 apiserver 登记的 host（acr_host，VPC）；token 实例级，
+            # 对公网 endpoint 同样有效（prefer_public 时连接走公网、签名仍走这里）。
             try:
                 self._t.get_acr_credentials(self._p.acr_host)
             except Exception:  # noqa: BLE001 — 预热失败不阻断，真正推镜像时再报

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/clients/versions.py

@@ -699,10 +699,10 @@ class VersionsClient:
                                              kw.get("split", "default"))
             kw["recorded_images"] = recorded
             for iid, img in sorted(recorded.items()):
-                if img and not img.startswith(self._p.acr_host + "/"):
+                if img and not img.startswith(self._p.effective_acr_host + "/"):
                     skipped.append({
                         "instance_id": iid, "image": img,
-                        "reason": f"not on source ACR {self._p.acr_host}; "
+                        "reason": f"not on source ACR {self._p.effective_acr_host}; "
                                   f"base/共享镜像不随数据集上架搬运",
                     })
         wf = self.publish(dataset, version, instances=instances, images=images, **kw)
@@ -814,8 +814,8 @@ class VersionsClient:
                     raise SchemaError("images='on' 需要 instances 列表（镜像按实例枚举）")
                 image_dists = R.build_image_distributions(
                     dataset, version, instances,
-                    src_acr=self._p.acr_host, src_namespace=self._p.acr_namespace,
-                    dst_acr=dst.acr_host,
+                    src_acr=self._p.effective_acr_host, src_namespace=self._p.acr_namespace,
+                    dst_acr=dst.effective_acr_host,
                     # 目标命名空间：v0.8 之前解析了 --target-acr-namespace 却只换 host，
                     # 该参数从未生效；这里真正把它传下去。为空则保留源命名空间（旧行为）。
                     dst_namespace=dst.acr_namespace,

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/repo.py

@@ -70,7 +70,9 @@ class Repo:
         self._content = OssContentStore(
             self.transport, self.profile.oss_bucket,
             bucket_factory=bucket_factory)
-        self._image = AcrImageStore(self.transport, runner=runner)
+        self._image = AcrImageStore(
+            self.transport, runner=runner,
+            prefer_public=self.profile.prefer_public_registry)
         # 读路径必须与写路径对称下发 environment 与 metadata_model：
         # ingest 按 storage_env 写 pre 集合、默认 split_first，读若不下发会查 online/
         # version_first 而闭环断裂（历史真实缺陷，见 store/registry.py）。
@@ -308,8 +310,8 @@ class Repo:
             raise SchemaError(
                 "rewrite_task_toml_image 需要目标 oss_bucket（用 target_overrides 提供），"
                 "否则无法把改写后的 content.tgz 直传目标桶")
-        src_acr = self.profile.acr_host
-        dst_acr = dst.acr_host
+        src_acr = self.profile.effective_acr_host
+        dst_acr = dst.effective_acr_host
         dst_ns = dst.acr_namespace
 
         # instance_id → 本地目录（仅 harbor 目录；SWE 是 .json 文件，没有 task.toml）

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo/store/acr.py

@@ -192,10 +192,15 @@ def _pin_digest(ref: str, digest: str) -> str:
 
 
 class AcrImageStore(BaseImageStore):
-    def __init__(self, transport, *, runner: Runner | None = None) -> None:
+    def __init__(self, transport, *, runner: Runner | None = None,
+                 prefer_public: bool = False) -> None:
         self._t = transport
         self._injected_runner = runner is not None
         self._run = runner or _default_runner
+        # prefer_public：runner 不在 VPC 内网时置 True（对应 profile.prefer_public_registry）。
+        # 连接优先公网 endpoint；凭据签名仍用 private canonical host（apiserver acr_profiles
+        # 只登记 VPC host，GetAuthorizationToken 的 token 是实例级、对两个 endpoint 通用）。
+        self._prefer_public = prefer_public
 
     def _deadline(self) -> float:
         return time.monotonic() + _DEFAULT_OPERATION_DEADLINE_SECONDS
@@ -225,9 +230,13 @@ class AcrImageStore(BaseImageStore):
         host = _registry_host(ref)
         route = _plan_acr_route(host)
         canonical = _with_host(ref, route.private_endpoint)
-        candidates = [canonical]
-        if route.public_endpoint and route.public_endpoint != route.private_endpoint:
-            candidates.append(_with_host(ref, route.public_endpoint))
+        if self._prefer_public and route.public_endpoint \
+                and route.public_endpoint != route.private_endpoint:
+            candidates = [_with_host(ref, route.public_endpoint), canonical]
+        else:
+            candidates = [canonical]
+            if route.public_endpoint and route.public_endpoint != route.private_endpoint:
+                candidates.append(_with_host(ref, route.public_endpoint))
         return canonical, tuple(candidates)
 
     def _net_ref(self, ref: str) -> str:
@@ -413,11 +422,14 @@ class AcrImageStore(BaseImageStore):
     def pull(self, ref: str, tar_path: Path, *, overwrite: bool = False) -> str:
         """把远端镜像拉到本地 docker-archive tar；返回实际拉取的 digest 固定引用。
 
-        与 OSS 下载同口径：``pull`` 是**下载动作，强制私网**——只用私网候选，不做公网回退。
+        与 OSS 下载同口径：``pull`` 是**下载动作，默认强制私网**——只用私网候选，不做公网回退。
         私网端点无法确认为标准 ACR 私网地址（自定义 registry），或私网连通性失败时，抛
         ``PrivateNetworkRequired``，绝不静默走公网。
 
-        源引用先经私网 inspect 取得不可变 digest 并以 digest 固定后再拉，避免 tag 在
+        例外：构造时 ``prefer_public=True``（IR_ACR_PREFER_PUBLIC=1，runner 不在 VPC 内网）
+        时改走**公网 endpoint**（仍经标准 ACR 确认；凭据仍用 VPC host 签，token 实例级通用）。
+
+        源引用先经 inspect 取得不可变 digest 并以 digest 固定后再拉，避免 tag 在
         inspect 与 copy 之间被覆盖、导致拉到非预期镜像。
         """
         deadline = self._deadline()
@@ -428,26 +440,29 @@ class AcrImageStore(BaseImageStore):
                 "download requires private data-plane access; registry "
                 f"{_registry_host(ref)} cannot be confirmed as a standard "
                 "private ACR endpoint; public fallback is disabled")
-        private_ref = _with_host(ref, route.private_endpoint)
+        if self._prefer_public:
+            data_ref = _with_host(ref, route.public_endpoint)
+        else:
+            data_ref = _with_host(ref, route.private_endpoint)
 
-        authfile = self._authfile(private_ref, credentials=credentials)
+        authfile = self._authfile(data_ref, credentials=credentials)
         try:
-            inspected = self._inspect(private_ref, authfile, deadline)
+            inspected = self._inspect(data_ref, authfile, deadline)
         finally:
             self._cleanup(authfile)
         if inspected.state is _InspectState.ERROR:
-            error = self._inspect_error(private_ref, inspected, authfile)
+            error = self._inspect_error(data_ref, inspected, authfile)
             if _is_skopeo_connectivity_error(inspected.stderr):
                 raise PrivateNetworkRequired(
-                    "download requires private data-plane access; private "
-                    f"registry {route.private_endpoint} is unreachable; "
+                    "download data-plane access failed; registry "
+                    f"{_registry_host(data_ref)} is unreachable; "
                     "public fallback is disabled", cause=error)
             raise error
         if inspected.state is _InspectState.ABSENT:
-            raise TransportError(f"source image manifest not found: {private_ref}")
+            raise TransportError(f"source image manifest not found: {data_ref}")
         if inspected.digest is None:
             raise TransportError(
-                f"source inspect returned no immutable digest: {private_ref}")
+                f"source inspect returned no immutable digest: {data_ref}")
 
         target = Path(tar_path)
         if target.exists() and not overwrite:
@@ -456,7 +471,7 @@ class AcrImageStore(BaseImageStore):
         if target.parent and not target.parent.exists():
             target.parent.mkdir(parents=True, exist_ok=True)
 
-        pinned = _pin_digest(private_ref, inspected.digest)
+        pinned = _pin_digest(data_ref, inspected.digest)
         authfile = self._authfile(pinned, credentials=credentials)
         try:
             command = self._run_command(
@@ -470,8 +485,8 @@ class AcrImageStore(BaseImageStore):
                     "skopeo copy(reg→archive) failed", command.stderr, authfile)
                 if _is_skopeo_connectivity_error(command.stderr):
                     raise PrivateNetworkRequired(
-                        "download requires private data-plane access; private "
-                        f"registry {route.private_endpoint} is unreachable; "
+                        "download data-plane access failed; registry "
+                        f"{_registry_host(data_ref)} is unreachable; "
                         "public fallback is disabled", cause=cause)
                 raise cause
         finally:

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/instance_repo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.0.dev0
+Version: 1.3.1
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -58,6 +58,12 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 `profile_overrides={"acr_namespace": ...}`；默认 namespace 由 repo-config 返回，但**必须由部署方
 在 ACR 企业版实例中预建**，SDK 不会创建）。
 
+**公网 ACR registry（runner 不在 VPC 内网时）**：默认使用 repo-config 返回的 `registry`
+（VPC 内网域名）。runner 不在对应 VPC 内时，设环境变量 `IR_ACR_PREFER_PUBLIC=1`（或
+`Repo(profile_overrides={"prefer_public_registry": True})`），SDK 会改走 `public_registry`
+（公网域名）；公网值缺失时静默回落到 VPC 值。也可用 `IR_ACR_PUBLIC_HOST` /
+`profile_overrides={"acr_public_host": ...}` 显式指定公网 registry。
+
 兼容别名表：
 
 | 旧名 | 新名或状态 | 优先级 | 告警 |

{instance_repo-1.3.0.dev0 → instance_repo-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.3.0.dev0"
+version = "1.3.1"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"