扫描仪常见问题
本文档汇总病理扫描仪现场运维中的常见故障排查方法，以及 Linux 工作站常用的系统操作与网络配置指令。适用于 Debian / Ubuntu 环境，与 Medipath 部署文档配套使用。
一、扫描仪常见故障及解决方法
1.1 系统无法识别扫描仪
现象： 扫描软件中看到扫描仪离线或设备一直连接中。
排查步骤：
- 确认扫描仪电源已开启，状态指示灯正常（通常为绿色或蓝色常亮）。
- 检查设备与电脑所有连接的数据线和通讯线连接是否正常。
- 如使用USB相机，更换 USB 数据线或 USB 端口（优先使用主机后置 USB 3.0 端口，避免使用无源 USB Hub）。
- 在终端检查系统网络或USB 设备是否被系统识别，检查系统、设备的IP地址信息配置是否正确。
bash
# 查看 USB 设备列表
lsusb
# 查看内核是否检测到新设备（插入扫描仪后执行）
dmesg | tail -30
# 查看块设备（部分扫描仪以存储设备形式挂载）
lsblk- 若
lsusb中无对应厂商设备，尝试重启扫描仪和主机。 - 检查 USB 自动挂起是否导致设备休眠：
bash
# 查看当前 USB 电源管理状态
cat /sys/bus/usb/devices/*/power/control
# 临时关闭 USB 自动挂起（重启后失效）
echo 'on' | sudo tee /sys/bus/usb/devices/*/power/control1.2 USB 权限不足
现象： 普通用户无法访问扫描仪，提示权限错误或 Permission denied。
解决方法：
bash
# 查看当前用户所属组
groups
# 将用户加入 dialout 和 plugdev 组（注销后重新登录生效）
sudo usermod -aG dialout,plugdev $USER
# 查看 udev 规则（部分厂商会提供专用规则文件）
ls /etc/udev/rules.d/若厂商提供了 .rules 文件，将其复制到 /etc/udev/rules.d/ 后执行：
bash
sudo udevadm control --reload-rules
sudo udevadm trigger1.3 网络扫描仪连接失败
现象： 扫描仪通过网口连接，软件无法发现设备或连接超时。
排查步骤：
- 确认扫描仪与工作站在同一网段，网线连接牢固，交换机端口指示灯正常。
- 获取扫描仪 IP 地址（通常可在扫描仪面板或厂商管理软件中查看）。
- 测试网络连通性：
bash
# 替换为扫描仪实际 IP
ping -c 4 192.168.5.11
# 查看本机 IP 与网关
ip addr show
ip route show
# 扫描同网段活跃主机（需安装 arp-scan）
sudo arp-scan --localnet- 检查防火墙是否拦截了扫描仪通信端口：
bash
# 查看防火墙状态
sudo ufw status
# 如需临时关闭防火墙测试（排查完毕后请恢复）
sudo ufw disable- 确认扫描仪 IP 与工作站 IP 无冲突（ARP 表中如出现相同 MAC 地址需排查）。
1.4 扫描图像质量异常
现象： 图像模糊、色差、条纹、黑边或对焦不准。
常见原因与处理：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 图像模糊 | 物镜脏污、切片未放平 | 清洁物镜；重新放置切片并压紧 |
| 色差/偏色 | 光源老化、白平衡未校准 | 执行厂商白平衡校准流程 |
| 横向条纹 | 数据线接触不良、电磁干扰 | 更换数据线；远离强电磁设备 |
| 黑边/裁切异常 | 扫描区域设置错误 | 在扫描软件中重新框选扫描区域 |
| 对焦失败 | 切片厚度超限、气泡 | 检查切片质量；调整对焦参数 |
建议： 定期按厂商手册执行光学校准（Calibration），并记录每次校准日期。
1.5 扫描速度慢或中途卡顿
现象： 单张切片扫描耗时明显变长，或进度条长时间停滞。
排查步骤：
- 检查磁盘剩余空间（扫描缓存需要足够空间）：
bash
df -h- 检查内存与 CPU 占用：
bash
free -h
top -o %CPU- 检查扫描输出目录所在磁盘 I/O：
bash
# 查看磁盘写入速度（示例，按实际挂载点修改）
sudo apt-get install -y hdparm
sudo hdparm -t /mnt/data- 网络扫描仪场景下，检查网络带宽与延迟：
bash
# 测试到扫描仪的网络质量
ping -c 20 192.168.5.110
iperf3 -c 192.168.5.110 # 需扫描仪端支持- 关闭不必要的后台程序，释放系统资源后重试扫描任务。
1.6 扫描软件无法启动或闪退
现象： 双击扫描程序无响应，或启动后立即退出。
排查步骤：
bash
# 从终端启动，查看错误输出
cd /opt/PathnanoSlideScanner/
./run.sh
# 查看系统日志中的相关报错
journalctl -xe --no-pager | tail -50
# 检查是否缺少动态链接库
ldd /opt/PathnanoSlideScanner/PathnanoSlideScanner | grep "not found"
# 修复缺失依赖
sudo apt-get update
sudo apt-get install -f -y若近期更新了系统内核或显卡驱动，尝试回退到厂商认证的驱动版本。
1.7 切片进片/退片故障
现象： 切片卡住、进片失败、重复进片或退片异常。
处理建议：
- 立即停止使用，避免强行拉扯切片造成机械损坏。
- 按厂商手册执行玻片清理、「复位 / Home」等操作，等待机构归位。
- 检查切片架是否变形、玻片是否破损。
- 清洁进片轨道，清除灰尘和碎屑。
- 若故障反复出现，联系厂商技术支持并提供错误代码（Error Code）。
1.8 显卡异常
现象： 扫描软件界面花屏、黑屏、闪退，预览窗口无画面，或提示 OpenGL / CUDA / 显卡驱动相关错误。
常见原因与处理：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 显示器无信号 / 黑屏 | 显卡供电或数据线松动、驱动未加载 | 检查电源线与视频线；重启后查看驱动状态 |
| 软件提示显卡驱动错误 | 驱动未安装、版本不匹配或损坏 | 重新安装厂商认证驱动版本 |
| 预览画面花屏 / 撕裂 | 驱动异常或 OpenGL 加速冲突 | 更新或回退显卡驱动；尝试关闭硬件加速 |
| 扫描卡顿、GPU 占用 100% | 驱动异常或散热不良 | 检查 GPU 温度与风扇；清理灰尘 |
| 内核更新后无法进入桌面 | 显卡驱动与新内核不兼容 | 在 GRUB 选择旧内核启动，重装匹配驱动 |
排查步骤：
- 确认系统是否识别到显卡：
bash
# 查看显卡硬件信息
lspci | grep -iE 'vga|3d|display'
# NVIDIA 显卡：查看驱动与 GPU 状态（需已安装驱动）
nvidia-smi
# 查看当前加载的显卡驱动模块
lsmod | grep -iE 'nvidia|nouveau|amdgpu|radeon'- 若
nvidia-smi报错或命令不存在，检查驱动安装情况：
bash
# 查看推荐驱动（Ubuntu）
ubuntu-drivers devices
# 安装推荐驱动（示例，按实际推荐版本修改）
sudo apt-get update
sudo apt-get install -y nvidia-driver-535
# 安装后重启
sudo reboot- 查看内核日志中的显卡相关报错：
bash
dmesg | grep -iE 'nvidia|gpu|drm' | tail -30
journalctl -b | grep -iE 'nvidia|gpu' | tail -30- 检查 OpenGL 是否正常工作（扫描软件预览常依赖 OpenGL）：
bash
# 安装检测工具
sudo apt-get install -y mesa-utils
# 查看 OpenGL 渲染器（应显示独立显卡型号，而非 llvmpipe 软件渲染）
glxinfo | grep -iE 'OpenGL vendor|OpenGL renderer'若输出为 llvmpipe 或 Software Rasterizer，说明未正确使用独立显卡驱动。
- NVIDIA 驱动异常时，可尝试重新加载驱动模块：
bash
# 查看当前驱动版本
cat /proc/driver/nvidia/version
# 重新加载 NVIDIA 模块（会中断图形界面，建议在本地控制台操作）
sudo systemctl isolate multi-user.target
sudo modprobe -r nvidia_drm nvidia_modeset nvidia_uvm nvidia
sudo modprobe nvidia
sudo systemctl isolate graphical.target- 检查 GPU 温度与功耗（过热会导致降频或宕机）：
bash
nvidia-smi --query-gpu=temperature.gpu,power.draw,utilization.gpu --format=csv
watch -n 1 nvidia-smi # 实时监控，按 Ctrl+C 退出- 若近期执行了系统升级导致故障，可临时回退内核启动：
- 重启时长按 Shift（或 Esc）进入 GRUB 菜单
- 选择 Advanced options for Ubuntu，进入上一个可用内核版本
- 进入系统后重装与当前内核匹配的显卡驱动
建议：
- 扫描工作站优先使用厂商认证或现场验证过的显卡驱动版本，避免随意升级。
- 安装驱动前，先通过
ubuntu-drivers devices或厂商文档确认推荐版本。 - 若扫描软件明确依赖 CUDA，确认 CUDA 版本与驱动版本兼容：
nvidia-smi右上角会显示最高支持 CUDA 版本。
二、Linux 常用操作指令
以下命令适用于 Debian / Ubuntu 工作站日常运维，建议在现场终端中直接复制使用。
2.1 系统信息
bash
# 查看系统版本
cat /etc/os-release
# 查看内核版本
uname -a
# 查看主机名
hostname
# 查看系统运行时间与负载
uptime
# 查看硬件概要
sudo lshw -short2.2 用户与权限
bash
# 查看当前用户
whoami
# 切换为 root（或使用 sudo）
sudo -i
# 修改文件所有者
sudo chown user:group /path/to/file
# 修改文件权限（示例：所有者可读写，其他人只读）
chmod 644 /path/to/file2.3 进程与服务管理
bash
# 查看所有运行中的进程
ps aux
# 实时查看进程（按 q 退出）
top
# 或使用更友好的 htop
sudo apt-get install -y htop && htop
# 按名称查找进程
pgrep -a scanner
# 终止进程（先尝试正常终止）
kill <PID>
kill -9 <PID> # 强制终止，仅在无响应时使用
# 查看 systemd 服务状态
sudo systemctl status caddy
sudo systemctl status docker
# 启动 / 停止 / 重启服务
sudo systemctl start <服务名>
sudo systemctl stop <服务名>
sudo systemctl restart <服务名>
# 设置服务开机自启
sudo systemctl enable <服务名>2.4 磁盘与存储
bash
# 查看磁盘使用情况
df -h
# 查看目录占用大小
du -sh /path/to/dir
du -h --max-depth=1 /home
# 查看块设备与挂载点
lsblk
# 挂载外置硬盘（示例）
sudo mkdir -p /mnt/data
sudo mount /dev/sdb1 /mnt/data
# 查看挂载配置
cat /etc/fstab2.5 软件包管理
bash
# 更新软件源索引
sudo apt-get update
# 升级已安装软件包
sudo apt-get upgrade -y
# 安装软件
sudo apt-get install -y <包名>
# 搜索软件包
apt-cache search <关键词>
# 查看已安装软件
dpkg -l | grep <关键词>
# 修复依赖问题
sudo apt-get install -f -y2.6 日志查看
bash
# 查看系统日志（最近 100 行）
journalctl -n 100
# 实时跟踪日志
journalctl -f
# 查看指定服务的日志
journalctl -u caddy -n 50
journalctl -u docker -n 50
# 查看内核日志
dmesg | less2.7 文件操作
bash
# 列出文件（含隐藏文件、详细信息）
ls -la
# 复制 / 移动 / 删除
cp -r src/ dest/
mv oldname newname
rm -rf /path/to/dir # 谨慎使用
# 查找文件
find /home -name "*.svs"
# 查看文件内容
cat file.txt
less file.txt # 分页查看，按 q 退出
tail -f /var/log/syslog # 实时跟踪文件末尾2.8 Docker 常用命令
Medipath 后端以 Docker Compose 部署时，可在部署目录执行：
bash
# 查看容器状态
docker compose ps
# 查看容器日志
docker compose logs -f expert-service
docker compose logs --tail 100 alg-0
# 重启所有服务
docker compose restart
# 停止 / 启动
docker compose down
docker compose up -d三、网络配置
3.1 查看当前网络状态
bash
# 查看所有网卡 IP 地址
ip addr show
# 简写形式
ip a
# 查看路由表（含默认网关）
ip route show
# 查看 DNS 配置
cat /etc/resolv.conf
# 查看监听端口
sudo ss -lntp
# 或
sudo netstat -lntp3.2 临时修改 IP 地址
临时配置在重启后失效，适合现场快速测试：
bash
# 为 eth0 设置临时 IP（按实际网卡名修改，可能是 enp0s3、ens33 等）
sudo ip addr add 192.168.1.50/24 dev eth0
sudo ip link set eth0 up
sudo ip route add default via 192.168.1.1查看网卡名称：
bash
ip link show3.3 永久配置静态 IP（Netplan，Ubuntu 18.04+）
编辑 Netplan 配置文件（文件名因系统而异）：
bash
ls /etc/netplan/
sudo nano /etc/netplan/01-netcfg.yaml示例配置：
yaml
network:
version: 2
renderer: networkd
ethernets:
ens33:
dhcp4: no
addresses:
- 192.168.1.50/24
routes:
- to: default
via: 192.168.1.1
nameservers:
addresses:
- 8.8.8.8
- 114.114.114.114应用配置：
bash
sudo netplan apply3.4 永久配置静态 IP（/etc/network/interfaces，Debian）
bash
sudo nano /etc/network/interfaces示例：
auto eth0
iface eth0 inet static
address 192.168.1.50
netmask 255.255.255.0
gateway 192.168.1.1
dns-nameservers 8.8.8.8 114.114.114.114重启网络服务：
bash
sudo systemctl restart networking3.5 DNS 配置
bash
# 编辑 DNS（systemd-resolved 环境）
sudo nano /etc/systemd/resolved.conf
# 设置 DNS 后重启
sudo systemctl restart systemd-resolved
# 测试 DNS 解析
nslookup static.medipath.com.cn
dig static.medipath.com.cn3.6 防火墙配置（UFW）
bash
# 查看状态
sudo ufw status verbose
# 允许 SSH（远程维护前务必先放行）
sudo ufw allow 22/tcp
# 允许 Medipath 相关端口（按实际部署修改）
sudo ufw allow 8090/tcp
sudo ufw allow 8091/tcp
sudo ufw allow 9090/tcp
# 启用防火墙
sudo ufw enable
# 禁用防火墙（排查网络问题时临时使用）
sudo ufw disable3.7 网络连通性测试
bash
# 测试本机回环
ping -c 4 127.0.0.1
# 测试网关
ping -c 4 192.168.1.1
# 测试外网
ping -c 4 8.8.8.8
# 测试域名解析与 HTTPS 访问
ping -c 4 static.medipath.com.cn
curl -I https://static.medipath.com.cn
# 追踪路由
traceroute 8.8.8.8
# 测试指定端口是否可达
nc -zv 192.168.1.100 80
curl -I http://192.168.1.100:803.8 远程协助（RustDesk）网络设置
Palgo 部署脚本安装 RustDesk 后，需在客户端 网络设置 中填写：
| 配置项 | 值 |
|---|---|
| ID 服务器 | git.medipath.com.cn |
| 中继服务器 | git.medipath.com.cn |
| Key | Gv4NLEOCdFe3n1b66xQG+yYfVcsZus3qRXCDs2HgcI0= |
若远程连接失败，先确认本机可访问 git.medipath.com.cn：
bash
ping -c 4 git.medipath.com.cn
curl -I https://git.medipath.com.cn四、快速排查清单
现场遇到问题时，可按以下顺序快速检查：
| 步骤 | 检查项 | 命令 / 操作 |
|---|---|---|
| 1 | 扫描仪电源与指示灯 | 目视确认 |
| 2 | USB / 网线连接 | 更换端口或线缆 |
| 3 | 系统是否识别设备 | lsusb / ping <扫描仪IP> |
| 4 | 磁盘空间是否充足 | df -h |
| 5 | 网络是否通畅 | ip a / ping |
| 6 | 服务是否运行 | systemctl status / docker compose ps |
| 7 | 查看错误日志 | journalctl -xe / dmesg |
五、联系支持
若以上方法无法解决问题，请联系 Medipath 技术支持，并提供：
- 扫描仪品牌与型号
- 操作系统版本（
cat /etc/os-release输出） - 错误截图或错误代码
- 相关日志（
journalctl或扫描软件日志）