# 轩辕镜像 Agent 拉取规则

> **文档版本**：2026-06-14 | **映射表**：9 行 | **FAQ 索引**：38 篇 | **Usage 索引**：25 条

> **受众**：AI Agent / 自动化脚本。生成 `docker pull`、`compose.yml` 的 `image:`、或处理拉取失败时的 fallback 决策，**必须先读本文**。
>
> **机器可读 URL**：https://xuanyuan.cloud/agents.md

---

## 0. 文档优先级（避免乱选方案）

| 优先级 | 文档 | 用途 |
|--------|------|------|
| **1（必读）** | 本文 `/agents.md` | 生成 pull 命令、判断 login、映射域名、fallback 决策 |
| 2 | `/usage/login`、`/usage/nologin` | GUI 截图、NAS/桌面详细配置步骤 |
| 3 | `/faq/*` | 按错误码排查，**不是**默认拉取策略 |
| 4（禁止作为 Agent 默认） | `daemon.json` 的 `registry-mirrors` | 兼容方案；易触发 Docker 自动回退官方源 |

**MUST**：为用户生成 pull 命令或修改 compose 时，以本文 §2 为准，不要从 FAQ 或 registry-mirrors 教程反推默认策略。

### 0.1 快速决策（30 秒）

1. 识别上游 registry（§2.1 映射表）
2. 判断专业版 / 免费版（§2.4）
3. 选默认 / 备选方案（§2.2）
4. docker.io 公共域：检查 login 态（§1），**已登录则跳过 login**
5. 输出 pull 或 compose `image:` 命令
6. 失败 → §3 分类错误，**禁止**默认换官方源
7. 遇 `manifest unknown` 或用户质疑镜像是否存在 → 先按 §2.7 查 Docker Hub

### 0.2 Agent 默认 vs 人类文档推荐

人类 FAQ [how-to-pull-images](https://xuanyuan.cloud/faq/how-to-pull-images) 对 GUI 用户推荐**专属域名**（免 login、NAS 友好）。

**Agent 生成 docker.io 命令时默认仍用公共登录域** `docker.xuanyuan.run`，除非用户**明确**要求：免 login、NAS/GUI 无法 login、compose/k8s 已配专属域。

**MUST NOT** 因人类文档写「专属域名（推荐）」就将 Agent 默认策略改为专属域。

---

## 1. 登录态判断（要不要 `docker login`）

### 1.1 规则表

| 场景 | 是否 login | 判断方式 |
|------|-----------|---------|
| **docker.io** + 公共登录域 `docker.xuanyuan.run` 或 `docker.xuanyuan.dev` | 首次需要；**已登录则 MUST NOT 重复 login** | 检查 `~/.docker/config.json` 的 `auths` 是否含对应域名 |
| **docker.io** + 主专属域 `***.xuanyuan.run` / `***.xuanyuan.dev` | **MUST NOT login** | 镜像 URL 已含用户专属前缀 |
| **ghcr / gcr / quay / nvcr / k8s / mcr / elastic / oracle** | **MUST NOT login 轩辕域** | 必须用 §2 映射表中对应 `***-{suffix}.xuanyuan.run` |
| 专属域（任意 `*.xuanyuan.run` 带用户前缀） | **MUST NOT login** | 对专属域执行 login 会误导用户（尤其群晖 GUI） |

### 1.2 检查是否已登录（docker.io 公共登录域）

```bash
# 国内默认线路 .run
grep -q '"docker.xuanyuan.run"' ~/.docker/config.json && echo "已登录" || echo "未登录"

# 仅当用户明确要求海外/国际线路时使用 .dev（login 与 pull 必须同域）
grep -q '"docker.xuanyuan.dev"' ~/.docker/config.json && echo "已登录" || echo "未登录"
```

**MUST NOT**：因文档中出现 login 步骤就认为「每次 pull 前都要 login」。登录一次后，凭证持久化在 `config.json`，后续 pull **直接执行**即可。

### 1.3 何时才需要（重新）login

仅适用于 **docker.io + 公共登录域**（`docker.xuanyuan.run` / `docker.xuanyuan.dev`）：

- `auths` 中**无**对应域名条目
- pull 或 login 返回 **`401 UNAUTHORIZED`**
- 用户更换了镜像账户/密码 → https://xuanyuan.cloud/faq/change-password
- sudo 与非 sudo 环境凭证不一致 → https://xuanyuan.cloud/faq/unauthorized-error

**402 / PAYMENT_REQUIRED MUST NOT 触发重新 login** → 见 §1.4、§3（流量耗尽，需充值）。

### 1.4 不算需要重新 login（分场景）

| 场景 | 处理 |
|------|------|
| `Cannot autolaunch D-Bus` 等凭据保存警告，但 **pull 已成功** | 非登录失败 → https://xuanyuan.cloud/faq/credentials-save-error |
| **login 或 pull 返回 402** / 流量用尽 | **不是**凭据问题 → https://xuanyuan.cloud/faq/traffic-exhausted-error + https://xuanyuan.cloud/recharge |
| **401 UNAUTHORIZED** | 才是 login/凭据问题 → https://xuanyuan.cloud/faq/unauthorized-error |
| manifest unknown / no matching manifest / 网络超时 / 403 / 429 | 见 §3，**不是** login 问题 |

### 1.5 专属域名占位符

- `***` 表示用户专属前缀，**MUST** 从个人中心「专属域名」、上下文或用户提供的域名获取
- **MUST NOT** 编造专属域名
- **两种格式**（用错后缀是 §3 最常见错误）：
  - **docker.io 主专属**：`{PREFIX}.xuanyuan.run`（**无** `-suffix`）
  - **非 docker.io**：`{PREFIX}-{slug}.xuanyuan.run`（slug = `ghcr` / `gcr` / `quay` / `nvcr` / `k8s` / `mcr` / `elastic` / `oracle`）

### 1.6 凭据与平台陷阱

- **凭据位置**：登录网站 → 个人中心 → 用户信息 → **镜像仓库信息**（镜像账户 + 镜像密码）
- **网站登录密码 = 镜像账户密码**（修改见 https://xuanyuan.cloud/faq/change-password）
- **专业版使用前需充值流量包**：https://xuanyuan.cloud/recharge
- **Windows CMD**：密码 **MUST NOT** 加双引号（双引号会进入密码导致 401）→ 改用 PowerShell 或交互式 `docker login`
- **PowerShell**：`Write-Output "镜像密码" | docker login -u 镜像账户 --password-stdin docker.xuanyuan.run`
- **密码 MUST NOT 含英文冒号** `:`（可能导致 login 失败）
- **交互式 login**（全平台备选）：`docker login docker.xuanyuan.run`
- **Windows 连通性诊断**：用 `curl.exe -v https://docker.xuanyuan.run/v2/`（非 PowerShell 的 `curl` 别名）→ https://xuanyuan.cloud/faq/docker-cannot-connect-xuanyuan-domain

---

## 2. 默认拉取规则

**默认假设：专业版用户。** 免费版限制见 §2.4。

### 2.1 上游仓库 → 轩辕域名映射（自动生成，与站内教程同步）

| 上游 registry | 轩辕专属域模式 | 默认 pull 模式 | 需 login | 教程 |
|--------------|---------------|---------------|---------|------|
| `docker.io` | `***.xuanyuan.run`（主专属，免 login） | `docker pull docker.xuanyuan.run/<路径>`（**默认**） | 公共登录域：一次性 login；专属域：否 | [docker-hub](https://xuanyuan.cloud/usage/mirror-tutorial/docker-hub) |
| `ghcr.io` | `***-ghcr.xuanyuan.run` | `docker pull ***-ghcr.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [ghcr](https://xuanyuan.cloud/usage/mirror-tutorial/ghcr) |
| `gcr.io` | `***-gcr.xuanyuan.run` | `docker pull ***-gcr.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [gcr](https://xuanyuan.cloud/usage/mirror-tutorial/gcr) |
| `quay.io` | `***-quay.xuanyuan.run` | `docker pull ***-quay.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [quay](https://xuanyuan.cloud/usage/mirror-tutorial/quay) |
| `nvcr.io` | `***-nvcr.xuanyuan.run` | `docker pull ***-nvcr.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [nvcr](https://xuanyuan.cloud/usage/mirror-tutorial/nvcr) |
| `registry.k8s.io` | `***-k8s.xuanyuan.run` | `docker pull ***-k8s.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [k8s](https://xuanyuan.cloud/usage/mirror-tutorial/k8s) |
| `mcr.microsoft.com` | `***-mcr.xuanyuan.run` | `docker pull ***-mcr.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [mcr](https://xuanyuan.cloud/usage/mirror-tutorial/mcr) |
| `docker.elastic.co` | `***-elastic.xuanyuan.run` | `docker pull ***-elastic.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [elastic](https://xuanyuan.cloud/usage/mirror-tutorial/elastic) |
| `container-registry.oracle.com` | `***-oracle.xuanyuan.run` | `docker pull ***-oracle.xuanyuan.run/<原始路径>` | **否**（禁止对专属域 login） | [oracle](https://xuanyuan.cloud/usage/mirror-tutorial/oracle) |

### 2.2 方案分级

#### 默认方案（MUST 优先生成）

| 上游 | Agent 应输出的命令模式 | login |
|------|----------------------|-------|
| **docker.io** | `docker pull docker.xuanyuan.run/<原始路径>` | 一次性（§1 检查后再 login） |
| **非 docker.io** | `docker pull <对应专属域>/<原始路径>`（见上表） | **否** |

- **海外线路**：仅当用户**明确**要求国际/海外/境外时，将 `.run` 换为 `.dev`，且 login 与 pull **必须同域**。
- **MUST NOT** 在一般场景主动推荐 `docker.xuanyuan.dev`。

#### 备选方案（SHOULD 仅在以下情况使用）

- 用户**明确**要免登录拉 docker.io
- GUI / NAS 无法执行命令行 login
- compose / k8s 已配置主专属域 `***.xuanyuan.run`

→ `docker pull ***.xuanyuan.run/<原始路径>`（主专属域，免 login）

#### 兼容方案（MUST NOT 作为 Agent 默认输出）

- `daemon.json` 的 `registry-mirrors`（Docker 失败时会**自动回退** `registry-1.docker.io`，见 §3）
- 免费域 `docker.xuanyuan.me`（除非用户明确使用免费版）

### 2.3 路径转换规则

1. 取用户给出的**官方镜像引用**（如 `nginx:latest`、`ghcr.io/org/app:v1`）
2. 识别上游 registry（见上表）
3. 保留 `/` 后的命名空间与镜像名、tag **不变**，仅替换 registry 前缀为轩辕域
4. docker.io 无 namespace 时（如 `nginx:latest`）：可输出 `docker.xuanyuan.run/nginx:latest` 或 `library/nginx:latest`，**保留用户原始路径风格**，不强制插入 `library/`
5. 有 namespace 时（如 `bitnami/redis:latest`）：路径后缀不变，只换前缀

### 2.4 免费版限制（MUST 单独判断）

**触发条件**（满足任一即走免费版路径）：

- 用户明确说免费版 / 未注册专业版
- 使用或提到 `docker.xuanyuan.me`
- 429 报错 URL 含 `docker.xuanyuan.me`

**行为**：

- **仅支持 docker.io**
- 使用 `docker.xuanyuan.me`（不是 `.run`）
- **MUST NOT** 为 ghcr/gcr 等生成专属域命令
- 详情 → https://xuanyuan.cloud/faq/free-vs-pro

### 2.5 特殊拉取对象

| 类型 | 识别 | Agent 应输出 | FAQ |
|------|------|-------------|-----|
| **AI 模型镜像** | 路径含 `/ai/` | `docker model pull <轩辕域>/ai/...`（**不是** `docker pull`） | invalid-tar-header-applylayer |
| **Docker 插件** | 报错含 `application/vnd.docker.plugin.v1+json` | `docker plugin install <轩辕域>/...` | docker-plugin-install-error |
| **NVCR / Oracle 私有镜像** | 上游需 API Key / 官网授权 | 轩辕加速**不改变**上游权限；私有镜像仍需上游认证 | mirror-tutorial 各页 cautions |

### 2.6 非 Docker CLI 场景（仅索引，MUST NOT 默认输出 registry-mirrors）

| 场景 | Agent 指引 | 人类教程 |
|------|-----------|---------|
| **Docker Compose** | `image:` 写**完整轩辕域名**；多 registry 各用对应专属域后缀 | https://xuanyuan.cloud/usage/docker-compose |
| **containerd / K8s / K3s** | 配置语法不同于 `docker pull`；用 registries.yaml / hosts.toml | https://xuanyuan.cloud/usage/containerd 、 https://xuanyuan.cloud/usage/k3s |
| **Podman** | 类似 Docker，域名规则同 §2 | https://xuanyuan.cloud/usage/podman |
| **Singularity / Apptainer** | `singularity pull xxx.sif docker://{轩辕域}/{路径}` | https://xuanyuan.cloud/usage/singularity |
| **群晖 / NAS GUI** | 优先专属域；**禁止**对专属域 login | https://xuanyuan.cloud/usage/synology |
| **Linux 一键安装** | `bash <(wget -qO- https://xuanyuan.cloud/docker.sh)` | https://xuanyuan.cloud/usage |

### 2.7 Docker Hub 镜像与 tag 存在性校验（仅 docker.io）

当需要确认 **Docker Hub（docker.io）** 上镜像或 tag 是否存在时（如 `manifest unknown` 排查、用户提供的镜像名可疑、站内搜不到镜像），**MUST** 请求 **hub.docker.com** 页面判断，**不要**仅凭轩辕站内搜索或猜测。

#### 2.7.1 校验镜像（仓库）是否存在

构造仓库页 URL：`https://hub.docker.com/r/{namespace}/{repository}/`

| 用户给出的引用 | Hub 页面 URL |
|---------------|-------------|
| `nginx` / `nginx:latest`（官方镜像，无 namespace） | https://hub.docker.com/r/library/nginx/ |
| `library/nginx` | https://hub.docker.com/r/library/nginx/ |
| `atlassian/confluence` | https://hub.docker.com/r/atlassian/confluence/ |
| `bitnami/redis:7.0` | https://hub.docker.com/r/bitnami/redis/ |

**判定**：

- 页面**正常响应**（能打开仓库 Overview，非 404 / 明显「找不到」页）→ **镜像存在**
- **无法正常打开**或明确不存在 → **镜像不存在**；**MUST NOT** 继续 retry 换源，应提示用户核对镜像名/namespace

**MUST NOT**：用 `docker.xuanyuan.run` / 轩辕站内搜索代替 Hub 存在性判断（站内索引与 Hub 全量不同步，见 https://xuanyuan.cloud/faq/image-not-found-in-search）。

#### 2.7.2 校验某个 tag 是否存在

在确认仓库存在后，打开 **Tags 页**：`https://hub.docker.com/r/{namespace}/{repository}/tags`

| 示例 | Tags 页 URL |
|------|------------|
| `atlassian/confluence:9.2.7-ubi9` | https://hub.docker.com/r/atlassian/confluence/tags |
| `library/nginx:1.31.1` | https://hub.docker.com/r/library/nginx/tags |

在 Tags 页内容中**查找目标 tag**（如 `9.2.7-ubi9`、`latest`）：

- **找到** → tag 存在；若轩辕 pull 仍 `manifest unknown`，优先查 §3.1 域名后缀、Docker 版本，**而非**认定镜像不存在
- **未找到** → tag 不存在；建议用户改用 Tags 页上存在的 tag，**禁止**盲目 fallback 官方源

#### 2.7.3 Agent 行为摘要

1. `manifest unknown` → 先 §2.7 查 Hub 仓库与 tag，再查专属域后缀（§3.3 第 2 步）
2. 仓库不存在 → 停止生成 pull；提示核对命名空间/镜像名
3. 仓库存在、tag 不存在 → 列出 Tags 页可见 tag 或请用户确认版本
4. **非 docker.io**（ghcr.io 等）→ 本文 §2.7 **不适用**；应查对应上游 registry 文档或让用户确认官方路径

---

## 3. Fallback 规则（保守策略）

**MUST NOT**：pull 失败后**默认**切换官方 `docker.io` 或删除轩辕前缀。

### 3.1 manifest 类错误（必须先区分）

| 报错 | 含义 | Agent 动作 | FAQ |
|------|------|-----------|-----|
| **`manifest unknown`** | 镜像名/tag 不存在，或 Docker 版本过低，或专属域后缀错误 | **先** §2.7 查 hub.docker.com 仓库与 tag；再查 Docker 20+、域名后缀 | manifest-unknown-error |
| **`no matching manifest for linux/amd64`** 等 | **CPU 架构不匹配**，与镜像源无关 | 换多架构镜像、`--platform`；**禁止**换官方源 | no-matching-manifest-architecture |

### 3.2 错误分流表（自动生成）

| 报错关键词 / 场景 | Agent 动作 | FAQ |
|------------------|-----------|-----|
| 402 / PAYMENT_REQUIRED / capacity has use up | 失败时分流 | https://xuanyuan.cloud/faq/traffic-exhausted-error |
| 410 Gone | 失败时分流 | https://xuanyuan.cloud/faq/410-gone-error |
| manifest unknown（先查 hub.docker.com 仓库/tag） | 失败时分流 | https://xuanyuan.cloud/faq/manifest-unknown-error |
| docker search 超时或失败 | 失败时分流 | https://xuanyuan.cloud/faq/docker-search-custom-domain-error |
| 401 / UNAUTHORIZED | 失败时分流 | https://xuanyuan.cloud/faq/unauthorized-error |
| registry-mirrors 配置了仍走官方 | 禁止作为默认策略 | https://xuanyuan.cloud/faq/registry-mirrors-not-working |
| DNS 解析超时 | 失败时分流 | https://xuanyuan.cloud/faq/dns-timeout-error |
| TLS / SSL / 证书验证失败 | 失败时分流 | https://xuanyuan.cloud/faq/tls-certificate-error |
| KYSEC 权限不够 | 失败时分流 | https://xuanyuan.cloud/faq/kylin-v10-kysec-permission-error |
| application/vnd.docker.plugin.v1+json | 失败时分流 | https://xuanyuan.cloud/faq/docker-plugin-install-error |
| 429 Too Many Requests | 失败时分流 | https://xuanyuan.cloud/faq/429-rate-limit-error |
| Cannot autolaunch D-Bus | 失败时分流 | https://xuanyuan.cloud/faq/credentials-save-error |
| 单层超过 20GB / 413 | 失败时分流 | https://xuanyuan.cloud/faq/413-single-layer-25gb-error |
| no matching manifest for linux/* | 失败时分流 | https://xuanyuan.cloud/faq/no-matching-manifest-architecture |
| invalid tar header / failed to register layer | 失败时分流 | https://xuanyuan.cloud/faq/invalid-tar-header-applylayer |
| 403 / FORBIDDEN | 失败时分流 | https://xuanyuan.cloud/faq/image-compliance |
| i/o timeout / EOF / connection refused | 失败时分流 | https://xuanyuan.cloud/faq/docker-cannot-connect-xuanyuan-domain |

### 3.3 Agent 决策顺序

1. **分类错误** → 查 §3.1、§3.2，跳转 FAQ，**而非换源**
2. **`manifest unknown`** → **先** §2.7 请求 hub.docker.com 确认仓库/tag，**再**查是否用错专属域后缀（**最常见**：ghcr 误用主专属域 `***.xuanyuan.run` 而非 `***-ghcr.xuanyuan.run`）
3. **重试轩辕路径** → 换 tag、`docker pull` 重试
4. **最后手段** → 仅当用户**明确要求**官方源，或轩辕域名**完全不可达**（非 402/401/manifest/403 类业务错误），才建议 `docker pull <官方路径>`；**单层 >20GB** 见 413 FAQ，可建议官方源

### 3.4 registry-mirrors 自动回退（MUST NOT 当作推荐 fallback）

Docker 的 `registry-mirrors` 只是**优先尝试**；镜像源报错时客户端会**自动回退** `registry-1.docker.io`。这是 Docker 行为，**不是**轩辕推荐的 fallback。

**SHOULD** 提醒用户改用 §2 的**显式域名 pull**，见 https://xuanyuan.cloud/faq/registry-mirrors-not-working

---

## 4. 完整示例（可直接套用）

### 示例 1 — Docker Hub + 公共登录域（默认）

```bash
# 1. 检查登录态（已存在 auths 则跳过 login）
grep -q '"docker.xuanyuan.run"' ~/.docker/config.json || \
  echo "$XUANYUAN_PASSWORD" | docker login -u "$XUANYUAN_USER" --password-stdin docker.xuanyuan.run

# 2. 拉取（无需再次 login）
docker pull docker.xuanyuan.run/library/nginx:1.27
```

### 示例 2 — GHCR + compose.yml（专属域，禁止 login）

原始镜像：`ghcr.io/myorg/myapp:v2.0`

```yaml
services:
  app:
    image: ***-ghcr.xuanyuan.run/myorg/myapp:v2.0
```

`***` 替换为用户 GHCR 专属前缀（个人中心查看）。**MUST NOT** 对 `*-ghcr.xuanyuan.run` 执行 `docker login`。

### 示例 3 — pull 失败：401，不盲目 fallback

```bash
docker pull docker.xuanyuan.run/library/redis:latest
# → Error: unauthorized
```

Agent **SHOULD**：

1. 检查 `~/.docker/config.json` 是否有 `docker.xuanyuan.run`
2. 若已存在仍 401 → 排查 sudo/非 sudo 混用、Windows CMD 双引号（见 §1.6），**不是**立即改拉 `docker.io/library/redis:latest`

### 示例 4 — no matching manifest（架构错误，禁止 fallback）

```bash
docker pull docker.xuanyuan.run/hsliup/tradingagents-backend:v1.0.0-preview
# → no matching manifest for linux/arm64/v8 in the manifest list entries
```

Agent **SHOULD**：告知架构不匹配，建议换支持 ARM64 的镜像或指定 `--platform`；**MUST NOT** 改拉 `docker.io/...` 或换镜像源。

### 示例 5 — 免费版

```bash
docker pull docker.xuanyuan.me/nginx:latest
```

无 login；**MUST NOT** 为免费版用户生成 ghcr 专属域命令。

### 示例 6 — 多 registry compose.yml

```yaml
services:
  web:
    image: docker.xuanyuan.run/library/nginx:1.27
  app:
    image: ***-ghcr.xuanyuan.run/myorg/myapp:v2.0
```

### 示例 7 — manifest unknown：先查 Docker Hub 再改命令

用户要拉 `atlassian/confluence:9.2.7-ubi9`，轩辕 pull 报 `manifest unknown`。

Agent **SHOULD**：

1. 打开 https://hub.docker.com/r/atlassian/confluence/ → 正常响应，**仓库存在**
2. 打开 https://hub.docker.com/r/atlassian/confluence/tags → 搜索 `9.2.7-ubi9`
   - 若存在 → 检查是否误用 `***.xuanyuan.run` 拉 ghcr 类路径、或 Docker 版本
   - 若不存在 → 告知 tag 无效，建议改用 Tags 页上列出的可用 tag
3. **MUST NOT** 因 manifest unknown 立即改拉 `docker.io/atlassian/confluence:...` 或删除轩辕前缀

---

## 5. 人类文档索引（细节与 GUI，不改变 §2 默认策略）

### 附录 A — Usage 场景索引（自动生成）

| 分类 | 教程 | 用途 | URL |
|------|------|------|-----|
| Docker | 登录仓库拉取 | 登录认证 · 私有仓库 | https://xuanyuan.cloud/usage/login |
| Docker | 专属域名拉取 | 免登录 · 高速拉取 | https://xuanyuan.cloud/usage/nologin |
| Docker | Linux | Docker 镜像配置 | https://xuanyuan.cloud/usage/linux |
| Docker | Windows / Mac | Docker Desktop 配置 | https://xuanyuan.cloud/usage/desktop |
| Docker | MacOS OrbStack | OrbStack 容器 | https://xuanyuan.cloud/usage/orbstack |
| Docker | Docker Compose | Compose 项目配置 | https://xuanyuan.cloud/usage/docker-compose |
| NAS | 群晖 | Synology 配置 | https://xuanyuan.cloud/usage/synology |
| NAS | 飞牛 | fnOS 镜像配置 | https://xuanyuan.cloud/usage/feiniu |
| NAS | 绿联 | 绿联 NAS | https://xuanyuan.cloud/usage/lvlian |
| NAS | 威联通 | QNAP 配置 | https://xuanyuan.cloud/usage/weiliantong |
| NAS | 极空间 | 极空间 NAS | https://xuanyuan.cloud/usage/jikongjian |
| 企业仓库 | 其他仓库 | ghcr · Quay · nvcr | https://xuanyuan.cloud/usage/mirror-tutorial |
| 企业仓库 | Harbor 镜像源 | Proxy Repository 对接 | https://xuanyuan.cloud/usage/harbor |
| 企业仓库 | Portainer 镜像源 | Registries 配置 | https://xuanyuan.cloud/usage/portainer |
| 企业仓库 | Nexus 镜像源 | Docker Proxy 缓存 | https://xuanyuan.cloud/usage/nexus |
| 开发工具 | Dev Containers | VS Code 开发容器 | https://xuanyuan.cloud/usage/devcontainer |
| 开发工具 | Podman | Podman 配置指南 | https://xuanyuan.cloud/usage/podman |
| 开发工具 | Singularity / Apptainer | HPC 科学计算容器 | https://xuanyuan.cloud/usage/singularity |
| Kubernetes | K8s Containerd | Kubernetes · Containerd | https://xuanyuan.cloud/usage/containerd |
| Kubernetes | K3s | 轻量级集群 | https://xuanyuan.cloud/usage/k3s |
| 面板 / 网络 | 爱快路由 | iKuai 镜像加速 | https://xuanyuan.cloud/usage/ikuai |
| 面板 / 网络 | 宝塔面板 | 一键配置镜像源 | https://xuanyuan.cloud/usage/baota |
| AI | 用 AI 使用轩辕镜像 | agents.md · AI 对话 · 提示词 | https://xuanyuan.cloud/usage/agents |
| 一键安装 | 一键安装 Docker | Linux Docker 一键安装 | https://xuanyuan.cloud/install/linux |
| 安装 | Linux 一键安装配置脚本 | 自动安装 Docker 并配置轩辕镜像源 | https://xuanyuan.cloud/docker.sh |

### 附录 B — FAQ 排错索引（自动生成）

#### 配置与原理类

| 标题 | Agent 动作 | URL |
|------|-----------|-----|
| mirrors 不生效 | 禁止作为默认策略 | https://xuanyuan.cloud/faq/registry-mirrors-not-working |
| 去掉域名前缀 | 背景参考 | https://xuanyuan.cloud/faq/remove-domain-prefix |
| 指定架构拉取 | 背景参考 | https://xuanyuan.cloud/faq/pull-multi-architecture |
| 拉取速度原因 | 背景参考 | https://xuanyuan.cloud/faq/image-pull-speed-factors |
| latest 与「最新」 | 背景参考 | https://xuanyuan.cloud/faq/docker-latest-tag-not-newest |

#### 错误码

| 标题 | Agent 动作 | URL |
|------|-----------|-----|
| manifest unknown | 失败时分流 | https://xuanyuan.cloud/faq/manifest-unknown-error |
| 402 与流量用尽 | 失败时分流 | https://xuanyuan.cloud/faq/traffic-exhausted-error |
| 410 Gone | 失败时分流 | https://xuanyuan.cloud/faq/410-gone-error |
| 401 认证失败 | 失败时分流 | https://xuanyuan.cloud/faq/unauthorized-error |
| 429 限流 | 失败时分流 | https://xuanyuan.cloud/faq/429-rate-limit-error |
| 413 与超大单层 | 失败时分流 | https://xuanyuan.cloud/faq/413-single-layer-25gb-error |
| 406 OCI index | 背景参考 | https://xuanyuan.cloud/faq/406-oci-index-error |
| 422 Unknown | 背景参考 | https://xuanyuan.cloud/faq/422-unknown-error |
| 400 TAG_INVALID | 背景参考 | https://xuanyuan.cloud/faq/400-tag-invalid-error |

#### 其他报错

| 标题 | Agent 动作 | URL |
|------|-----------|-----|
| no matching manifest（架构） | 失败时分流 | https://xuanyuan.cloud/faq/no-matching-manifest-architecture |
| invalid tar header（解压） | 失败时分流 | https://xuanyuan.cloud/faq/invalid-tar-header-applylayer |
| Schema 1 已废弃 | 背景参考 | https://xuanyuan.cloud/faq/schema-1-manifest-deprecated |
| TLS 证书失败 | 失败时分流 | https://xuanyuan.cloud/faq/tls-certificate-error |
| DNS 超时 | 失败时分流 | https://xuanyuan.cloud/faq/dns-timeout-error |
| 域名连通性排查 | 失败时分流 | https://xuanyuan.cloud/faq/docker-cannot-connect-xuanyuan-domain |
| D-Bus 凭证提示 | 失败时分流 | https://xuanyuan.cloud/faq/credentials-save-error |

#### 使用与功能问题

| 标题 | Agent 动作 | URL |
|------|-----------|-----|
| docker search 限制 | 失败时分流 | https://xuanyuan.cloud/faq/docker-search-custom-domain-error |
| 站内搜不到镜像 | 背景参考 | https://xuanyuan.cloud/faq/image-not-found-in-search |
| 原仓库同步与拉取 | 背景参考 | https://xuanyuan.cloud/faq/full-upstream-image-sync |
| 离线 save/load | 背景参考 | https://xuanyuan.cloud/faq/offline-image-transfer |
| 插件要用 plugin install | 失败时分流 | https://xuanyuan.cloud/faq/docker-plugin-install-error |
| WSL 拉取慢 | 背景参考 | https://xuanyuan.cloud/faq/wsl-docker-pull-slow |
| 安全与 digest | 背景参考 | https://xuanyuan.cloud/faq/image-security |
| 新手拉取配置 | 背景参考 | https://xuanyuan.cloud/faq/how-to-pull-images |
| 镜像合规机制 | 失败时分流 | https://xuanyuan.cloud/faq/image-compliance |
| 不支持 push | 背景参考 | https://xuanyuan.cloud/faq/docker-push-not-supported |

#### 账号 / 计费 / 权限

| 标题 | Agent 动作 | URL |
|------|-----------|-----|
| 免费版与专业版区别 | 背景参考 | https://xuanyuan.cloud/faq/free-vs-pro |
| 支持的镜像仓库 | 背景参考 | https://xuanyuan.cloud/faq/supported-registries |
| 失败是否计费 | 背景参考 | https://xuanyuan.cloud/faq/pull-failed-traffic-charge |
| KYSEC 拦截脚本 | 失败时分流 | https://xuanyuan.cloud/faq/kylin-v10-kysec-permission-error |
| 申请开发票（企业开发票 / 个人开发票） | 背景参考 | https://xuanyuan.cloud/faq/request-invoice |
| 修改登录密码 | 背景参考 | https://xuanyuan.cloud/faq/change-password |
| 注销账户 | 背景参考 | https://xuanyuan.cloud/faq/account-delete |

---

## 6. 服务边界（Agent MUST 遵守）

- **仅支持 pull**，**不支持 push** → https://xuanyuan.cloud/faq/docker-push-not-supported
- 不支持私有仓库托管
- 镜像账户/密码在个人中心查看；与网站登录密码相同（修改见 FAQ change-password）