纸影 冒险营

© 2026 纸影

湘ICP备2026013764号-3

N1 + OpenBiliClaw 极客 AI 部署完全手册

---
title: N1 + OpenBiliClaw 极客 AI 部署完全手册
created: 2026-05-15
updated: 2026-06-22
type: guide
tags: [n1, armbian, openbiliclaw, ai, gemini, bilibili]
cross-refs: "[[README|Armbian 概览]], [[../README|N1 概览]], [[Open WebUI Docker Compose 配置 (dpanel 适用)]], [[New API 完整部署与初始化教程]]"
---

# 🚀 N1 + OpenBiliClaw 极客 AI 部署完全手册  
> *斐讯N1盒子 · Armbian系统 · 边缘+云端混合架构 · 零成本接入AI能力*

---

## 📋 环境速览

| 组件 | 配置要求 | 说明 |
|------|---------|------|
| 📦 硬件 | 斐讯N1盒子（S905D + 2GB RAM） | 建议搭配散热片 |
| 💾 存储 | 外置U盘挂载 `/mnt/usb` | 避免eMMC频繁读写 |
| 🐧 系统 | Armbian（推荐 latest stable） | 内核≥5.10 |
| 🐳 容器 | dpanel + Docker Compose | 图形化容器管理 |
| 🌐 网络 | ShellCrash 科学上网（端口7890） | 全局代理模式 |
| 📦 项目 | GitHub: OpenBiliClaw | 开源B站视频AI分析工具 |

---

## 🏗️ 一、核心架构设计：边缘+云端，最大化白嫖体验

### 🎯 设计理念
> 针对N1硬件限制，采用 **「边缘计算 + 云端AI推理」** 混合架构  
> ✅ 规避本地大模型内存崩盘风险    ✅ 24小时稳定运行    ✅ 零成本接入AI

### 🔀 分工明细

```
┌─────────────────────────────────────┐
│  📦 本地（N1盒子）· 后勤管理          │
├─────────────────────────────────────┤
│  • 爬取B站视频元数据                  │
│  • 任务队列调度与管理                 │
│  • 语义去重 + 内容智能筛选            │
│  • 轻量级数据预处理                  │
└─────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────┐
│  ☁️ 云端（API接口）· 大脑运算         │
├─────────────────────────────────────┤
│  🔹 主力：Gemini免费版API（文本分析）│
│  🔹 备用：硅基流动/DeepSeek          │
│       （OpenAI兼容接口，高可用兜底） │
└─────────────────────────────────────┘
```

---

## 🛠️ 二、手把手部署步骤

### 1️⃣ 环境准备（基于 dpanel + 外置U盘）

```bash
# 📁 确认部署路径（所有操作在此目录下）
cd /mnt/usb/docker-data/dpanel/compose/openbiliclaw

# 📥 获取代码（二选一）
# 方式A：终端执行
git clone https://github.com/your-repo/OpenBiliClaw.git

# 方式B：dpanel界面直接拉取

# ⚙️ 初始化配置
mkdir -p runtime
# 将 config.toml 配置文件放入 runtime/ 目录

# 🔐 Git权限修复（如遇报错）
git config --global --add safe.directory /mnt/usb/docker-data/dpanel/compose/openbiliclaw
```

> 💡 **路径提醒**：所有文件操作务必在 `/mnt/usb` 下进行，保护N1内置eMMC寿命

最终yaml如下：

```yaml
services:
  # Ollama sidecar — bundled embedding service so users don't need to
  # install Ollama on their host. Pulls bge-m3 on first start (~568MB,
  # CPU-only) and keeps the daemon running on the internal Docker
  # network at http://ollama:11434. The backend's [llm.embedding] gets
  # seeded to point here automatically on first config bootstrap.
  #
  # Disable this entire block by removing it (and the depends_on +
  # OPENBILICLAW_SEED_OLLAMA_DEFAULTS env in the backend service) if
  # you'd rather run an embedding API key from a cloud provider — see
  # docs/docker-deployment.md.

  openbiliclaw-backend:
    build:
      context: .
      dockerfile: Dockerfile
      # The Dockerfile only depends on python:3.11-slim, which is
      # published as a multi-arch manifest. ``docker compose build``
      # picks the architecture matching the host (amd64 on Intel,
      # arm64 on Apple Silicon / Raspberry Pi). To explicitly cross-
      # build a release image, use buildx:
      #   docker buildx build --platform linux/amd64,linux/arm64 \
      #     -t openbiliclaw-backend:vX.Y.Z .
    container_name: openbiliclaw-backend
    environment:
      OPENBILICLAW_PROJECT_ROOT: /app/runtime
      OPENBILICLAW_CONFIG_TEMPLATE: /app/config.toml
      OPENBILICLAW_PROXY_HOST: "192.168.0.200"
      OPENBILICLAW_PROXY_PORT: "7890"
      OPENBILICLAW_PROXY_TIMEOUT: "5"
      # On first config bootstrap, seed [llm.ollama] base_url and
      # [llm.embedding] to point at the bundled sidecar above. Lets
      # Docker users have local embedding out of the box, even if they
      # later pick OpenAI / Claude / etc for chat. Existing config.toml
      # is never overwritten.
      OPENBILICLAW_SEED_OLLAMA_DEFAULTS: "0"
      # OPENBILICLAW_XHS_SIDECAR_URL: http://xhs-sidecar:5556  # sidecar removed — extension extracts metadata from DOM
    mem_limit: 512M
    memswap_limit: 512M
    command:
      - python
      - -m
      - openbiliclaw.docker_runtime
      - openbiliclaw
      - serve-api
      - --host
      - 0.0.0.0
      - --port
      - "8420"
    # ``host.docker.internal`` resolves the host machine from inside
    # the container. Used by:
    #   - HTTP proxy auto-detect (OPENBILICLAW_PROXY_HOST)
    #   - any user that picks "use my host's Ollama instead of the
    #     bundled sidecar" by overriding OPENBILICLAW_OLLAMA_BASE_URL
    # Required on Linux Docker; auto-provided by Docker Desktop on
    # Mac / Windows. The ``host-gateway`` magic value tells the engine
    # to inject the right address per platform.
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "8420:8420"
    volumes:
      - /mnt/usb/docker-data/openbiliclaw/config:/app/runtime
      - /mnt/usb/docker-data/openbiliclaw/data:/app/runtime/data
      - /mnt/usb/docker-data/openbiliclaw/logs:/app/runtime/logs
    # Compose-level healthcheck mirrors the Dockerfile HEALTHCHECK so
    # ``docker compose ps`` shows ``healthy`` only when /api/health
    # returns 200, not just when the container process is alive.
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8420/api/health', timeout=4).status==200 else 1)"]
      interval: 30s
      timeout: 5s
      start_period: 20s
      retries: 3
    restart: unless-stopped

volumes:
  openbiliclaw_config:
  openbiliclaw_data:
  openbiliclaw_logs:
  # Persists ollama models across container recreations so users don't
  # have to re-pull bge-m3 on every rebuild.
  openbiliclaw_ollama:
```

| 资源     | 建议上限   | 说明               |
| ------ | ------ | ---------------- |
| 🧠 内存  | 512MB  | 预留1.5GB给系统+其他容器  |
| 💾 磁盘  | 外置U盘存储 | 保护N1内置eMMC寿命     |

---

### 2️⃣ 核心配置（config.toml）⭐ 关键步骤

> ⚠️ **注意**：配置项大小写敏感，请严格按以下模板填写

```toml
[llm]
# 🔹 主力AI提供商
default_provider = "gemini"

# 🔹 并发数调优：由3降为2，防止免费版API限流
concurrency = 2

# 🔹 请求超时时间（秒）
timeout = 300

# 🔹 开启备用API兜底机制
fallback_enabled = true

# 🔹 备用API类型（兼容OpenAI格式）
fallback_provider = "openai_compatible"

# 🔹 模型名称【关键】：必须全小写，否则调用报错！
model = "gemini-3.1-flash-lite"
```

| 配置项 | 推荐值 | 说明 |
|--------|--------|------|
| `default_provider` | `"gemini"` | 主力使用免费Gemini API |
| `concurrency` | `2` | 避免触发15 RPM限流 |
| `model` | `"gemini-3.1-flash-lite"` | 🔴 必须小写！否则400错误 |
| `fallback_enabled` | `true` | 建议开启，提升稳定性 |

---

### 3️⃣ 代理配置（ShellCrash 本地代理）

```bash
# ✅ 确认ShellCrash状态
crash status

# ✅ 验证宿主机代理连通性
curl -I https://google.com
# 返回 HTTP/2 200 即表示正常

# ✅ Docker容器代理配置（dpanel默认继承宿主机网络）
# 如需强制指定，在 docker-compose.yml 中添加：
environment:
  - HTTP_PROXY=http://127.0.0.1:7890
  - HTTPS_PROXY=http://127.0.0.1:7890
  - NO_PROXY=localhost,127.0.0.1
```

> 🔹 ShellCrash默认端口：`7890`（如自定义请同步修改）  
> 🔹 建议开启「全局代理」模式，避免规则漏配

---

## 🚨 三、常见问题与解决方案（生死磨难指南）

### 🔌 问题1：代理链路断连（Gemini报错核心）

| 现象 | `Provider gemini failed`，但谷歌后台无请求记录 |
|------|---------------------------------------------|
| 🔍 排查流程 | 
| 1️⃣ | `crash status` 确认ShellCrash服务运行中 |
| 2️⃣ | N1终端执行 `curl -I https://google.com` 验证宿主机代理 |
| 3️⃣ | 进入容器执行相同curl，验证容器内网络 |
| 4️⃣ | 容器内不通 → 在Compose中添加`HTTP_PROXY`环境变量（见上文） |

---

### ⚡ 问题2：API频率限流（429 / WARNING警告）

| 现象 | 日志频繁弹出 `WARNING: Rate limit exceeded` |
|------|-------------------------------------------|
| 🎯 原因 | 免费版Gemini限制：**每分钟15次请求（15 RPM）** |
| ✅ 解决 | 将 `config.toml` 中 `concurrency = 2`，平滑请求节奏 |
| 💡 进阶 | 可添加请求间隔逻辑，或轮换多个API Key（如有） |

N1