Docker Compose 部署 nanobot：超轻量本地 AI 助手搭建指南

1. 为什么我最终选择了 nanobot 而不是其他方案1.1 从一次“助手泛滥”的困扰说起去年有段时间我同时开着好几个 AI 工具浏览器里挂着网页版对话本地跑着一个大模型推理服务手机里还装了两三个助手类应用。结果就是——每个工具都只解决一小块问题真正需要“随手问一句、顺手记一下”的时候反而要在几个窗口之间来回切。更麻烦的是有些对话内容涉及我自己的笔记和项目资料走云端总让我心里不太踏实。后来我开始找一种更“收敛”的方案一个能跑在自己机器上、界面干净、能对接本地模型、还能通过容器一键拉起来的轻量助手。试过几个开源项目之后nanobot 进入了我的视野。它的定位很明确——超轻量的个人 AI 助手不追求大而全而是把“对话 本地模型 简洁 WebUI”这条链路做扎实。配合 Docker 部署基本上就是“拉镜像、写 Compose、起容器”三步走。这篇文章就是把我从零到跑通、再到日常使用的完整过程整理出来。适合两类人看一是手里有台闲置机器NAS、小主机、旧笔记本想折腾点实用东西的朋友二是已经用过一些 AI 工具但想要一个更可控、更私密、部署更省心的本地助手的同学。全程不需要你懂太多底层原理跟着 Compose 配置抄作业就行。1.2 nanobot 到底解决了什么问题先把话说清楚nanobot 不是一个“万能 AI 平台”它更像是一个个人助手的外壳。核心能力可以拆成三块对话入口提供一个 WebUI浏览器打开就能聊不用装客户端。模型对接可以接本地推理服务比如常见的本地大模型运行时也可以接兼容接口的在线服务具体看你自己的取舍。容器化交付官方和社区都提供了 Docker 镜像配合 Compose 可以把依赖、网络、存储一次性定义清楚。这三块组合起来解决的就是“我想有个自己的助手但不想被某个平台绑死、也不想每次重装系统都重新配一遍”的问题。Docker 在这里的价值不是赶时髦而是把环境固化下来——今天跑通的配置半年后换台机器改几个路径就能复现。1.3 部署前你需要想清楚的三件事在动手之前我建议你先花五分钟想清楚下面三个问题这比急着敲命令重要得多。第一模型从哪来。nanobot 本身不包含模型权重它需要一个推理后端。你可以用本地跑的模型服务也可以用兼容接口的在线服务。本地跑的好处是数据不出机器代价是需要一定的显存或内存在线服务省资源但对话内容会经过外部。这个取舍只有你自己能定。第二数据存哪。对话记录、配置、可能的向量数据都要挂载到宿主机上否则容器一删就全没了。我习惯在宿主机建一个专门的目录比如/opt/nanobot/data所有持久化内容都往里放。第三怎么访问。如果只是本机用映射到127.0.0.1最安全如果想让局域网内其他设备也能用就映射到0.0.0.0但要想清楚网络边界。这一步的配置直接写在 Compose 的端口映射里。把这三个问题想明白后面的步骤就是纯执行了。2. 环境准备Docker 与 Compose 的安装细节2.1 不同系统下 Docker 的安装路径差异Docker 的安装本身不复杂但不同系统踩的坑完全不一样我分开说。Linux以 Ubuntu 为例最稳的方式是用官方仓库安装而不是系统自带的版本。系统自带的往往版本偏旧Compose 插件可能缺失。大致流程是先更新包索引、装依赖、添加官方仓库、再安装。装完之后用docker --version和docker compose version各验证一次。注意这里有个高频坑老教程里写的是docker-compose带横杠新版本已经统一成docker compose空格。如果你敲docker compose提示unknown command八成是 Compose 插件没装上补装一下插件包即可。Windows推荐直接装 Docker Desktop。安装过程中它会让你确认是否启用相关虚拟化组件这一步必须同意否则启动时会报虚拟化支持相关的错误。装完第一次启动可能要等一会儿右下角图标变成稳定状态才算就绪。如果你在 Windows 上遇到启动失败并提示虚拟化未检测到先去 BIOS 里确认虚拟化开关是打开的再检查系统里相关的功能组件有没有启用。macOS同样是 Docker DesktopApple 芯片和 Intel 芯片的安装包不同别下错。装完之后建议在设置里给容器分配足够的内存默认值有时候偏小跑模型对接会卡。2.2 验证 Docker 是否真的可用很多人装完看到图标亮了就以为好了其实要验证两件事守护进程是否在跑以及当前用户有没有权限。在 Linux 上普通用户默认不在 docker 用户组里直接敲 docker 命令会提示权限不足。解决办法是把当前用户加入 docker 组然后重新登录一次让权限生效。这一步不做后面所有命令都得加 sudo很别扭。验证命令很简单docker run --rm hello-world能正常输出一段欢迎信息说明守护进程、镜像拉取、容器运行这条链路是通的。如果卡在拉取镜像多半是网络问题换个时间段或者配置镜像加速再试。2.3 Compose 版本与项目目录规划Compose 现在已经是 Docker 的一部分用docker compose version确认即可。我建议在宿主机上先规划好目录结构后面所有操作都在这个目录里进行mkdir -p /opt/nanobot/{data,config,logs} cd /opt/nanobot这样做的原因是Compose 文件里会用相对路径挂载这些目录目录结构清晰迁移的时候整个/opt/nanobot打包带走就行。我见过太多人把数据卷散落在各处最后想备份都找不全。提示目录权限要提前处理好。容器内进程往往以非 root 用户运行如果宿主机目录权限太严容器会写不进去表现为启动后日志报权限错误。稳妥做法是先把目录属主调整成容器内对应的用户或者临时放宽权限再收紧。3. 编写 Compose 配置把服务定义清楚3.1 一份可直接复用的 compose.yaml下面这份配置是我实际在用的精简版本去掉了花哨的东西只保留核心。你可以直接拿去改路径和端口。services: nanobot: image: nanobot/nanobot:latest container_name: nanobot restart: unless-stopped ports: - 127.0.0.1:8080:8080 volumes: - ./data:/app/data - ./config:/app/config - ./logs:/app/logs environment: - TZAsia/Shanghai - NANOBOT_MODEL_ENDPOINThttp://host.docker.internal:11434 - NANOBOT_MODEL_NAMEyour-model-name extra_hosts: - host.docker.internal:host-gateway这份配置里有几个点值得展开说因为它们直接决定了能不能跑通。3.2 端口映射为什么我坚持绑 127.0.0.1端口映射写成127.0.0.1:8080:8080而不是8080:8080是故意的。前者意味着只有本机能访问局域网里其他设备连不上后者会监听所有网卡同一网络下的任何人都能访问。如果你的机器是个人电脑、只自己用绑127.0.0.1是最省心的安全选择。如果确实需要局域网访问比如手机也想用再改成0.0.0.0或者具体的内网 IP同时确保你的网络环境是可信的。这个决定没有标准答案但一定要有意识地做而不是随手复制。3.3 模型对接容器怎么访问宿主机上的服务这是新手最容易卡住的地方。假设你的模型推理服务跑在宿主机的11434端口容器里直接写localhost:11434是访问不到的——因为容器里的 localhost 指的是容器自己。解决办法有两种。一种是用host.docker.internal这个特殊域名指向宿主机配合extra_hosts里的host-gateway配置在 Linux 上也能用。另一种是把模型服务也放进同一个 Compose 网络里用服务名互相访问。前者适合模型服务已经在宿主机跑着的情况后者适合你想把所有东西都容器化。我选的是前者因为模型服务我经常单独重启调试放在容器外更灵活。配置里的NANOBOT_MODEL_ENDPOINT就指向host.docker.internal加端口。3.4 数据卷挂载哪些目录必须持久化三个挂载点各有用途data存对话记录和运行时数据config存配置文件logs存日志。这三个都必须挂出来否则容器重建后一切归零。有个细节挂载用的是相对路径./data相对于 compose.yaml 所在目录。所以一定要在/opt/nanobot目录里执行 compose 命令否则路径会错位。我习惯在命令前先pwd确认一下当前位置这个习惯帮我避免过好几次“数据莫名其妙没了”的乌龙。4. 启动、验证与首次配置4.1 启动命令与日志观察配置写好后在 compose.yaml 所在目录执行docker compose up -d-d是后台运行。启动后别急着打开浏览器先看日志docker compose logs -f nanobot日志里会显示服务初始化过程。正常情况下你会看到监听端口的提示、模型连接的状态。如果模型连接失败日志里通常会有明确的报错比如连接超时或者返回格式不对。这一步是排查问题的黄金窗口比在界面上瞎点高效得多。4.2 打开 WebUI 并完成初始设置浏览器访问http://127.0.0.1:8080应该能看到界面。第一次进入可能需要设置管理员账号或者确认一些基础配置按提示走就行。如果页面打不开按这个顺序排查先确认容器状态是 runningdocker compose ps再看端口有没有被占用ss -tlnp | grep 8080最后检查防火墙规则。这三步能覆盖九成的“打不开”问题。4.3 发一条消息验证整条链路界面能打开不代表模型能通。发一条简单的消息观察返回。如果一直转圈或者报错回到日志里找线索。常见的失败原因包括模型名称写错、接口地址不对、模型服务本身没启动、网络不通。我建议第一次测试用最短的提示词比如“你好”减少变量。等链路通了再去调参数、换模型。5. 实际使用中踩过的坑与排查思路5.1 容器起来了但模型连不上这是最高频的问题。排查链路我总结成一条线先确认模型服务本身可用再确认容器能访问到它最后确认配置参数正确。第一步在宿主机上直接请求模型服务的接口确认它活着。第二步进容器里用 curl 请求同样的地址确认网络通。第三步核对配置里的模型名称和接口路径注意有些服务需要在路径里带版本号。我遇到过一次模型服务监听的是127.0.0.1而不是0.0.0.0导致容器通过host.docker.internal访问时被拒。把模型服务的监听地址改成0.0.0.0就好了。这个坑很隐蔽因为宿主机上测试一切正常。5.2 数据没保存容器一删全没了前面强调过挂载但还是要再提醒一次。判断数据有没有真正落盘最简单的办法是往data目录里看一眼有没有文件生成。如果目录是空的说明挂载没生效或者路径写错了。还有一种情况是权限问题导致写入失败容器表面在跑实际写不进去。日志里会有权限相关的报错别忽略。5.3 端口冲突与访问异常8080 是个很热门的端口被占用是常事。启动时报端口绑定失败换个端口就行比如映射成18080:8080。注意左边是宿主机端口右边是容器内端口改左边即可。另外如果你之前用docker run起过同名容器再compose up可能冲突。先docker compose down清理干净再起。5.4 更新镜像后配置丢失更新镜像的正确姿势是先备份config和data目录再docker compose pull拉新镜像然后docker compose up -d重建容器。因为配置和数据都挂载在宿主机上重建容器不会丢。但如果你把配置写在了镜像内部或者没挂载那就麻烦了。这也是我坚持所有重要内容都挂载的原因。6. 让 nanobot 更好用的几个进阶思路6.1 和本地知识库结合nanobot 作为对话入口如果能接上你自己的文档资料实用性会大幅提升。思路是把文档做向量化处理后存起来对话时先检索再交给模型。这部分需要额外的组件但整体架构还是容器化的可以再起一个服务放进同一个 Compose 网络里用服务名互相访问。6.2 多设备访问与反向代理如果你想让手机、平板都能用可以在前面加一层反向代理统一处理访问入口和证书。反向代理同样可以用容器跑和 nanobot 放在一个网络里。这样对外只暴露代理端口nanobot 本身不直接对外安全性更好。6.3 资源限制与稳定性在 Compose 里可以给服务加资源限制比如限制内存和 CPU避免助手把整台机器拖垮。对于长期运行的服务加上restart: unless-stopped能让它在异常退出后自动拉起。这两条配置看起来不起眼但对稳定性影响很大。6.4 备份策略我的做法是写一个简单的脚本定期把/opt/nanobot整个目录打包保留最近几份。因为所有状态都在这个目录里备份和恢复都极其简单。恢复的时候把目录放回原位docker compose up -d就完事了。这种“一个目录搞定一切”的部署方式是我越来越偏爱容器化的核心原因。7. 我个人的几点体会折腾这套东西最大的感受是轻量方案的价值不在于功能多而在于你能完全掌控它。nanobot 没有堆砌一堆用不上的功能反而让部署和维护变得简单。Compose 文件就那几十行出问题的时候一眼能看完不用在复杂的配置海洋里捞针。另一个体会是关于“本地优先”的取舍。本地跑模型确实吃资源但换来的是数据可控和响应稳定。如果你的机器配置一般可以先接在线服务跑通流程等确认这个助手真的融入你的日常了再考虑把模型迁到本地。先跑通再优化这个顺序别搞反。最后说个实操小技巧每次改完 Compose 配置别直接up -d先docker compose config验证一下语法。这个命令会把最终解析后的配置打印出来路径、环境变量、端口一目了然。我靠它提前发现过好几次路径写错的问题省下了反复重启的时间。