快速排障指南

遇到问题时，按症状查找 → 按步骤排查 → 快速解决问题。

目录

• 症状一：软件无法启动
• 症状二：扫描/索引卡住或失败
• 症状三：照片无法显示或显示异常
• 症状四：搜索结果不准确或无结果
• 症状五：人脸识别不准确
• 症状六：软件运行缓慢
• 症状七：内存/CPU 占用过高
• 症状八：Docker 部署失败
• 症状九：激活失败
• 通用排查步骤

症状一：软件无法启动

排查步骤

1. 检查系统要求

   • Windows 10+ / Windows Server 2012 R2+ / macOS Apple Silicon / Ubuntu 24.04+
   • 64 位 CPU，4 GB 以上内存

2. Windows Server 2012 R2 需安装运行库

   该版本系统默认缺少必需的 Visual C++ 运行库，会导致软件无法启动。请安装：

   Visual C++ Redistributable for Visual Studio 2015

   下载后安装 vc_redist.x64.exe 即可。

3. 检查安装完整性

   • 重新下载安装包，覆盖安装

4. 查看日志文件

   • 找到数据目录下的日志文件
   • 搜索 [ERROR] 或 panic 关键词定位问题

5. 重置数据目录（最后手段）

   • 备份数据目录
   • 删除数据目录后重新启动
   • 注意：这将丢失索引和配置，照片原文件不受影响

相关章节

• 安装与系统要求
• 系统设置

症状二：扫描/索引卡住或失败

症状表现

• 扫描进度长时间不动
• 索引进度条卡住
• 错误提示扫描失败

排查步骤

重启软件 → 检查目录权限 → 检查磁盘空间 → 单独测试 → 刷新索引 → 重建索引

1. 重启软件（最优先）

已完成的索引不会丢失。软件会在启动时自动检测到中断，从中断处继续扫描，跳过已处理完的照片。

此功能由设置 → 索引设置 →「自动恢复索引」控制（默认开启）。

2. 检查文件夹权限

确保 Photocatalyst 对所添加的文件夹有读取权限。在文件管理器中验证能否正常访问。

3. 检查磁盘空间

确认磁盘有足够可用空间（建议至少保留 1 GB）。

4. 单独测试

• 移除所有文件夹
• 添加一个小文件夹（少量照片）测试
• 如果正常，逐批添加大文件夹

5. 刷新索引（手动恢复）

菜单 → 刷新索引。手动触发从当前状态恢复，跳过已完成的，仅处理剩余。

6. 重建索引（最后手段）

设置 → 数据重建 → 重建索引。将全面重建，耗时较长。

预防措施

• AI 能力选择：首次添加文件夹前先配置好 AI 能力（设置 → AI 配置）。仅需基础管理时选 Lightweight 预设，不开启人脸/语义/OCR 可大幅提升速度
• 大量照片建议分批添加（每批不超过 10000 张）
• 合理设置忽略规则，排除不需要的文件
• 设置最小图片尺寸过滤（默认 96 px）

相关章节

• 照片导入与索引
• 扫描设置

症状三：照片无法显示或显示异常

症状表现

• 缩略图显示为空白或叉号
• 预览照片黑屏
• 部分格式照片不显示
• EXIF 信息缺失

排查步骤

验证原文件 → 检查格式支持 → 检查 FFmpeg → 清理缓存 → 重建索引

1. 验证原文件

用系统默认图片查看器打开原文件，确认文件未损坏。

2. 检查格式支持

确认文件格式在支持列表中。常见不支持的格式需要额外配置：

3. 安装 FFmpeg

HEIC/HEIF 需要 FFmpeg 解码： 设置 → 系统设置 → FFmpeg 下载/安装。

4. 清理缩略图缓存

删除数据目录下的缓存文件后重启软件，让系统重新生成缩略图。

5. 重建索引

设置 → 数据重建 → 重建索引，重新扫描和生成缩略图。

相关章节

• 照片浏览
• 支持的图片格式

症状四：搜索结果不准确或无结果

症状表现

• 搜索某些关键词无结果
• 以图搜图结果不相关
• AI 语义搜索结果偏差大
• 人脸搜索结果不准确

排查步骤

确认索引状态 → 调整搜索参数 → 优化搜索条件 → 重建索引

1. 确认照片已索引

检查状态栏，确保所有照片扫描完成。未索引的照片无法被搜索。

2. 调整搜索参数

3. 优化搜索技巧

• 文件信息搜索：使用通配符 * 和 ?
• 画面内容搜索：用逗号分隔多个主体，如 猫, 室内, 沙发
• 人脸搜索：使用正面、光线充足的照片
• 高级搜索：利用组合条件精确筛选

4. 重建索引（最后手段）

设置 → 数据重建 → 重建索引。当数据异常时此操作最有效。

相关章节

• 搜索功能
• 数据重建

症状五：人脸识别不准确

症状表现

• 人脸检测遗漏
• 同一人被识别为多个人物
• 不同人被合并在同一人物
• 非人脸区域被误识

排查步骤

调整参数 → 手动纠正 → 合并/拆分 → 重建人脸分组

1. 调整人脸参数

设置 → AI 配置 → 人脸设置：

• 识别阈值：调低（如 0.15）可检测更多人脸，调高（如 0.3）减少误检
• 建议：先小幅调整，测试效果后再微调

2. 手动纠正

3. 处理未分类人脸

• 人物页面中查看未分类人脸
• 手动分配到已有的人物
• 或批量创建新人物

4. 重建人脸分组

设置 → 数据重建 → 重建分组 → 人脸。完全重新聚类所有人物。

相关章节

• 人脸识别
• AI 配置

症状六：软件运行缓慢

症状表现

• 界面响应迟钝
• 照片加载缓慢
• 切换视图卡顿

排查步骤

硬件检查 → 软件设置优化 → 数据库优化 → 数据清理

1. 硬件优化

2. 软件设置优化

3. 数据库优化

每月执行一次：设置 → 系统设置 → 优化数据库。

4. 数据清理

• 清理缺失文件记录：设置 → 删除缺失
• 清空回收站中的照片
• 清理重复照片

相关章节

• 性能优化建议

症状七：内存/CPU 占用过高

排查步骤

1. 减少并发量

   • 设置 → AI 配置 → 处理模式 → 逐个（而非并行）

2. 限制待处理照片数量

   • 分批添加照片，避免一次添加数万张

3. 调整 AI 能力范围

   • 设置 → AI 配置 → 推理能力 → 按需选择（基础/人脸/文字/语义）

4. 重启软件

   • 大数据量处理后重启可释放内存碎片

症状八：Docker 部署失败

症状表现

• 容器启动后立即退出
• 端口无法访问
• 数据目录权限错误

排查步骤

检查日志 → 检查端口 → 检查挂载 → 检查权限

1. 查看容器日志

docker-compose logs -f

搜索 [ERROR] 定位具体问题。

2. 检查端口

• 确认主机端口（如 10242）未被占用
• 防火墙放行对应端口
• 访问 URL 格式：http://<服务器IP>:10242

3. 检查卷挂载

volumes:
  - /your/photos:/photos:ro    # 确认主机路径存在且有读取权限
  - ./data:/app/data            # 确认数据目录有写入权限

• 照片目录结尾的 :ro 表示只读，不可省略
• 确保主机路径使用绝对路径

4. 检查镜像架构

5. 检查磁盘空间

df -h

确保有充足空间存放索引数据。

相关章节

• Docker 部署
• docker-arm64

症状九：激活失败

桌面版排查

1. 确认请求码复制完整无遗漏
2. 确认激活码输入正确（注意大小写）
3. 确认激活码与请求码匹配
4. 激活后需重启软件

Docker 版排查

1. 确认容器可以访问互联网（在线激活需要）
2. 确认激活码输入正确
3. 检查激活状态：菜单 → 帮助 → 关于

相关章节

• 软件激活

通用排查步骤

当遇到未列出的问题时，按以下顺序排查：

1. 重启软件 —— 多数问题重启即可解决
   ↓ 如重启无法解决
2. 联系供应商获取技术支持（附上日志文件）

获取更多帮助

• 帮助文档：菜单 → 帮助 → 文档
• 检查更新：菜单 → 帮助 → 检查更新
• 查看版本：菜单 → 帮助 → 关于
• 日志文件：菜单 → 帮助 → 打开日志文件
• 数据目录：设置 → 系统设置 → 打开数据目录

提交问题报告时，请附上日志文件中的相关错误信息和软件版本号。

如仍无法排除故障，请即时联系供应商获取技术支持。