lingyue-zhibao

灵越智报 2.0 部署指南

目录

• 环境要求
• 快速开始
• 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 或更高版本

快速开始

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

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

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

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

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

方式二: 手动 Docker 部署

# 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. 准备工作

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

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

2. 修改配置

编辑 .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. 启动服务

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

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

4. 验证部署

# 查看服务状态
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

# 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

# Ubuntu/Debian
sudo apt install redis-server

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

安装 RabbitMQ（可选）

# 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. 编译项目

cd backend
mvn clean package -DskipTests

3. 配置应用

编辑 backend/lingyue-starter/src/main/resources/application.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

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

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

4. 运行应用

# 方式一: 使用 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:

[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

启动服务:

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. 数据库连接失败

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

解决方案:

# 检查 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 连接超时或拒绝连接

解决方案:

# 检查 Redis 是否运行
docker-compose ps redis
# 或
sudo systemctl status redis

# 测试 Redis 连接
redis-cli ping

3. 端口被占用

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

解决方案:

# 查看占用端口的进程
sudo lsof -i :8000
sudo netstat -tulpn | grep 8000

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

4. 内存不足

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

解决方案:

修改 Dockerfile 中的 JVM 参数:

ENV JAVA_OPTS="-Xms1024m -Xmx2048m -XX:+UseG1GC"

或在启动时指定:

docker-compose up -d --build

5. 查看应用日志

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

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

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

6. 重置数据库

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

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

性能优化建议

1. JVM 调优

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

2. 数据库优化

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

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

3. Redis 优化

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

安全建议

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

备份与恢复

数据库备份

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

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

文件备份

# 备份上传文件
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