国内网络环境下优化 Nanobot 项目升级完整指南

type

Post

status

Published

date

Mar 22, 2026

slug

tech-Nanobot-update

summary

📋 目录

问题背景

环境准备

优化 Dockerfile 配置

完整构建流程

常见问题排查

附录：完整代码

问题背景

Nanobot 是一个基于 Python 的 AI 机器人框架，使用 Docker 容器化部署。在国内网络环境下构建时，常遇到以下问题：

问题	表现	原因
APT 源超时	`apt-get update` 卡住 300 秒+	连接 Debian 官方源速度慢
PyPI 下载慢	`pip install` 耗时过长	连接 Python 官方源速度慢
构建失败	`failed to solve: deadline exceeded`	网络超时导致构建中断

优化目标：将构建时间从 30+ 分钟缩短至 5-10 分钟，并确保构建稳定性。

环境准备

系统要求

Git 配置（首次操作）

优化 Dockerfile 配置

使用 cat > Dockerfile << 'EOF' 命令一次性写入完整内容

优化后的完整 Dockerfile

验证 Dockerfile 内容

完整构建流程

步骤 1：提交修改到 Git

步骤 2：构建 Docker 镜像

预期构建时间对比：

步骤	优化前	优化后
APT 更新安装	300+ 秒	60 秒
Python 依赖安装	600+ 秒	200 秒
NPM 构建	120 秒	120 秒
总计	~1000 秒	~380 秒

步骤 3：启动容器

步骤 4：验证服务状态

成功标志：

容器状态显示 Up

日志中出现 Listening on port 18790 或 Nanobot started

API 返回 JSON 格式的状态信息

常见问题排查

问题 1：Dockerfile 第一行显示 `cat > Dockerfile`

原因：手动粘贴代码时包含了写入命令本身

解决：

问题 2：构建在 `uv pip install` 步骤卡住超过 15 分钟

原因：未配置 PyPI 国内源

解决：确保 Dockerfile 中的 pip 命令包含 -i 参数：

问题 3：构建完成后服务无法启动

排查步骤：

问题 4：后续更新如何复用缓存

最佳实践：

附录：完整代码

📄 一键优化脚本

将以下内容保存为 optimize_build.sh，执行后可自动完成所有优化：

使用方法：

📋 快速参考命令表

操作	命令
查看构建日志	`docker compose logs -f nanobot-gateway`
重启服务	`docker compose restart nanobot-gateway`
停止服务	`docker compose down nanobot-gateway`
查看容器状态	`docker compose ps`
进入容器调试	`docker compose exec nanobot-gateway bash`
重新构建	`docker compose build --no-cache nanobot-gateway`

总结

通过配置国内镜像源和优化 Dockerfile，Nanobot 项目的构建时间可从 30+ 分钟 缩短至 5-10 分钟，且构建成功率显著提升。关键优化点：

APT 源：使用阿里云镜像加速系统包安装

PyPI 源：使用清华镜像加速 Python 依赖下载

Git 配置：使用 HTTPS 替代 SSH 避免 GitHub 访问超时

Docker 缓存：合理利用层缓存减少重复构建

建议将此文档保存为团队内部知识库，后续升级时直接参考执行。

最后更新时间：2025 年 11 月

适用版本：Nanobot 最新主干分支

测试环境：Debian 12 (Bookworm) + Docker 24.0+

📋 目录

问题背景