• 教程
• 文档
• AI Agent
• 人工智能

本文带你用 learn-nanobot 教程仓库，10 分钟掌握基于 Nanobot 框架构建的 AI Agent 的Docker 部署 + 生产安全策略：从镜像构建、容器编排，到沙箱隔离、密钥管理、监控备份的 6 大安全要点，让你的 AI Agent 不止"能跑"，更能"安全上线"。🚀

一、为什么 AI Agent 要用 Docker 部署？

很多新手第一次把 Agent 跑起来后，会直接在服务器裸机上运行。但 Agent 和传统 Web 服务不同——它能执行命令、读写文件，一旦出问题，破坏面更大。Docker 容器化正是解决这个问题的关键：

💡 部署前建议先读懂架构：Nanobot 由核心引擎（AgentLoop）、记忆系统、技能加载器、工具注册表四大模块组成，理解它们才知道该持久化哪些数据。详见 docs/03-architecture-deep-dive/README.md。

二、Docker 部署四步走

第 1 步：准备配置，密钥走环境变量

生产环境的第一原则：API Key 绝不硬编码进配置文件。用.env文件管理密钥，config.json里只写引用：

{ "providers": { "openai": { "api_key": "${OPENAI_API_KEY}" } } }

环境变量示例（.env文件，记得加入.gitignore）：

OPENAI_API_KEY=sk-xxxxxxxx TELEGRAM_BOT_TOKEN=123456:ABC...

仓库中的 projects/01-hello-nanobot/config.json 就是这种"只引用环境变量"的规范写法，可以直接参考。

第 2 步：构建镜像

Dockerfile 抓住三个关键点即可：

• 用python:3.12-slim精简基础镜像，减少攻击面
• 安装nanobot-ai后，创建非 root 用户运行
• 配置健康检查（HEALTHCHECK），方便编排系统自动巡检

第 3 步：Compose 编排启动

docker-compose.yml的核心配置建议包含四件事：

services: nanobot: build: . restart: unless-stopped # 崩溃自动重启 environment: - OPENAI_API_KEY=${OPENAI_API_KEY} # 密钥从 .env 注入 volumes: - ./config.json:/home/nanobot/workspace/config.json:ro # 配置只读 - nanobot-memory:/home/nanobot/workspace/memory # 记忆持久化 deploy: resources: limits: cpus: '2.0' memory: 2G

• :ro表示只读挂载——配置文件、技能目录只读，防止 Agent 篡改自己的配置
• memory/、sessions/用命名卷读写挂载，数据才能持久保存

第 4 步：启动与验证

docker-compose build # 构建镜像 docker-compose up -d # 后台启动 docker-compose logs -f nanobot # 查看日志确认正常

完整可运行的 Dockerfile 与 Compose 示例在 docs/11-security-and-deploy/README.md 的 11.4 节，零基础安装流程可配合 docs/06-install-and-hands-on/README.md 一起看。

三、生产安全策略的 6 个关键要点

这是全文最重要的部分。AI Agent 会自主调用工具执行操作，安全防线必须建在代码层面，而不是指望大模型"听话"。

1️⃣ 工作区沙箱：restrict_to_workspace

这是 Nanobot 最核心的安全机制——所有文件读写、Shell 命令都被限制在 workspace 目录内。即使 Prompt 注入让 Agent"想"去读/etc/passwd，代码层的路径校验也会直接拒绝。

2️⃣ 危险命令检测

exec 工具内置正则黑名单，rm -rf /、磁盘格式化、curl | bash远程脚本执行等危险模式会被自动拦截，并配有执行超时控制，防止无限运行。

3️⃣ SSRF 防护

Agent 的web_fetch工具会阻止访问内网地址和云平台元数据地址（如169.254.169.254），防止攻击者借 Agent 之手探测你的内网。生产环境建议再叠加域名白名单，只放行allowed_domains里配置的站点。

4️⃣ 密钥管理三道关

• ✅ API Key 通过环境变量传入，配置文件只写${VAR}引用
• ✅.env文件加入.gitignore，永不进 Git
• ✅ 日志中对密钥脱敏，只显示前 8 位

5️⃣ 迭代次数限制

max_tool_iterations建议生产环境设为30 以内。它限制了单次对话的工具调用轮数，即使 Agent 被诱导"不停地做"，也会到限自动停止——这同时是成本控制手段。

6️⃣ 最小权限原则

SubAgent（子 Agent）默认没有发消息、再派生子 Agent、创建定时任务的权限，迭代上限也更低（15 次）。每个执行层级只拿到完成任务所需的最少权限。

📚 六大攻击场景（Prompt 注入、路径遍历、命令注入等）与防御机制的完整对照表，见 docs/11-security-and-deploy/README.md 的 11.1~11.2 节。

四、记忆数据持久化与备份

AI Agent 的"灵魂"一半在配置里，另一半在记忆文件中。如果容器重建后记忆丢了，你的 Agent 就会"失忆"。

必须持久化/备份的数据：

备份实践建议（保持精简，别学太多花活）：

1. 每天凌晨用tar打包 workspace 到备份目录，保留最近 30 天
2. 用crontab定时执行备份脚本
3. 定期做一次恢复演练——没验证过的备份等于没有备份

完整备份脚本与恢复流程在 docs/11-security-and-deploy/README.md 的 11.8 节。记忆系统的原理可回看 docs/07-memory-system/README.md。

五、上线前安全清单（建议逐条打勾）

其中成本监控值得多说一句：LLM API 是 Agent 最大的运行成本。生产环境建议把temperature调低到 0.3 获得更稳定的输出，把context_window_tokens设为模型窗口的一半（更频繁触发记忆压缩，节省 Token）。

六、延伸：从单实例走向生产架构

完成单机部署后，可以继续进阶：

• 多平台接入：把 Agent 接到 Telegram、飞书、钉钉，Webhook 建议加 Nginx 反向代理 + HTTPS，详见 docs/09-multi-platform/README.md
• 多实例架构：客服、运维、开发 Agent 各占一个独立容器，配置、数据、端口互相隔离
• 子 Agent 与定时任务：用 Cron 让 Agent 定时汇报，详见 docs/10-subagent-and-cron/README.md
• 更多实战：projects/04-multi-platform-bot/ 提供了多平台 Bot 的完整示例配置

小结

记住一个核心理念：即使大模型被 Prompt 注入操纵，代码级的安全机制依然有效——这就是纵深防御的价值。按本文清单走完，你的 AI Agent 就能安心上线了。🎉

• 教程
• 文档
• AI Agent
• 人工智能