# 灵越智报 2.0 - 服务器部署指南

> **部署环境**: Ubuntu 22.04 LTS  
> **服务器**: lanaipc (RTX 4070 Ti Super 16GB)  
> **更新日期**: 2026-01-17  
> **项目路径**: `/mnt/win_home/lingyue-zhibao`

---

## 🖥️ 服务器环境

```
GPU:    NVIDIA GeForce RTX 4070 Ti Super (16GB)
CUDA:   12.5
Driver: 555.42.02
OS:     Ubuntu 22.04.5 LTS
Kernel: 5.15.0-164-generic
```

**已运行的服务（GPU 占用 ~15.7GB）：**
- dongshi-hanlp (308MB)
- subtitle_venv (2.2GB)  
- venv (1.8GB)
- VLLM::EngineCore (11.3GB)

---

## 📋 环境要求

### 需要安装

| 组件 | 版本要求 | 安装命令 |
|------|----------|----------|
| Java 17 | OpenJDK 17+ | `apt install openjdk-17-jdk` |
| Maven | 3.6+ | `apt install maven` |
| PostgreSQL | 14+ | `apt install postgresql postgresql-contrib` |
| Redis | 6+ | `apt install redis-server` |
| RabbitMQ | 3.9+ | `apt install rabbitmq-server` |
| pgvector | 0.5+ | 见下方步骤 |

---

## 🚀 完整部署步骤

### 步骤 1：安装基础依赖

```bash
# 更新系统
apt update && apt upgrade -y

# 安装 Java 17
apt install -y openjdk-17-jdk

# 安装 Maven
apt install -y maven

# 验证安装
java -version
mvn -version
```

### 步骤 2：安装 PostgreSQL + pgvector

```bash
# 安装 PostgreSQL
apt install -y postgresql postgresql-contrib

# 安装 pgvector 依赖
apt install -y postgresql-server-dev-all build-essential git

# 编译安装 pgvector
cd /tmp
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
make install

# 启动 PostgreSQL
systemctl enable postgresql
systemctl start postgresql
```

### 步骤 3：创建数据库

```bash
# 切换到 postgres 用户
sudo -u postgres psql

# 在 psql 中执行
CREATE USER lingyue WITH PASSWORD '123123';
CREATE DATABASE lingyue_zhibao OWNER lingyue;
GRANT ALL PRIVILEGES ON DATABASE lingyue_zhibao TO lingyue;
\c lingyue_zhibao
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
\q
```

### 步骤 4：安装 Redis

```bash
apt install -y redis-server
systemctl enable redis-server
systemctl start redis-server

# 验证
redis-cli ping
```

### 步骤 5：安装 RabbitMQ

```bash
apt install -y rabbitmq-server
systemctl enable rabbitmq-server
systemctl start rabbitmq-server

# 启用管理插件
rabbitmq-plugins enable rabbitmq_management

# 创建用户
rabbitmqctl add_user admin admin123
rabbitmqctl set_user_tags admin administrator
rabbitmqctl set_permissions -p / admin ".*" ".*" ".*"
```

### 步骤 6：部署项目

```bash
# 创建项目目录
mkdir -p /mnt/win_home/lingyue-zhibao
cd /mnt/win_home/lingyue-zhibao

# 克隆项目（或从本地复制）
git clone <your-gitlab-repo-url> .

# 初始化数据库表
psql -U lingyue -d lingyue_zhibao -f database/init.sql
psql -U lingyue -d lingyue_zhibao -f backend/sql/rag_tables.sql

# 编译项目
cd backend
mvn clean package -DskipTests
```

### 步骤 7：配置应用

编辑 `backend/lingyue-starter/src/main/resources/application.properties`:

```properties
# 数据库配置
spring.datasource.druid.url=jdbc:postgresql://localhost:5432/lingyue_zhibao
spring.datasource.druid.username=lingyue
spring.datasource.druid.password=123123

# Redis 配置
spring.data.redis.host=localhost
spring.data.redis.port=6379

# RabbitMQ 配置
spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672
spring.rabbitmq.username=admin
spring.rabbitmq.password=admin123

# Ollama 配置（使用本地 vLLM 或远程服务）
ollama.url=http://localhost:11434
ollama.embedding.model=nomic-embed-text

# DeepSeek API（可选，使用本地 vLLM 替代）
# deepseek.api.url=http://localhost:8080/v1
# deepseek.api.key=token-abc123
```

### 步骤 8：启动应用

```bash
cd /mnt/win_home/lingyue-zhibao/backend

# 前台启动
java -Xms1g -Xmx2g -jar lingyue-starter/target/lingyue-starter.jar

# 或后台启动
nohup java -Xms1g -Xmx2g -jar lingyue-starter/target/lingyue-starter.jar > /var/log/lingyue.log 2>&1 &
```

---

## 🤖 配置 Embedding 服务

### 方案 A：使用 Ollama（推荐，简单）

```bash
# 安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 下载 Embedding 模型
ollama pull nomic-embed-text

# 启动服务
nohup ollama serve > /var/log/ollama.log 2>&1 &
```

### 方案 B：使用现有的 vLLM（高效）

如果你的 vLLM 已经在运行，可以配置兼容的 Embedding 服务：

```properties
# application.properties
ollama.url=http://localhost:8080
```

### 方案 C：使用 HuggingFace TEI（专业）

```bash
# 使用 Docker（如果可用）
docker run -d --gpus all -p 8081:80 \
  ghcr.io/huggingface/text-embeddings-inference:latest \
  --model-id BAAI/bge-base-zh-v1.5
```

---

## 🔧 Systemd 服务配置

创建 `/etc/systemd/system/lingyue.service`:

```ini
[Unit]
Description=Lingyue Zhibao Application
After=network.target postgresql.service redis.service rabbitmq-server.service

[Service]
Type=simple
User=root
WorkingDirectory=/mnt/win_home/lingyue-zhibao/backend
ExecStart=/usr/bin/java -Xms1g -Xmx2g -jar lingyue-starter/target/lingyue-starter.jar
Restart=always
RestartSec=10

Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
systemctl daemon-reload
systemctl enable lingyue
systemctl start lingyue

# 查看状态
systemctl status lingyue

# 查看日志
journalctl -u lingyue -f
```

---

## 📡 API 接口一览

### 认证接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录 |
| POST | `/auth/logout` | 用户登出 |

### 文件上传接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/v1/parse/upload` | 上传文件 |
| GET | `/api/v1/parse/file/exists` | 检查文件是否存在 |

### 解析接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/parse/start` | 启动解析任务 |
| GET | `/parse/status/{documentId}` | 查询解析状态 |

### RAG 接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/rag/index` | 索引文档 |
| POST | `/api/rag/query` | RAG 问答 |
| GET | `/api/rag/chunks/{documentId}` | 获取文档分块 |
| DELETE | `/api/rag/index/{documentId}` | 删除索引 |

---

## 🧪 测试部署

```bash
# 1. 检查服务状态
curl http://localhost:8000/actuator/health

# 2. 用户注册
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"admin@lingyue.com","password":"admin123"}'

# 3. 用户登录
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 4. 上传测试文件
curl -X POST http://localhost:8000/api/v1/parse/upload \
  -F "file=@test.pdf" \
  -F "userId=admin"
```

---

## 🌐 Nginx 反向代理（可选）

```nginx
# /etc/nginx/sites-available/lingyue
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        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_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # 文件上传大小限制
    client_max_body_size 100M;
}
```

启用：

```bash
ln -s /etc/nginx/sites-available/lingyue /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```

---

## 📊 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| 灵越智报 | 8000 | 主应用 |
| PostgreSQL | 5432 | 数据库 |
| Redis | 6379 | 缓存 |
| RabbitMQ | 5672 | 消息队列 |
| RabbitMQ 管理 | 15672 | Web 管理界面 |
| Ollama | 11434 | Embedding 服务 |
| vLLM（现有） | - | LLM 推理服务 |

---

## 🔥 快速部署脚本

在服务器上执行：

```bash
#!/bin/bash
# deploy.sh

set -e

PROJECT_DIR="/mnt/win_home/lingyue-zhibao"

echo "=== 检查服务状态 ==="
systemctl is-active postgresql || systemctl start postgresql
systemctl is-active redis-server || systemctl start redis-server
systemctl is-active rabbitmq-server || systemctl start rabbitmq-server

echo "=== 编译项目 ==="
cd $PROJECT_DIR/backend
mvn clean package -DskipTests -q

echo "=== 停止旧进程 ==="
pkill -f "lingyue-starter.jar" || true
sleep 2

echo "=== 启动应用 ==="
nohup java -Xms1g -Xmx2g -jar lingyue-starter/target/lingyue-starter.jar > /var/log/lingyue.log 2>&1 &

sleep 10

echo "=== 检查应用状态 ==="
curl -s http://localhost:8000/actuator/health || echo "启动中，请稍候..."

echo "=== 部署完成 ==="
echo "访问地址: http://$(hostname -I | awk '{print $1}'):8000"
```

---

## 📝 更新日志

- **2026-01-17**: 服务器部署版本，支持 Ubuntu 22.04 + RTX 4070 Ti