常见问题 Q&A

最近更新:2026-11-07

建站、用站、升级过程中最常碰到的情况,一条一条给答案。装不了先看第一组,站出状况先看第二组;都查不到再看文末「日志在哪」。

一、安装与准备

1.1 装墨林需要什么环境?

PHP 8.2 或更高,MySQL 8(或 MariaDB 10.5 以上),一个已解析到服务器的域名。

PHP 必需扩展五个:pdo_mysql、mbstring、json、openssl、fileinfo。建议再装:gd(生成缩略图)、zip(后台上传主题/插件包)、intl(本地化日期)、opcache(加速)。缺必需扩展安装向导会直接拦下并写明缺哪个;缺推荐扩展也能装,只是对应功能缺一块。宝塔用户建站时 PHP 版本选 8.2+,选低了后面会白屏。

1.2 安装包从哪下?为什么打开报「vendor/autoload.php 找不到」?

用官方下载页或 Releases 给的安装包,它自带依赖,解压到站点根就能装。

仓库页 Code → Download ZIP 下的是源码包,不含 vendor/ 目录,打开必报:

require(.../vendor/autoload.php): Failed to open stream

这不是程序坏了,是少一步:要么换 Releases 的包,要么在站点根跑一次 composer install --no-dev。另外源码包会多套一层目录(如 molinink-main/),必须把里面的文件"提"到站点根,多套一层打不开。也不要用面板的「运行目录」去指那层子目录——/uploads/ 与 /storage/ 的规则都是按站点根写的,指偏了会图片 404、备份反而能被下载。

1.3 安装后首页能开,但后台和文章页全是 404?

伪静态没生效。程序是单入口,像 /admin、/blog 这类地址在磁盘上没有对应文件,nginx 必须被告知"找不到就交给 index.php"。

宝塔:网站 → 设置 → 伪静态,粘入(完整说明见安装包内 install/安装说明.txt):

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

location = /admin {
    try_files $uri /index.php$is_args$args;
}
location = /admin/ {
    return 301 /admin;
}

只粘第一段、漏掉 /admin 两行,症状会变成:文章页正常,进后台 403 Forbidden——因为站点根下真有个 admin/ 目录(只放静态资源),nginx 会按目录索引处理它。

1.4 /storage/ 要不要拦?怎么拦?

要拦,这是安全项。storage/ 在站点根目录里,装着全站备份包、运行日志、缓存和远端备份凭据,不拦的话知道地址就能下载。

宝塔:网站 → 设置 → 配置文件,粘进 server { } 里:

location ^~ /storage/ {
    return 404;
}

装完自查:访问你的域名/storage/backups/ 返回 404 = 生效了。备份包文件名本身也带 8 位随机串防猜测,但这条规则该配还是要配。

1.5 安装向导最后一步失败,数据库连不上?

按顺序查三点:主机填 127.0.0.1(数据库和网站在同一台机器时)、库名/用户名/密码与建站时记下的一致、数据库用户对那个库有全部权限。向导有「测试连接」按钮,先点它;中途失败会整体回滚,不会留下半装的站。

1.6 装完还要做什么?

三件:删掉站点根的 install/ 目录(留着别人还能打开安装页);进后台「设置 → 固定链接」选一个样式并保存;浏览器自查四个地址——首页能开、/admin 出登录页、/storage/backups/ 是 404、文章里图片能显示。四条都对上就算装好了。

二、站点出状况

2.1 整站白屏或 500?

最常见两个原因:PHP 版本低于 8.2;storage/ 目录不可写。宝塔里把站点 PHP 版本切到 8.2+,storage/ 及其子目录权限给 www 用户、755。具体报错看 storage/logs/ 下当天的日志文件,比白屏本身有用得多。

2.2 文章里的图片是破图?

先确认文件确实在 storage/uploads/ 下。默认配置下程序自己会兜底发图,不加任何 nginx 配置也应该能显示;破图多半是文件真不在(上传失败过)或迁移时没搬 uploads 目录。想让图片走 nginx 直发更快,可加 /uploads/ 的 alias 配置(见安装说明「可选」一节),加了别忘了把路径换成真实路径。

2.3 上传图片失败?

两处限制:PHP 的 upload_max_filesize(默认建议 2M 以上,宝塔可在 PHP 设置里调);storage/uploads/ 必须可写。另外缺 gd 扩展时缩略图生成会失败。都不对再看当天日志。

2.4 后台登录老被锁?

密码连错 5 次,锁 15 分钟,这是防暴力破解的,不是故障。等 15 分钟再登,或查清是谁在试你的密码——如果日志里有大量失败记录,建议改强密码。锁定期内即使密码正确也进不去。

2.5 登录状态一会儿就失效,提示要重新登录?

会话过期属正常安全设计。如果是刚登录就立刻被踢,通常是两点:站点地址(设置里的 URL)与实际访问域名不一致,浏览器认为跨站;或服务器时钟不准导致 cookie 有效期异常。核对「设置 → 常规」里的站点地址与浏览器地址栏一致(协议也要一致,https 就都 https)。

2.6 评论没显示出来?

评论默认「先审后显」:新评论进后台「评论」页排队,审核通过才出现在前台。想省事可以在「设置 → 讨论」里把默认状态改成直接通过,或按用户注册与否分别控制。评论关闭的文章不会注入提交地址,主题模板里要用 is defined 判断——这是给主题作者的注意项。

2.7 找回密码邮件收不到?

发信不在内核里,装并配置 mail-smtp 插件(随包自带)后才寄信:后台 → 插件 → mail-smtp → 设置,填 SMTP 服务器、端口、账号、授权码。配置存在 storage/.secrets/ 下,不进数据库。没配插件时,「找回密码」能生成链接但发不出去。收不到再看插件的日志与垃圾箱。

2.8 忘了管理员密码怎么办?

前提是 2.7 的邮件能发:登录页点「找回密码」,填管理员邮箱,收信点链接重置。邮件发不了的情况下,只能进数据库改——问懂行的人帮忙,或用备份恢复。平时把管理员邮箱配好、邮件插件装上,就不至于走这步。

2.9 误删了文章/页面能找回来吗?

删除的内容先进回收站(storage/trash/),后台可恢复;彻底删除后才真没了。重要改动前建议先在「工具 → 备份」打个全站备份,备份包含整库加全部文件,可随时恢复。

2.10 网站搬家或恢复备份怎么做?

后台「工具 → 备份」生成全站备份包并下载;新机器装好墨林(同版本),用恢复功能导入该包即可,域名不同改「设置」里的站点地址。「工具 → 导入与导出」则是另一回事:那是文章数据的导出导入(也支持从 WordPress 迁移,装 molin-wp-import 插件),不是整站恢复。

2.11 页面改了没生效/样式还是旧的?

三层缓存:页面缓存、Twig 模板缓存、浏览器缓存。后台「工具」里「清理缓存」一次清掉数据缓存与页面缓存;改过主题模板文件的话同一次操作也会重编模板;浏览器端硬刷新(Ctrl+F5)一遍。主题静态资源的地址自带版本号,文件一改自动变,不赖缓存。

2.12 站还在试写,不想让搜索引擎收录?

安装向导「站点」那一步有「搜索引擎可见」勾选项,默认勾选;不勾的话 robots.txt 整站谢客、sitemap 不输出,适合还在试写的站点。这个开关目前只在安装时设,装完想改要进数据库改 blog_public(1 = 公开,0 = 关);要"临时维护不给任何人看",在 nginx 层给全站加 403 更直接——程序没有内置维护模式。

三、主题与插件

3.1 主题/插件包上传被拒?

看拒收提示,常见三种:清单字段缺或错(name 与目录名不一致、settings 缺 default、hooks 声明不合法);包超限(主题 ≤ 5 MB、文件数 ≤ 2000;插件 ≤ 32 MB,解压后 ≤ 256 MB);包内带了脚本文件(主题包禁一切 .php/.py/.sh 等脚本;插件包允许自己的 php,但不许路径穿越)。逐条对上再传。

3.2 插件装上了但功能没生效?

九成是钩子声明问题:插件靠懒加载,只在 plugin.json 的 hooks 声明过的钩子被触发时才载入代码,漏声明的回调永远不会执行,而且不报错。开发模式(站点调试开着)下不一致会直接抛异常;生产模式记 WARNING 日志。自查方法:对照插件代码里每个 add_action/add_filter 的钩子名,确认清单 hooks 里都写了;不想逐个写可以声明 "hooks": ["*"] 全量加载,牺牲一点性能。

3.3 想改主题外观,直接改文件吗?

两说:改配色、开关、内容宽度这类,走后台「外观 → 主题设置」,主题声明了什么就能调什么;改版式、加功能,不要直接改正在用的主题文件——升级会被覆盖。正确做法是建子主题:目录里放一个 theme.json(parent 指向原主题),把要改的模板抄进去改。注意当前子主题没有跨主题的 {% extends %},改哪页就把那页整份抄过来。

3.4 页面模板下拉里没有我的模板?

主题模板文件开头第一行必须是 {# molin:template 显示名 #},标记必须在文件最开头(上方有别的注释就不识别),显示名留空等于没声明;只扫 templates/ 这一层。另外主题没声明任何页面模板时,这个下拉整个不出现——不是出了故障。

3.5 升级主题后新页面模板没出现?

主题升级靠版本号判断"有没有新版":theme.json 的 version 没升,升级通道认为没变化,新增文件送不到老站点。作者发新版必须随内容升 version;站长这边确认包里 version 确实变了再升级。

3.6 市场在哪?插件去哪找?

内置市场尚未开张,当前分发靠 zip 互传与官方站点下载页。后台「插件 → 上传插件」选 zip 安装;升级=传同名的新版包,版本号必须严格更高,不许同版本重装或降级。

四、更新与维护

4.1 怎么升级程序?

后台「设置 → 更新」里一键升级,流程九步:检查更新 → 前置体检 → 备份(默认不勾,可手动勾上)→ 进入维护模式(对外 503,仅管理员可访问)→ 下载+校验(核对 sha256 与签名)→ 替换文件(旧文件保留为 .bak)→ 执行迁移 → 体检+清缓存 → 退出维护模式(失败自动回滚)。更新源是官方带签名的清单,签名不对直接拒装;当前官方只开开发版一条通道。也可以手动:下载新版安装包覆盖前,务必备份。

4.2 升级会丢我的数据和设置吗?

正常不会。升级不覆盖站点上已有的主题文件(只补新增的)、不动数据库结构之外的数据、主题设置与插件配置都保留。升级流程里「备份」这一步默认跳过、可以勾上;想稳就勾它——出问题用对应版本的备份包回滚。

4.3 备份怎么配?放哪?

后台「工具 → 备份」手动打全站包;远端备份(传对象存储)要装对应支持并填凭据,凭据加密存放。备份包在 storage/backups/ 下,文件名带随机串不可猜,但记住 1.4 的规则:/storage/ 整段必须拦成 404,备份别只靠文件名保密。定期把备份下载到本机一份,别全留在服务器上。

4.4 网站被刷、想限制访问频率怎么办?

墨林自带:登录限速(5 次锁 15 分钟)、评论反垃圾钩子(可装验证码插件如 zaxu-captcha)。更上层的限流在 nginx 做(如 limit_req),或上你机房/CDN 的防护。程序日志能帮你确认是谁在刷:storage/logs/ 按天记。

4.5 站点速度慢,从哪下手?

按收益排:确认 PHP 装了 opcache(推荐扩展之一);nginx 直发 /uploads/ 与 /themes/ 静态文件(见安装说明「可选」两段);页面缓存默认就开着(匿名访客命中缓存不进 PHP),别动它,改版式后内容没变先去「工具 → 清理缓存」;图片压缩可装 molin-image-optimize 插件。想整体关缓存(调试时),在 config.php 加 'cache' => ['backend' => 'null']。前三条配完,大多数站就够了。

五、内容与功能

5.1 固定链接怎么选?改了会不会断链?

「设置 → 固定链接」里选样式,默认 /%postname%/。改结构只影响之后的文章地址吗——不,影响所有文章地址,搜索引擎与外链会断。老站改动要慎重,改完确认 sitemap.xml 已更新并提交搜索引擎。新站随便选,选好就别频繁动。

5.2 RSS 与站点地图在哪?要配吗?

自带,不用配:/feed(RSS,另有 /feed/atom)、/sitemap.xml、/robots.txt 都是自动的。搜索引擎收录提交 sitemap.xml 即可。RSS 输出的是已发布内容,草稿与私密内容不会进。

5.3 多语言站点怎么做?

内核带 i18n 基建(界面语言 zh-Hans / zh-Hant / en),主题用 html_lang() 输出语言标签。内容层面做多语言文章,当前要靠自定义内容类型或插件规划,内核没有内置"一篇文章多语言版本"的关联功能——有这需求先在交流渠道提。

5.4 怎么从 WordPress 搬过来?

装 molin-wp-import 插件(官方插件,后台 → 工具 → 导入):把 WordPress 导出的 WXR(.xml)传进去,分四步完成作者映射、分类层级、文章与页面、嵌套评论、附件与正文配图,跑完给前后对照报告。搬完抽查几篇文章的图片与评论,再切正式域名。

5.5 想加统计代码/广告位加在哪?

不动主题文件的办法:装插件挂 theme/head/render 或 theme/footer/render 钩子输出(内核汇总进 head_output / footer_output,主题模板原样输出变量)。或者主题设置了 code 类字段的主题,直接在后台主题设置里贴。改主题文件的办法见 3.3 的子主题。

出问题时总的原则:先看 storage/logs/ 当天的日志,再看后台「工具 → 健康」的环境自检;还是定位不了,带上「做了什么操作 + 日志相关段落」去官方交流渠道问,比只发一句"打不开了"快得多。

*墨林 - Molinink · 作者 Kira · https://www.molinink.com*