1. 为什么我选择用 Docker 跑 nanobot1.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 本身对硬件要求不高但你要跑本地模型的话硬件瓶颈主要在模型那边。下面是我整理的一个参考表场景CPU内存硬盘说明仅跑 nanobot 调用云端 API1 核1GB5GB最省配置模型走 APInanobot 本地小模型7B 量化4 核8GB20GB需要 GPU 或纯 CPU 推理nanobot 本地中模型13B 量化8 核16GB40GB建议有独立显卡nanobot 知识库 多用户4 核8GB50GB知识库文件占空间操作系统方面Ubuntu 20.04/22.04、Debian 11/12 是最省心的CentOS 和 Rocky Linux 也能跑但要注意 SELinux 可能会拦 volume 挂载。Windows 用户建议用 WSL2 或者 Docker DesktopNAS 用户群晖、绿联等直接用自带的 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: - TZAsia/Shanghai - NANOBOT_MODEL_PROVIDERopenai - NANOBOT_MODEL_NAMEgpt-4o-mini - NANOBOT_API_KEYsk-xxxxxxxxxxxx - NANOBOT_BASE_URLhttps://api.openai.com/v1 - NANOBOT_MAX_TOKENS4096 - NANOBOT_TEMPERATURE0.7 - NANOBOT_LOG_LEVELinfo # 数据持久化 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: bridge3.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_PROVIDERollama - NANOBOT_MODEL_NAMEqwen2.5:7b - NANOBOT_BASE_URLhttp://host.docker.internal:11434注意host.docker.internal这个域名在 Linux 上默认是不存在的需要在 compose 文件里加一行extra_hostsextra_hosts: - host.docker.internal:host-gateway如果你把 Ollama 也放在 Docker 里跑那就更简单了两个容器放同一个 network 下直接用容器名访问environment: - NANOBOT_BASE_URLhttp://ollama:114344. 启动、验证与 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 了。界面很简洁左侧是对话列表中间是聊天区域右侧是设置面板。第一次进去建议先做三件事改默认密码如果 nanobot 有默认登录凭证第一时间改掉。测试对话随便发一条消息确认模型能正常响应。检查上下文长度在设置里看看max_tokens和context_window的配置根据你的模型能力调整。我实测下来nanobot 的 WebUI 响应速度很快流式输出也很流畅。如果你之前用过 Open WebUI会发现 nanobot 的界面更简洁功能没那么多但核心的对话、上下文管理、知识库挂载都有。4.4 挂载知识库的实操nanobot 支持挂载本地知识库这是我觉得最实用的功能之一。操作步骤把你的文档PDF、TXT、Markdown 都行放到/opt/docker/nanobot/data/knowledge/目录下。在 WebUI 的设置里找到“知识库”选项点击“重建索引”。等索引构建完成就可以在对话中让 AI 参考知识库内容了。注意知识库索引构建比较吃 CPU 和内存如果文档很多建议在低峰期操作。另外文档格式尽量用纯文本或 MarkdownPDF 里的复杂排版可能会导致解析效果打折扣。5. 常见问题排查与避坑指南5.1 容器启动失败排查表下面这个表是我在实际部署中遇到过的各种启动失败情况以及对应的排查方向现象可能原因排查方法解决方案容器反复重启配置文件格式错误docker compose logs nanobot检查 config.yaml 缩进和语法端口无法访问防火墙未放行ss -tlnp | grep 18080开放防火墙端口或换端口健康检查失败start_period 太短看日志启动耗时加大 start_period 到 60s模型调用报错API Key 无效日志里看 401/403检查 key 和 base_url内存溢出被杀模型太大dmesg | grep oom换小模型或加内存volume 挂载失败SELinux 拦截ls -Z /opt/docker/nanobot加:z或:Z后缀网络不通容器间网络隔离docker network inspect确认在同一 network 下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 对接多个模型做 fallbacknanobot 支持配置多个模型 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/config6.4 后续可以折腾的方向如果你已经把基础版跑起来了下面这几个方向可以继续折腾接入更多工具nanobot 支持 function calling可以给它挂上天气查询、网页搜索、日历管理这些工具。多用户隔离如果想让家人朋友也用可以配置多用户模式每个人独立的对话历史和知识库。对接企业知识库把公司内部的文档、Wiki 导入知识库做一个内部问答助手。移动端适配nanobot 的 WebUI 是响应式的手机浏览器访问体验也不错可以加到主屏幕当 PWA 用。我在实际使用中最大的体会是nanobot 这种轻量级方案最大的优势不是功能多而是“够用且不折腾”。它不会让你花大量时间在环境配置和依赖冲突上而是让你把精力放在真正重要的事情上——怎么把 AI 助手调教得更符合自己的需求。如果你也在找一个小巧、稳定、能长期跑的 AI 助手方案nanobot 值得一试。