❓ 常见问题

安装、配置、使用 TBlog 过程中最常遇到的问题与解决方案。

🚀 安装

访问 install.php 提示 404

原因：Web 服务器没把请求路由到 PHP。

解决：

• 确认 install.php 真的在网站根目录
• Nginx 用户检查 location ~ \.php$ 配置（参考安装指南）
• Apache 用户确认 mod_php 或 php-fpm 已启用

数据库连接失败，提示 Access denied

• 检查 config.php 中的 DB_USER / DB_PASS 是否正确
• 登录 MySQL 确认用户存在：SELECT user, host FROM mysql.user;
• 确认用户有权访问该数据库：SHOW GRANTS FOR 'tblog'@'localhost';

表前缀已存在

如果之前装过 TBlog 没清干净，可以换一个新前缀，或者手动删除旧表：

-- 删除旧表（⚠️ 会清空所有数据）
DROP TABLE IF EXISTS tblog_posts, tblog_categories, tblog_comments, tblog_settings;

🔐 登录

忘记管理员密码

使用 密码重置工具，30 秒搞定。

登录提示「会话已过期」

• 清空浏览器 cookie 重试
• 如果用了 CDN 或反向代理，检查 session.cookie_domain 配置
• 检查 PHP session 目录可写：ls -ld /var/lib/php/sessions

后台登录页能打开但提交后 500 错误

查看 PHP 错误日志：

# Nginx + PHP-FPM
tail -f /var/log/php7.4-fpm.log /var/log/nginx/error.log

# Apache
tail -f /var/log/apache2/error.log

✏️ 编辑器

粘贴图片不显示

检查 uploads/ 目录权限：

mkdir -p uploads
chown -R www-data:www-data uploads
chmod 755 uploads

保存文章后样式丢了

TBlog 内置白名单 XSS 净化，不在白名单的标签会被剥掉。检查 HTML 源码是否包含合法标签。

🎨 主题

切换主题后没生效

• 硬刷新浏览器（Ctrl+Shift+R / Cmd+Shift+R）
• 检查浏览器是否缓存了旧的 CSS
• 确认主题目录存在：ls templates/ 应能看到 flow / magine

自定义主题显示空白页

• 检查 index.php 是否有 PHP 语法错误：php -l templates/mytheme/index.php
• 检查主题目录权限
• 查看 PHP 错误日志

⚡ 性能

首页加载慢

• 启用 PHP OPcache
• 用 CDN 缓存静态资源
• 文章数超过 1000 篇时考虑分页

opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000

数据库查询慢

检查是否缺少索引：

-- 查看慢查询
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 1;

-- 添加常用索引
CREATE INDEX idx_created_at ON tblog_posts(created_at);
CREATE INDEX idx_status ON tblog_posts(status);

🛡 安全

如何防止暴力破解登录？

• 使用强密码（12 位以上，包含大小写数字符号）
• 改默认后台路径：把 admin/ 改名或加 HTTP Basic Auth
• 用 fail2ban 限制 SSH 登录失败
• 开启 HTTPS（Let's Encrypt 免费）

如何启用 HTTPS？

使用 Let's Encrypt 一键签发免费证书：

# 安装 certbot
apt install certbot python3-certbot-nginx

# 自动配置 Nginx
certbot --nginx -d tblog.cn -d www.tblog.cn

# 自动续期已默认配置

🔄 迁移服务器

1. 在旧服务器打包：mysqldump + tar
2. 在旧服务器下载到本地
3. 在新服务器安装 PHP + MySQL + Nginx
4. 上传并恢复文件、导入数据库
5. 修改 config.php（如果 DB 账号/密码变了）
6. 修改 DNS 解析到新服务器 IP

📞 还没解决？

• 在 GitHub Issues 搜索类似问题
• 没找到？提交新 Issue，附上：
  • TBlog 版本号
  • PHP / MySQL 版本
  • Web 服务器（Nginx / Apache）及版本
  • 复现步骤
  • 错误截图或日志
• 查看 更新日志，确认不是已知 bug