1. 为什么我最终选了 nanobot 而不是其他 AI 助手方案1.1 从一次折腾了三天的部署说起前阵子我想给自己搭一个能长期跑在 NAS 上的个人 AI 助手需求其实很朴素能对话、能记住上下文、能挂本地模型、最好有个网页界面别太吃资源。一开始我试了几个热门的开源方案要么依赖一大堆 Python 包装到一半就报版本冲突要么镜像动辄好几个 G我那台 4G 内存的小主机直接卡死。折腾到第三天我在一个技术群里看到有人提到 nanobot 这个项目说是超轻量抱着试试看的心态拉了下来结果从docker compose up到浏览器里能正常对话前后不到十分钟。这就是我写这篇东西的起因。nanobot 这个项目最大的特点就是轻——镜像体积小、内存占用低、依赖少非常适合个人用户或者小团队拿来当自用的 AI 助手底座。它本身是一个 AI 代理agent框架可以对接本地模型比如通过 Ollama 跑起来的模型也可以对接云端 API同时自带一个 WebUI打开浏览器就能用不需要额外装客户端。这篇文章适合谁看如果你满足下面任意一条那接下来的内容应该对你有用手里有一台闲置的机器NAS、迷你主机、旧笔记本、云服务器都行想跑个自己的 AI 助手对 Docker 有一点点了解但没系统部署过带 WebUI 的 AI 服务想用本地模型不想把对话数据发到别人服务器上之前被各种一键部署脚本坑过想要一份能看懂每一步在干什么的教程。我会从整体思路讲起然后拆解核心配置再给完整的实操流程最后把我踩过的坑整理成排查表。全程用 Docker Compose 编排命令都是可以直接复制粘贴的。1.2 nanobot 到底是个什么东西先把概念理清楚不然后面配置容易懵。nanobot 本质上是一个AI 代理运行时你可以把它理解成一个中间层一边连着大模型本地或云端一边提供对外的交互接口WebUI、API。它自己不训练模型也不存储模型权重它负责的是把用户的输入整理好、带上上下文和工具调用能力发给模型再把模型的回复处理成人类能看的形式。这种架构的好处很明显。模型可以随时换今天用本地的小模型明天想换成更大的只要改一下配置里的模型地址就行nanobot 本身不用动。工具调用比如让 AI 帮你查天气、算数、读文件也是在这一层实现的跟具体用哪个模型解耦。跟同类项目比nanobot 的差异化在于极简。很多 AI 助手框架功能确实全但配置项几百个文档看得人头大。nanobot 的配置文件相对精简核心就是模型地址、端口、密钥这几项新手半小时能搞明白。代价是它没有那些花哨的企业级功能比如多租户、权限体系、审计日志——但对个人用户来说这些本来也用不上。1.3 整体部署架构长什么样在动手之前先在脑子里画一张图。我这套方案一共涉及三个部分组件作用是否必须nanobot 容器AI 代理核心 WebUI必须模型服务提供推理能力本地 Ollama 或云端 API必须数据卷持久化配置和对话记录强烈建议如果你用云端 API那模型服务这部分就不用自己搭填个地址和密钥就行。如果你想完全本地化那就再起一个 Ollama 容器nanobot 通过 Docker 内部网络去访问它。我个人的选择是本地 Ollama原因很简单数据不出门而且不花钱。三个组件之间的通信走 Docker 的自定义网络这样容器之间可以用服务名互相访问不用记 IP。数据卷挂载到宿主机上这样容器删了重建配置和聊天记录还在。这套结构听起来简单但每一步都有坑下面逐个拆。2. 部署前的环境准备与关键决策2.1 Docker 和 Compose 的安装要点不管你用 Windows、macOS 还是 Linux第一步都是把 Docker 装好。Windows 和 macOS 用户直接去官网下 Docker Desktop 就行安装过程一路下一步没什么好说的。Linux 用户尤其是 Ubuntu建议用官方脚本装别用系统自带的 apt 版本那个版本往往太旧Compose 插件可能都没有。Ubuntu 上我一般这么操作# 卸载可能存在的旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg # 添加官方 GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 添加软件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin装完之后验证一下docker --version docker compose version两个命令都能正常输出版本号说明装好了。这里有个细节新版 Docker 的 Compose 是作为插件存在的命令是docker compose中间有空格不是老的docker-compose中间有横杠。如果你敲docker compose报unknown command八成是装成了老版本或者插件没装上。提示Linux 下如果不想每次都敲 sudo把自己加到 docker 用户组里sudo usermod -aG docker $USER然后重新登录一次生效。这一步能省很多事但要注意加进 docker 组等于给了这个用户 root 级别的权限自己权衡。Windows 用户有个高频报错值得提前说Virtualization support not detected或者Docker Desktop failed to start。这基本是两个原因——要么 BIOS 里没开虚拟化Intel VT-x / AMD-V要么 WSL2 没装好。前者进 BIOS 开一下后者在 PowerShell 里跑wsl --install然后重启。这两个问题解决了Docker Desktop 一般就能正常起来。2.2 硬件和系统的最低要求nanobot 本身很轻但它要连的模型服务可能很重。所以硬件要求得分开看只跑 nanobot 云端 API1 核 1G 内存就够镜像体积小跑起来内存占用也就一两百兆。nanobot 本地小模型如 1.5B、3B 参数建议 4 核 8G 内存起步模型加载后大概占 2-4G。nanobot 本地 7B 以上模型建议 8 核 16G 内存有独立显卡更好纯 CPU 推理会慢到让你怀疑人生。磁盘空间方面Docker 镜像本身加上模型文件预留 20G 比较稳妥。模型文件是大头一个 7B 的量化模型动辄 4-5G。系统层面Linux 是最省心的Windows 和 macOS 因为有 Docker Desktop 这层虚拟化性能会打点折扣但日常用没问题。NAS 用户要注意群晖、绿联这类设备的 Docker 版本可能比较老Compose 语法支持不全遇到问题优先考虑升级系统或者用命令行手动跑容器。2.3 网络与端口规划端口规划这事很多人忽略结果部署完发现端口冲突服务起不来。我一般这么规划服务容器内端口宿主机端口说明nanobot WebUI30003000浏览器访问入口Ollama API1143411434本地模型服务宿主机端口可以改比如 3000 被占了就改成 13000只要在 compose 文件里对应改一下就行。但要注意容器内端口一般不要动因为容器内部的服务是监听固定端口的改了容易出问题。网络模式上我强烈建议用自定义 bridge 网络而不是默认的 bridge。原因有两个一是自定义网络里容器可以用服务名互相访问配置里写http://ollama:11434就行不用管 IP二是默认 bridge 网络的容器之间默认不通还得手动 link麻烦。自定义网络在 compose 文件里声明一下就行后面会给完整示例。3. Compose 文件逐行拆解与配置要点3.1 完整的 compose 文件长什么样先上完整文件然后逐段解释。我把它命名为docker-compose.yml放在一个专门的目录里比如~/nanobot。services: nanobot: image: nanobot/nanobot:latest container_name: nanobot restart: unless-stopped ports: - 3000:3000 environment: - NANOBOT_MODEL_PROVIDERollama - NANOBOT_MODEL_BASE_URLhttp://ollama:11434 - NANOBOT_MODEL_NAMEqwen2.5:3b - NANOBOT_API_KEYyour_api_key_here - TZAsia/Shanghai volumes: - ./data:/app/data - ./config:/app/config networks: - nanobot-net depends_on: - ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped ports: - 11434:11434 volumes: - ./ollama:/root/.ollama networks: - nanobot-net networks: nanobot-net: driver: bridge这个文件不到 40 行但每一行都有讲究。下面拆开说。3.2 镜像选择与版本策略image: nanobot/nanobot:latest这行latest标签意味着每次拉取都是最新版。开发阶段图方便可以用 latest但生产环境我建议锁定具体版本号比如nanobot/nanobot:1.2.3。原因很现实某次更新可能改了配置格式或者环境变量名你docker compose pull之后服务直接起不来排查半天才发现是版本问题。锁定版本升级时手动改标签可控得多。Ollama 那边同理。不过 Ollama 的模型和运行时是分开的镜像更新一般不影响已下载的模型所以用 latest 风险相对小一些。镜像拉取速度是个绕不开的话题。国内网络环境下直接从 Docker Hub 拉镜像可能很慢甚至超时。解决办法是配置镜像加速器在 Docker Desktop 的设置里或者 Linux 的/etc/docker/daemon.json里加上加速地址。这个配置网上教程很多我就不展开了只提醒一句加速器地址会失效多备几个哪个能用用哪个。3.3 环境变量的作用与取值逻辑环境变量这块是配置的核心我逐个解释NANOBOT_MODEL_PROVIDERollama告诉 nanobot 用哪种模型提供方。可选值一般有ollama、openai、anthropic等。用本地 Ollama 就填ollama用云端兼容 OpenAI 接口的服务就填openai。NANOBOT_MODEL_BASE_URLhttp://ollama:11434是模型服务的地址。注意这里写的是ollama而不是localhost或 IP。因为在同一个 Docker 网络里容器可以用服务名互相解析ollama就是上面定义的 service 名。如果你写成localhostnanobot 容器会去连自己内部的 11434 端口那当然连不上——这是新手最容易犯的错。NANOBOT_MODEL_NAMEqwen2.5:3b指定用哪个模型。这个名字必须和 Ollama 里ollama list显示的名字完全一致。我选 3B 参数是因为它在小内存机器上跑得动中文能力也还行。你要是机器够强换成qwen2.5:7b或者llama3.1:8b都行。NANOBOT_API_KEY这个字段用本地模型时其实用不上但有些版本的 nanobot 启动时会校验这个变量是否存在所以随便填个值占位别留空。TZAsia/Shanghai设置时区影响日志时间戳和对话记录的时间。不设的话容器默认 UTC看日志会差 8 小时容易懵。3.4 数据卷挂载的必要性volumes: - ./data:/app/data - ./config:/app/config这两行是把容器内的目录映射到宿主机的./data和./config。为什么要这么做因为容器是无状态的删了重建里面的数据就没了。对话记录、用户配置这些如果存在容器里一次docker compose down就全丢了。映射到宿主机之后数据实际存在你本地的目录里容器怎么折腾都不怕。而且备份也方便直接打包./data目录就行。Ollama 那边挂载./ollama:/root/.ollama是为了持久化模型文件。模型下载一次好几个 G要是每次重建容器都重新下那真是要命。注意挂载目录的权限问题在 Linux 上很常见。如果容器启动后报权限错误检查一下宿主机目录的属主。简单粗暴的办法是chmod -R 777 ./data但不推荐长期这么干正规做法是查清楚容器内运行用户的 UID把宿主机目录改成对应的属主。3.5 依赖关系与启动顺序depends_on: - ollama这行告诉 Docker启动 nanobot 之前先启动 ollama。但要注意depends_on只保证启动顺序不保证 ollama已经准备好接受请求。Ollama 容器起来了但模型可能还在加载这时候 nanobot 去请求会失败。nanobot 一般有重试机制等几秒就好了。如果它没有重试或者你发现启动后第一次对话总是失败那就得考虑加健康检查。不过对个人使用来说等半分钟再打开 WebUI 基本就没事了不用搞太复杂。4. 从零到能用的完整实操流程4.1 目录准备与文件创建先建目录把 compose 文件放进去mkdir -p ~/nanobot cd ~/nanobot mkdir -p data config ollama然后把上面那份 compose 文件内容保存成docker-compose.yml。用nano或者vim都行nano docker-compose.yml粘贴内容CtrlO保存CtrlX退出。这里有个小细节data、config、ollama这三个目录提前建好是为了让 Docker 挂载时直接用现成的目录避免 Docker 自动创建时属主是 root导致后面写文件权限不对。4.2 拉取镜像与启动服务先拉镜像这一步可能要等一会儿取决于网速docker compose pull拉完之后启动docker compose up -d-d是后台运行。启动后看一下状态docker compose ps正常的话两个容器都是Up状态。如果 nanobot 显示Restarting或者Exited那就是出问题了看日志docker compose logs nanobot日志里一般会明确告诉你哪里错了比如连不上模型、配置项缺失、端口被占用等等。4.3 下载并验证本地模型Ollama 容器起来之后里面是空的一个模型都没有。得手动拉一个docker exec -it ollama ollama pull qwen2.5:3b这个命令会下载模型3B 的量化版大概 2G 左右看网速几分钟到十几分钟不等。下载完验证一下docker exec -it ollama ollama list能看到qwen2.5:3b就说明模型就位了。再测一下模型能不能正常推理docker exec -it ollama ollama run qwen2.5:3b 你好请用一句话介绍你自己如果模型正常返回一段文字说明模型服务没问题。这一步很重要先把模型单独验证通过再去排查 nanobot 的问题能省很多时间。因为如果模型本身就没跑起来nanobot 那边怎么调都是白搭。4.4 访问 WebUI 并完成首次对话模型就位后浏览器打开http://你的机器IP:3000。如果是本机直接http://localhost:3000。第一次打开可能会让你做一些初始化设置比如设置管理员密码、选择默认模型。模型那一栏如果下拉框里能看到qwen2.5:3b说明 nanobot 已经成功连上 Ollama 了。选上保存然后就能开始对话了。我实测下来3B 模型在 4 核 8G 的机器上纯 CPU 推理首字延迟大概 2-3 秒后续输出速度每秒 10 个字左右。日常问答够用但别指望它写长文。想要更流畅要么上更好的硬件要么换云端 API。4.5 参数调优让响应更快更稳跑起来之后有几个参数值得调一调体验会好很多。上下文长度。默认的上下文窗口可能比较小多轮对话容易忘事。在 nanobot 的配置里可以调大但要注意上下文越长内存占用越高推理越慢。3B 模型建议设 40967B 模型可以设 8192。温度temperature。这个参数控制输出的随机性。0 最确定1 最随机。日常助手场景建议 0.7 左右既有一定灵活性又不会胡说八道。写代码或者做严谨问答时调到 0.2-0.3。最大输出长度。限制单次回复的长度防止模型啰嗦个没完。设 1024 或 2048 比较合适。这些参数在 WebUI 的设置界面里一般都能改改完即时生效不用重启容器。如果 WebUI 里没有那就得改配置文件然后重启。5. 常见问题排查与避坑经验5.1 容器起不来怎么办这是最高频的问题我整理了一个速查表现象可能原因排查方法容器状态 Restarting配置错误或依赖缺失docker compose logs 服务名看报错端口被占用宿主机端口冲突netstat -tlnp | grep 3000查占用权限拒绝挂载目录属主不对检查目录权限改属主或权限镜像拉取失败网络问题配置镜像加速器重试内存不足被 kill模型太大dmesg | grep -i kill确认换小模型日志是排查的第一手资料遇到问题先看日志90% 的情况日志里写得清清楚楚。5.2 nanobot 连不上模型服务这个问题的表现是WebUI 能打开但一发消息就报错或者一直转圈。排查思路分三步。第一步确认 Ollama 容器在跑docker compose ps。第二步从 nanobot 容器内部去 ping Ollamadocker exec -it nanobot ping ollama如果 ping 不通说明网络有问题检查两个容器是不是在同一个 network 里。第三步如果 ping 通但请求失败那可能是端口或者路径问题用 curl 测一下docker exec -it nanobot curl http://ollama:11434/api/tags能返回模型列表就说明网络和端口都没问题问题出在 nanobot 的配置上重点检查NANOBOT_MODEL_BASE_URL和NANOBOT_MODEL_NAME这两个变量。5.3 模型下载慢或失败Ollama 拉模型走的是它自己的源国内速度不稳定。几个应对办法一是换个时间段试晚上可能快一些二是手动下载模型文件再导入Ollama 支持从本地文件导入模型三是先用小模型跑通流程比如qwen2.5:0.5b只有几百兆下载快验证完流程再换大的。5.4 内存不够用怎么优化小内存机器跑本地模型内存是硬约束。几个优化方向换更小的量化版本比如q4_0比q8_0省一半内存精度损失可接受限制 Ollama 的并发数默认可能允许多个请求同时处理改成 1 能省不少内存调小上下文窗口上下文是内存大户如果实在跑不动本地模型老老实实用云端 APInanobot 本身占用很小云端方案对硬件几乎没要求。5.5 数据备份与迁移数据都在./data和./config目录里备份就是打包这两个目录tar -czvf nanobot-backup-$(date %Y%m%d).tar.gz data config迁移到新机器时把 compose 文件、这两个目录、还有./ollama目录一起拷过去在新机器上docker compose up -d一切照旧。模型文件大如果新机器网络好也可以不拷./ollama重新拉一遍模型。提示升级 nanobot 版本前先备份 data 和 config。万一新版本改了数据格式还能回滚。升级操作就是改 compose 文件里的镜像标签然后docker compose pull docker compose up -d。6. 进阶玩法与扩展思路6.1 接入云端 API 做混合方案本地模型能力有限遇到复杂任务可以切到云端。nanobot 支持配置多个模型提供方在 WebUI 里切换。配置方式是把NANOBOT_MODEL_PROVIDER改成openaiNANOBOT_MODEL_BASE_URL填云端服务的地址NANOBOT_API_KEY填真实的密钥。混合方案的好处是日常闲聊、简单问答用本地模型省钱又保护隐私遇到难题切云端保证效果。切换在界面上点一下就行不用重启服务。6.2 反向代理与域名访问直接暴露 3000 端口不太优雅也不安全。可以用 Nginx 或者 Caddy 做一层反向代理配上域名和 HTTPS。Caddy 配置最简单两行搞定your-domain.com { reverse_proxy localhost:3000 }Caddy 会自动申请和续期证书省心。Nginx 稍微麻烦点但可控性更强。这一步做完就能用https://your-domain.com访问了比记 IP 和端口舒服多了。6.3 让 AI 助手接入更多工具nanobot 的代理能力支持工具调用理论上可以接入搜索、计算、文件读写等能力。具体怎么配取决于版本和文档但思路是通用的在配置里声明工具模型在需要时会自动调用。这块我还在摸索等玩明白了再单独写一篇。6.4 多用户与权限控制nanobot 本身面向个人多用户支持比较弱。如果想让家里人一起用简单的办法是每人起一个实例用不同端口互不干扰。复杂一点可以套一层认证代理但那就偏离轻量的初衷了。我的建议是个人助手就个人用别搞太复杂。7. 我在实际部署中总结的几条经验折腾这一套下来有几个体会值得分享。第一先把模型单独跑通再上 nanobot。很多人一上来就docker compose up结果一堆服务互相依赖出错了根本不知道是哪一层的问题。正确的顺序是Ollama 起来 → 拉模型 → 命令行验证模型能对话 → 再启动 nanobot。这样每一层都是验证过的出问题范围小好排查。第二配置文件里的地址别写 localhost。这是 Docker 新手最常踩的坑。容器里的 localhost 指的是容器自己不是宿主机。容器之间通信用服务名容器访问宿主机用host.docker.internalDocker Desktop或者宿主机的实际 IP。记住这条能省很多调试时间。第三版本锁定比追新重要。个人项目图省事用 latest 没问题但一旦跑起来稳定了就别随便更新。我吃过亏某次手贱docker compose pull结果新版本改了环境变量名服务直接起不来回滚又折腾半天。现在我的习惯是跑通之后把镜像标签改成具体版本号除非有明确需求否则不升级。第四数据备份要养成习惯。Docker 的便利性容易让人忘记数据其实很脆弱。一次误操作docker compose down -v带 -v 会删数据卷聊天记录就没了。定期打包 data 目录花不了几分钟关键时刻能救命。第五别追求一步到位。我见过太多人一开始就想搭一个功能齐全的企业级助手结果配置复杂到自己都维护不了。先用最简配置跑起来用一段时间发现缺什么再加什么。nanobot 的轻量优势就在于可以慢慢长不用一开始就背上沉重的架构包袱。这套方案我目前跑在一台 4 核 8G 的迷你主机上日常当问答助手和文档摘要工具用稳定运行了两个多月没出过问题。如果你也在找一套轻量、可控、数据在自己手里的 AI 助手方案nanobot 加 Docker Compose 这个组合值得试试。