飞牛部署教程

# 一，python:3.11-slim安装

### 方法一：通过飞牛 NAS Docker 图形界面拉取（推荐）

1.  打开飞牛 NAS 的 Docker 界面。
2.  点击左侧菜单的 **「镜像仓库」**（Registry）。
3.  在顶部的搜索框里，输入 `python`，然后按回车搜索。
4.  在搜索结果列表里，找到官方的 `python` 镜像（通常是第一个，带有 OFFICIAL 标识）。
5.  点击 `python` 镜像右侧的 **「拉取」**（Pull）按钮。
6.  在弹出的标签选择框里，选择 **`3.11-slim`**（不要选默认的 latest，体积太大）。
7.  点击「确定」，等待镜像拉取完成（通常需要几分钟，取决于网速）。

* * *

### 方法二：通过命令行拉取（如果你熟悉 SSH）

如果你开启了飞牛 NAS 的 SSH 功能，可以用终端登录后，直接执行以下命令：

```

docker pull python:3.11-slim

```

### 验证镜像是否拉取成功

镜像拉取完成后，点击左侧菜单的 **「本地镜像」**（Images），在列表里能看到 `python:3.11-slim`，就说明获取成功了，可以直接用来创建容器。

# 二，部署Docker
## 一、准备工作

1.  在飞牛 NAS 文件管理器中，创建一个专属目录，例如：
    
    `/vol2/1000/nanobot-hl/`
2.  在该目录下再创建一个 `config` 子目录，用于存放启动脚本：
    
    `/vol2/1000/nanobot-hl/config/`

* * *

## 二、核心文件配置

### 1\. 启动脚本 `start.sh`

在 `/vol2/1000/nanobot-hl/config/` 目录下，创建文件 `start.sh`，内容如下（这是最终验证成功的版本）：

```
#!/bin/bash

# ========== 核心配置 ==========
SERVER_PORT=28080
ZHIPU_API_KEY="82fd8fba52fd42edb127366946a00512.0PykyujsKdc851mAq"
CONFIG_PATH="/root/.nanobot/config.json"

# ========== 1. 初始化环境 ==========
mkdir -p /root/.nanobot /app/.nanobot /root/.config/nanobot

# 生成配置文件，新增host字段，指定监听所有网络接口
cat > "$CONFIG_PATH" << EOF
{
  "providers": {
    "zhipu": {
      "api_key": "${ZHIPU_API_KEY}",
      "api_base": "https://open.bigmodel.cn/api/paas/v4/"
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": ${SERVER_PORT}
  }
}
EOF

# 同步配置到所有可能的读取路径
cp "$CONFIG_PATH" /app/.nanobot/config.json
cp "$CONFIG_PATH" /root/.config/nanobot/config.json

# 打印配置确认
echo "==================================="
echo "✅ 配置文件生成成功，内容如下："
cat "$CONFIG_PATH"
echo "==================================="

# ========== 2. 依赖检查 ==========
echo "? 开始检查/安装依赖..."
pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple/ --no-cache-dir || echo "⚠️ pip升级跳过"
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ nanobot-ai zhipuai --no-cache-dir || echo "⚠️ 依赖安装跳过"
echo "✅ 依赖检查完成"

# ========== 3. 服务启动（循环保活） ==========
echo "? 启动nanobot网关服务（端口：${SERVER_PORT}）"
echo "==================================="
# 【关键修正】删掉无效的--host参数，只保留--port
while true; do
  nanobot gateway --port ${SERVER_PORT}
  echo "⚠️ 服务异常退出，3秒后自动重启..."
  sleep 3
done
```

### 2\. 给脚本添加执行权限

在飞牛 NAS 文件管理器中，右键点击 `start.sh`，选择「属性」或「权限」，确保勾选了「可执行」权限（如果是命令行，执行 `chmod +x start.sh`）。

* * *

## 三、Docker 容器配置

在飞牛 NAS 的 Docker 界面，点击「添加容器」，按以下配置填写：

### 1\. 基础设置

*   **容器名称**：`nanobot-hkuds`（或你喜欢的名字）
*   **镜像**：`python:3.11-slim`（轻量级 Python 镜像，稳定可靠）

### 2\. 存储管理（卷映射）

添加卷映射，把 NAS 上的配置目录挂载到容器里：

*   **本地路径**：`/vol2/1000/nanobot-hl/config`
*   **容器路径**：`/app/config`
*   **类型**：读写（Read/Write）

### 3\. 网络设置

*   **网络模式**：选择 `bridge`（桥接模式，最稳定）
*   **端口映射**（关键）：
    
    *   点击「添加端口」
    *   **本地端口**：`28080`
    *   **容器端口**：`28080`
    *   **协议**：`TCP`

### 4\. 启动命令

在「命令」或「Entrypoint」输入框中，填入：

```

bash /app/config/start.sh

```

### 5\. 重启策略

建议设置为「除非手动停止，否则总是重启」（Always Restart），配合脚本里的循环保活，服务会非常稳定。

* * *

## 四、启动与验证

### 1\. 启动容器

点击「创建」或「启动」容器，等待 1-2 分钟（首次启动需要安装依赖）。

### 2\. 查看日志

点击容器右侧的「日志」，确认出现以下关键成功标识：

```
✅ 配置文件生成成功
✅ 依赖检查完成
? 启动nanobot网关服务（端口：28080）
Starting nanobot gateway on port 28080...
Agent loop started
```

### 3\. 验证访问

在和 NAS 同局域网的设备浏览器中，访问：

```

http://<你的NAS\_IP>:28080

```

只要页面能正常加载（哪怕是空白页），就代表部署成功。

* * *

## 五、关键避坑总结（本次踩过的坑）

1.  **不要在 `nanobot gateway` 命令后加 `--host` 参数**：当前版本不支持，加了会直接报错退出。
2.  **监听地址写在配置文件里**：在 `config.json` 的 `gateway` 配置里加上 `"host": "0.0.0.0"`，确保外部能访问。
3.  **脚本开头不要加 `set -e`**：它会导致任何小警告都让脚本退出，容器重启。
4.  **端口映射必须一致**：本地端口、容器端口、配置文件里的端口，三者必须完全一致（例如都是 28080）。
5.  **使用循环保活**：在脚本最后用 `while true` 循环启动服务，即使服务崩溃也会自动重启，容器不会停止。