2026年10月27日

问题排查指南

在安装或使用 SetFN 的过程中可能会遇到问题。本文档按常见症状整理原因和解决方法。请在下面的列表中查找您遇到的症状并进行确认。

安装相关

Q：安装过程中出现端口冲突错误？

当 SetFN 使用的端口已被其他程序占用时会出现此问题。

确认正在使用该端口的程序
关闭冲突的程序，或更改 SetFN 的端口设置
重新进行安装

Q：安装已完成，但服务无法启动？

如果已设置自动启动（systemd），请确认服务状态和日志。

使用 systemctl status setfn-spacebuilder 确认运行状态
如果处于停止状态，使用 sudo systemctl start setfn-spacebuilder 启动
仍无法启动时，使用 journalctl -u setfn-spacebuilder -n 100 --no-pager 查看错误信息
确认服务文件中的 User 和 ExecStart 值与实际的用户名和可执行文件路径一致

如果未设置自动启动，请在终端中重新运行可执行文件。详细内容请参考在 Linux 上安装。

Q：可以使用 Docker 安装吗？

目前尚未提供官方 Docker 镜像。请勿使用任意镜像名称执行 docker pull 或 docker run。

目前请按照在 Linux 上安装中的方法安装
Docker 支持状态请在使用 Docker 安装中确认

访问相关

Q：无法在浏览器中访问 SetFN？

网络设置或服务状态可能存在问题。

确认 SetFN 服务是否正常运行
确认访问地址（IP、端口）是否正确
确认防火墙是否已允许该端口
尝试从同一网络中的其他设备访问

Q：无法登录？

确认用户名和密码是否正确
确认 Caps Lock 是否未开启
忘记密码时，请使用重置密码功能
账户可能已被管理员禁用，请联系管理员

Q：无法从外部访问？

需要确认外部访问设置是否配置正确。

先确认在同一网络中能否通过内网地址访问
确认 Cloudflare Tunnel 等外部访问连接是否正在运行
确认域名是否已正确连接
在 屏蔽管理 的 有效屏蔽列表 中确认要访问的 IP 是否未被屏蔽

Q：只有特定用户无法访问？

登录多次失败时，IP 可能会被自动屏蔽。请在 屏蔽管理 的 有效屏蔽列表 中确认该用户的 IP
确认用户账户的权限和状态是否正常

Q：管理员也无法登录？

如果管理员账户也被屏蔽，或者因不知道密码而无法进入管理员页面，请在安装了 SpaceBuilder 的计算机终端中使用命令进行恢复。

登录屏蔽使用 unblock 命令解除
管理员密码使用 user password 命令更改
如果因 IP 访问限制而无法访问管理员页面，使用 ip 命令修改允许列表

详细方法请参考使用命令管理服务器。

文件相关

Q：文件上传失败？

确认对上传目标文件夹是否有写入权限
确认服务器的剩余磁盘容量
确认文件大小是否未超过设定的限制
确认网络连接是否稳定

Q：文件下载速度慢？

确认服务器和客户端是否在同一内网中
确认网络带宽是否充足
确认服务器的 CPU、内存使用率是否未过高
同时在线人数较多时，考虑升级服务器配置

Q：文件在列表中不显示？

确认当前用户的等级和团队是否可以访问该文件夹
确认是否因应用了文件夹筛选而隐藏了文件
清除浏览器缓存后刷新

性能相关

Q：SetFN 整体运行变慢了？

服务器资源可能不足。

确认服务器的 CPU、内存使用率
确认磁盘容量是否充足（剩余空间低于 10% 时性能可能下降）
在 系统管理 > 后台服务 中确认 AI、索引等任务是否占用了过多资源
尝试重启服务器

Q：搜索很慢或没有结果？

确认搜索索引是否已正常构建
文件数量非常多时，尝试将搜索范围缩小到特定文件夹
服务器重启后，索引重新构建可能需要一些时间

其他

Q：有浏览器兼容性问题？

SetFN 建议使用最新版本的 Web 浏览器。请确认以下事项。

确认是否使用 Chrome、Edge、Firefox、Safari 的最新版本
不支持 Internet Explorer，请使用其他浏览器
删除浏览器缓存和 Cookie 后重试

Q：上述方法都无法解决？

在服务器日志中查看错误信息。如果通过自动启动运行，请使用 journalctl -u setfn-spacebuilder -n 100 --no-pager
在 系统管理 > 设备信息 中检查操作系统和磁盘状态
向 SetFN 官方技术支持团队咨询，并附上错误信息和环境信息

相关文档