数字档案馆系统故障快速排查及落地解决实操指南

一、排查前置准备

1. 排查工具安装与验证

Linux环境下安装curl用于服务状态检测，执行对应系统命令：

Debian/Ubuntu系统：

sudo apt install curl -y

RHEL/CentOS系统：

sudo yum install curl -y

执行验证命令：

curl --version

输出curl版本信息则安装完成，Docker部署需提前安装docker-ce，命令为：

 Docker国内源安装命令（Debian/Ubuntu）
curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

2. 核心配置文件与目录确认

数字档案馆系统核心配置文件默认路径：

• 独立部署：/opt/archivesystem/conf/system.properties
• Docker部署：进入容器后路径为/opt/archivesystem/conf/system.properties，进入容器命令：

docker exec -it 你的容器ID /bin/bash

注：修改配置文件前必须执行备份：

cp /opt/archivesystem/conf/system.properties /opt/archivesystem/conf/system.properties.bak

二、三类高频故障分步排查与解决

故障1：档案检索无结果

步骤1：验证检索服务运行状态，替换为实际端口（默认8080）执行：

curl http://127.0.0.1:8080/archivesystem/api/search/status

返回{"code":200,"msg":"service running"}则服务正常，若返回503，执行步骤2。

步骤2：检查索引生成状态，进入索引目录查看：

cd /opt/archivesystem/index && ls -l

若目录为空，执行手动重建索引：

/opt/archivesystem/bin/reindex.sh --all

等待5分钟后重新执行步骤1验证。

步骤3：检查元数据映射配置，打开system.properties，确认映射字段与实际档案表字段完全匹配，示例内容：

 元数据映射配置（必须与档案库表字段一致）
metadata.mapping=id:档案编号,title:档案题名,create_time:创建时间,dept:形成部门,file_path:存储路径

字段不匹配时修改配置，保存后重启服务：

systemctl restart archivesystem

故障2：元数据同步失败

步骤1：验证数据库连通性，替换为实际账号密码执行：

mysql -u root -p'你的数据库密码' -h 127.0.0.1 archivesystem_db

输入密码后执行show tables;，查看是否存在archive_metadata表，若不存在，执行数据库初始化脚本：

/opt/archivesystem/bin/init_db.sh

步骤2：检查同步定时任务状态，查看crontab任务：

crontab -l

若未显示同步任务，添加每5分钟执行的同步任务：

crontab -e

在文件末尾添加：

/5     /opt/archivesystem/bin/sync_meta.sh >> /var/log/archivesync.log 2>&1

步骤3：查看同步错误日志，执行实时日志查看：

tail -f /var/log/archivesync.log

若显示ERROR: connection refused，检查system.properties中数据库url是否正确，示例：

database.url=jdbc:mysql://127.0.0.1:3306/archivesystem_db?useSSL=false&characterEncoding=utf8

故障3：存储节点离线

步骤1：查看所有存储节点状态，执行命令：

/opt/archivesystem/bin/storage_node.sh list

显示节点状态为OFFLINE时，执行步骤2。

步骤2：检查存储目录权限，默认存储目录为/opt/archivesystem/storage，执行权限查看：

ls -ld /opt/archivesystem/storage

若权限为其他用户，修改为系统运行用户权限（假设运行用户为archivesys）：

chown -R archivesys:archivesys /opt/archivesystem/storage

步骤3：重启存储节点服务：

systemctl restart storage-node

三、故障排查后的验证与优化

1. 核心服务状态验证，确认所有服务运行正常：

systemctl status archivesystem storage-node --no-pager

2. 长期定时维护配置，添加2项基础维护任务：

• 每月1号凌晨2点重建全量索引，避免索引失效：

0 2 1   /opt/archivesystem/bin/reindex.sh --all >> /var/log/reindex.log 2>&1

• 每月1号凌晨3点清理过期日志，释放磁盘空间：

0 3 1   truncate -s 0 /var/log/archivesync.log /var/log/reindex.log