![Gemini_Generated_Image_5sb9hr5sb9hr5sb9.png](/static/img/6b3b6067647613be3734e1048031ea69.Gemini_Generated_Image_5sb9hr5sb9hr5sb9.webp)


# 从超时到狂飙：极空间 NAS 完美配置 KSpeeder 与 Docker 代理分流指南

最近在国内玩 NAS 和 Docker 的朋友们肯定深有体会：Docker Hub 的直连网络越来越薛定谔，基础镜像拉取极其困难；而各种前沿的 AI 项目（比如 Open WebUI）又常常托管在 `ghcr.io`，直连几乎 100% 被阻断。

为了解决这个问题，我今天进行了一场深度的网络折腾。最初的设想是利用旁路由提供全局代理，同时在本地部署 **KSpeeder** 来实现官方镜像的 P2P 满速下载。没想到在这个过程中，遇到了意想不到的“代理冲突”大坑。

这篇文章将详细记录我从遇到 `Timeout` 报错，到揪出底层配置元凶，再到最终构建出**“本地 KSpeeder 满速加速 + 远端魔法代理兜底”**完美混合网络架构的全过程。

## 踩坑实录：为什么我的本地加速器卡死了？

为了给 Docker 提速，我在极空间 NAS 上通过 Docker Compose 部署了 KSpeeder：

```yaml
services:
  kspeeder:
    image: registry.kspeeder.com/linkease/kspeeder:latest
    container_name: kspeeder
    ports:
      - 5443:5443
      - 5003:5003
    volumes:
      - ./kspeeder-data:/kspeeder-data
      - ./kspeeder-config:/kspeeder-config
    restart: unless-stopped
```

部署完成后，我在极空间的 Docker 界面配置了加速器地址：`https://registry.linkease.net:5443`。
本以为大功告成，结果一跑 `docker pull alpine`，直接喜提报错：
`Client.Timeout exceeded while awaiting headers`

进 KSpeeder 后台看日志，又发现了协议冲突警告：
`client sent an HTTP request to an HTTPS server`

经过 `ping` 和 `curl -v` 命令的一番交叉排查，我终于发现了盲点：**Docker 的全局代理劫持了本地流量！**

因为我之前为了拉取海外镜像，给 Docker 配置了一个局域网内的代理节点（例如 `192.168.31.221:20172`）。当 Docker 试图连接 `registry.linkease.net` 时，它**并没有在 NAS 本地找**，而是直接把请求打包扔给了外网代理服务器。远端代理自然找不到我部署在本地的 KSpeeder，最终导致了超时卡死。

## 破局：潜入 Linux 底层修改 No Proxy 白名单

既然症结在于全局代理，解决思路就很清晰了：我们需要告诉 Docker，**“访问 KSpeeder 时，不要走全局代理！”**

无奈的是，极空间（ZOS）的图形化界面在这方面做了过度精简，只提供了填代理 IP 和端口的地方，**把设置 `No Proxy`（免代理白名单）的入口给阉割了**。我们只能通过 SSH 登录到底层进行硬改。

### 操作步骤：
1. **SSH 登录极空间**并获取 root 权限。
2. **寻找真实的配置文件**：在 Systemd 架构下，Docker 的代理环境变量并不在 `daemon.json` 里。我们利用现有的代理 IP 全局搜寻：
   ```bash
   sudo grep -rl "192.168.31.221" /etc/systemd/system/
   ```
   *果不其然，系统返回了路径：`/etc/systemd/system/docker.service.d/http-proxy.conf`*
3. **编辑配置文件**：极空间内置了友好的 `nano` 编辑器（如果没有也可以用 `vi`）：
   ```bash
   sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
   ```
4. **添加白名单**：找到 `Environment="NO_PROXY=..."` 这一行，在末尾加上 KSpeeder 的域名。
   修改后类似这样：
   `Environment="NO_PROXY=registry.zenithspace.net,localhost,127.0.0.1,registry.linkease.net"`
5. **保存并重启服务**：
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl restart docker
   ```

## 终极形态：教科书级的双轨分流架构

配置生效后，奇迹发生了。当我尝试拉取体积庞大的 `gitlab/gitlab-ce` 镜像进行压力测试时，速度瞬间飙升到了 **25.6 MB/s**！单层几百兆的文件毫无波澜地跑满了我家的物理带宽，KSpeeder 的仪表盘流量也精准对账。

至此，我的 NAS 拥有了一套堪称完美的网络分流架构：

1. **✈️ 常规流量（Docker Hub）：走本地 KSpeeder 专线**
   因为配置了 `NO_PROXY` 白名单，常见的官方基础镜像（如 Nginx、Alpine、LinuxServer 系列）会精准命中本地的 KSpeeder 容器。不仅多线程拉满，数据还会沉淀在 NAS 硬盘缓存中。日后局域网其他设备再需要这些镜像，直接内网秒传！
2. **🛡️ 特殊流量（GHCR、Quay 等）：走旁路由代理兜底**
   遇到像 `open-webui` 这样前缀自带 `ghcr.io` 的第三方或海外独家镜像时，Docker 会自动判定跳过本地加速器，无缝走全局代理节点（`192.168.31.221`）去拉取。这就相当于加了一把万能钥匙，彻底告别了“网络连接重置”的痛点。

## 结语

折腾 NAS 的乐趣往往就在于此：看似枯燥的日志报错背后，其实隐藏着严密的网络逻辑。通过这次排错，不仅理清了 HTTP/HTTPS 的冲突原理，也深刻理解了 Linux 底层环境变量对 Docker 行为的影响。

如果你也正被 Docker 拉取缓慢折磨，不妨试试这套 **“KSpeeder 缓存加速 + 全局代理兜底”** 的组合拳，绝对能让你体验到久违的丝滑！

极空间配置 KSpeeder 与 Docker 代理分流

![Gemini_Generated_Image_uzghmduzghmduzgh.png](/static/img/e7cadae52367738509205ccc614f0f30.Gemini_Generated_Image_uzghmduzghmduzgh.webp)


在完成docker 项目本地开发后，如何优雅、安全且全自动地将应用分发给全球用户？

这篇文章是我在经历了本地联调、上游代码冲突、自动化流水线报错以及网络环境阻断后，沉淀下来的一套标准工程化工作流 (SOP)。日后维护此项目，请严格遵循此流程。

---


### 第一阶段：本地项目管理与云端关联（代码推流前的基建）

在把代码推向开源社区或自己的云端仓库之前，必须确保本地 Git 环境专业、不泄露隐私，并且只上传真正需要的源码。

#### 1. 配置项目级独立身份
Git 默认会读取系统的全局用户名。为了防止真名或私人主邮箱泄露，必须在项目初始化阶段手动锁定身份：

```bash
# 1. 进入项目根目录
cd /your/project/dir

# 2. 仅针对当前项目设置开源使用的匿名身份
git config user.name "your-github-username"
git config user.email "your-github-email@users.noreply.github.com"

# 3. 验证配置是否生效
git config --local --list | grep user
```

#### 2. 初始化本地仓库与配置 `.gitignore`
在开始追踪代码之前，一定要配置好忽略清单。把构建产物、依赖包和敏感凭证传上 GitHub 是工程化的大忌。

```bash
# 1. 初始化 Git 仓库
git init

# 2. 创建并编辑 .gitignore 文件 (以常见 Docker/Node/Python 项目为例)
cat <<EOT >> .gitignore
# 依赖文件
node_modules/
venv/
__pycache__/

# 环境变量与机密
.env
*.pem
*.key

# 操作系统自动生成的文件
.DS_Store
Thumbs.db

# 个人 IDE 配置
.vscode/
.idea/
EOT
```

#### 3. 首次提交并建立本地基线
确认无关文件被拦截后，将核心源码提交到本地，打下项目的第一个基石：

```bash
# 1. 将所有文件加入暂存区
git add .

# 2. 检查当前状态（确保没有不该传的文件被追踪）
git status

# 3. 完成初始提交
git commit -m "chore: initial commit and project setup"
```

#### 4. 创建 GitHub 仓库并建立连接
在 GitHub 网页端点击 `New Repository` 创建一个**空仓库**（不要勾选初始化 README 或 .gitignore，以免与本地冲突）。拿到仓库地址后，在本地终端执行关联：

```bash
# 1. 将默认分支重命名为业界标准的 main
git branch -M main

# 2. 关联远程 GitHub 仓库 (将 URL 换成您自己的)
git remote add origin https://github.com/your-username/your-repo-name.git

# 3. 将本地代码推送到云端，并建立长期的分支绑定 (-u)
git push -u origin main
```

至此，您的代码已经安全、干净地驻扎在了 GitHub 上。接下来，我们就可以让 GitHub Actions 接手自动化构建工作了。

---


## 第二阶段：GitHub Actions 自动化流水线搭建

这是“镜像工厂”的灵魂所在。目标是实现：**本地只管写代码，云端自动打包推送**。

### 1. 配置云端凭证 (Secrets)
流水线需要拿到 Docker Hub 的钥匙才能把打包好的镜像放进去。
1. **获取 Docker Token**：登录 Docker Hub -> 右上角头像 `Account settings` -> `Security` -> `Personal access tokens` -> `Generate new token`，权限选择 `Read, Write, Delete`。**复制这串密钥（仅显示一次）**。
2. **存入 GitHub**：进入 GitHub 仓库主页 -> `Settings` -> 左侧 `Secrets and variables` 展开选择 `Actions` -> 点击绿色的 `New repository secret`。
3. **设置变量**：
   * **Name**: `DOCKER_PASSWORD`
   * **Secret**: 填入刚刚复制的 Docker Token。

### 2. 编写 CI/CD 构建脚本
在项目根目录创建 `.github/workflows/docker-publish.yml` 文件。

考虑到我们可能要在 x86 架构的云服务器和 ARM 架构的设备上运行，这里的脚本加入了 `platforms` 参数，实现一次提交，双架构镜像同时出炉（注意这个脚本里硬编码了 dockerhub 的用户名）：

```yaml
name: Docker Build and Publish

on:
  push:
    branches: [ "main" ]  # 监听 main 分支的每次提交

env:
  REGISTRY: docker.io
  IMAGE_NAME: tomfocker/maptoposter-web # 明确指定最终的镜像名称

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up QEMU # 用于支持多架构跨平台构建
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log into Docker Hub
        uses: docker/login-action@v3
        with:
          username: tomfocker
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          # 同时构建 amd64 和 arm64 架构
          platforms: linux/amd64,linux/arm64 
          tags: ${{ env.IMAGE_NAME }}:latest, ${{ env.IMAGE_NAME }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
```

---

## 第三阶段：日常维护与敏捷迭代流

这套基建跑通后，以后的二次开发将变得极其舒适。请遵循以下标准三步曲：

1. **本地开发与测试 (充分利用本地算力)**
   修改代码或 JSON 主题后，在本地终端执行：
   ```bash
   docker-compose up -d --build
   ```
   打开 `localhost:端口号` 确认效果。如果遇到拉取底包卡死，请检查本地网络环境的旁路由规则，或临时配置 Docker Daemon 代理。

2. **安全合并上游 (防覆辙)**
   若发现原项目有更新，**切勿在 GitHub 网页端直接点击强制覆盖**。应在本地拉取代码，在 IDE 中手动解决冲突，确保本地 Web 版仍能正常渲染后，再做提交。

3. **一键推送发版**
   ```bash
   git add .
   git commit -m "feat: update poster themes"
   git push origin main
   ```
   
**收工！** 去泡杯咖啡。GitHub Actions 会自动接管跨平台打包工作，5 分钟后，您的服务器通过 `docker pull tomfocker/项目名:latest` 即可无缝拉取到最新版本并上线。

Docker 开发全流程工程化与自动化部署指南

![Gemini_Generated_Image_lbogaylbogaylbog.png](/static/img/e665e7a9c8ad24734382fc23e3fe2c76.Gemini_Generated_Image_lbogaylbogaylbog.webp)


### 前言
最近接了一个“小私活”：给一位做实业的老板做一个极其简单的企业展示页。需求很典型：
1. **要快：** 手机点开瞬间就能看。
2. **要省：** 不想买云服务器，不想交年费。
3. **要稳：** 别动不动就因为家里断电或 DDNS 抽风打不开。
4. **要逼格：** 必须有独立域名，必须带“小绿锁”HTTPS。

在反复权衡了 **DDNS+内网穿透** 和 **云服务器部署** 后，我选择了最“优雅”的方案：**阿里云 OSS 香港节点静态托管**。今天就把这套“点烟级”的造火箭流程记录下来。

---

### 一、 核心架构：为什么选择 OSS + 香港节点？

* **避开备案：** 选“中国香港”节点，直接绕过 ICP 备案，域名秒解析，即刻上线。
* **隐藏端口：** OSS 绑定自定义域名后，默认监听 80/443 端口，彻底告别 `:8888` 这种难看的尾巴。
* **极致省钱：** 静态网页那点流量和存储，一个月可能也就几毛钱，充 10 块钱能用到公司倒闭。
* **高可用：** 阿里背书，不宕机，不维护，真正的“写完即焚”。

---

### 二、 避坑实录：那些让你怀疑人生的“小妖精”

在折腾过程中，我遇到了三个最经典的坑，在这里划重点：

#### 1. 默认域名变“下载”
**现象：** 上传完 `index.html`，点击阿里云给的长链接，浏览器直接弹下载，不显示网页。
**真相：** 阿里云的安全策略。OSS 默认域名禁止直接预览 HTML。
**解药：** 必须绑定**自定义域名**，用你自己的域名访问就正常了。

#### 2. SSL 证书的“捉迷藏”
**现象：** 证书列表全是好几千块一年的企业证书，找不到免费版。
**真相：** 免费版被藏在了“个人测试证书”里。
**解药：** 购买时选择“个人测试证书（免费）”，每个账号每年有 20 个 0 元额度。

#### 3. 图片“碎裂”与 404
**现象：** 网页文字出来了，但图片全是红叉。
**真相：** * **大小写敏感：** Linux 环境（OSS）下，`pic1.jpg` 和 `pic1.JPG` 是两个东西！
* **权限覆盖：** Bucket 设为公共读了，但单独上传的文件有时需要再次确认权限。

---

### 三、 动手实操：五分钟部署流程

#### 1. 库房搭建（OSS 设置）
* 创建 Bucket，地域选 **中国（香港）**。
* 读写权限设为 **公共读**。
* 在“静态页面”菜单里，把 **默认首页** 设为 `index.html`。

#### 2. 脸面设计（前端代码）
为了让老板满意，我设计了一套“轻奢风”模板。核心思路是：
* **CSS Grid：** 适配手机端的海报墙布局。
* **Fade-in 动画：** 元素交替浮现，增加高级感。
* **一键拨号：** `<a href="tel:...">` 手机点一下直接呼叫老板。

```html
<style>
    @keyframes fadeInUp {
        from { opacity: 0; transform: translateY(20px); }
        to { opacity: 1; transform: translateY(0); }
    }
    .fade-in { animation: fadeInUp 1s ease forwards; }
</style>
```

#### 3. 灵魂注入（域名与 HTTPS）
* 在 OSS **域名管理** 开启“自动添加 CNAME 解析”。
* 申请免费证书后，直接在控制台点击 **“一键部署至 OSS”**。
* **必做：** 开启“强制 HTTPS”，让所有访问都带上安全锁。

---

### 四、 总结与心得

这次折腾让我意识到，很多时候我们习惯了在 HomeLab 里搞各种复杂的 Nginx 反代、FRP 穿透，但对于这种纯展示的生产环境，**“简单”才是最高级的优雅**。

OSS 静态托管不仅是存文件的地方，它更像是一个免维护的超级 Web 服务器。对于小微企业、个人名片、甚至是你的静态博客（如 Hexo/Hugo），这套方案几乎是目前的“版本答案”。

**费用总结：**
* **域名：** 几十块/年
* **存储：** 几分钱/月
* **流量：** 几毛钱/GB
* **心情：** 看到绿锁和老板转账时的愉悦，无价。

---

**zym588's Blog**
*记录每一次折腾，让技术更有温度。*

利用阿里云 OSS 打造免备案企业官网

![Gemini_Generated_Image_9i38o09i38o09i38.png](/static/img/38a24f37cb32198ce1e82a7dc9b4566c.Gemini_Generated_Image_9i38o09i38o09i38.webp)


## 多端折腾不掉队：我的 OneDrive 跨设备配置同步实践（PC/Mac/HomeLab）

### 1\. 前言：折腾党的“环境焦虑”

作为一名在不同设备之间反复横跳的“双修”玩家，我最怕的不是配置服务器，而是\*\*“环境不一致”\*\*。

刚在 WindTerm 里写好一个复杂的 Docker 组合命令，回到家发现 Mac 上的终端还是“出厂设置”；或者在 PC 上调优了 WSL2 的镜像网络模式，换台机器又要翻文档重新配。

今天分享我如何利用 **OneDrive**（哪怕只有 5GB 免费空间）把这些零碎的配置缝合在一起。

-----

### 2\. 核心架构：热数据同步 vs 冷数据备份

在开始前，必须明确我的存储策略，否则 5GB 空间瞬间就会爆掉：

  * **热数据 (OneDrive)：** 软件配置文件、SSH 密钥、Docker Compose 脚本、个人笔记（Markdown）。这些文件极小（KB 级），但修改频繁，需要秒级同步。
  * **冷数据 (NAS/ZimaCube)：** 视频素材、Docker 镜像文件、系统 ISO。这些通过 Alist 挂载或局域网 SMB 访问。

-----

### 3\. 实战案例：WindTerm 的“瞬移”配置

WindTerm 是目前我最推荐的 SSH 工具，因为它不仅强，而且是**纯绿色软件**，配置都在安装目录下。

#### **具体步骤：**

1.  **路径迁移：** 将整个 WindTerm 文件夹移入 OneDrive 目录下（例如 `OneDrive\Tools\WindTerm`）。
2.  **锁定本地副本：** 右键点击该文件夹，勾选 **“始终保留在此设备上”**。
      * **理由：** 这样即便在 200KB/s 的限速下，软件启动时也是直接读取硬盘，不会因为网络波动导致加载配置卡顿。
3.  **参数化同步：** 记得利用 WindTerm 的“参数”功能。我配置了“端口占用终结者”和“一键清理 Docker”等按钮，这些通过 `.json` 存储的逻辑会在 PC 和 Mac 间实时同步。

-----

### 4\. 高阶玩法：WSL2 与 SSH 的“全局一致性”

除了工具，系统底层的配置更需要同步。

  * **SSH 密钥同步：** 我将 `.ssh` 文件夹（含 `config` 和私钥）放在 OneDrive 建立软链接。这样我在 PC 上连接 Tailscale 内网节点（100.64.0.x）时，换到 Mac 上无需重新导入密钥，开箱即用。
  * **WSL2 镜像模式配置：** 我在 OneDrive 里维护了一份 `.wslconfig` 模板，开启了 `networkingMode=mirrored`。每当我在 PC 上更新了网络策略（比如解决 `localhostForwarding` 失效问题），我只需简单拷贝，Mac 端的虚拟机环境也能立刻同步最强网络体验。

-----

### 5\. 针对“5GB + 200KB/s”的生存指南

如果你像我一样目前使用的是 5GB 免费版，且直连速度只有 200KB/s，请记住这三条军规：

1.  **拒绝“碎文件地狱”：** 绝对不要同步 `node_modules` 或 `.git` 文件夹。如果你是前端开发者，记得把项目放在同步区之外，只把 `deploy.sh` 脚本放进来。
2.  **强制开启“按需同步”：** 确保非核心文件夹显示为“蓝色小云朵”，只给最关键的配置文件打上“实心绿勾”。
3.  **代理加持：** 在 OneDrive 的设置中配置好你的加速通道，200KB 变 20MB 只需要一个勾选。

-----

### 6\. 结语：折腾的本质是提高效率

利用 OneDrive 并不是为了备份，而是为了**消除设备间的边界感**。

当你发现无论坐在哪台电脑前，你的快捷命令都在手边，你的服务器列表实时更新，你的 WSL2 网络环境始终如一时，这种折腾带来的掌控感才是最爽的。

Onedrive初体验

![Gemini_Generated_Image_ps8kh3ps8kh3ps8k.png](/static/img/5e4bb326b7244c8d95dcb34a4a68c3f6.Gemini_Generated_Image_ps8kh3ps8kh3ps8k.webp)


看着市面上百花齐放的开源大模型，谁不想在本地养一个专属的、保护隐私的 AI 助手？

手持 **i7-14700K + 64GB 内存 + RTX 4070 SUPER (12GB 显存)** 的配置，本以为在 Windows 下装个环境轻轻松松，结果却踩了无数关于 C 盘爆满、显存溢出、网络代理失效以及模型“胡言乱语”的深坑。

如果你也是 12GB 显存的玩家，或者正在被 WSL2 的默认设置折磨，请直接**抄作业**。这篇文章将手把手带你避开所有暗礁，搭建一个满血运行的本地 AI 工作站。

---

## 阶段一：基础搭建与 C 盘“大逃亡”

在 Windows 下跑 AI，目前最稳的方案是使用 WSL2（Windows 下的 Linux 子系统）。但微软默认会把它装在 C 盘，一旦后续下载十几个 G 的大模型，你的 C 盘会瞬间爆红。

**核心战略：先安装，立刻“搬家”到 D 盘。**

### 1. 一键安装 Ubuntu
右键点击 Windows 的“开始”菜单，选择 **“终端 (管理员)”** 或 **“PowerShell (管理员)”**，执行：
```powershell
wsl --install
```
安装完成后**重启电脑**，并在弹出的 Ubuntu 终端里设置初始账号和密码。

### 2. 乾坤大挪移（释放 C 盘）
既然 D 盘空间大（比如咱们那 1007G 的空间），就必须把它挪过去。继续在 PowerShell (管理员) 中一行行执行：
```powershell
# 彻底关闭 WSL
wsl --shutdown

# 打包导出到 D 盘根目录（可能需要几分钟）
wsl --export Ubuntu D:\ubuntu_backup.tar

# 注销原系统（关键操作！瞬间释放 C 盘空间）
wsl --unregister Ubuntu

# 在 D 盘新建文件夹并重新导入
wsl --import Ubuntu D:\WSL_Data D:\ubuntu_backup.tar

# 清理过渡文件
del D:\ubuntu_backup.tar
```

---

## 阶段二：打通任督二脉（资源限制与镜像网络）

WSL2 是一只贪婪的性能野兽，如果不加限制，它会吃光你的物理内存。此外，默认的 NAT 网络模式是本地跑服务和挂代理的噩梦。我们需要给它写一份**“配置文件”**。

1. 按下 `Win + R` 打开运行窗口，输入 `%USERPROFILE%` 回车。
2. 在该目录下新建一个文本文件，命名为 **`.wslconfig`**。
3. 填入以下终极调优代码并保存：

```ini
[wsl2]
# 限制最大使用内存（建议设为物理内存的 1/3 或 1/2，我有 64G，所以给 24G）
memory=24GB
# 限制使用的 CPU 核心数
processors=8
# 自动回收空闲内存
guiApplications=false

[experimental]
# 开启镜像网络（核心！让 WSL 和 Windows 共享局域网 IP，告别端口转发）
networkingMode=mirrored
# 开启 DNS 隧道
dnsTunneling=true
# 自动同步代理（WSL 将自动使用 Windows 系统的局域网代理，拉取镜像直接起飞）
autoProxy=true
```
保存后，在 PowerShell 执行 `wsl --shutdown` 重启服务使其生效。*(注：启动时如果提示 `localhostForwarding` 无效，属于正常现象，忽略即可。)*

---

## 阶段三：显卡直通与 Docker 环境配置

在 WSL2 时代，只要你的 Windows 宿主机装了最新的 NVIDIA 显卡驱动，WSL 内部天然就能调用显卡，无需在 Linux 里重复装驱动。

进入 Ubuntu 终端（在 PowerShell 输入 `wsl`），依次执行以下命令：

### 1. 一键安装 Docker
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

### 2. 安装 NVIDIA 容器工具（让 Docker 认识显卡）
直接复制这整段并回车：
```bash
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
```
更新并重启服务：
```bash
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

---

## 阶段四：一键起飞：Ollama + Open WebUI 部署

创建一个工作目录并编写 `docker-compose.yml`，一次性把后端（Ollama）和前端（Open WebUI）拉起来。

```bash
mkdir -p ~/ai-workspace && cd ~/ai-workspace
nano docker-compose.yml
```

填入以下内容（这里将模型路径直接映射到了 D 盘，进一步保护系统盘）：

```yaml
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - /mnt/d/ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    volumes:
      - ./webui_data:/app/backend/data
    ports:
      - 3000:8080
    environment:
      - 'OLLAMA_BASE_URL=http://ollama:11434'
      - 'HF_ENDPOINT=https://hf-mirror.com' # 国内镜像加速
    restart: unless-stopped
```
保存退出（`Ctrl+O`, `Enter`, `Ctrl+X`），然后一键启动：
```bash
sudo docker compose up -d
```
此时，打开浏览器访问 `http://localhost:3000`，注册管理员账号，你的 AI 基地就建好了！

---

## 阶段五：12G 显卡的“天命之选”与极限调优

> ⚠️ **巨坑警告：千万不要去乱下 `.gguf` 文件手动导入！** 极易丢失对话模板（Template）和停止词，导致 AI 像精神分裂一样胡言乱语。**一定要通过官方命令拉取！**

对于 12GB 显存的 RTX 4070 SUPER，**Qwen 3.5 (9B)** 是完美的“甜点级”选择。它能 100% 塞进显存，速度极快，且原生支持视觉（Vision）多模态。

### 1. 拉取模型
在 Ubuntu 终端执行：
```bash
docker exec -it ollama ollama pull qwen3.5
```

### 2. 显存压榨（解决出字龟速问题）
如果你发现模型出字慢，大概率是因为“上下文缓存 (Context)”吃光了显存，导致运算掉进了 CPU。
1. 在 Open WebUI 中，点击模型旁边的**齿轮设置** -> **高级参数**。
2. 将 **Context Length (上下文长度)** 从默认的 4096 改为 **`2048`** 并保存。
3. **终极验证：** 对话时，在终端输入 `docker exec -it ollama ollama ps`。只要 `PROCESSOR` 栏显示 **`100% GPU`**，你的 4070S 就已经满血释放，出字速度将如丝般顺滑！

---

## 阶段六：后期维护（空间回收与终极“后悔药”）

WSL2 的 `.vhdx` 虚拟硬盘文件有一个“只大不小”的毛病。清理了 Docker 废弃镜像后，你需要手动给它“抽脂”。

### 1. 压榨虚拟硬盘（回收 D 盘空间）
关闭 WSL (`wsl --shutdown`) 后，在 PowerShell (管理员) 执行 `diskpart`，依次输入：
```text
select vdisk file="D:\WSL_Data\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit
```

### 2. 打快照备份（吃后悔药）
在折腾出一个完美的纯净环境后，养成打快照的好习惯：
```powershell
wsl --export Ubuntu D:\Ubuntu_Perfect_Snapshot.tar
```
以后系统被玩崩了，只需 `unregister` 删掉坏的，再 `import` 这个备份包，三分钟满血复活。

至此，一个不吃 C 盘、满血释放 GPU、网络畅通无阻的本地 AI 工作站彻底大功告成。放开手脚去折腾吧！