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 a+r /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 + 云端 API：1 核 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 WebUI | 3000 | 3000 | 浏览器访问入口 |
| Ollama API | 11434 | 11434 | 本地模型服务 |
宿主机端口可以改，比如 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_PROVIDER=ollama - NANOBOT_MODEL_BASE_URL=http://ollama:11434 - NANOBOT_MODEL_NAME=qwen2.5:3b - NANOBOT_API_KEY=your_api_key_here - TZ=Asia/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_PROVIDER=ollama告诉 nanobot 用哪种模型提供方。可选值一般有ollama、openai、anthropic等。用本地 Ollama 就填ollama，用云端兼容 OpenAI 接口的服务就填openai。
NANOBOT_MODEL_BASE_URL=http://ollama:11434是模型服务的地址。注意这里写的是ollama而不是localhost或 IP。因为在同一个 Docker 网络里，容器可以用服务名互相解析，ollama就是上面定义的 service 名。如果你写成localhost，nanobot 容器会去连自己内部的 11434 端口，那当然连不上——这是新手最容易犯的错。
NANOBOT_MODEL_NAME=qwen2.5:3b指定用哪个模型。这个名字必须和 Ollama 里ollama list显示的名字完全一致。我选 3B 参数是因为它在小内存机器上跑得动，中文能力也还行。你要是机器够强，换成qwen2.5:7b或者llama3.1:8b都行。
NANOBOT_API_KEY这个字段，用本地模型时其实用不上，但有些版本的 nanobot 启动时会校验这个变量是否存在，所以随便填个值占位，别留空。
TZ=Asia/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粘贴内容，Ctrl+O保存，Ctrl+X退出。
这里有个小细节：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 模型建议设 4096，7B 模型可以设 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 Ollama：
docker 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 能省不少内存；
- 调小上下文窗口，上下文是内存大户；
- 如果实在跑不动本地模型，老老实实用云端 API，nanobot 本身占用很小，云端方案对硬件几乎没要求。
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改成openai，NANOBOT_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.internal（Docker Desktop）或者宿主机的实际 IP。记住这条，能省很多调试时间。
第三，版本锁定比追新重要。个人项目图省事用 latest 没问题，但一旦跑起来稳定了，就别随便更新。我吃过亏，某次手贱docker compose pull，结果新版本改了环境变量名，服务直接起不来，回滚又折腾半天。现在我的习惯是，跑通之后把镜像标签改成具体版本号，除非有明确需求，否则不升级。
第四，数据备份要养成习惯。Docker 的便利性容易让人忘记数据其实很脆弱。一次误操作docker compose down -v（带 -v 会删数据卷），聊天记录就没了。定期打包 data 目录，花不了几分钟，关键时刻能救命。
第五，别追求一步到位。我见过太多人一开始就想搭一个功能齐全的"企业级"助手，结果配置复杂到自己都维护不了。先用最简配置跑起来，用一段时间，发现缺什么再加什么。nanobot 的轻量优势就在于可以慢慢长，不用一开始就背上沉重的架构包袱。
这套方案我目前跑在一台 4 核 8G 的迷你主机上，日常当问答助手和文档摘要工具用，稳定运行了两个多月没出过问题。如果你也在找一套轻量、可控、数据在自己手里的 AI 助手方案，nanobot 加 Docker Compose 这个组合值得试试。
