🚀 快速开始

本文档将引导你完成 NeoWeb AI 的安装、首次使用和日常运维，整个过程大约需要 5 分钟。

系统要求

项目	要求
操作系统	macOS 12+、Ubuntu 20.04+、Debian 11+
Node.js	18.0.0 或更高版本
内存	最低 512MB，建议 2GB+
磁盘空间	至少 200MB 可用空间
网络	用于下载安装包和调用云端模型 API

安装方式

方式一：一键安装（推荐）

运行以下命令，脚本将自动检测环境、下载并安装：

bash

curl -fsSL https://ai.neowebai.com/install.sh | bash

安装脚本会自动完成以下步骤：

检测并安装 Node.js（如果未安装）
下载最新版本并解压到 ~/NeoWebAI/
安装依赖
安装 PM2 进程守护（崩溃自动重启 + 开机自启）
启动服务并自动打开浏览器

方式二：手动安装

bash

# 1. 下载最新版
curl -fSL https://ai.neowebai.com/neowebai-v1.0.0.tar.gz -o neowebai.tar.gz

# 2. 解压到安装目录
mkdir -p ~/NeoWebAI && tar xzf neowebai.tar.gz -C ~/NeoWebAI

# 3. 安装依赖
cd ~/NeoWebAI && npm install --omit=dev

# 4. 启动服务
node server.js

💡 手动安装不会配置进程守护，建议安装后参考下方「日常运维」章节设置 PM2。

首次配置

安装完成后，浏览器会自动打开 http://localhost:3001。如果没有打开，手动访问即可。

第一步：配置 AI 模型

这是唯一必须做的配置。进入 设置 → 模型，添加至少一个 AI 模型：

国内模型：通义千问、DeepSeek 等，填入对应平台的 API Key
国际模型：Claude、GPT-4 等，填入服务商的 API Key
本地模型：配置 Ollama（http://localhost:11434/v1）或 EXO 的地址，完全离线运行

配置好模型后就可以开始使用了。详细配置方法请参考模型配置文档。

第二步：开始对话

直接在对话框中描述你的需求，AI 会自动选择合适的工具完成任务：

"帮我写一个计算器网页" → 自动创建 HTML 文件并启动
"查一下我电脑的内存使用情况" → 自动执行 Shell 命令
"搜索最近的 AI 新闻" → 自动调用网络搜索

验证安装

也可以通过命令行验证服务是否正常：

bash

curl http://localhost:3001/api/status

正常响应：

json

{
  "ok": true,
  "version": "1.0.0",
  "models": 1,
  "tools": 96,
  "skills": 5
}

日常运维

一键安装会自动配置 PM2 进程守护。以下是你可能用到的常用命令：

查看运行状态

bash

# 查看服务状态
pm2 status

# 查看详细信息（版本、内存、运行时间、重启次数）
pm2 describe neowebai

也可以使用安装脚本查看：

bash

cd ~/NeoWebAI && bash install.sh status

重启服务

bash

# 重启
pm2 restart neowebai

# 停止
pm2 stop neowebai

# 启动（停止后）
pm2 start neowebai

查看日志

bash

# 实时查看日志（Ctrl+C 退出）
pm2 logs neowebai

# 查看最近 100 行日志
pm2 logs neowebai --lines 100

# 日志文件位置
# 输出日志：/tmp/neowebai-out.log
# 错误日志：/tmp/neowebai-error.log

进程守护说明

NeoWeb AI 安装时会自动配置以下保护机制：

保护	说明
崩溃自动重启	进程异常退出后 2 秒自动拉起，无限次重试
内存保护	内存超过 512MB 自动重启，防止内存泄漏
开机自启	系统重启后自动启动服务
指数退避	连续崩溃时逐步延长重启间隔（最长 15 秒），避免死循环

ℹ️ 简单来说：装完不用管。崩了自己起来，重启电脑也自己起来。

更新版本

bash

cd ~/NeoWebAI && bash install.sh update

ℹ️ 更新只覆盖代码文件，不会影响你的数据。模型配置、对话记录、技能、记忆等全部保留。

数据安全

NeoWeb AI 的所有数据存储在本地，不会上传到任何服务器：

数据	存储位置	更新/重装是否保留
模型配置 & API Key	`~/NeoWebAI/neowebai.db`	✅ 保留
对话记录 & 记忆	`~/NeoWebAI/neowebai.db`	✅ 保留
技能 & 自编程工具	`~/NeoWebAI/neowebai.db`	✅ 保留
SSH 服务器配置	`~/NeoWebAI/neowebai.db`	✅ 保留
环境配置	`~/NeoWebAI/.env`	✅ 保留
自定义工具	`~/NeoWebAI/tools/custom/`	✅ 保留

备份数据

如需备份，只需要复制一个文件：

bash

# 备份数据库（包含所有配置和记录）
cp ~/NeoWebAI/neowebai.db ~/Desktop/neowebai-backup-$(date +%Y%m%d).db

# 恢复数据
cp ~/Desktop/neowebai-backup-20260401.db ~/NeoWebAI/neowebai.db
pm2 restart neowebai

卸载

bash

cd ~/NeoWebAI && bash install.sh uninstall

ℹ️ 卸载只停止服务和取消自启，不删除文件。你的数据保留在 ~/NeoWebAI/，如需完全清除：rm -rf ~/NeoWebAI

故障排除

服务没有启动

bash

# 检查 PM2 状态
pm2 status

# 如果显示 errored 或 stopped，查看错误日志
pm2 logs neowebai --lines 50

# 手动启动排查
cd ~/NeoWebAI && node server.js

浏览器打不开页面

确认服务在运行：pm2 status
确认端口 3001 是否被占用：lsof -i :3001
尝试重启：pm2 restart neowebai

npm install 失败

检查 Node.js 版本：node --version（需要 18+）
清理后重试：cd ~/NeoWebAI && rm -rf node_modules package-lock.json && npm install
如果报 node-gyp 错误，安装 Xcode 命令行工具：xcode-select --install

端口被占用

bash

# 查看占用 3001 端口的进程
lsof -i :3001

# NeoWeb AI 会自动尝试 3002、3003... 最多到 3010
# 也可以手动指定端口（在 .env 中设置）
echo "PORT=8080" >> ~/NeoWebAI/.env
pm2 restart neowebai

添加模型后 AI 不回复

检查 API Key 是否正确：进入「设置 → 模型」，点击「测试连接」确认连通
确认 API 余额充足：部分供应商余额耗尽后会返回 401/403 错误
检查 API 地址：OpenAI 官方用 https://api.openai.com/v1，国内中转地址请咨询供应商
查看详细错误日志：pm2 logs neowebai --lines 20，搜索 API 或 error 关键字

AI 回复很慢或超时

网络问题：国内直连 OpenAI 可能不稳定，建议使用国内中转或本地模型
模型选择：较大的模型（如 GPT-4）响应时间比小模型（GPT-3.5）长 3-5 倍
本地模型：如使用 EXO/Ollama 本地模型，确认 GPU 服务正在运行

更新后数据丢失了？

ℹ️ 更新不会丢失数据。所有数据（模型配置、对话记录、技能、记忆）都存在 neowebai.db 中，更新只替换代码文件。

如果确实找不到数据，可能是安装到了不同目录
查找所有数据库：find ~ -name "neowebai.db" 2>/dev/null
恢复备份：cp ~/Desktop/neowebai-backup.db ~/NeoWebAI/neowebai.db && pm2 restart neowebai

内存占用过高 / 频繁重启

PM2 设置了 512MB 内存上限，超出会自动重启（这是正常的保护机制）
检查重启次数：pm2 describe neowebai | grep restarts
如果持续重启，查看日志定位问题：pm2 logs neowebai --err --lines 30
清理旧对话可释放内存：在界面中删除不需要的历史对话

macOS 提示"无法验证开发者"

NeoWeb AI 是通过 npm 安装的 Node.js 应用，不涉及 macOS 的应用签名
如果 better-sqlite3 编译时报安全错误，运行：xcode-select --install

如何完全重置

bash

# 停止服务
pm2 stop neowebai

# 删除数据库（所有数据将丢失！请先备份）
rm ~/NeoWebAI/neowebai.db

# 重启（会自动创建全新的空数据库）
pm2 restart neowebai

需要更多帮助？

查看日志：pm2 logs neowebai
邮件联系：support@liurenai.com
官网：www.neowebai.com

🚀 Quick Start

This guide walks you through installing NeoWeb AI, first-time setup, and daily maintenance. Takes about 5 minutes.

System Requirements

Item	Requirement
OS	macOS 12+, Ubuntu 20.04+, Debian 11+
Node.js	18.0.0 or higher
Memory	Min 512MB, 2GB+ recommended
Disk	At least 200MB free
Network	For downloading packages and calling cloud model APIs

Installation

Option 1: One-click Install (Recommended)

bash

curl -fsSL https://ai.neowebai.com/install.sh | bash

The script will automatically:

Detect and install Node.js if needed
Download the latest version to ~/NeoWebAI/
Install dependencies
Set up PM2 process guardian (auto-restart on crash + auto-start on boot)
Start the service and open your browser

Option 2: Manual Installation

bash

# 1. Download
curl -fSL https://ai.neowebai.com/neowebai-v1.0.0.tar.gz -o neowebai.tar.gz

# 2. Extract
mkdir -p ~/NeoWebAI && tar xzf neowebai.tar.gz -C ~/NeoWebAI

# 3. Install dependencies
cd ~/NeoWebAI && npm install --omit=dev

# 4. Start
node server.js

Initial Setup

After installation, your browser will open http://localhost:3001 automatically.

Step 1: Configure an AI Model

This is the only required setup. Go to Settings → Models and add at least one AI model:

Cloud models: Claude, GPT-4, Qwen, DeepSeek — enter your API Key
Local models: Ollama (http://localhost:11434/v1) or EXO — fully offline

See Model Configuration for details.

Step 2: Start Chatting

Describe your task in the chat box. The AI will pick the right tools automatically:

"Build me a calculator web page" → creates HTML and launches it
"Check my system memory" → runs shell commands
"Search for AI news" → searches the web

Verify Installation

bash

curl http://localhost:3001/api/status

Daily Operations

Check Status

bash

# Service status
pm2 status

# Detailed info (version, memory, uptime, restarts)
pm2 describe neowebai

# Or use the install script
cd ~/NeoWebAI && bash install.sh status

Restart / Stop / Start

bash

pm2 restart neowebai    # Restart
pm2 stop neowebai       # Stop
pm2 start neowebai      # Start (after stop)

View Logs

bash

# Live logs (Ctrl+C to exit)
pm2 logs neowebai

# Last 100 lines
pm2 logs neowebai --lines 100

# Log files:
#   Output: /tmp/neowebai-out.log
#   Errors: /tmp/neowebai-error.log

Process Guardian

NeoWeb AI automatically configures these protections:

Protection	Description
Crash recovery	Auto-restarts 2 seconds after crash, unlimited retries
Memory guard	Auto-restarts if memory exceeds 512MB
Boot startup	Auto-starts after system reboot
Backoff	Gradually increases restart delay on repeated crashes (max 15s)

ℹ️ In short: install and forget. It recovers from crashes and system reboots automatically.

Update

bash

cd ~/NeoWebAI && bash install.sh update

ℹ️ Updates only replace code files. Your data is never touched — models, conversations, skills, and memories are all preserved.

Data Safety

All data is stored locally and never uploaded to any server:

Data	Location	Preserved on update?
Model configs & API Keys	`~/NeoWebAI/neowebai.db`	✅ Yes
Conversations & memories	`~/NeoWebAI/neowebai.db`	✅ Yes
Skills & custom tools	`~/NeoWebAI/neowebai.db`	✅ Yes
SSH server configs	`~/NeoWebAI/neowebai.db`	✅ Yes
Environment config	`~/NeoWebAI/.env`	✅ Yes

Backup

bash

# Backup (just one file)
cp ~/NeoWebAI/neowebai.db ~/Desktop/neowebai-backup-$(date +%Y%m%d).db

# Restore
cp ~/Desktop/neowebai-backup-20260401.db ~/NeoWebAI/neowebai.db
pm2 restart neowebai

Uninstall

bash

cd ~/NeoWebAI && bash install.sh uninstall

ℹ️ Uninstall only stops the service. Your files remain in ~/NeoWebAI/. To fully remove: rm -rf ~/NeoWebAI

Troubleshooting

Service not starting

bash

# Check PM2 status
pm2 status

# View error logs
pm2 logs neowebai --lines 50

# Manual start for debugging
cd ~/NeoWebAI && node server.js

Browser can't connect

Confirm service is running: pm2 status
Check if port 3001 is in use: lsof -i :3001
Try restarting: pm2 restart neowebai

npm install fails

Check Node.js version: node --version (needs 18+)
Clean and retry: cd ~/NeoWebAI && rm -rf node_modules package-lock.json && npm install
For node-gyp errors on macOS: xcode-select --install

Port conflict

bash

# Check what's using port 3001
lsof -i :3001

# Change port (NeoWeb AI auto-tries 3002-3010, or set manually)
echo "PORT=8080" >> ~/NeoWebAI/.env
pm2 restart neowebai

Model added but AI doesn't respond

Verify your API Key: go to Settings → Models, click "Test Connection"
Check API balance: some providers return 401/403 when credits are exhausted
Verify API URL: OpenAI official is https://api.openai.com/v1
Check error logs: pm2 logs neowebai --lines 20, look for API or error

AI responds slowly or times out

Network issues: if connecting to overseas APIs, consider using a proxy or local models
Model size: larger models (e.g., GPT-4) take 3-5x longer than smaller ones (GPT-3.5)
Local models: if using EXO/Ollama, ensure the GPU service is running

Data lost after update?

ℹ️ Updates never delete your data. All data (models, conversations, skills, memories) lives in neowebai.db. Updates only replace code files.

If data appears missing, you may have installed to a different directory
Find all databases: find ~ -name "neowebai.db" 2>/dev/null
Restore backup: cp ~/Desktop/neowebai-backup.db ~/NeoWebAI/neowebai.db && pm2 restart neowebai

High memory usage / frequent restarts

PM2 enforces a 512MB memory limit — automatic restarts are a safety mechanism
Check restart count: pm2 describe neowebai | grep restarts
If restarting repeatedly, check logs: pm2 logs neowebai --err --lines 30
Deleting old conversations in the UI can free up memory

macOS "unidentified developer" warning

NeoWeb AI is a Node.js app installed via npm — no macOS code signing is involved
If better-sqlite3 fails to compile, run: xcode-select --install

How to fully reset

bash

# Stop the service
pm2 stop neowebai

# Delete the database (ALL data will be lost! Back up first)
rm ~/NeoWebAI/neowebai.db

# Restart (a fresh empty database will be created automatically)
pm2 restart neowebai

Need more help?

Check logs: pm2 logs neowebai
Email: support@liurenai.com
Website: www.neowebai.com