开源oa系统常见问题排查手册：最全故障解决指南

分类： 开源oa办公系统

tags： 开源oa故障排查,oa系统报错解决,服务器问题处理,oa登录失败原因,数据库连接异常,oa性能优化,系统运维手册

字数： 约5600字

---

开源oa系统上线了，总会遇到各种奇怪的问题。

有些错误第一次遇到，不知道从哪下手，网上搜索也找不到清晰的答案——这篇文章，把最常见的问题和解决方法整理成手册，你能直接对号入座。

---

一、启动类问题

问题一：后端启动失败，提示端口占用

error: port 8080 already in use

原因： 8080端口被其他进程占用（可能是上次的进程没有正常关闭）

解决：

bash

查看占用8080端口的进程

netstat -tlnp | grep 8080

或者

lsof -i :8080

杀掉占用的进程（把pid替换为实际的进程号）

kill -9

或者改变应用端口，在application.yml里

server:

port: 8081

---

问题二：数据库连接失败

error: unable to acquire jdbc connection

com.mysql.cj.jdbc.exceptions.communicationsexception:

communications link failure

可能原因和排查：

bash

1. mysql服务是否在运行

systemctl status mysql

2. 连接地址是否正确

检查 application.yml 中的 datasource.url

本地部署用 localhost，远程用实际ip

3. 数据库密码是否正确

mysql -u oa_user -p # 尝试手动连接

4. 数据库用户权限是否配置

mysql -u root -p

select host, user from mysql.user where user=oa_user;

show grants for oa_user@localhost;

5. mysql防火墙是否允许连接

如果是远程mysql

sudo ufw allow 3306

---

问题三：redis连接失败

unable to connect to redis

排查：

bash

检查redis服务状态

systemctl status redis

测试redis连接

redis-cli ping # 应返回pong

如果redis有密码，application.yml里要配置

spring:

redis:

password: your_password

---

问题四：jvm内存不足，启动崩溃

java.lang.outofmemoryerror: java heap space

解决： 增加jvm内存参数

bash

启动时加上内存参数

java -xms512m -xmx2048m -jar jeecg-boot.jar

如果是systemd服务，在execstart里加

execstart=/usr/bin/java -xms512m -xmx2048m -jar /path/to/app.jar

---

二、登录类问题

问题五：无法登录，一直提示用户名或密码错误

排查步骤：

1. 确认你输入的是初始账号（默认通常是 admin/admin123 或 admin/123456，查项目readme）

2. 检查是否有验证码问题（验证码错了也会提示密码错误）

3. 直接查数据库确认账号是否存在：

sql

select * from sys_user where username = admin;

4. 如果账号被锁定（多次登录失败）：

sql

-- 解锁账号

update sys_user set login_time = null, status = 1 where username = admin;

---

问题六：登录成功但页面空白或一直跳转到登录页

原因： token验证失败或前后端跨域问题

排查：

bash

打开浏览器开发者工具（f12）→ network

查看登录请求的响应，是否有错误信息

查看后续请求是否有401 unauthorized

常见原因：

1. 前端配置的api地址和后端实际地址不匹配

2. nginx代理配置有问题（前端发请求到了错误的地址）

3. token签名密钥配置不一致

检查nginx代理配置：

nginx

location /jeecg-boot/ {

proxy_pass http://localhost:8080/jeecg-boot/;

# 确保这个地址和后端实际地址一致

}

---

三、功能类问题

问题七：文件上传失败

常见原因1：目录权限

bash

检查上传目录是否存在且有写入权限

ls -la /opt/jeecg/upload/

如果没有写入权限

sudo chown -r ubuntu:ubuntu /opt/jeecg/upload/

chmod 755 /opt/jeecg/upload/

常见原因2：文件大小超限

nginx

nginx限制上传大小，修改nginx配置

client_max_body_size 50m;

常见原因3：application.yml配置路径不对

yaml

jeecg:

path:

upload: /opt/jeecg/upload # 确认这个路径存在

---

问题八：发送邮件通知失败

排查：

bash

1. 检查邮件服务器配置

application.yml中的mail配置

spring:

mail:

host: smtp.example.com

port: 465

username: your@email.com

password: your_password

protocol: smtp

default-encoding: utf-8

2. 检查邮件服务器是否允许smtp访问

很多邮件服务需要单独开启"smtp服务"并生成授权码

3. 如果是企业邮箱，确认端口和加密方式（ssl/tls/starttls）

---

问题九：流程审批点击无反应

浏览器控制台查错：

1. f12打开开发者工具

2. console标签查看是否有js报错

3. network标签查看具体api请求是否成功

常见原因：

- 流程引擎配置有问题（activiti表未初始化）

- 用户没有相关审批权限

- 流程定义有语法错误

重新初始化activiti表（谨慎操作，会清空历史数据）：

yaml

spring:

activiti:

database-schema-update: true # 自动创建/更新表

---

四、性能类问题

问题十：页面响应很慢（超过5秒）

排查工具：

bash

服务器负载

top

看cpu使用率和负载均值

内存使用

free -h

磁盘io

iostat -x 1

查看慢sql（需要在mysql开启慢查询日志）

set global slow_query_log = on;

set global long_query_time = 1; # 记录超过1秒的sql

查看慢查询日志文件

常见优化方向：

1. 数据库加索引：找出执行慢的sql，在where字段上加索引

2. redis缓存热点数据：频繁查询的配置/字典数据加缓存

3. 增加jvm内存：减少gc频率

4. 升级服务器配置：如果硬件瓶颈，考虑升配置

---

问题十一：并发多人使用时崩溃

现象： 正常使用没问题，同时多人操作就挂

原因： 通常是数据库连接池耗尽

解决： 增加连接池大小

yaml

spring:

datasource:

hikari:

maximum-pool-size: 30 # 默认通常是10，适当增大

minimum-idle: 5

connection-timeout: 30000

---

五、备份和恢复

数据库备份

bash

创建备份脚本 /opt/scripts/backup-db.sh

#!/bin/bash

date=$(date +%y%m%d_%h%m%s)

backup_dir="/opt/backup/db"

mkdir -p $backup_dir

备份数据库

mysqldump -u oa_user -pyour_password \

--single-transaction \

--routines \

--triggers \

oa_db > $backup_dir/oa_db_$date.sql

压缩

gzip $backup_dir/oa_db_$date.sql

删除30天前的备份

find $backup_dir -name "*.sql.gz" -mtime +30 -delete

echo "backup completed: oa_db_$date.sql.gz"

设置定时任务：每天凌晨2:00备份

crontab -e

0 2 * /opt/scripts/backup-db.sh >> /opt/backup/backup.log 2>&1

数据库恢复

bash

从备份文件恢复

gunzip -c /opt/backup/db/oa_db_20260420_020001.sql.gz | \

mysql -u oa_user -pyour_password oa_db

---

六、常用运维命令速查

bash

启动/停止/重启oa服务

sudo systemctl start jeecg-oa

sudo systemctl stop jeecg-oa

sudo systemctl restart jeecg-oa

查看实时日志

tail -f /opt/jeecg/logs/oa.log

查看最近100行日志

tail -100 /opt/jeecg/logs/oa.log

搜索错误日志

grep "error" /opt/jeecg/logs/oa.log | tail -50

查看服务器资源

htop # 需要先安装: sudo apt install htop

nginx重载配置（修改nginx.conf后）

sudo nginx -t && sudo systemctl reload nginx

---

结语

遇到问题不要慌，按步骤排查。

90%的问题，不是代码bug，是配置问题、权限问题、或者资源不足——这些都是可以解决的。

如果你遇到了本文没有覆盖的问题，把错误信息带上来，欢迎留言，帮你一起看。

---

发布时间：2026-04-20

关键词：开源oa故障排查,oa系统运维,数据库连接失败,nginx配置,日志分析,服务器问题,oa性能优化