企业官网建设流程全解析

nanobot 自托管 AI Agent 部署指南：从本地网关到生产级服务

【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot

nanobot 是一个基于 Python 的轻量级、开源、可自托管的个人 AI Agent 框架。本文以官方指南 self-hosted-ai-agent.md 为主线，完整讲解如何在自有机器或服务器上把 nanobot 运行成一个长期在线的网关进程：它将统一承载 WebUI 浏览器工作台、聊天应用（chat apps）、自动化任务与 OpenAI 兼容 API 集成。读完本文，你将掌握从pip安装、config.json模型配置，到 Docker / systemd / macOS LaunchAgent 生产部署、健康检查与安全加固的完整自托管方案。

自托管路径解决什么问题

选择自托管路径，意味着对 Agent 的进程、工作区文件、记忆文件与模型密钥拥有完全的所有权。它与临时运行一个 CLI 命令的本质区别在于：Agent 必须在某条终端命令结束后继续运行——网关进程需要把聊天应用、定时自动化、WebSocket 消息投递等服务长期维持在线上。

从源码结构看，整个自托管能力围绕gateway这一核心命令展开：CLI 入口位于 nanobot/cli/gateway.py，进程生命周期管理（前台/后台、按需启动/常驻）实现在 nanobot/gateway/runtime.py，而网关真正拉起 WebUI、聊天频道、cron 系统任务与健康端点的共享运行时则位于 nanobot/cli/gateway_runtime.py。

安装与最小可用验证

1. 安装 nanobot

官方指南推荐使用 pip 安装稳定版：

python -m pip install nanobot-ai

随后通过向导初始化配置：

nanobot onboard --wizard

该命令会创建~/.nanobot/config.json和~/.nanobot/workspace/。如果配置已存在但版本较旧，可用nanobot onboard --refresh在保留既有值的前提下补充新增的默认字段。

2. CLI 连通性检查

部署网关之前，务必先完成 CLI 检查：

nanobot agent -m "Hello!"

这一步同时验证了安装、配置、Provider、模型与工作区写入五个环节。指南明确强调：部署问题在 Provider 和模型已被证明可用之后要容易调试得多——如果连 CLI 单次对话都不通，就不应继续排查网关或频道问题。

nanobot status可在不调用模型的前提下检查配置与工作区是否就绪、活动模型与 Provider 是否已配置，是部署前最常用的预检命令。

最小可用示例：两个启动入口的选择

nanobot gateway：面向聊天应用与自动化的常驻进程

nanobot gateway

这是聊天应用（Telegram、Discord、Slack、Feishu 等）、自动化任务与 WebSocket 投递的入口。启动后它会加载启用状态的聊天频道、WebUI/WebSocket 通道、cron 系统任务、Dream、心跳与健康端点。默认以前台方式运行，Ctrl+C可停止；需要脱离终端常驻时使用nanobot gateway --background，配合nanobot gateway status、logs、restart、stop管理后台进程。

nanobot webui：浏览器工作台的启动器

nanobot webui

浏览器表面使用 WebUI 启动器，它会为你准备本地 WebUI 设置、启动网关并打开浏览器，通常监听http://127.0.0.1:8765。WebUI 启动器可以替你把本地网关管理起来；关闭最后一个交互式启动器时按需网关才会停止，若希望持久后台运行，可改用nanobot gateway --background。

通过 config.json 接入聊天频道

在~/.nanobot/config.json中启用一个频道后，保持同一个网关进程即可持续接收消息。例如接入 Telegram：

{ "agents": { "defaults": { "workspace": "~/.nanobot/workspace" } }, "channels": { "telegram": { "enabled": true, "token": "YOUR_TELEGRAM_BOT_TOKEN" } }, "gateway": { "host": "127.0.0.1", "port": 18790 } }

注意：config.json使用 camelCase 键（如apiKey、intervalS），snake_case 键仅为兼容而保留；编辑配置后需重启部署的进程，长驻进程只在启动时读取配置。启动频道前可用nanobot channels status预检，用nanobot gateway --verbose观察频道启动日志。

配置模型 Provider：config.json 的连接方式

自托管的关键一步是把模型 Provider 接入config.json。一个通用的 OpenAI 兼容 Provider 配置形如：

{ "providers": { "custom": { "apiKey": "${PROVIDER_API_KEY}", "apiBase": "https://api.example.com/v1" } }, "modelPresets": { "primary": { "provider": "custom", "model": "model-id-from-your-provider" } }, "agents": { "defaults": { "modelPreset": "primary" } } }

三个层次各司其职：

• providers.<name>：定义凭证与端点。apiKey可写apiKey字段，apiBase仅在端点与默认值不同时需要设置；
• modelPresets.<preset>：给模型组合命名（Provider + 模型 ID），便于切换与回退；
• agents.defaults.modelPreset：指定活动预设，决定 Agent 默认调用哪个模型。

配置提示：若配置文件中缺少当前 schema 的字段，运行nanobot onboard --refresh即可补齐默认值。完整的字段参考见 configuration.md，模型与 Provider 匹配问题可先查 providers.md。

生产部署：让进程在终端退出后继续存活

指南强调，当进程需要在终端退出后依然存活时，应使用 Docker、systemd 或 macOS LaunchAgent。以下按官方部署文档 deployment.md 展开三种主流运行时。

部署前的检查清单

Docker Compose 部署

仓库自带 docker-compose.yml 与 Dockerfile。典型流程：

docker compose run --rm nanobot-cli onboard # 首次初始化 vim ~/.nanobot/config.json # 添加 API 密钥 docker compose up -d nanobot-gateway # 启动网关

常用运维命令：

docker compose run --rm nanobot-cli agent -m "Hello!" # 运行 CLI docker compose logs -f nanobot-gateway # 查看日志 docker compose down # 停止

容器以非 root 用户nanobot（UID 1000）运行，读取/home/nanobot/.nanobot下的配置。务必把宿主配置目录挂载到该路径（-v ~/.nanobot:/home/nanobot/.nanobot），而非/root/.nanobot。遇到Permission denied时先在宿主机修正所有权：sudo chown -R 1000:1000 ~/.nanobot，或传入--user $(id -u):$(id -g)匹配宿主 UID。

关键限制：网关与 WebSocket 通道默认绑定host: "127.0.0.1"（默认值定义于 nanobot/config/schema.py）。Docker 的-p端口转发无法到达容器的 loopback 接口，因此要让宿主机或局域网访问暴露的端口，必须在容器启动前把两个绑定都改为0.0.0.0：

{ "gateway": { "host": "0.0.0.0" }, "channels": { "websocket": { "host": "0.0.0.0", "port": 8765, "tokenIssueSecret": "your-secret-here" } } }

当 WebSockethost为0.0.0.0时，频道会拒绝启动，除非同时配置了token、tokenIssueSecret或完整的trustedProxyAuth。健康路由本身刻意保持极简且未认证：容器将其绑定到0.0.0.0时，应只把端口18790发布到宿主 loopback，并把任何远程监控所需的健康端点置于防火墙或反向代理之后。

systemd 用户服务（Linux）

先预览生成的 unit：

nanobot gateway install-service --manager systemd --dry-run

安装、启用并启动：

nanobot gateway install-service --manager systemd

为自定义实例传递与网关运行一致的配置/工作区选择器：

nanobot gateway install-service \ --manager systemd \ --name nanobot-telegram \ --config ~/.nanobot-telegram/config.json \ --workspace ~/.nanobot-telegram/workspace

日常操作：

systemctl --user status nanobot-gateway # 查看状态 systemctl --user restart nanobot-gateway # 修改配置后重启 journalctl --user -u nanobot-gateway -f # 跟踪日志 nanobot gateway uninstall-service --manager systemd

安装器会写入~/.config/systemd/user/nanobot-gateway.service，以当前 Python 解释器执行python -m nanobot gateway --foreground，因此服务运行在你安装 nanobot 的同一环境中。注意：用户服务只在登录期间运行，若要在注销后继续存活，启用 lingering：

loginctl enable-linger $USER

macOS LaunchAgent

nanobot gateway install-service --manager launchd --dry-run # 预览 plist nanobot gateway install-service --manager launchd # 安装并启动

自定义实例与 systemd 用法一致（--name、--config、--workspace）。安装器写入~/Library/LaunchAgents/ai.nanobot.gateway.plist，日志落在~/.nanobot/logs/。若启动报 "address already in use"，先停止手动启动的nanobot gateway进程。

多实例隔离：给每个部署独立的 config、workspace 与端口

指南生产注意事项中强调"给每个部署实例独立的配置路径、工作区路径与端口集合"，这正是 multiple-instances.md 的主题：--config是主要入口，--workspace在需要初始化或更新某个实例的已存工作区时可选传入。

初始化多个实例：

nanobot onboard --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace nanobot onboard --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace

分别运行：

nanobot status --config ~/.nanobot-telegram/config.json nanobot gateway --config ~/.nanobot-telegram/config.json nanobot gateway --config ~/.nanobot-discord/config.json --port 18792

各组件解析来源：

同一时刻运行的每个实例必须使用不同端口；会话数据跟随活动配置目录，每个实例使用独立 workspace 可隔离记忆、技能与稳定的会话命名空间 ID。

健康检查：只探测进程与 WebSocket 通道

指南要求"对网关或 API 进程做健康检查，而不是把聊天应用投递作为唯一信号"。健康检查的实现可以从源码确认：_health_server在 nanobot/cli/gateway_runtime.py 中作为极简 HTTP 端点实现，GET /health的响应载荷由_gateway_readiness_payload生成：

{"status":"ok","process":"alive","ready":true,"websocket":"disabled"}

语义明确：

• 当 WebSocket 通道禁用或运行中，返回200 OK；
• 当 WebSocket 通道已启用但未运行，返回503 Service Unavailable；
• 其他路径返回404；
• ready目前只反映 WebSocket 通道；200响应不验证其他聊天频道、MCP 服务器或模型 Provider 的连通性。

该检查逻辑在 nanobot/gateway/runtime.py 的_gateway_health_ready中用于后台网关就绪诊断，要求响应status == "ok"且ready不为false。默认健康端点：http://127.0.0.1:18790/health（由--port覆盖），而 OpenAI 兼容 API 的/health在 nanobot/api/server.py 中返回{"status": "ok"}，且明确放行未认证访问。健康端点刻意保持未认证与最小化，需要远程监控时务必用防火墙或反向代理保护。

安全加固：暴露前的必备检查

指南的安全注意事项可以展开为四组可落地的配置。

1. 工作区限制与 shell 沙箱

{ "tools": { "restrictToWorkspace": true, "exec": { "enable": true, "sandbox": "bwrap" } } }

• restrictToWorkspace是应用层防护，不是操作系统沙箱，它会将工具的文件读写约束在工作区内；
• bwrap仅限 Linux，需要安装 bubblewrap；macOS 或 Windows 上应保持restrictToWorkspace开启并谨慎审查 shell 访问；
• tools.exec.enable: false可彻底移除 shell 执行能力；
• 在 Docker 中启用bwrap需要额外的能力（CAP_SYS_ADMIN，并关闭 AppArmor/seccomp 限制），否则bwrap可能报clone3: Operation not permitted，详见 deployment.md 中的 bwrap override 方案。

2. 网络与密钥

• 除非刻意暴露，否则把仅本地的服务绑定到127.0.0.1；
• 在把 OpenAI 兼容 API 绑定到公网接口之前，必须设置 API 密钥（公开绑定要求api.apiKey，以 Bearer token 形式发送）；
• 密钥使用${VAR_NAME}占位符从环境变量解析，解析仅在启动时于内存中进行，永不写回磁盘：

  { "channels": { "telegram": { "token": "${TELEGRAM_TOKEN}" } }, "providers": { "groq": { "apiKey": "${GROQ_API_KEY}" } } }

  若引用的环境变量未设置，nanobot 会快速失败并报告具体配置字段与变量名（不回显字段值）。systemd 可用EnvironmentFile=、Docker 可用--env-file、本地可用 direnv 或op run/pass等密钥管理器加载变量；

• HTTP web fetch 与 HTTP MCP 默认启用 SSRF 防护；放宽tools.ssrfWhitelist会增大暴露面。

3. 聊天应用访问控制

• 支持私聊（DM）的聊天应用优先使用**配对（pairing）**机制；
• 必须使用静态白名单时，保持allowFrom严格（如["alice", "bob"]）；
• allowFrom: ["*"]会绕过配对，意味着任何能触达该频道的人都能与机器人对话；
• 群组策略优先设为仅提及（mention-only）；
• 暴露 WebSocket 通道时，websocketRequiresToken默认true，生产环境优先用短时签发 token（tokenIssuePath+tokenIssueSecret）而非把静态密钥嵌入客户端，详见 websocket.md。

4. 每信任边界一个 workspace

保持"每个信任边界一个 workspace"：不同团队、不同租户或测试/生产环境之间用独立 workspace 隔离记忆、技能与会话。安全主题的完整清单见 secure-local-ai-agent.md 与 configuration.md 的 Security、Pairing 章节。

故障排查

指南给出的三个诊断手段，可以进一步结合 CLI 参考 cli-reference.md 展开：

1. 用服务相同的选择器检查状态：使用服务启动时相同的--config与--workspace标志运行nanobot status，确认进程读取的是你预期的那份配置；
2. 调试频道启动：运行nanobot gateway --verbose观察详细日志（-v会把日志级别提升到 DEBUG）；nanobot channels status可在启动前预检频道配置；
3. 检查端口冲突：WebUI、WebSocket 通道或 API 端点绑定失败时，优先确认端口占用。默认端口为：网关健康18790、WebUI/WebSocket8765、nanobot serveAPI8900。

相关文档导航

• Deployment：Render、Docker、systemd、LaunchAgent 全量部署手册
• Multiple Instances：多实例路径解析与端口规划
• Configuration：完整配置参考与安全/配对章节
• Chat Apps：各聊天平台接入前置条件
• OpenAI-Compatible API：nanobot serve的 API 集成方式
• Quick Start：首次安装与浏览器工作台路径
• CLI Reference：全部命令的精确参数与形态

【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot