# 灵越智报 2.0 部署指南

## 目录

- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [Docker 部署（推荐）](#docker-部署推荐)
- [传统部署](#传统部署)
- [配置说明](#配置说明)
- [常见问题](#常见问题)

## 环境要求

### 基础环境
- **操作系统**: Linux / macOS / Windows
- **Java**: JDK 17 或更高版本
- **Maven**: 3.8.0 或更高版本

### 运行环境（如果使用 Docker 则自动提供）
- **PostgreSQL**: 16.0 或更高版本
- **Redis**: 7.0 或更高版本
- **RabbitMQ**: 3.13 或更高版本（可选）

### Docker 环境（推荐）
- **Docker**: 20.10 或更高版本
- **Docker Compose**: 2.0 或更高版本

## 快速开始

### 方式一: 使用部署脚本（最简单）

```bash
# 1. 进入项目根目录
cd lingyue-zhibao

# 2. 赋予执行权限
chmod +x deploy.sh

# 3. 启动服务（不包含 OCR）
./deploy.sh start

# 或者启动完整服务（包含 PaddleOCR）
./deploy.sh start-with-ocr
```

### 方式二: 手动 Docker 部署

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

# 2. 复制环境变量配置
cp .env.example .env

# 3. 修改 .env 文件中的配置（特别是 JWT_SECRET 和 API 密钥）
vim .env

# 4. 启动服务
docker-compose up -d

# 5. 查看日志
docker-compose logs -f lingyue-app
```

## Docker 部署（推荐）

### 1. 准备工作

```bash
# 克隆或进入项目目录
cd lingyue-zhibao

# 复制环境配置文件
cp .env.example .env
```

### 2. 修改配置

编辑 `.env` 文件，修改以下重要配置:

```env
# 数据库密码（生产环境务必修改！）
DB_PASSWORD=your-strong-password

# JWT 密钥（生产环境务必修改！）
JWT_SECRET=your-very-long-random-secret-key

# DeepSeek API Key（如需 AI 功能）
DEEPSEEK_API_KEY=your-deepseek-api-key
```

### 3. 启动服务

```bash
# 完整启动（包含所有服务）
docker-compose --profile with-ocr up -d

# 或者不启动 OCR 服务
docker-compose up -d
```

### 4. 验证部署

```bash
# 查看服务状态
docker-compose ps

# 查看应用日志
docker-compose logs -f lingyue-app

# 健康检查
curl http://localhost:8000/actuator/health
```

### 5. 访问应用

- **应用主页**: http://localhost:8000
- **API 文档**: http://localhost:8000/swagger-ui.html
- **Druid 监控**: http://localhost:8000/druid/ (admin/admin123)
- **RabbitMQ 管理**: http://localhost:15672 (admin/admin123)

## 传统部署

### 1. 环境准备

#### 安装 PostgreSQL

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install postgresql-16

# 创建数据库
sudo -u postgres psql
CREATE DATABASE lingyue_zhibao;
CREATE USER lingyue WITH PASSWORD '123123';
GRANT ALL PRIVILEGES ON DATABASE lingyue_zhibao TO lingyue;
```

#### 安装 Redis

```bash
# Ubuntu/Debian
sudo apt install redis-server

# 启动 Redis
sudo systemctl start redis-server
sudo systemctl enable redis-server
```

#### 安装 RabbitMQ（可选）

```bash
# Ubuntu/Debian
sudo apt install rabbitmq-server

# 启动 RabbitMQ
sudo systemctl start rabbitmq-server
sudo systemctl enable rabbitmq-server

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

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

### 2. 编译项目

```bash
cd backend
mvn clean package -DskipTests
```

### 3. 配置应用

编辑 `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

# JWT配置
jwt.secret=your-jwt-secret-key
```

或者通过环境变量配置（推荐用于生产环境）:

```bash
export DB_USERNAME=lingyue
export DB_PASSWORD=123123
export JWT_SECRET=your-very-long-random-secret-key
```

### 4. 运行应用

```bash
# 方式一: 使用 java -jar
cd backend/lingyue-starter/target
java -jar lingyue-starter.jar

# 方式二: 使用 Maven
cd backend
mvn spring-boot:run -pl lingyue-starter

# 方式三: 后台运行
nohup java -jar lingyue-starter.jar > app.log 2>&1 &
```

### 5. 使用 systemd 管理服务

创建服务文件 `/etc/systemd/system/lingyue-zhibao.service`:

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

[Service]
Type=simple
User=lingyue
WorkingDirectory=/opt/lingyue-zhibao
ExecStart=/usr/bin/java -Xms512m -Xmx1024m -jar /opt/lingyue-zhibao/lingyue-starter.jar
Restart=on-failure
RestartSec=10

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

启动服务:

```bash
sudo systemctl daemon-reload
sudo systemctl start lingyue-zhibao
sudo systemctl enable lingyue-zhibao
sudo systemctl status lingyue-zhibao
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| DB_USERNAME | 数据库用户名 | postgres |
| DB_PASSWORD | 数据库密码 | postgres |
| REDIS_HOST | Redis 主机 | localhost |
| REDIS_PORT | Redis 端口 | 6379 |
| REDIS_PASSWORD | Redis 密码 | (空) |
| RABBITMQ_HOST | RabbitMQ 主机 | localhost |
| RABBITMQ_PORT | RabbitMQ 端口 | 5672 |
| RABBITMQ_USERNAME | RabbitMQ 用户名 | guest |
| RABBITMQ_PASSWORD | RabbitMQ 密码 | guest |
| JWT_SECRET | JWT 密钥 | (需修改) |
| PADDLEOCR_SERVER_URL | PaddleOCR 服务地址 | http://localhost:8866 |
| DEEPSEEK_API_KEY | DeepSeek API 密钥 | (需配置) |

### 端口说明

| 服务 | 端口 | 说明 |
|------|------|------|
| 应用主服务 | 8000 | 主应用端口 |
| PostgreSQL | 5432 | 数据库端口 |
| Redis | 6379 | 缓存服务端口 |
| RabbitMQ | 5672 | 消息队列端口 |
| RabbitMQ 管理 | 15672 | RabbitMQ 管理界面 |
| PaddleOCR | 8866 | OCR 服务端口 |

## 常见问题

### 1. 数据库连接失败

**问题**: 应用启动时提示数据库连接失败

**解决方案**:
```bash
# 检查 PostgreSQL 是否运行
docker-compose ps postgres
# 或
sudo systemctl status postgresql

# 检查数据库配置
docker-compose exec postgres psql -U postgres -c "SELECT 1"

# 查看详细日志
docker-compose logs postgres
```

### 2. Redis 连接失败

**问题**: Redis 连接超时或拒绝连接

**解决方案**:
```bash
# 检查 Redis 是否运行
docker-compose ps redis
# 或
sudo systemctl status redis

# 测试 Redis 连接
redis-cli ping
```

### 3. 端口被占用

**问题**: 服务启动失败，提示端口已被占用

**解决方案**:
```bash
# 查看占用端口的进程
sudo lsof -i :8000
sudo netstat -tulpn | grep 8000

# 修改 docker-compose.yml 中的端口映射
# 例如将 8000:8000 改为 8080:8000
```

### 4. 内存不足

**问题**: 应用运行缓慢或频繁重启

**解决方案**:

修改 `Dockerfile` 中的 JVM 参数:
```dockerfile
ENV JAVA_OPTS="-Xms1024m -Xmx2048m -XX:+UseG1GC"
```

或在启动时指定:
```bash
docker-compose up -d --build
```

### 5. 查看应用日志

```bash
# Docker 部署
docker-compose logs -f lingyue-app

# 传统部署
tail -f /opt/lingyue-zhibao/logs/lingyue.log

# systemd 服务
sudo journalctl -u lingyue-zhibao -f
```

### 6. 重置数据库

```bash
# Docker 环境
docker-compose down -v  # 删除所有卷
docker-compose up -d

# 传统部署
sudo -u postgres psql
DROP DATABASE lingyue_zhibao;
CREATE DATABASE lingyue_zhibao;
```

## 性能优化建议

### 1. JVM 调优

```bash
# 生产环境建议
JAVA_OPTS="-Xms2g -Xmx4g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/app/logs"
```

### 2. 数据库优化

```sql
-- 增加连接池大小
ALTER SYSTEM SET max_connections = 200;

-- 优化缓存
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
```

### 3. Redis 优化

```bash
# 增加最大内存
redis-cli CONFIG SET maxmemory 2gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru
```

## 安全建议

1. **修改默认密码**: 生产环境务必修改所有默认密码
2. **配置防火墙**: 只开放必要的端口
3. **启用 HTTPS**: 使用 Nginx 反向代理配置 SSL
4. **定期备份**: 配置数据库自动备份
5. **监控告警**: 配置应用和基础设施监控

## 备份与恢复

### 数据库备份

```bash
# 备份
docker-compose exec postgres pg_dump -U postgres lingyue_zhibao > backup.sql

# 恢复
docker-compose exec -T postgres psql -U postgres lingyue_zhibao < backup.sql
```

### 文件备份

```bash
# 备份上传文件
docker run --rm -v lingyue_app_data:/data -v $(pwd):/backup ubuntu tar czf /backup/app_data_backup.tar.gz /data
```

## 技术支持

如有问题,请联系:
- 邮箱: support@lingyue.com
- 文档: https://docs.lingyue.com
- Issues: https://github.com/lingyue/lingyue-zhibao/issues