故障排查
针对最常见的安装、媒体与配置问题的解决方法。
大多数问题归结为几个常见原因：PHP 版本、文件权限、数据库凭据、Web 服务器重写或缺少工作进程。本页列出了运营者最常遇到的症状及其解决方法。如有疑问，PHP 错误日志是最快找到真相的途径。
安装问题
"您的 PHP 版本不受支持"
TubePress 需要 PHP 8.2 或更高版本，由一个在其他任何操作之前运行的解析安全版本检测器强制执行。在您的主机控制面板中切换 PHP 版本（或将虚拟主机指向更新的 PHP-FPM 套接字）并重新加载。请参阅 系统要求。
"无法连接到数据库"
在安装程序的数据库步骤中，请仔细检查主机（通常是 localhost 或 127.0.0.1）、数据库名称、用户名和密码，以及该用户是否具有该数据库的权限。数据库必须已经存在——安装程序只创建数据表，而不是数据库本身。
安装程序无法写入配置 / 出现"不可写"错误
Web 服务器在安装过程中需要对 config/ 和 storage/ 目录具有写权限。将这些目录设置为 PHP 用户可写，然后重试。请参阅 安装 中的权限说明。
我完成了安装，但 /install 仍然加载
安装过程会写入 config/installed.php。如果该文件缺失，应用程序会认为尚未安装；如果安装已完成，该文件应该存在，且安装程序会自动锁定。请重新检查 config/ 目录是否可写。
网站可以加载，但页面返回 404
如果首页正常，但其他所有 URL 均返回 404，则说明 URL 重写未能到达前端控制器。
- Apache — 确认已启用
mod_rewrite，并设置了AllowOverride All，以便捆绑的.htaccess生效。 - Nginx — 您的
location /必须回落到前端控制器，例如try_files $uri $uri/ /index.php?$query_string;。有关 Web 服务器说明，请参阅 架构。
登录与管理员访问
我找不到管理员登录入口
如果您出于安全考虑设置了自定义管理员 URL，则面板不再位于 /admin——它只响应您的私密路径。如果您有数据库访问权限，可从 settings 表中恢复。请参阅 安全。
双因素认证将我锁定了
如果您丢失了身份验证器，请在数据库中禁用用户的 TOTP（users 表中的相关列）以重新获得访问权限，然后重新注册。详情请参阅 安全。
上传与媒体
大文件上传失败或超时
提高 PHP 限制 upload_max_filesize 和 post_max_size，并在 Nginx 上增加 client_max_body_size。演示站通过较高的 client_max_body_size 允许数 GB 的上传；在您的服务器上对大文件进行相同配置。
视频无法播放
新上传的视频可能仍在 处理中，直到转码完成。确认格式可在网页上播放，存储中存在渲染文件，并且您的服务器为 .mp4/.webm 发送正确的 MIME 类型。请参阅 播放器。
缩略图或预览图缺失
缩略图和预览图生成需要 GD 或 Imagick 扩展（以及用于视频帧提取的 FFmpeg）。确认它们已安装，并且 uploads/ 目录可写。
转码卡住了
如果任务长时间在队列中且从未完成：
- 确认在转码运行的地方（本地服务器或远程工作节点）已安装 FFmpeg。
- 如果您使用远程 转码服务器，请检查工作节点是否正在运行，以及其 API 密钥是否与管理员中配置的一致。
- 确保调度器正在运行（见下文）——任务调度和重试依赖伪 cron。
计划任务未运行
伪 cron 仅在页面渲染时触发。在访问量较低的网站上，心跳可保持其活跃——请确保 heartbeat_enabled 为 1。如果您禁用了它，请重新启用，或添加一个定期访问您网站的系统 cron 条目。
邮件无法发送
在 邮件与通知 下配置 SMTP，并使用内置的发送测试邮件按钮进行确认。如果测试失败，请验证 SMTP 主机/端口/凭据，以及您的主机是否允许外发邮件；为提高送达率，请在您的域名上设置 SPF/DKIM。
性能
要使大规模网站保持流畅：启用 OPcache，给 PHP 足够的内存，将 MySQL 与 PHP 放在同一网络中，并保持 CTR 重新计算和其他计划任务运行。TubePress 内置了大型内容库所需的索引和分块任务——请参阅 维护。
更新失败
如果更新无法应用，请确认核心文件对 PHP 用户可写，并且您使用的是 PHP 8.2+。更新前务必 备份，以便回滚。请参阅 更新。
仍然遇到问题？
收集确切的错误消息和相关日志行，然后从您的控制台或管理后台的支持小部件提交工单。您提供的上下文越多——PHP 版本、Web 服务器以及您当时的操作——解决速度越快。请参阅 公告与支持。