木漏茶室安装教程
从源码下载中心下载「完整源码 ZIP」,按你的主机环境选择对应步骤。安装程序会引导完成数据库、管理员和站点信息;install.php 会永久保留,请不要手动删除。
〇、安装前准备
先确认你下载的是完整源码包,不是系统升级包。完整源码包里有 index.php、inc/、assets/ 和 install.php;升级包只用于已经装好的站点升级,不能拿来全新安装。
komorebi-forum/ 文件夹,index.php 和 install.php 会直接位于解压目录第一层。环境要求
| 项目 | 要求 |
|---|---|
| PHP | 7.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/ 子目录都可以,程序会自动识别访问路径。
data/komorebi.sqlite 自动生成数据库。虚拟主机和轻量云服务器都适合。需要多人同时大量写入、或主机只提供 MySQL 时,再选 MySQL。二、云服务器安装
适合有 SSH 的 VPS / 云服务器。下面以 Ubuntu 22.04 + Nginx + PHP 8.1 + MySQL 8.0 为例;Debian 12、CentOS / AlmaLinux 思路相同,只是包名和 PHP-FPM 服务名不同。
第 1 步:准备域名和服务器
- 把域名 A 记录解析到服务器公网 IP;等解析生效后再申请 SSL。
- 在云厂商安全组放行 22(SSH)、80(HTTP)、443(HTTPS);不要放行数据库 3306 到公网。
- 用 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
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 步:安装并保留入口
- 浏览器打开
https://bbs.example.com/install.php。 - 选 SQLite 或 MySQL,填写管理员和站点信息,完成安装。
install.php永久保留,不要执行删除命令;完成页不会提供删除入口。- 把根目录恢复为
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 步:安装宝塔面板
- 准备一台全新或干净的 Linux 云服务器,建议 Ubuntu 22.04 / Debian 12 / CentOS 7+,至少 1 核 2G 内存、20G 磁盘。
- 到宝塔官网下载页获取对应系统的安装命令,用 SSH 以 root 执行。安装完成后记下面板地址、用户名和密码。
- 在云厂商安全组放行宝塔面板端口(安装完成时会提示,常见是
8888或自定义端口),以及80、443。安装完成后建议在面板「安全」中修改默认面板端口并开启面板 SSL。
第 2 步:安装运行环境
- 登录宝塔面板,进入「软件商店」,安装 Nginx 1.22+、MySQL 5.7/8.0(用 SQLite 可不装 MySQL)、PHP 8.1。
- 点 PHP 8.1 的「设置」→「安装扩展」,安装
fileinfo、mbstring、pdo_mysql、sqlite3、zip、curl、gd。 - 在 PHP 设置 →「配置修改」中确认:
upload_max_filesize=1000M、post_max_size=1100M、max_execution_time=300、memory_limit=256M;保存后重载 PHP。
第 3 步:添加站点和数据库
- 「网站」→「添加站点」:填写已解析到服务器的域名;根目录例如
/www/wwwroot/bbs.example.com;PHP 版本选 8.1;数据库选 MySQL(或稍后选 SQLite)。 - 如果创建 MySQL,记下宝塔生成的数据库名、用户名、密码;主机填
localhost,端口3306。 - 不需要设置伪静态。宝塔默认的 Nginx 配置即可运行
index.php?page=xxx;如果面板提示伪静态,选择「无」或留空。
第 4 步:上传并解压源码
- 「文件」进入站点根目录,上传完整源码 ZIP。
- 右键压缩包 →「解压」。解压后确保
index.php、install.php直接位于站点根目录。 - 如果多出一层文件夹,进入该文件夹全选文件,剪切到站点根目录,再删除空目录。
- 检查「网站目录」:运行目录必须是包含
index.php的那一层;不要误把运行目录设成public或子文件夹。
第 5 步:设置权限和防跨站
- 在文件管理器选中站点根目录,设置「权限」为 755,「所属用户」为 www;
data/、storage/、uploads/设为可写。 - 安装时根目录需要可写来生成
config.php;安装完成后把根目录恢复为 755,config.php设为 644。 - 如果出现 500 或「open_basedir 限制」,在站点设置 →「网站目录」里检查「防跨站攻击(open_basedir)」;确认站点根目录和临时目录都在允许范围内,或临时关闭后再安装,装完按需开启。
第 6 步:开启 HTTPS
- 站点设置 →「SSL」→「Let's Encrypt」,勾选域名申请免费证书。
- 申请成功后打开「强制 HTTPS」,再访问一次
https://你的域名/install.php确认证书正常。
第 7 步:安装并保留入口
- 打开
https://你的域名/install.php,按向导选择 SQLite 或 MySQL,填写管理员和站点信息。 - install.php 会永久保留,系统不会自动删除;如需保留安装入口,无需额外操作。
- 再次访问
/install.php应显示安装已完成提示;确认首页、后台、发帖、上传都正常。
宝塔收尾建议
- 在「计划任务」添加每日备份:备份站点目录 + 数据库,保留 7~30 天,并定期下载到本地。
- 在「安全」中只放行 80、443 和你的 SSH / 面板端口;不要对公网开放 3306。
- 后台「站点设置」中配置文件上传上限、SMTP 邮件和站点 Logo;这些是应用层设置,和 PHP 的
upload_max_filesize是两回事。
四、通用安装流程(三种环境都一样)
- 访问 install.php:打开
https://你的域名/install.php;子目录安装则加上子目录路径。 - 同意使用协议:阅读后勾选同意,进入环境检测。
- 选择数据库:SQLite 直接下一步;MySQL 填主机、端口、库名、用户名、密码,表前缀可留空。
- 创建管理员:用户名 2~20 位,昵称是前台显示名,密码至少 6 位;该账号是超级管理员。
- 填写站点信息:站点名称、介绍;完成后自动登录管理员账号。
- 保留 install.php:按站长设置永久保留,不要手动删除;安装入口如需限制请使用主机密码保护。
config.php、data/、uploads/、storage/。五、装完必做
config.php 644;只保留 data/、storage/、uploads/ 可写。upload_max_filesize / post_max_size 与后台附件上限要匹配。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;子目录安装要访问子目录路径。 |
| 页面空白或 500 | PHP 版本低于 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。 |