troubleshooting

故障排除

本页面提供了LAN文件服务器常见问题的详细排查步骤和解决方案，帮助您快速解决问题。

1. 安装与启动问题

1.1 Python版本不兼容

症状：服务器无法启动，报错显示Python版本过低。

排查步骤：

1. 检查Python版本：在命令行中运行 python --version 或 python3 --version
2. 确认Python版本是否为3.7或更高

解决方案：

• 下载并安装最新版本的Python（推荐Python 3.10+）
• 确保系统环境变量中Python路径正确

1.2 端口被占用

症状：服务器无法启动，报错显示端口已被占用。

排查步骤：

1. 检查端口使用情况：
   • Windows: netstat -ano | findstr :8000
   • Linux/macOS: lsof -i :8000 或 netstat -tuln | grep 8000
2. 查看占用端口的进程

解决方案：

• 关闭占用端口的进程
• 或在config.json中修改server.port配置项，使用其他端口

1.3 配置文件格式错误

症状：服务器无法启动，报错显示配置文件解析错误。

排查步骤：

1. 检查config.json文件格式
2. 确认所有配置项都符合JSON文件格式要求
3. 检查是否有缺少的配置节或配置项

解决方案：

• 删除错误的配置文件，重新运行服务器自动生成默认配置
• 或手动修复配置文件中的格式错误

1.4 共享目录不存在

症状：服务器启动成功，但无法访问文件。

排查步骤：

1. 检查config.json中server.share_dir配置项
2. 确认配置的共享目录是否存在

解决方案：

• 创建缺失的共享目录
• 或修改server.share_dir配置项，指向存在的目录

2. 访问与连接问题

2.1 其他设备无法访问服务器

症状：服务器在本地可以访问，但同一局域网内的其他设备无法访问。

排查步骤：

1. 确认所有设备都在同一局域网内
2. 检查服务器IP地址是否正确
3. 检查防火墙是否允许服务器端口访问
4. 尝试使用IP地址而非localhost访问

解决方案：

• 在防火墙中添加服务器端口的允许规则
• 确保路由器没有启用隔离功能
• 尝试重启路由器和所有设备

2.2 登录失败

症状：输入正确的用户名和密码，但无法登录。

排查步骤：

1. 检查用户名和密码是否正确
2. 检查config.json文件中的auth配置是否正确
3. 检查是否被IP封禁（查看日志文件）
4. 检查浏览器Cookie设置是否允许保存Cookie

解决方案：

• 确认用户名和密码正确
• 如果被IP封禁，等待5分钟后重试
• 清除浏览器Cookie，重新登录
• 或使用initialize-server.ps1脚本重新初始化认证信息

2.3 会话丢失

症状：登录后不久自动退出，或刷新页面后需要重新登录。

排查步骤：

1. 检查浏览器Cookie设置
2. 确认浏览器没有开启隐私模式
3. 检查config.json中的server.session_timeout配置

解决方案：

• 确保浏览器允许保存Cookie
• 关闭浏览器隐私模式
• 检查系统时间是否正确（会话依赖于时间戳）

3. 文件与功能问题

3.1 文件不显示

症状：共享目录中有文件，但服务器页面不显示。

排查步骤：

1. 检查文件类型是否在白名单中
2. 检查文件是否在共享目录内
3. 检查文件权限是否允许读取
4. 检查日志文件是否有相关错误

解决方案：

• 确认文件类型在config.py的WHITELIST_EXTENSIONS中
• 确保文件在配置的共享目录内
• 检查并修改文件权限，确保服务器可以读取
• 重启服务器刷新索引

3.2 搜索功能不工作

症状：搜索关键词后没有返回结果，或返回错误结果。

排查步骤：

1. 检查共享目录中是否有匹配的文件
2. 检查搜索关键词是否正确
3. 检查日志文件是否有相关错误
4. 尝试清除浏览器缓存

解决方案：

• 确认共享目录中有匹配的文件
• 尝试使用更精确的搜索关键词
• 增加SEARCH_CACHE_SIZE配置项大小
• 重启服务器刷新索引

3.3 文件无法预览

症状：点击文件后无法预览，或预览显示错误。

排查步骤：

1. 检查文件类型是否支持预览
2. 检查浏览器是否支持该文件格式预览
3. 检查文件是否损坏
4. 检查日志文件是否有相关错误

解决方案：

• 确认文件类型在支持的预览格式列表中
• 尝试使用其他浏览器
• 检查文件是否损坏，尝试重新上传或修复
• 确保文件大小在浏览器可处理范围内

3.4 文件无法下载

症状：点击下载按钮后没有反应，或下载失败。

排查步骤：

1. 检查网络连接是否稳定
2. 检查浏览器下载设置
3. 检查文件是否存在
4. 检查日志文件是否有相关错误

解决方案：

• 确保网络连接稳定
• 检查浏览器下载路径是否正确
• 确认文件在共享目录中存在
• 尝试使用其他浏览器下载

4. 性能问题

4.1 页面加载缓慢

症状：页面加载时间过长，或卡顿严重。

排查步骤：

1. 检查共享目录中的文件数量
2. 检查服务器硬件配置
3. 检查网络连接速度
4. 检查日志文件是否有性能相关错误

解决方案：

• 减少共享目录中的文件数量，或分类整理文件
• 增加INDEX_CACHE_SIZE配置项大小
• 关闭不必要的其他程序，释放系统资源
• 确保使用有线网络连接，或使用更快的无线网络

4.2 搜索速度慢

症状：搜索关键词后需要等待很长时间才能显示结果。

排查步骤：

1. 检查共享目录中的文件数量
2. 检查服务器硬件配置
3. 检查SEARCH_CACHE_SIZE配置项大小

解决方案：

• 增加SEARCH_CACHE_SIZE配置项大小
• 减少共享目录中的文件数量
• 优化服务器硬件配置（增加内存、使用更快的硬盘）

4.3 服务器占用资源过高

症状：服务器占用CPU或内存过高，导致系统卡顿。

排查步骤：

1. 检查服务器进程的资源占用情况
2. 检查共享目录中的文件数量
3. 检查日志文件是否有异常

解决方案：

• 减少共享目录中的文件数量
• 降低MAX_CONCURRENT_THREADS配置项值
• 关闭不必要的其他程序
• 优化服务器硬件配置

5. 安全问题

5.1 可疑登录尝试

症状：日志文件中显示大量失败的登录尝试。

排查步骤：

1. 检查日志文件，查看失败登录的IP地址
2. 确认是否为自己或信任的设备的尝试

解决方案：

• 检查并确认IP地址是否为信任的设备
• 如为恶意尝试，考虑启用更严格的防火墙规则
• 更改密码为更复杂的密码
• 增加FAILED_AUTH_LIMIT和FAILED_AUTH_BLOCK_TIME配置项值

5.2 权限问题

症状：担心文件被未授权访问。

排查步骤：

1. 确认服务器仅在信任的局域网内运行
2. 检查用户名和密码是否足够复杂
3. 确认共享目录仅包含需要共享的文件

解决方案：

• 确保服务器不在公网中暴露
• 使用强密码，定期更换
• 仅共享必要的目录和文件
• 考虑使用VPN增加安全性

6. 移动端问题

6.1 移动端无法访问

症状：手机或平板无法访问服务器。

排查步骤：

1. 确认移动设备与服务器在同一局域网内
2. 检查移动设备的网络连接
3. 尝试使用IP地址而非域名访问

解决方案：

• 确保移动设备与服务器在同一局域网内
• 检查移动设备的Wi-Fi连接
• 尝试关闭移动设备的移动数据，仅使用Wi-Fi
• 尝试重启移动设备和服务器

6.2 移动端界面显示异常

症状：移动端页面布局错乱，或功能无法正常使用。

排查步骤：

1. 检查移动设备的浏览器版本
2. 尝试使用其他浏览器
3. 检查服务器是否为最新版本

解决方案：

• 更新移动设备的浏览器到最新版本
• 尝试使用Chrome或Safari浏览器
• 确保服务器为最新版本
• 清除浏览器缓存，重新加载页面

7. 日志分析

7.1 查看日志文件

日志文件是排查问题的重要工具，默认保存在lan_file_server.log文件中。您可以使用文本编辑器查看日志文件，或使用命令行工具：

Windows：

Get-Content lan_file_server.log -Tail 100

Linux/macOS：

tail -n 100 lan_file_server.log

7.2 常见日志错误

错误信息	可能原因	解决方案
Python version 3.6 is not supported	Python版本过低	安装Python 3.7+
Address already in use	端口被占用	更改端口或关闭占用端口的进程
No such file or directory: 'share_dir'	共享目录不存在	创建共享目录或修改配置
Invalid config file format	配置文件格式错误	修复配置文件或重新生成
Authentication failed for user	用户名或密码错误	检查用户名和密码
IP address blocked	IP被封禁	等待封禁时间到期或修改配置

8. 高级排查

8.1 启用调试日志

如果您遇到复杂问题，可以启用调试日志获取更详细的信息：

1. 在config.json文件中修改日志级别：

   {
     "logging": {
       "log_level": "DEBUG"
     }
   }

2. 重启服务器
3. 查看日志文件获取详细信息

8.2 检查系统资源

Windows：

• 打开任务管理器，查看CPU、内存和磁盘使用情况

Linux：

• 使用top或htop命令查看系统资源占用

macOS：

• 打开活动监视器，查看系统资源占用

8.3 网络抓包

如果您怀疑是网络问题，可以使用网络抓包工具查看网络请求：

• Windows：Wireshark
• Linux/macOS：tcpdump或Wireshark

9. 重置与重新安装

如果以上方法都无法解决问题，您可以尝试重置或重新安装服务器：

9.1 重置配置

1. 备份现有的配置文件（可选）
2. 删除config.json文件
3. 重新运行服务器，自动生成默认配置
4. 重新配置服务器

9.2 重新安装

1. 备份配置文件和数据（可选）
2. 删除整个服务器目录
3. 重新克隆或下载服务器代码
4. 重新配置和启动服务器

10. 寻求帮助

如果您无法自行解决问题，可以通过以下方式寻求帮助：

1. 查看常见问题(FAQ)页面
2. 在GitHub项目页面提交Issue，提供详细的错误信息和日志
3. 检查项目README.md文件获取更多信息
4. 尝试联系项目维护者

下一步

• 常见问题(FAQ)：查看常见问题解答
• 使用指南：详细了解如何使用文件服务器
• 配置说明：了解如何配置服务器