INSTALL GUIDE

木漏茶室安装教程

从源码下载中心下载「完整源码 ZIP」,按你的主机环境选择对应步骤。安装程序会引导完成数据库、管理员和站点信息;install.php 会永久保留,请不要手动删除。

当前站点 v6.25.232 · 适用于 PHP 7.4~8.3

〇、安装前准备

先确认你下载的是完整源码包,不是系统升级包。完整源码包里有 index.php、inc/、assets/ 和 install.php;升级包只用于已经装好的站点升级,不能拿来全新安装。

下载入口:源码下载中心 →「打包下载完整最新源码 ZIP」。下载后先在电脑上解压检查:新版源码包不会再多套一层 komorebi-forum/ 文件夹,index.php 和 install.php 会直接位于解压目录第一层。

环境要求

项目要求
PHP7.4 / 8.0 / 8.1 / 8.2 / 8.3,推荐 8.1 或 8.2
数据库SQLite(默认,免配置)或 MySQL 5.7+ / MariaDB 10.2+
必需扩展pdo、pdo_sqlite 或 pdo_mysql、mbstring、json、session、fileinfo
推荐扩展curl、gd、zip、openssl、xml
目录权限data/、storage/、uploads/ 可写;安装时网站根目录也要可写,用来生成 config.php
Web 服务器Apache / Nginx / 宝塔 / 虚拟主机面板均可

不需要伪静态

木漏茶室的所有页面都走 index.php?page=xxx,不需要配置伪静态规则。站点放在域名根目录或 bbs/ 子目录都可以,程序会自动识别访问路径。

第一次安装建议先用 SQLite:不用建库、不用填数据库账号,安装程序会在 data/komorebi.sqlite 自动生成数据库。虚拟主机和轻量云服务器都适合。需要多人同时大量写入、或主机只提供 MySQL 时,再选 MySQL。

一、虚拟主机安装

适合没有 SSH、只能通过主机控制面板管理文件的环境。下面以常见「PHP 虚拟主机 / 香港主机 / 宝塔以外的面板」为例,具体按钮名称可能略有不同。

第 1 步:选择 PHP 版本和扩展

  1. 进入主机面板的「PHP 设置 / PHP 版本」,选择 PHP 8.1;没有 8.1 时选 8.0 或 8.2,最低 7.4。
  2. 在「PHP 扩展」中确认启用:pdo、pdo_sqlite(用 SQLite 时)、pdo_mysql(用 MySQL 时)、mbstring、fileinfo、zip、curl、gd。
  3. 把 upload_max_filesize 调到 1000M,post_max_size 调到 1100M;如果面板没有这么大的上限,按主机允许的最大值设置,安装完成后仍可在后台单独限制附件大小。
  4. 把 display_errors 设为 Off,避免报错暴露路径;安装调试时可临时打开。

第 2 步:准备数据库(可选)

选 SQLite 可跳过这一步。选 MySQL 时,在主机面板「数据库」中新建数据库,记录下面四项:

数据库主机常见是 localhost,部分主机给的是 127.0.0.1 或独立数据库地址
端口一般是 3306,面板有单独端口时按面板填写
数据库名 / 用户名面板通常会带主机前缀,必须完整复制
数据库密码新库的密码;不要用主机登录密码代替
如果面板不允许程序自动建库,先在面板把库和用户建好,再到安装向导里填写。安装向导里的「表前缀」可以留空。

第 3 步:上传并解压源码

  1. 进入主机面板的「文件管理 / 在线文件」,打开网站根目录。常见名称是 wwwroot、public_html、htdocs 或 web。
  2. 上传完整源码 ZIP 到该目录,点击「解压」。解压后检查:根目录下必须能直接看到 index.php、install.php、inc/、assets/。
  3. 新版源码包解压后不会多出一层文件夹;如果使用的是旧包并看到 komorebi-forum/,进入这一层,把里面的全部文件移动到网站根目录,再删除空文件夹。
  4. 不要覆盖或上传旧站点的 config.php、data/、uploads/、storage/。全新安装只需要源码文件。
新版源码包上传解压后,网站根目录必须能直接看到 index.php 和 install.php。不要把源码放进 public_html/komorebi-forum/ 后却访问域名根目录,否则会 404。

第 4 步:设置目录权限

  1. 把 data/、storage/、uploads/ 设为可写:目录 755,主机要求更宽时用 777;文件 644。
  2. 安装时网站根目录需要可写,用来生成 config.php;如果面板默认根目录只读,临时改为 755/777。
  3. 安装成功后把网站根目录恢复为 755,config.php 设为 644,只保留 data/、storage/、uploads/ 可写。

第 5 步:访问安装向导

浏览器打开:https://你的域名/install.php。如果站点在子目录,打开 https://你的域名/子目录/install.php。

  1. 先阅读使用协议,勾选同意后进入下一步。
  2. 数据库选择:建议直接选 SQLite;选 MySQL 则填写第 2 步记录的数据库信息,点击「下一步 · 验证数据库」。
  3. 填写管理员用户名、前台昵称、密码(至少 6 位)。这个账号是超级管理员,拥有全部后台权限。
  4. 填写站点名称、站点介绍,点击「开始安装」。
  5. 看到「安装完成」后,当前浏览器会自动登录刚创建的管理员账号。点「进入论坛首页」或「进入后台」即可。

第 6 步:确认安装入口并收尾

  1. 按站长设置,install.php 会永久保留,系统不会自动删除。
  2. 确认根目录仍有 install.php;再次访问 /install.php 应显示安装已完成提示。不要手动删除,否则 index.php 在未安装或配置丢失时会跳转到 404。
  3. 在主机面板开启 SSL(免费 Let's Encrypt 或面板自带证书),并把 HTTP 跳转到 HTTPS。
  4. 后台入口:https://你的域名/index.php?page=admin,也可以从首页右上角「管理」或底部「后台」进入。
虚拟主机常见限制:不能自动建 MySQL 库、PHP 版本不能切换、zip 扩展未开、根目录不可写。遇到这些情况先联系主机商,或在面板里切换到支持的环境,不要直接改源码绕过检查。

二、云服务器安装

适合有 SSH 的 VPS / 云服务器。下面以 Ubuntu 22.04 + Nginx + PHP 8.1 + MySQL 8.0 为例;Debian 12、CentOS / AlmaLinux 思路相同,只是包名和 PHP-FPM 服务名不同。

第 1 步:准备域名和服务器

  1. 把域名 A 记录解析到服务器公网 IP;等解析生效后再申请 SSL。
  2. 在云厂商安全组放行 22(SSH)、80(HTTP)、443(HTTPS);不要放行数据库 3306 到公网。
  3. 用 SSH 登录服务器,确认有 sudo 或 root 权限。

第 2 步:安装 Nginx、PHP 和 MySQL

Ubuntu 22.04 自带 PHP 8.1,执行:

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
如果你用 PHP 8.2/8.3,把上面的 php8.1-* 换成对应版本,并把后面 Nginx 配置里的 php8.1-fpm.sock 换成实际版本。只装 MySQL 时也要装 php8.x-mysql;只用 SQLite 则必须装 php8.x-sqlite3。

第 3 步:创建数据库(可选)

用 SQLite 可以跳过。用 MySQL 时执行:

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;

安装向导里数据库主机填 localhost,端口 3306,数据库名、用户名、密码对应上面的值。

第 4 步:上传源码并解压

在服务器上创建网站目录,把完整源码 ZIP 上传进去:

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

解压后确认 /www/wwwroot/komorebi/index.php 和 /www/wwwroot/komorebi/install.php 存在。如果多了一层目录,把里面的文件移动到网站根目录。

sudo chmod -R 755 /www/wwwroot/komorebi
sudo chmod -R 755 /www/wwwroot/komorebi/data \
  /www/wwwroot/komorebi/storage /www/wwwroot/komorebi/uploads
安装程序需要网站根目录可写来生成 config.php。目录属于 www-data 且权限为 755 时,PHP-FPM 以 www-data 运行即可写入。

第 5 步:配置 Nginx 站点

新建 /etc/nginx/sites-available/komorebi,写入下面的配置。把 bbs.example.com 换成你的域名:

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;
    }
}

启用站点并检查配置:

sudo ln -s /etc/nginx/sites-available/komorebi /etc/nginx/sites-enabled/komorebi
sudo nginx -t
sudo systemctl reload nginx

本项目不需要伪静态;上面的 try_files 只负责静态文件,所有页面仍然是 index.php?page=xxx。

第 6 步:调整 PHP 上传限制

编辑 /etc/php/8.1/fpm/php.ini,确认或修改:

upload_max_filesize = 1000M
post_max_size = 1100M
max_execution_time = 300
memory_limit = 256M
display_errors = Off
date.timezone = Asia/Shanghai

保存后重启 PHP-FPM:

sudo systemctl restart php8.1-fpm

第 7 步:申请 HTTPS

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d bbs.example.com

按提示选择自动跳转 HTTPS。证书会自动续期,可用 sudo certbot renew --dry-run 检查。

第 8 步:安装并保留入口

  1. 浏览器打开 https://bbs.example.com/install.php。
  2. 选 SQLite 或 MySQL,填写管理员和站点信息,完成安装。
  3. install.php 永久保留,不要执行删除命令;完成页不会提供删除入口。
  4. 把根目录恢复为 755,确认 config.php 为 644。

云服务器备份建议

# 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
不要把 config.php、数据库文件、备份包放进网站根目录的可公开访问路径。备份建议放在服务器非 Web 目录,并定期下载到本地。

三、宝塔面板安装

宝塔适合不熟悉命令行的用户。下面从安装面板到上线,按顺序操作;面板版本不同,按钮名称可能略有差异。

第 1 步:安装宝塔面板

  1. 准备一台全新或干净的 Linux 云服务器,建议 Ubuntu 22.04 / Debian 12 / CentOS 7+,至少 1 核 2G 内存、20G 磁盘。
  2. 到宝塔官网下载页获取对应系统的安装命令,用 SSH 以 root 执行。安装完成后记下面板地址、用户名和密码。
  3. 在云厂商安全组放行宝塔面板端口(安装完成时会提示,常见是 8888 或自定义端口),以及 80、443。安装完成后建议在面板「安全」中修改默认面板端口并开启面板 SSL。

第 2 步:安装运行环境

  1. 登录宝塔面板,进入「软件商店」,安装 Nginx 1.22+、MySQL 5.7/8.0(用 SQLite 可不装 MySQL)、PHP 8.1。
  2. 点 PHP 8.1 的「设置」→「安装扩展」,安装 fileinfo、mbstring、pdo_mysql、sqlite3、zip、curl、gd。
  3. 在 PHP 设置 →「配置修改」中确认:upload_max_filesize=1000M、post_max_size=1100M、max_execution_time=300、memory_limit=256M;保存后重载 PHP。

第 3 步:添加站点和数据库

  1. 「网站」→「添加站点」:填写已解析到服务器的域名;根目录例如 /www/wwwroot/bbs.example.com;PHP 版本选 8.1;数据库选 MySQL(或稍后选 SQLite)。
  2. 如果创建 MySQL,记下宝塔生成的数据库名、用户名、密码;主机填 localhost,端口 3306。
  3. 不需要设置伪静态。宝塔默认的 Nginx 配置即可运行 index.php?page=xxx;如果面板提示伪静态,选择「无」或留空。

第 4 步:上传并解压源码

  1. 「文件」进入站点根目录,上传完整源码 ZIP。
  2. 右键压缩包 →「解压」。解压后确保 index.php、install.php 直接位于站点根目录。
  3. 如果多出一层文件夹,进入该文件夹全选文件,剪切到站点根目录,再删除空目录。
  4. 检查「网站目录」:运行目录必须是包含 index.php 的那一层;不要误把运行目录设成 public 或子文件夹。

第 5 步:设置权限和防跨站

  1. 在文件管理器选中站点根目录,设置「权限」为 755,「所属用户」为 www;data/、storage/、uploads/ 设为可写。
  2. 安装时根目录需要可写来生成 config.php;安装完成后把根目录恢复为 755,config.php 设为 644。
  3. 如果出现 500 或「open_basedir 限制」,在站点设置 →「网站目录」里检查「防跨站攻击(open_basedir)」;确认站点根目录和临时目录都在允许范围内,或临时关闭后再安装,装完按需开启。

第 6 步:开启 HTTPS

  1. 站点设置 →「SSL」→「Let's Encrypt」,勾选域名申请免费证书。
  2. 申请成功后打开「强制 HTTPS」,再访问一次 https://你的域名/install.php 确认证书正常。

第 7 步:安装并保留入口

  1. 打开 https://你的域名/install.php,按向导选择 SQLite 或 MySQL,填写管理员和站点信息。
  2. install.php 会永久保留,系统不会自动删除;如需保留安装入口,无需额外操作。
  3. 再次访问 /install.php 应显示安装已完成提示;确认首页、后台、发帖、上传都正常。

宝塔收尾建议

  • 在「计划任务」添加每日备份:备份站点目录 + 数据库,保留 7~30 天,并定期下载到本地。
  • 在「安全」中只放行 80、443 和你的 SSH / 面板端口;不要对公网开放 3306。
  • 后台「站点设置」中配置文件上传上限、SMTP 邮件和站点 Logo;这些是应用层设置,和 PHP 的 upload_max_filesize 是两回事。

四、通用安装流程(三种环境都一样)

  1. 访问 install.php:打开 https://你的域名/install.php;子目录安装则加上子目录路径。
  2. 同意使用协议:阅读后勾选同意,进入环境检测。
  3. 选择数据库:SQLite 直接下一步;MySQL 填主机、端口、库名、用户名、密码,表前缀可留空。
  4. 创建管理员:用户名 2~20 位,昵称是前台显示名,密码至少 6 位;该账号是超级管理员。
  5. 填写站点信息:站点名称、介绍;完成后自动登录管理员账号。
  6. 保留 install.php:按站长设置永久保留,不要手动删除;安装入口如需限制请使用主机密码保护。
安装向导里的「格式化数据库」只会在你主动勾选时清空已有论坛数据表。全新安装不要勾选;重装前请先备份 config.php、data/、uploads/、storage/。

五、装完必做

保留 install.php按站长设置永久保留,系统不会自动删除;不要手动删除,否则配置丢失时首页会跳转到 404。
恢复目录权限根目录 755,config.php 644;只保留 data/、storage/、uploads/ 可写。
开启 HTTPS登录、后台和上传都走 HTTPS;开启后把站点地址统一到 https。
设置上传上限PHP 的 upload_max_filesize / post_max_size 与后台附件上限要匹配。
配置邮件QQ 邮箱用授权码,465 端口选 SSL、587 端口选 TLS;部分主机封 25 端口。
建立备份备份 config.php、data/(SQLite)、uploads/、storage/;MySQL 另导数据库。

后台入口

https://你的域名/index.php?page=admin,或首页右上角「管理」/ 底部导航「后台」。首次进入后建议在「账号设置」检查管理员邮箱和管理员保护锁,在「站点设置」完善站点名称、Logo、SEO 和 SMTP。

迁移和换域名

程序按当前访问地址自动推导站点路径,换域名或换子目录不需要改配置。迁移时把 config.php、data/(SQLite)、uploads/、storage/ 一起打包;MySQL 站点先导出数据库再导入新库。迁移后如登录态异常,清除浏览器 Cookie 重新登录。

六、常见报错

现象原因与处理
/install.php 404文件不在网站根目录、解压多了一层文件夹、域名绑定的目录不对。检查根目录是否有 install.php;子目录安装要访问子目录路径。
页面空白或 500PHP 版本低于 7.4、缺少 pdo/mbstring/fileinfo 扩展、目录权限不对。查看主机错误日志或临时打开 display_errors。
「data 目录不可写」把 data/ 设为 755/777,文件所有者与 PHP 运行用户一致;云服务器用 chown -R www-data:www-data,宝塔用 www。
SQLite 无法使用PHP 未启用 pdo_sqlite。在面板 PHP 扩展中勾选,或安装 php8.x-sqlite3 后重启 PHP-FPM。
MySQL 连接失败库未创建、用户名/密码不对、主机填错(localhost / 127.0.0.1)、用户没有该库权限,或端口不是 3306。
上传大文件 413 / 失败调大 Nginx 的 client_max_body_size、PHP 的 upload_max_filesize 和 post_max_size;确认 uploads/ 可写、磁盘空间足够。
源码打包下载报错PHP 未启用 zip 扩展;在面板扩展中开启后重试。
后台登录后马上退出Cookie 域/HTTPS 配置不一致、session 目录不可写。统一使用一个域名和 HTTPS,清除旧 Cookie 后重登。
宝塔提示 open_basedir站点根目录、临时目录不在允许路径。检查「网站目录」和防跨站设置,或临时关闭防跨站完成安装。
伪静态相关 404本项目不需要伪静态。清空伪静态规则,确保 Nginx 正常把 index.php 交给 PHP-FPM。
排查顺序:先确认 PHP 版本和扩展,再确认目录权限与网站根目录,最后看 Web 服务器错误日志。不要为了绕过检查直接修改安装程序或关闭全部安全设置。
主题