# 星秩AI群管系统 - 安装教程

## 环境要求

### 最低配置
- **操作系统**: Ubuntu 20.04+ / Debian 11+ / macOS 12+
- **Node.js**: v18.0.0 或更高版本
- **内存**: 2GB RAM
- **硬盘**: 10GB 可用空间

### 推荐配置
- **操作系统**: Ubuntu 22.04 LTS
- **Node.js**: v20.x LTS
- **内存**: 4GB RAM
- **CPU**: 2核以上

---

## 一、安装前准备

### 1.1 更新系统包（Linux）

```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# 安装基础依赖
sudo apt install -y curl git build-essential
```

### 1.2 安装 Node.js（如果尚未安装）

```bash
# 使用 NodeSource 安装 LTS 版本
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 验证安装
node -v   # 应显示 v20.x.x
npm -v    # 应显示 9.x.x 或更高
```

### 1.3 安装 PM2（进程管理器）

```bash
# 全局安装 PM2
sudo npm install -g pm2

# 验证安装
pm2 --version
```

---

## 二、安装 NapCat（QQ 机器人协议适配器）

NapCat 是让 QQ 机器人连接 OneBot 11 协议的适配器。

### 2.1 下载 NapCat

```bash
# 创建工作目录
mkdir -p ~/ai-groupbot/napcat && cd ~/ai-groupbot/napcat

# 从 GitHub 下载最新版本（替换 VERSION 为实际版本号）
# 查看最新版本: https://github.com/NapNeko/NapCatQQ/releases
VERSION=4.0.0
curl -L -o napcat.tar.gz "https://github.com/NapNeko/NapCatQQ/releases/download/v${VERSION}/NapCat.tar.gz"

# 解压
tar -xzf napcat.tar.gz
rm napcat.tar.gz
```

### 2.2 配置 NapCat

创建配置文件 `napcat-config.json`：

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 3001,
    "https": {
      "enable": false,
      "certPath": "",
      "keyPath": ""
    }
  },
  "account": {
    "uin": "你的QQ号",
    "password": "你的QQ密码"
  },
  "longConnection": true,
  "debug": false
}
```

> **注意**: 请将 `uin` 替换为你的机器人 QQ 号，`password` 替换为密码。

### 2.3 启动 NapCat

```bash
cd ~/ai-groupbot/napcat

# 直接启动（测试用）
./NapCat [--config napcat-config.json]

# 或使用 PM2 启动（生产环境）
pm2 start ./NapCat --name napcat -- --config napcat-config.json

# 保存 PM2 进程列表
pm2 save

# 设置开机自启
pm2 startup
```

### 2.4 验证 NapCat 连接

```bash
# 检查 WebSocket 是否正常监听
curl -s http://localhost:3001 || echo "NapCat 未正常启动"
```

---

## 三、安装后端服务

### 3.1 拉取项目代码

```bash
cd ~/ai-groupbot
git clone <项目仓库地址> backend
cd backend
```

### 3.2 安装依赖

```bash
cd backend
npm install
```

### 3.3 配置环境变量

创建 `.env` 文件：

```bash
# 后端服务端口
PORT=3000

# NapCat WebSocket 地址
NAPCAT_WS=ws://192.168.31.151:3001

# 后端公网访问地址（前端需要连接这个地址）
BACKEND_URL=http://192.168.31.151:3000

# JWT 密钥（请修改为随机字符串）
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# API 密钥加密密钥（请修改为32位随机字符串）
ENCRYPTION_KEY=your-32-char-encryption-key!!ABC
```

### 3.4 初始化数据库

后端首次启动时会自动创建 SQLite 数据库并插入默认管理员账号：

- **用户名**: `admin`
- **密码**: `admin123`

> ⚠️ **重要**: 请在首次登录后立即修改默认密码！

### 3.5 启动后端服务

```bash
# 开发模式（终端前台运行）
npm run dev

# 生产模式（使用 PM2）
pm2 start npm --name backend -- run start

# 查看后端日志
pm2 logs backend

# 重启后端
pm2 restart backend
```

### 3.6 验证后端服务

```bash
# 检查健康状态
curl http://localhost:3000/api/health

# 预期返回
# {"status":"ok","time":"2024-01-01T00:00:00.000Z"}
```

---

## 四、安装前端服务

### 4.1 安装依赖

```bash
cd ~/ai-groupbot/frontend
npm install
```

### 4.2 配置前端

创建 `.env` 文件：

```bash
# 后端 API 地址
VITE_API_BASE=http://192.168.31.151:3000
```

### 4.3 构建生产版本

```bash
npm run build
```

构建完成后，静态文件会生成在 `dist/` 目录。

### 4.4 启动前端服务（开发模式）

```bash
npm run dev
```

前端会在 `http://localhost:5173` 启动。

---

## 五、Nginx 反向代理配置（生产环境）

如果需要通过域名访问，需要配置 Nginx 反向代理。

### 5.1 安装 Nginx

```bash
sudo apt install -y nginx
```

### 5.2 配置 Nginx

```bash
sudo nano /etc/nginx/sites-available/ai-groupbot
```

写入以下配置（根据实际情况修改域名和路径）：

```nginx
# 后端 API 服务
server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_cache_bypass $http_upgrade;
        # 请求超时设置
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

# 前端静态服务
server {
    listen 80;
    server_name your-domain.com;

    root /home/your-user/ai-groupbot/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理到后端
    location /api {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 5.3 启用站点配置

```bash
# 测试配置语法
sudo nginx -t

# 启用配置
sudo ln -s /etc/nginx/sites-available/ai-groupbot /etc/nginx/sites-enabled/

# 重启 Nginx
sudo systemctl restart nginx

# 设置 Nginx 开机自启
sudo systemctl enable nginx
```

### 5.4 配置 SSL（HTTPS）

```bash
# 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx

# 自动配置 HTTPS
sudo certbot --nginx -d your-domain.com -d api.your-domain.com
```

---

## 六、PM2 进程管理配置

创建 PM2 配置文件 `ecosystem.config.js` 以统一管理所有进程：

```javascript
module.exports = {
  apps: [
    {
      name: 'napcat',
      script: './NapCat',
      args: '--config napcat-config.json',
      cwd: '~/ai-groupbot/napcat',
      autorestart: true,
      watch: false,
      max_restarts: 10,
      min_uptime: '10s',
    },
    {
      name: 'backend',
      script: 'npm',
      args: 'run start',
      cwd: '~/ai-groupbot/backend',
      autorestart: true,
      watch: false,
      max_restarts: 10,
      min_uptime: '10s',
      env: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
    },
  ],
};
```

启动所有进程：

```bash
# 使用配置文件启动
pm2 start ecosystem.config.js

# 查看所有进程状态
pm2 list

# 查看某个进程日志
pm2 logs backend

# 重启所有进程
pm2 restart all

# 保存进程列表
pm2 save

# 查看实时日志
pm2 logs --lines 100 --nostream
```

---

## 七、常见安装问题排查

### 问题1: NapCat 启动失败，显示 "WebSocket 连接失败"

**原因**: NapCat 配置的 WebSocket 地址不正确，或 QQ 账号存在异常。

**解决方法**:
1. 检查 `napcat-config.json` 中的 `uin` 和 `password` 是否正确
2. 确认 QQ 号没有开启设备锁（登录保护）
3. 查看 NapCat 日志：`pm2 logs napcat`

### 问题2: 后端启动报错 "Port 3000 has been used"

**解决方法**:
```bash
# 查看哪个进程占用了 3000 端口
lsof -i :3000

# 杀掉占用进程
kill -9 <PID>

# 或修改后端端口
PORT=3001 npm run start
```

### 问题3: 前端无法连接到后端 API

**解决方法**:
1. 检查后端是否正常运行：`curl http://localhost:3000/api/health`
2. 检查防火墙设置：
   ```bash
   # 开放 3000 端口（仅用于内网）
   sudo ufw allow 3000/tcp
   ```
3. 检查前端 `.env` 中的 `VITE_API_BASE` 地址是否正确

### 问题4: 数据库权限错误

**解决方法**:
```bash
# 修复数据库文件权限
chmod 644 backend/data.db

# 如果 data.db 不存在，先创建目录
mkdir -p backend/data
touch backend/data/data.db
chmod 666 backend/data/data.db
```

### 问题5: npm install 失败（网络问题）

**解决方法**:
```bash
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install

# 或者使用 VPN
```

### 问题6: PM2 进程意外退出

**解决方法**:
```bash
# 查看详细错误日志
pm2 logs --err --lines 50

# 检查系统日志
journalctl -xe

# 增加内存限制（如果内存不足）
pm2 restart all --update-env
```

---

## 八、系统架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                        用户 (QQ 群)                          │
└────────────────────────────┬────────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │     NapCat       │ ← QQ 机器人协议适配器
                    │  (WebSocket :3001) │
                    └────────┬────────┘
                             │
              ┌──────────────▼──────────────────┐
              │           Backend                │
              │     (Express :3000 + SQLite)    │
              │                                   │
              │  • 群组管理                       │
              │  • 关键词回复                      │
              │  • 规则引擎                       │
              │  • AI 对话 (GPT)                  │
              │  • 积分商城                       │
              │  • 定时广播                       │
              │  • 签到系统                       │
              └──────────────┬──────────────────┘
                             │
              ┌──────────────▼──────────────────┐
              │        Frontend (React)         │
              │     (Ant Design + Vite)         │
              │      管理后台 (:5173)            │
              └──────────────────────────────────┘
```

---

## 九、快速检查清单

安装完成后，逐项检查：

- [ ] NapCat 进程运行正常 (`pm2 list`)
- [ ] 后端 API 正常响应 (`curl http://localhost:3000/api/health`)
- [ ] 前端可以正常打开 (`http://localhost:5173`)
- [ ] 可以登录管理后台（默认账号: admin / admin123）
- [ ] 可以在管理后台添加群组
- [ ] 机器人可以接收和响应 QQ 消息

---

## 十、安全建议

1. **修改默认密码**: 首次登录后立即修改 `admin` 账户的密码
2. **修改密钥**: 在 `.env` 中修改 `JWT_SECRET` 和 `ENCRYPTION_KEY` 为随机字符串
3. **配置防火墙**: 仅开放必要的端口，阻止外部直接访问后端
4. **定期备份**: 定期备份 `data.db` 数据库文件
5. **更新软件**: 定期更新 Node.js、NPM 包和系统安全补丁

---

> 如有更多问题，请查看 [使用教程](./USER_GUIDE.md) 或提交 Issue。