当前位置：首页 > news >正文

今日开源[第2期]Project N.O.M.A.D. - zhang

news 2026/6/1 1:20:56

Project N.O.M.A.D. 项目深度分析

分析日期：2026-06-01
项目地址：https://github.com/Crosstalk-Solutions/project-nomad
最新版本：v1.32.1（2026-05-27）
开源协议：Apache License 2.0

一、项目介绍

1.1 项目概述

Project N.O.M.A.D. 全称为 "Node for Offline Media, Archives, and Data"（离线媒体、档案与数据节点），是一个自包含的、离线优先的知识与教育服务器。它将本地 AI 助手、完整维基百科离线库、全球地图、医疗急救手册、K-12 全套教育课程、加密分析工具以及文档检索系统打包到一台普通电脑中，安装完成后可彻底脱离互联网运行。

N.O.M.A.D. 是一个管理 UI（"Command Center"）和 API，通过 Docker 编排一系列容器化工具和资源，负责所有工具的安装、配置和更新。所有功能通过浏览器访问，无需桌面环境。

1.2 项目地址

类型	地址
GitHub 仓库	https://github.com/Crosstalk-Solutions/project-nomad
项目官网	https://www.projectnomad.us
安装指南	https://www.projectnomad.us/install
WSL2 安装指南	https://www.projectnomad.us/install/wsl2
硬件指南	https://www.projectnomad.us/hardware
基准测试排行榜	https://benchmark.projectnomad.us
产品路线图	https://roadmap.projectnomad.us
Discord 社区	https://discord.com/invite/crosstalksolutions
Crosstalk Solutions 公司	https://www.crosstalksolutions.com

1.3 项目示意图

项目 Logo：

官方视频教程：

教程	时长	说明
How to Install Project NOMAD	14 分钟	全新 Ubuntu 机器上的完整安装步骤
Access NOMAD Over Wi-Fi	10 分钟	使用旅行路由器将 NOMAD 变成便携 Wi-Fi 热点
How Much Disk Space Do You Need?	1 分钟	存储空间需求快速介绍（TikTok 30 万+ 播放）

在线展示：

官网交互式演示 — 功能展示、竞品对比、硬件推荐
基准测试排行榜 — 社区用户真实硬件跑分（92 个提交）
已测试硬件页面 — 官方安装、优化和测试过的设备

二、项目亮点

2.1 真正的离线优先设计

安装完成后可彻底脱离互联网运行。零内置遥测，不向任何外部服务器发送数据。所有计算和存储均在本地完成，是隐私和数据自主权的极致体现。

2.2 一站式知识平台

集成 8 大核心功能模块，覆盖信息获取、AI 对话、教育学习、数据分析等全方位需求：

功能	技术支撑	说明
AI 聊天与知识库	Ollama + Qdrant	本地 LLM + RAG 语义搜索
信息图书馆	Kiwix	离线维基百科、医学参考、电子书等
教育平台	Kolibri	Khan Academy 课程，进度跟踪
离线地图	ProtoMaps	可下载区域地图，搜索和导航
数据工具	CyberChef	加密、编码、哈希和数据分析
笔记系统	FlatNotes	本地 Markdown 笔记
系统基准测试	内置	硬件评分 + 社区排行榜
简易设置向导	内置	引导式首次配置

2.3 极低硬件门槛

最低配置仅需：2GHz 双核 CPU + 4GB 内存 + 5GB 存储。在普通旧电脑上即可运行基础功能（不含 AI），运行 AI 推理推荐 32GB 内存 + NVIDIA GPU。

2.4 GPU 加速 AI 推理

支持 NVIDIA 和 AMD GPU 加速，默认 AI 模型为 Qwen 2.5 3B（30 亿参数），可通过 Ollama 或 OpenAI 兼容 API（LM Studio、llama.cpp）使用更大模型。

2.5 Docker 容器化架构

所有组件通过 Docker 编排，一键安装、自动更新。6 个核心服务（admin、MySQL、Redis、updater、disk-collector、dozzle）协同工作。

2.6 自我更新机制

内置 sidecar 更新器容器，可自动检查和安装更新，无需手动维护。使用语义化发布（semantic-release）自动化版本管理，已发布 69 个版本。

2.7 社区基准测试排行榜

内置硬件评分系统，用户可提交跑分数据到社区排行榜，带有 HMAC-SHA256 签名防滥用和 Builder Tag 匿名分享机制。

2.8 丰富的内容生态

支持 ZIM 格式离线内容（维基百科、Stack Exchange、TED 演讲等）
支持分层内容安装（Essential/Standard/Complete）
社区插件支持第三方内容包

2.9 跨平台 Wi-Fi 热点

配合 GL.iNet 等旅行路由器，可将 NOMAD 设备变成便携 Wi-Fi 热点，多设备同时访问。

2.10 竞品碾压级性价比

竞品	价格	AI 能力	硬件	开源
Project NOMAD	免费	GPU 加速 LLM	任意 PC	Apache 2.0
PrepperDisk	$199-$279	无	树莓派（锁定）	部分
Doom Box	$699	基础 7B	树莓派（锁定）	否
R.E.A.D.I.	$499	基础 7B	树莓派（锁定）	否

三、项目运行环境介绍和运行条件介绍

3.1 系统要求

项目	最低配置	推荐配置（含 AI）	理想配置
操作系统	Debian 系 Linux（推荐 Ubuntu）	同左	同左
处理器	2 GHz 双核	AMD Ryzen 7 / Intel Core i7	更高性能多核
内存	4 GB	32 GB	64 GB
显卡	非必须	NVIDIA RTX 3060（8GB VRAM）	更高 VRAM（运行更大模型）
存储	5 GB（基础）	250 GB SSD	500 GB+ SSD
网络	安装时需要	同左	同左

注：不含 AI 功能时，最低配置即可运行。GPU 主要加速 LLM 推理和嵌入向量化。支持 NVIDIA（nvidia-container-toolkit）和 AMD（HSA_OVERRIDE）两种 GPU。

3.2 必须安装的软件

软件	用途	安装方式
Docker Engine	容器运行时	安装脚本自动安装
Docker Compose v2	容器编排	安装脚本自动安装
curl	下载脚本	`apt-get install curl`

NVIDIA GPU 支持为可选安装，安装脚本会自动检测并配置 nvidia-container-toolkit，失败不会中断安装。

3.3 核心技术栈

类别	技术
后端框架	AdonisJS v6（TypeScript 全栈框架）
前端	React 19 + Inertia.js + TailwindCSS 4 + Vite 6
数据库	MySQL 8.0
缓存/队列	Redis 7 + BullMQ
AI 推理	Ollama（OpenAI 兼容 API）
向量数据库	Qdrant
嵌入模型	nomic-embed-text:v1.5（768 维）
容器管理	dockerode
实时通信	@adonisjs/transmit（SSE）
离线内容	Kiwix（ZIM 格式）
离线地图	ProtoMaps（PMTiles 格式，OpenStreetMap）
OCR	Tesseract.js
图像处理	Sharp

3.4 快速安装步骤

# 一键安装（Debian 系 Linux）
sudo apt-get update && \
sudo apt-get install -y curl && \
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh \-o install_nomad.sh && \
sudo bash install_nomad.sh# 安装完成后，浏览器访问
http://localhost:8080

3.5 辅助管理脚本

安装后位于 /opt/project-nomad 目录：

脚本	功能
`start_nomad.sh`	启动所有已安装的容器
`stop_nomad.sh`	停止所有容器
`update_nomad.sh`	更新 Command Center 及依赖容器
`uninstall_nomad.sh`	完全卸载（不可逆）

四、项目代码介绍

4.1 代码架构图

project-nomad/
├── admin/                          # 核心管理应用（AdonisJS + React）
│   ├── ace.js                      # AdonisJS CLI 入口
│   ├── adonisrc.ts                 # 框架配置
│   ├── app/
│   │   ├── controllers/             # 控制器层（12 个）
│   │   │   ├── benchmark_controller.ts    # 基准测试
│   │   │   ├── chats_controller.ts        # AI 聊天
│   │   │   ├── downloads_controller.ts    # 下载管理
│   │   │   ├── easy_setup_controller.ts    # 安装向导
│   │   │   ├── home_controller.ts         # 首页仪表盘
│   │   │   ├── maps_controller.ts         # 离线地图
│   │   │   ├── rag_controller.ts          # 知识库/RAG
│   │   │   ├── services_controller.ts      # Docker 服务管理
│   │   │   ├── system_controller.ts        # 系统设置
│   │   │   ├── wikipedia_controller.ts     # Wikipedia 内容
│   │   │   ├── docs_controller.ts         # 文档
│   │   │   └── collection_updates_controller.ts  # 内容更新
│   │   ├── models/                  # 数据模型层（14 个）
│   │   │   ├── service.ts                # Docker 服务定义
│   │   │   ├── kv_store.ts               # 键值配置存储
│   │   │   ├── chat_session.ts           # 聊天会话
│   │   │   ├── chat_message.ts           # 聊天消息
│   │   │   ├── content_collection.ts     # 内容集合
│   │   │   ├── content_resource.ts       # 内容资源
│   │   │   ├── benchmark_result.ts       # 基准测试结果
│   │   │   └── kb_ingest_state.ts        # 知识库摄入状态
│   │   ├── services/                 # 服务层（17 个）★ 核心
│   │   │   ├── docker_service.ts         # Docker 容器管理 ★★★
│   │   │   ├── ollama_service.ts         # AI 模型管理 ★★★
│   │   │   ├── rag_service.ts            # RAG 检索增强 ★★★
│   │   │   ├── chat_service.ts           # 聊天业务逻辑
│   │   │   ├── download_service.ts       # 下载任务调度
│   │   │   ├── map_service.ts            # 地图数据管理
│   │   │   ├── queue_service.ts          # BullMQ 队列（单例）
│   │   │   ├── kiwix_library_service.ts  # Kiwix 库管理
│   │   │   ├── benchmark_service.ts      # 基准测试执行
│   │   │   ├── system_service.ts         # 系统信息采集
│   │   │   ├── container_registry_service.ts  # 镜像版本管理
│   │   │   └── zim_extraction_service.ts # ZIM 文件提取
│   │   ├── middleware/               # 中间件
│   │   ├── validators/               # 验证器
│   │   ├── jobs/                     # 后台任务
│   │   └── events/ + listeners/       # 事件系统
│   ├── config/                    # 配置文件
│   ├── database/                  # 数据库迁移和种子
│   ├── inertia/                   # Inertia.js 前端页面
│   ├── resources/                 # 前端资源（React + Vite）
│   └── public/                    # 静态资源（Logo 等）
│
├── collections/                   # 内容集合定义
│   ├── kiwix-categories.json      # Kiwix 内容分类
│   ├── maps.json                  # 地图数据源
│   └── wikipedia.json             # 维基百科内容定义
│
├── install/                       # 安装脚本和配置
│   ├── install_nomad.sh           # 主安装脚本（31KB）
│   ├── management_compose.yaml    # Docker Compose 模板
│   ├── entrypoint.sh              # Docker 入口
│   ├── start/stop/update/uninstall_nomad.sh  # 管理脚本
│   └── sidecar-updater/           # Sidecar 更新器
│
├── Dockerfile                     # 主 Docker 镜像（多阶段构建）
├── package.json                   # 项目元信息
└── LICENSE                        # Apache 2.0

4.2 核心模块介绍

模块一：`docker_service.ts` — Docker 容器管理（核心中的核心）

整个项目最关键的服务，负责所有 Docker 容器的生命周期管理。通过 dockerode 库与 Docker Engine 通信，实现服务的安装、卸载、启动、停止、更新等操作。

核心方法：

affectContainer(serviceName, action) — 启动/停止/重启容器
getServicesStatus() — 获取所有 nomad_ 前缀容器状态（5 秒缓存 + 并发请求合并）
createContainerPreflight(serviceName) — 安装前检查（防并发安装）
forceReinstall(serviceName) — 强制重装（停止→移除→清理卷→重建）
_createContainer(service, containerConfig) — 实际创建容器

关键设计：

支持 Linux（Unix socket）和 Windows（named pipe）两种 Docker 连接
内存级 activeInstallations Set 防止并发安装竞态条件
通过 Transmit SSE 广播安装进度事件
卷清理策略：只移除 Docker 命名卷，不动主机绑定挂载

模块二：`ollama_service.ts` — AI 模型管理

管理 Ollama 本地 AI 模型的下载、加载和对话。

核心方法：

downloadModel(model, progressCallback, signal, jobId) — 模型下载（支持取消、进度报告、并发去重）
chatStream(chatRequest) — 流式聊天（AsyncIterable）
embed(model, texts) — 文本向量化（用于 RAG）
getModels() — 获取已安装模型列表

关键设计：

支持远程 Ollama URL，可连接 LM Studio、llama.cpp 等后端
流式聊天中实现了 think 标签的跨 chunk 解析器
广播节流：500ms 间隔防止 SSE 通道被淹没
activeDownloads Map 防止同一模型并发下载

模块三：`rag_service.ts` — RAG 检索增强生成

知识库的核心服务，负责文档的向量化存储和语义检索。

核心方法：

embedAndStoreText(text, metadata, onProgress) — 文本分块、嵌入、存储到 Qdrant
preprocessQuery(query) — 查询预处理（领域术语扩展）
extractKeywords(query) — 关键词提取（混合搜索）

关键设计：

使用 nomic-embed-text:v1.5 嵌入模型（768 维）
文本分块：1500 tokens/块，300 字符重叠
批量嵌入：每批 8 个块（适配低端硬件）
内置应急准备领域术语词典（BOB、EDC、MRE、SHTF 等）
支持多种文件类型：ZIM（HTML）、PDF（OCR + 文本提取）、图片（Tesseract OCR）

模块四：`download_service.ts` — 下载任务调度

基于 BullMQ 队列的异步下载管理，处理 ZIM 文件、地图数据、AI 模型等大文件下载。

关键设计：

丰富的进度报告（已下载字节/总字节）
基于 Redis 的跨进程 abort signal 支持下载取消
实时状态指示器（绿色=活跃，橙色=停滞，灰色=排队）

模块五：`queue_service.ts` — BullMQ 队列服务

进程级单例模式，管理 BullMQ 队列连接。修复了之前每个静态调用创建新实例导致 ioredis 连接泄漏的问题（5 小时可泄漏 10000+ 连接）。

4.3 模块间调用关系

用户请求 (浏览器)│▼
[Controllers] ─── 路由层接收 HTTP 请求│├──→ ChatsController ──→ ChatService ──→ OllamaService (AI 对话)│                                  └──→ ChatSession/ChatMessage (持久化)│├──→ ServicesController ─→ DockerService (容器生命周期管理)│                          └──→ ContainerRegistryService (镜像版本)│├──→ DownloadsController ─→ DownloadService ──→ QueueService (BullMQ)│                           └──→ OllamaService (模型下载)│                           └──→ MapService (地图下载)│├──→ RAGController ──→ RagService ──→ OllamaService (嵌入模型)│                       └──→ QdrantClient (向量数据库)│                       └──→ ZIMExtractionService (ZIM 解析)│├──→ MapsController ─→ MapService ──→ CountriesService│                       └──→ DownloadService│├──→ BenchmarkController ─→ BenchmarkService ─→ DockerService (sysbench)│                              └──→ OllamaService (AI 性能测试)│└──→ EasySetupController ─→ DockerService (初始安装向导)│▼
[Models] ─── Lucid ORM (MySQL 8.0)├── Service (Docker 服务定义)├── KVStore (键值配置)├── ChatSession / ChatMessage (聊天)├── ContentCollection / ContentResource (内容管理)├── BenchmarkResult / BenchmarkSetting (基准测试)└── KbIngestState (知识库摄入状态)

4.4 核心代码解析：Docker 服务安装流程

以下为 docker_service.ts 中服务安装的核心逻辑：

// 安装前检查 —— 防止并发安装
async createContainerPreflight(serviceName: string) {if (this.activeInstallations.has(serviceName)) {throw new Error(`Service ${serviceName} is already being installed`);}this.activeInstallations.add(serviceName);
}// 实际创建容器
async _createContainer(service, containerConfig) {// 1. 解析容器配置（镜像、端口、卷、环境变量等）// 2. 通过 dockerode 创建容器// 3. 启动容器// 4. 通过 SSE 广播安装进度// 5. 更新数据库中的服务状态// 6. 清理 activeInstallations 标记
}// 获取所有服务状态（带缓存和并发合并）
async getServicesStatus() {// 5 秒缓存 + 并发请求合并// 列出所有 nomad_ 前缀容器// 返回每个容器的运行状态、端口、健康检查结果
}

4.5 Docker Compose 架构

项目使用 6 个 Docker 服务协同工作：

┌─────────────────────────────────────────────────────┐
│                  project-nomad                       │
│                                                     │
│  ┌──────────┐  ┌───────┐  ┌───────┐               │
│  │  admin   │  │ mysql │  │ redis │               │
│  │ (8080)   │←→│ (内部)│←→│ (内部)│               │
│  │ AdonisJS │  │  8.0  │  │  7-alp│               │
│  └────┬─────┘  └───────┘  └───────┘               │
│       │ Docker Socket                                │
│       ▼                                              │
│  ┌──────────┐  ┌────────────┐  ┌────────────────┐ │
│  │ updater  │  │dozzle(可选)│  │ disk-collector │ │
│  │(sidecar) │  │ (9999)     │  │ (特权,只读)    │ │
│  └──────────┘  └────────────┘  └────────────────┘ │
│                                                     │
│  管理的下游容器（按需安装）:                          │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐     │
│  │ Ollama │ │ Qdrant │ │  Kiwix │ │ Kolibri  │ ... │
│  └────────┘ └────────┘ └────────┘ └──────────┘     │
└─────────────────────────────────────────────────────┘

五、项目的应用、优点和不足

5.1 应用场景

场景	说明
应急准备	自然灾害、战争冲突、网络攻击导致基础设施瘫痪时，提供不依赖外部网络的知识终端
离网生活	房车旅行、帆船、偏远小屋，配合太阳能板和电池组，功耗 15-65W 即可运行
隐私与数据自主	零遥测设计，所有计算和存储均在本地，适合不信任云服务的用户
教育环境	为孩子搭建完全可控的学习环境，只有经过筛选的教育内容，无广告和推荐算法
技术爱好者 / Homelab	自托管知识库、运行本地 LLM、完全掌控数据
野外作业	地质勘探、科考队、军事单位等需要离线信息支持的场景

5.2 项目优点

真正的离线优先：安装后完全脱离互联网，零遥测，极致隐私保护
功能全面：8 大模块覆盖 AI、知识库、教育、地图、数据分析等全方位需求
极低门槛：最低 4GB 内存 + 5GB 存储即可运行基础功能
架构优雅：Docker 容器化编排，服务解耦，一键安装和自我更新
代码质量高：TypeScript 全栈，清晰的 MVC 分层，依赖注入，单例模式
安全意识强：路径遍历防护、CWE-209 安全审计、HMAC 签名防滥用、Dozzle 禁用 shell
活跃维护：69 个 Release 版本，582 次提交，语义化发布自动化
社区生态好：27K+ Star，ZDNet/Cybernews/Hacker News 等主流媒体报道
GPU 加速：支持 NVIDIA 和 AMD GPU，可运行从 3B 到 70B+ 参数的 LLM
Apache 2.0 许可：完全自由使用，包括商业用途
竞品碾压：相比 $199-$699 的商业竞品，功能更强且完全免费
社区排行榜：硬件基准测试 + 匿名分享，促进社区互动

5.3 项目不足

仅支持 Debian 系 Linux：不支持 CentOS、Arch、Fedora 等其他 Linux 发行版，Windows/macOS 仅能通过 WSL2 或虚拟机运行
无身份认证机制：设计为开放可用，不建议直接暴露到互联网，在共享网络环境中存在安全风险
AI 模型能力有限：默认 Qwen 2.5 3B 模型能力有限，运行大模型需要高端 GPU 和大量存储
离线地图体验有限：区域地图需要预先下载，全球地图数据量巨大（数百 GB），无法与在线地图相媲美
内容更新依赖手动：ZIM 文件和地图数据需要手动下载更新，无法自动同步最新内容
存储需求大：完整安装（含维基百科全量 + 地图 + AI 模型）可能需要 500GB+ 存储
RAG 性能依赖硬件：文档向量和语义搜索在低端硬件上较慢，批量嵌入每批仅 8 个块
前端技术栈较重：AdonisJS + React + Inertia.js 的组合相对小众，社区资源有限
安装脚本仅支持 x86_64：ARM64（如树莓派）仅为实验性支持
部分功能尚在开发中：根据公开路线图，部分计划功能尚未实现