木漏茶室源码下载中心
整站 PHP 源码:可浏览文件、复制路径、下载单文件或打包 ZIP。
发布版本 v6.25.231
升级后自动生成独立源码包,下载中心只发送这份冻结包
已排除 config.php / 用户数据 / 上传文件 / 升级备份
COMMUNITY DEPLOYMENTS
已经跑起来的木漏茶室
从源码下载中心下载、完成安装并回传验证的站外站点。每个站点只计 1 次部署下载量;已记录站点会实时读取名称、版本、Logo 与在线状态,本机、内网和证书异常站点无法完成回传。
实时检测
2
个站点已部署
木
木漏茶室
mlcs.xnn.lol · v6.25.232
访问 ↗
2026.11.21
在线
木
木漏茶室
mlcs.nbnb.mom · v6.25.231
访问 ↗
2026.11.20
在线
已展示全部 2 个站点。
pages/install_guide.php
26.7 KB · 发布包 v6.25.231
<?php
/**
* 源码下载中心 · 安装教程:虚拟主机 / 云服务器 / 宝塔面板
*/
if (site_upgrade_host_restricted()) {
http_response_code(404);
render_header('页面不存在');
echo '<section class="auth-wrap"><div class="auth-card"><h1>页面不存在</h1><p class="muted">本站未开放源码下载中心。</p></div></section>';
render_footer();
exit;
}
$GLOBALS['PAGE'] = 'install_guide';
render_header('安装教程');
?>
<section class="ext-hero small tutorial-hero">
<span class="hero-kicker">INSTALL GUIDE</span>
<h1>木漏茶室安装教程</h1>
<p>从源码下载中心下载「完整源码 ZIP」,按你的主机环境选择对应步骤。安装程序会引导完成数据库、管理员和站点信息;<code>install.php</code> 会永久保留,请不要手动删除。</p>
<div class="source-actions" style="margin-top:12px;justify-content:flex-start">
<a class="btn-mini" href="<?= e(page_url('source', ['act' => 'zip'])) ?>">打包下载完整源码 ZIP</a>
<a class="btn-mini ghost" href="<?= e(page_url('source')) ?>">返回源码下载中心</a>
</div>
<span class="tutorial-updated">当前站点 v<?= e(APP_VERSION) ?> · 适用于 PHP 7.4~8.3</span>
</section>
<div class="tutorial-layout">
<nav class="tutorial-nav" aria-label="安装教程目录">
<a href="#prepare" class="on">〇、安装前准备</a>
<a href="#shared">一、虚拟主机</a>
<a href="#cloud">二、云服务器</a>
<a href="#bt">三、宝塔面板</a>
<a href="#common">四、通用安装流程</a>
<a href="#after">五、装完必做</a>
<a href="#errors">六、常见报错</a>
</nav>
<main class="tutorial-main install-guide">
<section class="tutorial-section" id="prepare">
<h2>〇、安装前准备</h2>
<p>先确认你下载的是<strong>完整源码包</strong>,不是系统升级包。完整源码包里有 <code>index.php</code>、<code>inc/</code>、<code>assets/</code> 和 <code>install.php</code>;升级包只用于已经装好的站点升级,不能拿来全新安装。</p>
<div class="tutorial-note">下载入口:源码下载中心 →「打包下载完整最新源码 ZIP」。下载后先在电脑上解压检查:新版源码包不会再多套一层 <code>komorebi-forum/</code> 文件夹,<code>index.php</code> 和 <code>install.php</code> 会直接位于解压目录第一层。</div>
<h3>环境要求</h3>
<table class="tutorial-table">
<tr><th>项目</th><th>要求</th></tr>
<tr><td>PHP</td><td>7.4 / 8.0 / 8.1 / 8.2 / 8.3,推荐 8.1 或 8.2</td></tr>
<tr><td>数据库</td><td>SQLite(默认,免配置)或 MySQL 5.7+ / MariaDB 10.2+</td></tr>
<tr><td>必需扩展</td><td><code>pdo</code>、<code>pdo_sqlite</code> 或 <code>pdo_mysql</code>、<code>mbstring</code>、<code>json</code>、<code>session</code>、<code>fileinfo</code></td></tr>
<tr><td>推荐扩展</td><td><code>curl</code>、<code>gd</code>、<code>zip</code>、<code>openssl</code>、<code>xml</code></td></tr>
<tr><td>目录权限</td><td><code>data/</code>、<code>storage/</code>、<code>uploads/</code> 可写;安装时网站根目录也要可写,用来生成 <code>config.php</code></td></tr>
<tr><td>Web 服务器</td><td>Apache / Nginx / 宝塔 / 虚拟主机面板均可</td></tr>
</table>
<h3>不需要伪静态</h3>
<p>木漏茶室的所有页面都走 <code>index.php?page=xxx</code>,不需要配置伪静态规则。站点放在域名根目录或 <code>bbs/</code> 子目录都可以,程序会自动识别访问路径。</p>
<div class="tutorial-tip">第一次安装建议先用 <strong>SQLite</strong>:不用建库、不用填数据库账号,安装程序会在 <code>data/komorebi.sqlite</code> 自动生成数据库。虚拟主机和轻量云服务器都适合。需要多人同时大量写入、或主机只提供 MySQL 时,再选 MySQL。</div>
</section>
<section class="tutorial-section" id="shared">
<h2>一、虚拟主机安装</h2>
<p>适合没有 SSH、只能通过主机控制面板管理文件的环境。下面以常见「PHP 虚拟主机 / 香港主机 / 宝塔以外的面板」为例,具体按钮名称可能略有不同。</p>
<h3>第 1 步:选择 PHP 版本和扩展</h3>
<ol class="tutorial-steps">
<li>进入主机面板的「PHP 设置 / PHP 版本」,选择 <strong>PHP 8.1</strong>;没有 8.1 时选 8.0 或 8.2,最低 7.4。</li>
<li>在「PHP 扩展」中确认启用:<code>pdo</code>、<code>pdo_sqlite</code>(用 SQLite 时)、<code>pdo_mysql</code>(用 MySQL 时)、<code>mbstring</code>、<code>fileinfo</code>、<code>zip</code>、<code>curl</code>、<code>gd</code>。</li>
<li>把 <code>upload_max_filesize</code> 调到 <strong>1000M</strong>,<code>post_max_size</code> 调到 <strong>1100M</code>;如果面板没有这么大的上限,按主机允许的最大值设置,安装完成后仍可在后台单独限制附件大小。</li>
<li>把 <code>display_errors</code> 设为 <strong>Off</strong>,避免报错暴露路径;安装调试时可临时打开。</li>
</ol>
<h3>第 2 步:准备数据库(可选)</h3>
<p>选 SQLite 可跳过这一步。选 MySQL 时,在主机面板「数据库」中新建数据库,记录下面四项:</p>
<div class="tutorial-check-grid">
<div><strong>数据库主机</strong><span>常见是 <code>localhost</code>,部分主机给的是 <code>127.0.0.1</code> 或独立数据库地址</span></div>
<div><strong>端口</strong><span>一般是 <code>3306</code>,面板有单独端口时按面板填写</span></div>
<div><strong>数据库名 / 用户名</strong><span>面板通常会带主机前缀,必须完整复制</span></div>
<div><strong>数据库密码</strong><span>新库的密码;不要用主机登录密码代替</span></div>
</div>
<div class="tutorial-tip">如果面板不允许程序自动建库,先在面板把库和用户建好,再到安装向导里填写。安装向导里的「表前缀」可以留空。</div>
<h3>第 3 步:上传并解压源码</h3>
<ol class="tutorial-steps">
<li>进入主机面板的「文件管理 / 在线文件」,打开网站根目录。常见名称是 <code>wwwroot</code>、<code>public_html</code>、<code>htdocs</code> 或 <code>web</code>。</li>
<li>上传完整源码 ZIP 到该目录,点击「解压」。解压后检查:根目录下必须能直接看到 <code>index.php</code>、<code>install.php</code>、<code>inc/</code>、<code>assets/</code>。</li>
<li>新版源码包解压后不会多出一层文件夹;如果使用的是旧包并看到 <code>komorebi-forum/</code>,进入这一层,把里面的全部文件移动到网站根目录,再删除空文件夹。</li>
<li>不要覆盖或上传旧站点的 <code>config.php</code>、<code>data/</code>、<code>uploads/</code>、<code>storage/</code>。全新安装只需要源码文件。</li>
</ol>
<div class="tutorial-danger">新版源码包上传解压后,网站根目录必须能直接看到 <code>index.php</code> 和 <code>install.php</code>。不要把源码放进 <code>public_html/komorebi-forum/</code> 后却访问域名根目录,否则会 404。</div>
<h3>第 4 步:设置目录权限</h3>
<ol class="tutorial-steps">
<li>把 <code>data/</code>、<code>storage/</code>、<code>uploads/</code> 设为可写:目录 <strong>755</strong>,主机要求更宽时用 <strong>777</strong>;文件 <strong>644</strong>。</li>
<li>安装时网站根目录需要可写,用来生成 <code>config.php</code>;如果面板默认根目录只读,临时改为 755/777。</li>
<li>安装成功后把网站根目录恢复为 <strong>755</strong>,<code>config.php</code> 设为 <strong>644</strong>,只保留 <code>data/</code>、<code>storage/</code>、<code>uploads/</code> 可写。</li>
</ol>
<h3>第 5 步:访问安装向导</h3>
<p>浏览器打开:<code>https://你的域名/install.php</code>。如果站点在子目录,打开 <code>https://你的域名/子目录/install.php</code>。</p>
<ol class="tutorial-steps">
<li>先阅读使用协议,勾选同意后进入下一步。</li>
<li>数据库选择:建议直接选 <strong>SQLite</strong>;选 MySQL 则填写第 2 步记录的数据库信息,点击「下一步 · 验证数据库」。</li>
<li>填写管理员用户名、前台昵称、密码(至少 6 位)。这个账号是超级管理员,拥有全部后台权限。</li>
<li>填写站点名称、站点介绍,点击「开始安装」。</li>
<li>看到「安装完成」后,当前浏览器会自动登录刚创建的管理员账号。点「进入论坛首页」或「进入后台」即可。</li>
</ol>
<h3>第 6 步:确认安装入口并收尾</h3>
<ol class="tutorial-steps">
<li>按站长设置,install.php 会永久保留,系统不会自动删除。</li>
<li>确认根目录仍有 <code>install.php</code>;再次访问 <code>/install.php</code> 应显示安装已完成提示。不要手动删除,否则 <code>index.php</code> 在未安装或配置丢失时会跳转到 404。</li>
<li>在主机面板开启 SSL(免费 Let's Encrypt 或面板自带证书),并把 HTTP 跳转到 HTTPS。</li>
<li>后台入口:<code>https://你的域名/index.php?page=admin</code>,也可以从首页右上角「管理」或底部「后台」进入。</li>
</ol>
<div class="tutorial-note">虚拟主机常见限制:不能自动建 MySQL 库、PHP 版本不能切换、<code>zip</code> 扩展未开、根目录不可写。遇到这些情况先联系主机商,或在面板里切换到支持的环境,不要直接改源码绕过检查。</div>
</section>
<section class="tutorial-section" id="cloud">
<h2>二、云服务器安装</h2>
<p>适合有 SSH 的 VPS / 云服务器。下面以 <strong>Ubuntu 22.04 + Nginx + PHP 8.1 + MySQL 8.0</strong> 为例;Debian 12、CentOS / AlmaLinux 思路相同,只是包名和 PHP-FPM 服务名不同。</p>
<h3>第 1 步:准备域名和服务器</h3>
<ol class="tutorial-steps">
<li>把域名 A 记录解析到服务器公网 IP;等解析生效后再申请 SSL。</li>
<li>在云厂商安全组放行 <strong>22(SSH)</strong>、<strong>80(HTTP)</strong>、<strong>443(HTTPS)</strong>;不要放行数据库 3306 到公网。</li>
<li>用 SSH 登录服务器,确认有 <code>sudo</code> 或 root 权限。</li>
</ol>
<h3>第 2 步:安装 Nginx、PHP 和 MySQL</h3>
<p>Ubuntu 22.04 自带 PHP 8.1,执行:</p>
<pre class="tutorial-code"><code>sudo apt update
sudo apt install -y nginx mysql-server unzip
sudo apt install -y php8.1-fpm php8.1-mysql php8.1-sqlite3 \
php8.1-mbstring php8.1-xml php8.1-curl php8.1-zip php8.1-gd
sudo systemctl enable --now nginx php8.1-fpm mysql</code></pre>
<div class="tutorial-tip">如果你用 PHP 8.2/8.3,把上面的 <code>php8.1-*</code> 换成对应版本,并把后面 Nginx 配置里的 <code>php8.1-fpm.sock</code> 换成实际版本。只装 MySQL 时也要装 <code>php8.x-mysql</code>;只用 SQLite 则必须装 <code>php8.x-sqlite3</code>。</div>
<h3>第 3 步:创建数据库(可选)</h3>
<p>用 SQLite 可以跳过。用 MySQL 时执行:</p>
<pre class="tutorial-code"><code>sudo mysql
CREATE DATABASE komorebi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'komorebi'@'localhost' IDENTIFIED BY '这里换成强密码';
GRANT ALL PRIVILEGES ON komorebi.* TO 'komorebi'@'localhost';
FLUSH PRIVILEGES;
EXIT;</code></pre>
<p>安装向导里数据库主机填 <code>localhost</code>,端口 <code>3306</code>,数据库名、用户名、密码对应上面的值。</p>
<h3>第 4 步:上传源码并解压</h3>
<p>在服务器上创建网站目录,把完整源码 ZIP 上传进去:</p>
<pre class="tutorial-code"><code>sudo mkdir -p /www/wwwroot/komorebi
sudo chown -R www-data:www-data /www/wwwroot/komorebi
# 在本地电脑执行,把压缩包传到服务器
scp komorebi-forum-v*.zip root@你的服务器IP:/tmp/
# 回到服务器执行
sudo unzip /tmp/komorebi-forum-v*.zip -d /www/wwwroot/komorebi
sudo chown -R www-data:www-data /www/wwwroot/komorebi</code></pre>
<p>解压后确认 <code>/www/wwwroot/komorebi/index.php</code> 和 <code>/www/wwwroot/komorebi/install.php</code> 存在。如果多了一层目录,把里面的文件移动到网站根目录。</p>
<pre class="tutorial-code"><code>sudo chmod -R 755 /www/wwwroot/komorebi
sudo chmod -R 755 /www/wwwroot/komorebi/data \
/www/wwwroot/komorebi/storage /www/wwwroot/komorebi/uploads</code></pre>
<div class="tutorial-note">安装程序需要网站根目录可写来生成 <code>config.php</code>。目录属于 <code>www-data</code> 且权限为 755 时,PHP-FPM 以 <code>www-data</code> 运行即可写入。</div>
<h3>第 5 步:配置 Nginx 站点</h3>
<p>新建 <code>/etc/nginx/sites-available/komorebi</code>,写入下面的配置。把 <code>bbs.example.com</code> 换成你的域名:</p>
<pre class="tutorial-code"><code>server {
listen 80;
server_name bbs.example.com;
root /www/wwwroot/komorebi;
index index.php index.html;
client_max_body_size 1100m;
location / {
try_files $uri $uri/ =404;
}
# 禁止直接访问配置、数据、缓存和源码包含目录
location ~ ^/(data|storage|inc|plugins|config\.php) {
deny all;
}
# 上传目录只允许静态文件,禁止执行 PHP
location ~* ^/uploads/.*\.(php|phtml|phar)$ {
deny all;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
}
}</code></pre>
<p>启用站点并检查配置:</p>
<pre class="tutorial-code"><code>sudo ln -s /etc/nginx/sites-available/komorebi /etc/nginx/sites-enabled/komorebi
sudo nginx -t
sudo systemctl reload nginx</code></pre>
<p>本项目不需要伪静态;上面的 <code>try_files</code> 只负责静态文件,所有页面仍然是 <code>index.php?page=xxx</code>。</p>
<h3>第 6 步:调整 PHP 上传限制</h3>
<p>编辑 <code>/etc/php/8.1/fpm/php.ini</code>,确认或修改:</p>
<pre class="tutorial-code"><code>upload_max_filesize = 1000M
post_max_size = 1100M
max_execution_time = 300
memory_limit = 256M
display_errors = Off
date.timezone = Asia/Shanghai</code></pre>
<p>保存后重启 PHP-FPM:</p>
<pre class="tutorial-code"><code>sudo systemctl restart php8.1-fpm</code></pre>
<h3>第 7 步:申请 HTTPS</h3>
<pre class="tutorial-code"><code>sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d bbs.example.com</code></pre>
<p>按提示选择自动跳转 HTTPS。证书会自动续期,可用 <code>sudo certbot renew --dry-run</code> 检查。</p>
<h3>第 8 步:安装并保留入口</h3>
<ol class="tutorial-steps">
<li>浏览器打开 <code>https://bbs.example.com/install.php</code>。</li>
<li>选 SQLite 或 MySQL,填写管理员和站点信息,完成安装。</li>
<li><code>install.php</code> 永久保留,不要执行删除命令;完成页不会提供删除入口。</li>
<li>把根目录恢复为 <code>755</code>,确认 <code>config.php</code> 为 <code>644</code>。</li>
</ol>
<h3>云服务器备份建议</h3>
<pre class="tutorial-code"><code># SQLite 模式:备份配置、数据库、上传和运行数据
sudo tar -czf /root/komorebi-backup-$(date +%F).tar.gz \
-C /www/wwwroot/komorebi config.php data uploads storage
# MySQL 模式:额外导出数据库
mysqldump -u komorebi -p komorebi > /root/komorebi-db-$(date +%F).sql</code></pre>
<div class="tutorial-danger">不要把 <code>config.php</code>、数据库文件、备份包放进网站根目录的可公开访问路径。备份建议放在服务器非 Web 目录,并定期下载到本地。</div>
</section>
<section class="tutorial-section" id="bt">
<h2>三、宝塔面板安装</h2>
<p>宝塔适合不熟悉命令行的用户。下面从安装面板到上线,按顺序操作;面板版本不同,按钮名称可能略有差异。</p>
<h3>第 1 步:安装宝塔面板</h3>
<ol class="tutorial-steps">
<li>准备一台全新或干净的 Linux 云服务器,建议 Ubuntu 22.04 / Debian 12 / CentOS 7+,至少 1 核 2G 内存、20G 磁盘。</li>
<li>到宝塔官网下载页获取对应系统的安装命令,用 SSH 以 root 执行。安装完成后记下面板地址、用户名和密码。</li>
<li>在云厂商安全组放行宝塔面板端口(安装完成时会提示,常见是 <code>8888</code> 或自定义端口),以及 <code>80</code>、<code>443</code>。安装完成后建议在面板「安全」中修改默认面板端口并开启面板 SSL。</li>
</ol>
<h3>第 2 步:安装运行环境</h3>
<ol class="tutorial-steps">
<li>登录宝塔面板,进入「软件商店」,安装 <strong>Nginx 1.22+</strong>、<strong>MySQL 5.7/8.0</strong>(用 SQLite 可不装 MySQL)、<strong>PHP 8.1</strong>。</li>
<li>点 PHP 8.1 的「设置」→「安装扩展」,安装 <code>fileinfo</code>、<code>mbstring</code>、<code>pdo_mysql</code>、<code>sqlite3</code>、<code>zip</code>、<code>curl</code>、<code>gd</code>。</li>
<li>在 PHP 设置 →「配置修改」中确认:<code>upload_max_filesize=1000M</code>、<code>post_max_size=1100M</code>、<code>max_execution_time=300</code>、<code>memory_limit=256M</code>;保存后重载 PHP。</li>
</ol>
<h3>第 3 步:添加站点和数据库</h3>
<ol class="tutorial-steps">
<li>「网站」→「添加站点」:填写已解析到服务器的域名;根目录例如 <code>/www/wwwroot/bbs.example.com</code>;PHP 版本选 8.1;数据库选 MySQL(或稍后选 SQLite)。</li>
<li>如果创建 MySQL,记下宝塔生成的数据库名、用户名、密码;主机填 <code>localhost</code>,端口 <code>3306</code>。</li>
<li>不需要设置伪静态。宝塔默认的 Nginx 配置即可运行 <code>index.php?page=xxx</code>;如果面板提示伪静态,选择「无」或留空。</li>
</ol>
<h3>第 4 步:上传并解压源码</h3>
<ol class="tutorial-steps">
<li>「文件」进入站点根目录,上传完整源码 ZIP。</li>
<li>右键压缩包 →「解压」。解压后确保 <code>index.php</code>、<code>install.php</code> 直接位于站点根目录。</li>
<li>如果多出一层文件夹,进入该文件夹全选文件,剪切到站点根目录,再删除空目录。</li>
<li>检查「网站目录」:运行目录必须是包含 <code>index.php</code> 的那一层;不要误把运行目录设成 <code>public</code> 或子文件夹。</li>
</ol>
<h3>第 5 步:设置权限和防跨站</h3>
<ol class="tutorial-steps">
<li>在文件管理器选中站点根目录,设置「权限」为 <strong>755</strong>,「所属用户」为 <strong>www</strong>;<code>data/</code>、<code>storage/</code>、<code>uploads/</code> 设为可写。</li>
<li>安装时根目录需要可写来生成 <code>config.php</code>;安装完成后把根目录恢复为 755,<code>config.php</code> 设为 644。</li>
<li>如果出现 500 或「open_basedir 限制」,在站点设置 →「网站目录」里检查「防跨站攻击(open_basedir)」;确认站点根目录和临时目录都在允许范围内,或临时关闭后再安装,装完按需开启。</li>
</ol>
<h3>第 6 步:开启 HTTPS</h3>
<ol class="tutorial-steps">
<li>站点设置 →「SSL」→「Let's Encrypt」,勾选域名申请免费证书。</li>
<li>申请成功后打开「强制 HTTPS」,再访问一次 <code>https://你的域名/install.php</code> 确认证书正常。</li>
</ol>
<h3>第 7 步:安装并保留入口</h3>
<ol class="tutorial-steps">
<li>打开 <code>https://你的域名/install.php</code>,按向导选择 SQLite 或 MySQL,填写管理员和站点信息。</li>
<li>install.php 会永久保留,系统不会自动删除;如需保留安装入口,无需额外操作。</li>
<li>再次访问 <code>/install.php</code> 应显示安装已完成提示;确认首页、后台、发帖、上传都正常。</li>
</ol>
<h3>宝塔收尾建议</h3>
<ul class="tutorial-steps">
<li>在「计划任务」添加每日备份:备份站点目录 + 数据库,保留 7~30 天,并定期下载到本地。</li>
<li>在「安全」中只放行 80、443 和你的 SSH / 面板端口;不要对公网开放 3306。</li>
<li>后台「站点设置」中配置文件上传上限、SMTP 邮件和站点 Logo;这些是应用层设置,和 PHP 的 <code>upload_max_filesize</code> 是两回事。</li>
</ul>
</section>
<section class="tutorial-section" id="common">
<h2>四、通用安装流程(三种环境都一样)</h2>
<ol class="tutorial-steps">
<li><strong>访问 install.php</strong>:打开 <code>https://你的域名/install.php</code>;子目录安装则加上子目录路径。</li>
<li><strong>同意使用协议</strong>:阅读后勾选同意,进入环境检测。</li>
<li><strong>选择数据库</strong>:SQLite 直接下一步;MySQL 填主机、端口、库名、用户名、密码,表前缀可留空。</li>
<li><strong>创建管理员</strong>:用户名 2~20 位,昵称是前台显示名,密码至少 6 位;该账号是超级管理员。</li>
<li><strong>填写站点信息</strong>:站点名称、介绍;完成后自动登录管理员账号。</li>
<li><strong>保留 install.php</strong>:按站长设置永久保留,不要手动删除;安装入口如需限制请使用主机密码保护。</li>
</ol>
<div class="tutorial-tip">安装向导里的「格式化数据库」只会在你主动勾选时清空已有论坛数据表。全新安装不要勾选;重装前请先备份 <code>config.php</code>、<code>data/</code>、<code>uploads/</code>、<code>storage/</code>。</div>
</section>
<section class="tutorial-section" id="after">
<h2>五、装完必做</h2>
<div class="tutorial-check-grid">
<div><strong>保留 install.php</strong><span>按站长设置永久保留,系统不会自动删除;不要手动删除,否则配置丢失时首页会跳转到 404。</span></div>
<div><strong>恢复目录权限</strong><span>根目录 755,<code>config.php</code> 644;只保留 <code>data/</code>、<code>storage/</code>、<code>uploads/</code> 可写。</span></div>
<div><strong>开启 HTTPS</strong><span>登录、后台和上传都走 HTTPS;开启后把站点地址统一到 https。</span></div>
<div><strong>设置上传上限</strong><span>PHP 的 <code>upload_max_filesize</code> / <code>post_max_size</code> 与后台附件上限要匹配。</span></div>
<div><strong>配置邮件</strong><span>QQ 邮箱用授权码,465 端口选 SSL、587 端口选 TLS;部分主机封 25 端口。</span></div>
<div><strong>建立备份</strong><span>备份 <code>config.php</code>、<code>data/</code>(SQLite)、<code>uploads/</code>、<code>storage/</code>;MySQL 另导数据库。</span></div>
</div>
<h3>后台入口</h3>
<p><code>https://你的域名/index.php?page=admin</code>,或首页右上角「管理」/ 底部导航「后台」。首次进入后建议在「账号设置」检查管理员邮箱和管理员保护锁,在「站点设置」完善站点名称、Logo、SEO 和 SMTP。</p>
<h3>迁移和换域名</h3>
<p>程序按当前访问地址自动推导站点路径,换域名或换子目录不需要改配置。迁移时把 <code>config.php</code>、<code>data/</code>(SQLite)、<code>uploads/</code>、<code>storage/</code> 一起打包;MySQL 站点先导出数据库再导入新库。迁移后如登录态异常,清除浏览器 Cookie 重新登录。</p>
</section>
<section class="tutorial-section" id="errors">
<h2>六、常见报错</h2>
<table class="tutorial-table">
<tr><th>现象</th><th>原因与处理</th></tr>
<tr><td><code>/install.php</code> 404</td><td>文件不在网站根目录、解压多了一层文件夹、域名绑定的目录不对。检查根目录是否有 <code>install.php</code>;子目录安装要访问子目录路径。</td></tr>
<tr><td>页面空白或 500</td><td>PHP 版本低于 7.4、缺少 <code>pdo</code>/<code>mbstring</code>/<code>fileinfo</code> 扩展、目录权限不对。查看主机错误日志或临时打开 <code>display_errors</code>。</td></tr>
<tr><td>「data 目录不可写」</td><td>把 <code>data/</code> 设为 755/777,文件所有者与 PHP 运行用户一致;云服务器用 <code>chown -R www-data:www-data</code>,宝塔用 <code>www</code>。</td></tr>
<tr><td>SQLite 无法使用</td><td>PHP 未启用 <code>pdo_sqlite</code>。在面板 PHP 扩展中勾选,或安装 <code>php8.x-sqlite3</code> 后重启 PHP-FPM。</td></tr>
<tr><td>MySQL 连接失败</td><td>库未创建、用户名/密码不对、主机填错(<code>localhost</code> / <code>127.0.0.1</code>)、用户没有该库权限,或端口不是 3306。</td></tr>
<tr><td>上传大文件 413 / 失败</td><td>调大 Nginx 的 <code>client_max_body_size</code>、PHP 的 <code>upload_max_filesize</code> 和 <code>post_max_size</code>;确认 <code>uploads/</code> 可写、磁盘空间足够。</td></tr>
<tr><td>源码打包下载报错</td><td>PHP 未启用 <code>zip</code> 扩展;在面板扩展中开启后重试。</td></tr>
<tr><td>后台登录后马上退出</td><td>Cookie 域/HTTPS 配置不一致、<code>session</code> 目录不可写。统一使用一个域名和 HTTPS,清除旧 Cookie 后重登。</td></tr>
<tr><td>宝塔提示 open_basedir</td><td>站点根目录、临时目录不在允许路径。检查「网站目录」和防跨站设置,或临时关闭防跨站完成安装。</td></tr>
<tr><td>伪静态相关 404</td><td>本项目不需要伪静态。清空伪静态规则,确保 Nginx 正常把 <code>index.php</code> 交给 PHP-FPM。</td></tr>
</table>
<div class="tutorial-note">排查顺序:先确认 PHP 版本和扩展,再确认目录权限与网站根目录,最后看 Web 服务器错误日志。不要为了绕过检查直接修改安装程序或关闭全部安全设置。</div>
</section>
</main>
</div>
<?php render_footer(); ?>