Docker 部署 nanobot：轻量级个人 AI 助手搭建指南

1. 为什么我选择用 Docker 跑 nanobot

1.1 从一次折腾说起

去年年底我开始琢磨着给自己搭一个轻量级的 AI 助手，需求其实很简单：能对接本地模型、能通过浏览器访问、能记住对话上下文、最好还能挂个知识库。前前后后试过好几个方案，有的太重，光依赖就装了一下午；有的太轻，功能少得可怜。直到在一个技术群里看到有人提到 nanobot 这个项目，说是“超轻量个人 AI 助手”，我抱着试试看的心态用 Docker 跑了一下，结果从拉镜像到 WebUI 能打开，前后不到十分钟。

这篇文章就是把我整个部署过程、踩过的坑、以及后续优化的一些经验完整记录下来。如果你手头有一台闲置的 Linux 服务器、NAS，或者就是想在自己电脑上跑一个私人的 AI 助手，那这篇内容应该能帮你省下不少查文档的时间。

1.2 nanobot 到底是个什么东西

先把概念理清楚。nanobot 本质上是一个轻量级的 AI 代理框架，它的核心思路是把大语言模型的调用、对话管理、工具调用、知识库检索这些能力打包成一个可以独立运行的服务。你可以把它理解成一个“AI 助手的骨架”，你往里面填模型、填配置，它就能跑起来给你干活。

它和 Open WebUI 这类项目最大的区别在于定位。Open WebUI 更像是一个“前端界面 + 多模型管理平台”，功能全但体量也大；nanobot 则更偏向于“一个能快速启动的 AI 代理服务”，核心代码精简，资源占用低，适合个人用户或者小团队快速搭建自己的助手。

我实测下来，nanobot 在 1 核 1G 的轻量服务器上就能跑起来，内存占用稳定在 300MB 左右，这对于预算有限或者想跑在 NAS 上的用户来说非常友好。

1.3 为什么用 Docker 而不是直接装

这个问题我被问过很多次。直接装也不是不行，但 Docker 方案有几个实打实的好处：

• 环境隔离：nanobot 依赖 Python 环境和一堆库，直接装在宿主机上容易和系统自带的 Python 版本打架。Docker 把这一切封在容器里，宿主机干干净净。
• 迁移方便：今天在 Ubuntu 上跑，明天想换到群晖 NAS 上，直接把 compose 文件和 volumes 目录拷过去就行，不用重新配环境。
• 版本管理：想升级就换个镜像 tag，想回滚就换回去，比 pip 卸载重装靠谱得多。
• 数据持久化：对话记录、知识库文件、配置文件通过 volume 挂载出来，容器删了数据还在。

所以我的建议很明确：除非你有特殊需求必须裸装，否则一律走 Docker。

2. 部署前的环境准备与检查

2.1 硬件与系统要求

nanobot 本身对硬件要求不高，但你要跑本地模型的话，硬件瓶颈主要在模型那边。下面是我整理的一个参考表：

操作系统方面，Ubuntu 20.04/22.04、Debian 11/12 是最省心的，CentOS 和 Rocky Linux 也能跑，但要注意 SELinux 可能会拦 volume 挂载。Windows 用户建议用 WSL2 或者 Docker Desktop，NAS 用户（群晖、绿联等）直接用自带的 Docker 套件就行。

2.2 Docker 与 Docker Compose 安装

如果你还没装 Docker，下面这套命令在 Ubuntu 22.04 上实测可用：

# 更新包索引 sudo apt update # 安装依赖 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG key sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装 Docker Engine 和 Compose 插件 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 把当前用户加入 docker 组，避免每次都要 sudo sudo usermod -aG docker $USER newgrp docker # 验证 docker --version docker compose version

注意：docker compose和docker-compose是两个东西。新版 Docker 自带的是docker compose（作为插件），老版本是独立的docker-compose命令。网上很多教程混着写，你执行的时候如果报docker: unknown command: docker compose，说明你的 Docker 版本太老，需要升级或者单独装 compose 插件。

Windows 用户如果装 Docker Desktop 遇到Virtualization support not detected的报错，基本就是 BIOS 里没开虚拟化。重启进 BIOS，找到 Intel VT-x 或 AMD-V 选项打开就行。另外 Windows 家庭版需要先装 WSL2，这个在 Docker Desktop 安装向导里会有提示。

2.3 目录规划与端口确认

在开始之前，先把目录结构规划好。我习惯把所有 Docker 项目放在/opt/docker下面，每个项目一个子目录：

sudo mkdir -p /opt/docker/nanobot/{data,config,logs} cd /opt/docker/nanobot

端口方面，nanobot 默认的 WebUI 端口是 8080，但 8080 太容易被占用了。我建议先查一下端口占用情况：

# 查看 8080 是否被占用 ss -tlnp | grep 8080 # 如果被占用，换成 18080 或者其他端口

我自己的习惯是用 18080 作为 WebUI 端口，18081 作为 API 端口，这样不容易和别的服务冲突。

3. 编写 docker-compose.yml 与核心配置

3.1 compose 文件完整拆解

下面是我实际在用的docker-compose.yml，每一行我都加了注释说明为什么这么写：

version: "3.8" services: nanobot: # 镜像选择：官方镜像 tag 建议锁定具体版本，不要用 latest image: nanobot/nanobot:latest container_name: nanobot restart: unless-stopped # 端口映射：宿主机端口:容器端口 ports: - "18080:8080" # WebUI - "18081:8081" # API 接口 # 环境变量：模型配置、密钥等 environment: - TZ=Asia/Shanghai - NANOBOT_MODEL_PROVIDER=openai - NANOBOT_MODEL_NAME=gpt-4o-mini - NANOBOT_API_KEY=sk-xxxxxxxxxxxx - NANOBOT_BASE_URL=https://api.openai.com/v1 - NANOBOT_MAX_TOKENS=4096 - NANOBOT_TEMPERATURE=0.7 - NANOBOT_LOG_LEVEL=info # 数据持久化 volumes: - ./data:/app/data - ./config:/app/config - ./logs:/app/logs # 资源限制：防止容器吃满宿主机资源 deploy: resources: limits: cpus: "2.0" memory: 2G reservations: memory: 512M # 健康检查 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s # 网络配置 networks: - nanobot-net networks: nanobot-net: driver: bridge

3.2 关键参数逐个说明

镜像 tag 的选择：很多人图省事直接写latest，但我不推荐。latest意味着每次docker compose pull都可能拉到新版本，万一新版本有 breaking change，你的服务就挂了。建议去镜像仓库看一下有哪些 tag，选一个稳定的版本号锁定。

环境变量里的模型配置：NANOBOT_MODEL_PROVIDER决定了你用哪家的模型。如果你用本地模型（比如通过 Ollama 跑的），这里要改成ollama，然后NANOBOT_BASE_URL指向 Ollama 的地址。如果你用云端 API，就填对应的 base URL 和 key。

资源限制：deploy.resources.limits这组配置在docker compose模式下需要 Docker Swarm 才生效，普通模式下要用mem_limit和cpus。不过新版 Docker Compose V2 已经支持deploy字段了，实测在 Docker 24.x 上是可以生效的。如果你发现限制没起作用，可以改成：

mem_limit: 2g cpus: 2.0

健康检查：start_period这个参数很关键。nanobot 启动时需要加载配置、初始化模型连接，大概需要 20-30 秒。如果不设start_period，健康检查会在容器还没完全启动时就判定失败，导致容器被反复重启。

3.3 对接本地模型的配置方式

如果你打算用本地模型，最常见的组合是 Ollama + nanobot。假设你的 Ollama 跑在宿主机上，端口是 11434，那么 nanobot 的配置要改成：

environment: - NANOBOT_MODEL_PROVIDER=ollama - NANOBOT_MODEL_NAME=qwen2.5:7b - NANOBOT_BASE_URL=http://host.docker.internal:11434

注意：host.docker.internal这个域名在 Linux 上默认是不存在的，需要在 compose 文件里加一行extra_hosts：

extra_hosts: - "host.docker.internal:host-gateway"

如果你把 Ollama 也放在 Docker 里跑，那就更简单了，两个容器放同一个 network 下，直接用容器名访问：

environment: - NANOBOT_BASE_URL=http://ollama:11434

4. 启动、验证与 WebUI 初体验

4.1 启动容器与日志观察

配置文件写好后，启动就一条命令：

cd /opt/docker/nanobot docker compose up -d

-d是后台运行。启动后立刻看日志：

docker compose logs -f nanobot

正常情况下你会看到类似这样的输出：

[INFO] Loading config from /app/config/config.yaml [INFO] Initializing model provider: openai [INFO] Model: gpt-4o-mini [INFO] Starting WebUI server on 0.0.0.0:8080 [INFO] Starting API server on 0.0.0.0:8081 [INFO] nanobot is ready

看到nanobot is ready就说明启动成功了。如果卡在某个步骤不动，或者报错，先看日志里的错误信息，大部分问题都能从日志里找到线索。

4.2 验证服务是否正常

三个验证步骤，缺一不可：

# 1. 检查容器状态 docker compose ps # 2. 检查健康检查结果 docker inspect --format='{{.State.Health.Status}}' nanobot # 3. 直接请求健康检查接口 curl http://localhost:18080/health

如果健康检查返回healthy，接口返回{"status":"ok"}，那就没问题了。如果返回unhealthy，去看日志，通常是模型连接失败或者配置文件格式错误。

4.3 WebUI 功能速览

浏览器打开http://你的服务器IP:18080，就能看到 nanobot 的 WebUI 了。界面很简洁，左侧是对话列表，中间是聊天区域，右侧是设置面板。

第一次进去建议先做三件事：

1. 改默认密码：如果 nanobot 有默认登录凭证，第一时间改掉。
2. 测试对话：随便发一条消息，确认模型能正常响应。
3. 检查上下文长度：在设置里看看max_tokens和context_window的配置，根据你的模型能力调整。

我实测下来，nanobot 的 WebUI 响应速度很快，流式输出也很流畅。如果你之前用过 Open WebUI，会发现 nanobot 的界面更简洁，功能没那么多，但核心的对话、上下文管理、知识库挂载都有。

4.4 挂载知识库的实操

nanobot 支持挂载本地知识库，这是我觉得最实用的功能之一。操作步骤：

1. 把你的文档（PDF、TXT、Markdown 都行）放到/opt/docker/nanobot/data/knowledge/目录下。
2. 在 WebUI 的设置里找到“知识库”选项，点击“重建索引”。
3. 等索引构建完成，就可以在对话中让 AI 参考知识库内容了。

注意：知识库索引构建比较吃 CPU 和内存，如果文档很多，建议在低峰期操作。另外，文档格式尽量用纯文本或 Markdown，PDF 里的复杂排版可能会导致解析效果打折扣。

5. 常见问题排查与避坑指南

5.1 容器启动失败排查表

下面这个表是我在实际部署中遇到过的各种启动失败情况，以及对应的排查方向：

5.2 三个我踩过的坑

第一个坑：端口映射写反了。ports字段的格式是宿主机端口:容器端口，我一开始写成了8080:18080，结果怎么都访问不了。记住，冒号左边是你浏览器要访问的端口，右边是容器内部服务监听的端口。

第二个坑：volume 权限问题。Docker 容器里的进程通常以非 root 用户运行，如果挂载出来的目录权限是 root:root 且没有写权限，容器启动时会报Permission denied。解决办法：

# 查看容器内进程的 UID docker compose exec nanobot id # 把宿主机目录的属主改成对应的 UID sudo chown -R 1000:1000 /opt/docker/nanobot/data

第三个坑：Docker Desktop 在 Windows 上的网络问题。Windows 上跑 Docker Desktop，容器访问宿主机服务时，localhost是不通的，必须用host.docker.internal。而且 Windows 防火墙有时候会拦截 Docker 的内部网络，如果容器间通信异常，检查一下防火墙规则。

5.3 性能优化的几个实用技巧

跑了一段时间之后，我总结了几条优化经验：

• 限制日志大小：Docker 默认的日志驱动会把所有 stdout 输出写到磁盘，时间长了能把硬盘吃满。在 compose 文件里加日志限制：

logging: driver: "json-file" options: max-size: "10m" max-file: "3"

• 用 SSD 存数据：知识库索引和对话记录对磁盘 IO 比较敏感，机械硬盘上检索速度会明显变慢。
• 定期清理无用镜像：docker system prune -a可以清理掉不用的镜像和缓存，但注意这个命令会删掉所有未使用的镜像，执行前确认一下。
• 模型量化：如果跑本地模型，优先选 4-bit 量化版本，效果损失很小，但显存和内存占用能降一半以上。

6. 进阶玩法与扩展思路

6.1 对接多个模型做 fallback

nanobot 支持配置多个模型 provider，当一个模型不可用时自动切换到备用模型。配置方式是在 config.yaml 里加一个fallback列表：

model: provider: openai name: gpt-4o-mini fallback: - provider: ollama name: qwen2.5:7b base_url: http://ollama:11434

这样当云端 API 超时或者报错时，会自动切到本地模型，保证服务不中断。我实测下来，这个功能在网络不稳定的环境下特别有用。

6.2 用反向代理加 HTTPS

直接暴露 18080 端口不太安全，建议在前面挂一个 Nginx 或者 Caddy 做反向代理，顺便把 HTTPS 配上。Caddy 的配置最简单，两行搞定：

your-domain.com { reverse_proxy localhost:18080 }

Caddy 会自动申请和续期证书，比 Nginx 省心很多。如果你没有域名，也可以用自签名证书，但浏览器会报安全警告。

6.3 备份与迁移方案

nanobot 的所有重要数据都在data和config两个目录里。备份很简单：

# 打包备份 tar -czvf nanobot-backup-$(date +%Y%m%d).tar.gz /opt/docker/nanobot/data /opt/docker/nanobot/config # 迁移到新机器：把 tar 包拷过去，解压，然后 docker compose up -d

我习惯每周自动备份一次，用 cron 定时任务：

# 编辑 crontab crontab -e # 添加一行，每周日凌晨 3 点备份 0 3 * * 0 tar -czvf /backup/nanobot-$(date +\%Y\%m\%d).tar.gz /opt/docker/nanobot/data /opt/docker/nanobot/config

6.4 后续可以折腾的方向

如果你已经把基础版跑起来了，下面这几个方向可以继续折腾：

• 接入更多工具：nanobot 支持 function calling，可以给它挂上天气查询、网页搜索、日历管理这些工具。
• 多用户隔离：如果想让家人朋友也用，可以配置多用户模式，每个人独立的对话历史和知识库。
• 对接企业知识库：把公司内部的文档、Wiki 导入知识库，做一个内部问答助手。
• 移动端适配：nanobot 的 WebUI 是响应式的，手机浏览器访问体验也不错，可以加到主屏幕当 PWA 用。

我在实际使用中最大的体会是，nanobot 这种轻量级方案最大的优势不是功能多，而是“够用且不折腾”。它不会让你花大量时间在环境配置和依赖冲突上，而是让你把精力放在真正重要的事情上——怎么把 AI 助手调教得更符合自己的需求。如果你也在找一个小巧、稳定、能长期跑的 AI 助手方案，nanobot 值得一试。