Redline-NASAI - NAS 智能管理助手

基于大模型(LLM)的轻量级 NAS 命令行管理工具 支持任意 OpenAI 兼容 API（官方/内网/本地模型），中文对话式交互

---

目录

• 一、项目简介
• 二、环境要求与安装
• 三、软件更新升级
• 四、Web 界面模式
• 五、REST API 模式（对接飞书/外部系统）
• 六、配置 LLM
• 七、快速上手
• 八、详细使用指南
• 九、风险控制机制
• 十、常见问题排查
• 十一、推送到 Git
• 十二、附录：命令速查表

---

一、项目简介

它能做什么？

用中文自然语言指挥它管理 NAS：

你 > 查看一下磁盘使用情况
你 > 帮我检查 Docker 容器的运行状态
你 > 列出 /mnt/storage 下的所有文件
你 > 清理一下 /tmp 目录里超过 7 天的日志

核心特性

特性	说明
灵活切换 LLM	支持 OpenAI / vLLM / Ollama / 内网模型，随时切换
中文对话	纯中文界面，自然语言交互
风险控制	高危命令(rm -rf/mkfs/dd等)自动检测 + 用户确认
轻量级	仅依赖 requests，内存占用 < 50MB
4 大工具	命令执行、文件读写、目录浏览
命令历史	支持上下键翻历史

技术架构

用户输入(中文) → Agent(思维链+工具选择) → LLM API(OpenAI兼容格式) → 工具调用 → 结果返回 → 中文回复

---

二、环境要求与安装

环境要求

• OS: Linux / macOS / Windows
• Python: >= 3.8
• 内存: >= 256MB
• 依赖: 仅 requests

安装步骤

方式一：一键部署脚本（推荐，适用于 Linux 虚拟机）

# 在虚拟机上直接执行（需要 root 或 sudo）
curl -sSL http://8.140.62.87:7777/redline/Redline-NASAI/raw/branch/master/nas_agent/deploy.sh | bash

脚本会自动：

1. 检测操作系统并安装 Python3、Git、pip
2. 安装 Python 依赖（requests）
3. 从 Git 克隆项目代码
4. 交互式配置 LLM API Key
5. 验证安装并创建 nasai 命令别名

方式二：手动安装（从 Git 克隆）

# 1. 安装系统依赖
apt-get install -y python3 python3-pip git   # Debian/Ubuntu
# yum install -y python3 python3-pip git     # CentOS

# 2. 安装 Python 依赖
pip3 install requests

# 3. 克隆项目
#    ─── 如果仓库不需要认证 ───
git clone http://8.140.62.87:7777/redline/Redline-NASAI.git

#    ─── 如果仓库需要用户名密码（方式一：URL 中嵌入） ───
git clone http://你的用户名:你的密码@8.140.62.87:7777/redline/Redline-NASAI.git

#    ─── 如果仓库需要用户名密码（方式二：先克隆再配置） ───
git clone http://8.140.62.87:7777/redline/Redline-NASAI.git  # 会提示输入密码
cd Redline-NASAI
git config credential.helper store      # 保存凭证，之后不再提示

# 4. 进入项目目录
cd nas_agent

# 5. 验证安装
python3 -c "import py_compile; py_compile.compile('nas_agent.py', doraise=True); print('OK')"

# 6. 配置 API Key（任选一种）
export NAS_AGENT_API_KEY=sk-your-key
# 或编辑 nas_agent_config.json

# 7. 启动（任选一种）
# 方式 A：CLI 命令行模式
python3 nas_agent.py

# 方式 B：Web 界面模式（推荐）
python3 web_app.py
# 然后浏览器访问 http://NAS_IP:5000
# 默认密码: admin123

---

三、软件更新升级

方式一：git pull 更新（推荐）

cd /root/Redline-NASAI

# 拉取最新代码
git pull

# 如果仓库需要认证，在 URL 中嵌入用户名密码：
git pull http://用户名:密码@8.140.62.87:7777/redline/Redline-NASAI.git

# 或保存凭证，只需输入一次密码（推荐）：
git config credential.helper store
git pull  # 输入一次用户名密码，之后不再需要

方式二：重新执行部署脚本

curl -sSL http://8.140.62.87:7777/redline/Redline-NASAI/raw/branch/master/nas_agent/deploy.sh | bash

脚本会自动检测已有目录并执行 git pull 更新。

方式三：强制覆盖（本地有修改时）

cd /root/Redline-NASAI
git fetch origin
git reset --hard origin/master

⚠️ 注意：reset --hard 会丢弃本地修改。如果修改过配置文件，先备份：

cp nas_agent/nas_agent_config.json /tmp/
git reset --hard origin/master
cp /tmp/nas_agent_config.json nas_agent/

验证更新

cd /root/Redline-NASAI
git log --oneline -3

输出示例：

82e9a8f fix: only high-risk commands require confirmation
e3db1a6 feat: support git authentication in deploy script
a1b8c04 feat: add deploy.sh and update docs

更新后重启

# 重新启动程序
python3 nas_agent/nas_agent.py

# 或如果设置了别名
nasai

# 或 Web 界面模式
python3 web_app.py

---

四、Web 界面模式

除了命令行，还可以通过浏览器操作 NAS Agent。

启动 Web 服务

cd /root/Redline-NASAI/nas_agent

# 安装额外依赖
pip install flask

# 启动（默认端口 5000）
python3 web_app.py

访问

http://你的NAS_IP:5000

默认密码: admin123，登录后建议立即修改。

Web 界面功能

页面	功能
💬 对话	与 AI 对话管理 NAS，支持高危命令确认弹窗
⚙ 设置	修改 LLM 配置（API地址/模型/Key）、修改登录密码

后台运行（退出 SSH 后不中断）

# 方式一：screen（推荐）
screen -S nasai-web
python3 web_app.py
# 按 Ctrl+A 然后按 D 断开
# 重新连接: screen -r nasai-web

# 方式二：nohup
nohup python3 web_app.py > web.log 2>&1 &
# 查看日志: tail -f web.log

修改端口

# 编辑 web_app.py 最后几行，修改 port 参数
# 或启动时指定环境变量
export FLASK_PORT=8080
python3 web_app.py

---

五、REST API 模式（对接飞书/外部系统）

提供 HTTP API 接口，供飞书 Bot、自动化脚本或其他系统调用。

启动 API 服务

cd /root/Redline-NASAI/nas_agent
python3 nas_api.py

首次启动会生成 API Key，格式：na-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 地址

http://你的NAS_IP:5001

认证方式

所有请求头中携带 X-API-Key：

curl -X POST http://localhost:5001/v1/chat \
  -H "X-API-Key: na-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "查看磁盘使用情况"}'

API 端点

GET /v1/health — 健康检查

{"status": "ok", "version": "1.0.0", "sessions": 0}

POST /v1/chat — 发送消息

// 请求
{"message": "查看磁盘使用情况", "session_id": "自定义ID（可选）"}

// 普通回复
{"success": true, "type": "text", "content": "磁盘使用情况...", "session_id": "sess-xxx"}

// 高危操作确认
{"success": true, "type": "confirmation", "content": "准备删除文件...",
 "confirm": {"command": "rm -rf /tmp/test", "description": "清理临时目录",
             "risk_level": "high", "matched_pattern": "..."},
 "session_id": "sess-xxx"}

POST /v1/confirm — 确认/取消操作

// 请求（确认执行）
{"session_id": "sess-xxx", "confirmed": true}

// 请求（取消执行）
{"session_id": "sess-xxx", "confirmed": false}

POST /v1/reset — 重置会话

{"session_id": "sess-xxx"}

特殊命令

命令	作用
reset 或 重置	重置当前会话

对接飞书 Bot

与 feishu-ai-bot 项目配合使用：

1. 启动 NAS API：python3 nas_api.py（记录输出的 API Key）
2. 编辑飞书 Bot 的 config.json，设置 nas_agent 配置：

{
  "nas_agent": {
    "enabled": true,
    "api_url": "http://localhost:5001",
    "api_key": "na-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "command_prefix": "nas"
  }
}

3. 在飞书中使用 nas 命令 格式发送 NAS 管理指令：

nas 查看磁盘使用情况
nas 检查 Docker 容器状态
nas 列出 /mnt/share 的内容

高危命令会有确认流程：

用户: nas 删除 /tmp/test
机器人: ⚠️ 需要确认
        命令: rm -rf /tmp/test
        请回复「确认」执行，或「取消」取消

用户: 确认
机器人: ✅ 命令执行成功

后台运行

nohup python3 nas_api.py > nas_api.log 2>&1 &

---

六、配置 LLM

配置文件

编辑 nas_agent_config.json，首次运行会自动创建。

方案 A：OpenAI 官方 API

{
    "llm": {
        "api_base": "https://api.openai.com/v1",
        "api_key": "sk-your-key-here",
        "model": "gpt-4o",
        "max_tokens": 4096,
        "temperature": 0.1
    }
}

方案 B：内网 vLLM 服务器

{
    "llm": {
        "api_base": "http://192.168.1.100:8000/v1",
        "api_key": "token-abc123",
        "model": "/data/models/Qwen2.5-7B-Instruct",
        "max_tokens": 4096,
        "temperature": 0.1
    }
}

方案 C：Ollama（需开启 OpenAI 兼容模式）

{
    "llm": {
        "api_base": "http://localhost:11434/v1",
        "api_key": "ollama",
        "model": "qwen2.5:7b",
        "max_tokens": 4096,
        "temperature": 0.1
    }
}

方案 D：环境变量（推荐，避免 Key 泄露）

# Linux/macOS
export NAS_AGENT_API_KEY=sk-your-key-here

# Windows CMD
set NAS_AGENT_API_KEY=sk-your-key-here

# Windows PowerShell
$env:NAS_AGENT_API_KEY="sk-your-key-here"

运行时切换

无需编辑配置文件，运行时直接切换：

你 > /model gpt-4o
你 > /api http://192.168.1.100:8000/v1

---

七、快速上手

启动

cd nas_agent
python3 nas_agent.py

启动后界面：

╔══════════════════════════════════════════════════════╗
║              NAS Agent v1.0                         ║
║              轻量级 NAS 管理助手                     ║
╠══════════════════════════════════════════════════════╣
║  输入 /help 查看帮助，/exit 退出程序                 ║
║  模型: gpt-4o                                        ║
║  API:  https://api.openai.com/v1                     ║
╚══════════════════════════════════════════════════════╝

第一个任务

你 > 查看一下磁盘使用情况

系统会：调用 LLM -> 决定执行 df -h -> 执行命令 -> 分析结果 -> 中文回复

安全确认示例

你 > 删除 /tmp/test 目录

==================================================
 工具调用: execute_command
   目的: 删除测试目录
   命令: rm -rf /tmp/test
   风险等级: 高危
==================================================

 是否执行此命令？(y/N):

---

八、详细使用指南

常用场景

磁盘管理：

你 > 看看还有多少磁盘空间
你 > 检查 /mnt/storage 的目录结构
你 > 哪些目录占用的空间最大？

系统监控：

你 > 查看内存使用情况
你 > CPU 负载怎么样？
你 > 检查系统运行了多久

文件管理：

你 > 列出 /mnt/share 下的所有文件
你 > 读取 /etc/hosts 的内容
你 > 在 /opt/scripts 下创建一个备份脚本

Docker 管理：

你 > 查看所有运行中的容器
你 > 检查 nginx 容器的日志
你 > 列出所有镜像

服务管理：

你 > 检查 nginx 服务状态
你 > 查看系统有哪些服务在运行

特殊命令

命令	说明	示例
/exit	退出程序	/exit
/reset	重置对话历史	/reset
/help	显示帮助	/help
/config	显示当前配置	/config
/model	切换模型	/model qwen2.5:7b
/api	切换 API 地址	/api http://localhost:8000/v1

多轮对话示例

你 > 帮我检查一下 Docker 服务的状态

小纳: 好的，我来检查 Docker 服务的运行状态。

── 思考中 (1/10) ──
  Token: 520 / 80

工具调用: execute_command
  目的: 检查 Docker 服务状态
  命令: systemctl status docker
  风险等级: 安全

── 结果 ──
  ● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled)
     Active: active (running)

小纳: Docker 服务运行正常，状态为 active (running)。

你 > 那看看有哪些容器在运行

小纳: 好的，我来查看运行中的容器。
...

---

九、风险控制机制

风险等级

等级	颜色	说明	需要确认
安全	绿色	只读命令(ls/df/ps等)	否
低风险	青色	未匹配到已知模式	是
高危	红色	删除/格式化/磁盘操作	是
极度危险	红底白字	高危中的高危	是

高危命令检测范围

• 删除操作: rm -rf, rmdir
• 磁盘操作: mkfs, dd, fdisk, parted, lvcreate, pvcreate
• 系统操作: shutdown, reboot, systemctl stop
• 权限操作: chmod -R, chown -R
• 网络操作: curl ... | bash, wget ... | sh
• 包管理: apt remove, dpkg --purge, yum remove

自定义风险规则

编辑 nas_agent_config.json 中的 risk 部分：

{
    "risk": {
        "enabled": true,
        "auto_confirm_patterns": ["\\b(your_safe_pattern)\\b"],
        "high_risk_patterns": ["\\b(your_dangerous_pattern)\\b"]
    }
}

---

十、常见问题排查

Q1: 提示 API Key 未设置

原因: 配置文件中 api_key 为空，且未设置环境变量
解决:
  1. 编辑 nas_agent_config.json 设置 api_key
  2. 或运行: export NAS_AGENT_API_KEY=sk-xxx
  3. 或设置: export OPENAI_API_KEY=sk-xxx

Q2: 无法连接到 API 地址

原因: API 地址无法访问
排查:
  1. 检查网络: ping <api_base>
  2. 检查端口: curl <api_base>/models
  3. 确认服务是否启动
  4. 防火墙是否放行

Q3: HTTP 401/403 错误

原因: API Key 无效或未授权
排查:
  1. 检查 API Key 是否正确
  2. 确认 Key 是否有模型访问权限
  3. 对于 vLLM: 启动时需加 --api-key 参数

Q4: 模型回复乱码或不相关

原因: 模型能力不足或参数不合适
解决:
  1. 降低 temperature（推荐 0.1）
  2. 使用更强的模型（如 gpt-4o、qwen2.5-72b）
  3. 检查模型是否支持 function calling

Q5: 终端中文显示乱码

# Linux/Mac: 检查 locale
locale | grep LANG
export LANG=zh_CN.UTF-8

# Windows: 推荐使用 Windows Terminal 或 Git Bash

---

十一、推送到 Git

初始化仓库（首次）

# 进入项目目录
cd /path/to/Redline-NASAI

# 初始化 Git 仓库
git init
git remote add origin http://8.140.62.87:7777/redline/Redline-NASAI.git

# 添加所有文件
git add .
git commit -m "feat: init NAS Agent - LLM-powered NAS management tool"

# 推送到远程
git push -u origin main
# 如果远程已有内容，先 pull 再 push:
git pull origin main --rebase
git push -u origin main

推送更新

git add -A
git commit -m "update: description of changes"
git push

.gitignore 文件

创建 .gitignore：

__pycache__/
*.pyc
.nas_agent_history
.env
*.log

---

十二、附录：命令速查表

运行时命令

命令	作用
/exit	退出程序
/reset	重置对话(清除历史)
/help	显示帮助
/config	查看配置
/model	切换模型
/api	切换 API 地址

常用 NAS 任务示例

"查看磁盘使用情况"            → df -h
"查看目录大小"                → du -sh /path
"列出目录内容"                → ls -la /path
"查看内存使用"                → free -h
"查看 CPU 信息"               → cat /proc/cpuinfo
"查看系统负载"                → uptime
"查看进程"                    → ps aux
"查看 Docker 容器"            → docker ps
"查看 Docker 日志"            → docker logs <container>
"查看服务状态"                → systemctl status <service>
"查看网络连接"                → netstat -tlnp
"查看系统日志"                → journalctl -n 50
"读取配置文件"                → cat /etc/nginx/nginx.conf

---

项目文件结构

nas_agent/
├── nas_agent.py              # 主程序 (640行)
├── nas_agent_config.json     # 配置文件
├── requirements.txt           # 依赖
├── README.md                  # 本文档
└── .gitignore                 # Git 忽略规则

---

最后更新: 2026-07-22