安装说明

纸鱼博客支持 PHP 8.1+、MySQL 5.7.6+，可以运行在 Nginx、Apache、宝塔和常见共享主机环境中。

环境要求

如果使用应用商店安装主题或插件，建议将 post_max_size 设置为至少 16M，将 upload_max_filesize 设置为至少 12M。

获取发布包

请从官网下载页获取最新发布包。发布包已经包含运行所需的 PHP 依赖，生产环境不需要执行 Composer。

通用安装

1. 上传文件

将发布包解压到网站根目录。安装完成后，根目录中应能看到 index.php、install.php、app/、public/ 等文件和目录。

不要把网站根目录指向 public/，纸鱼博客的入口文件位于项目根目录。

2. 打开安装向导

在浏览器中访问：

https://你的域名/install.php

安装向导会依次检查 PHP 版本、扩展、目录权限和上传限制。上传限制低于 10M 时只显示警告，不影响核心安装；但如果 post_max_size / upload_max_filesize 处在 10M 到目标值之间，环境检查会判定不通过并禁用“下一步”，需要先调大限制或在 php.ini 中放行。

3. 填写安装信息

按照页面提示填写：

• 数据库地址、端口、名称、用户名和密码

• 站点名称和站点地址

• 管理员用户名、邮箱和密码

• 是否启用伪静态

数据库账号需要有创建数据库和写入数据表的权限。部分虚拟主机不允许程序自动建库，请先在主机面板创建数据库，再使用该数据库信息安装。

管理员密码至少 8 位，且不超过 72 字节。安装向导会自动创建数据表、初始设置和 runtime/config.php，不会要求手动导入 SQL 文件。

安装器需要写入的目录：

在线升级需要程序文件可写。建议日常不给目录写权限，只在执行对应操作时按需临时授权。

4. 完成安装

安装成功后：

1. 删除网站根目录中的 install.php。

2. 访问 https://你的域名/ 查看站点。

3. 访问 https://你的域名/admin/ 登录后台。

4. 在“站点设置”中补充邮件、评论、上传和 API 配置。

伪静态配置

启用伪静态时，Web 服务器必须将不存在的路径交给项目根目录的 index.php。文章、分类、API、插件私有路由和插件/主题自然路由都依赖这条规则。站点根目录不能指向 public/。

Nginx

安装完成并删除 install.php 后，将以下规则加入 Nginx server 配置。PHP 拦截规则必须位于通用 PHP-FPM 规则之前：

location ~* ^/(config\.php|composer\.(json|lock)|\.env)(/|$) {
    deny all;
}

location ^~ /runtime/ {
    deny all;
}

location ^~ /backups/ {
    deny all;
}

location ~ ^/(?!index\.php$|cron\.php$).*\.php(?:/|$) {
    deny all;
}

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

规则会拒绝访问配置、运行时和备份文件，并只允许 index.php、cron.php 执行；其余 PHP 文件及动态路径会被拦截或交给 pafish 路由。使用宝塔伪静态编辑器时，请确认它支持在 server 中添加多个 location 块；否则将这些规则加入站点 Nginx 配置。完整站点配置参见宝塔 Nginx 配置。

Apache

发布包已包含 .htaccess。请确认 Apache 已启用 mod_rewrite，并允许站点目录使用 .htaccess。

不支持伪静态

在安装向导中取消“启用伪静态”，或安装后在 runtime/config.php 中设置：

'pretty_urls' => false,

链接会自动使用 index.php?p=... 形式，功能不受影响。

宝塔面板

宝塔用户可以按以下顺序操作：

1. 创建 PHP 8.1+ 站点和 MySQL 数据库。

2. 上传并解压发布包到站点根目录。

3. 在 PHP 设置中启用所需扩展，并调整上传限制。

4. 访问 install.php 完成安装。

5. 删除 install.php 并配置伪静态。

完整步骤请参考宝塔面板部署指南。

安装后检查

• 首页和一篇已发布文章可以正常打开。

• /admin/ 可以登录后台。

• 能够上传图片到媒体库。

• 已配置伪静态时，文章地址不会返回 404。

• 已删除 install.php，并确认 runtime/config.php、runtime/、backups/ 不能被直接下载。

常见安装问题

• 提示扩展缺失：在 PHP 配置中启用对应扩展后重启 PHP。

• 提示目录不可写：确保 runtime/、public/uploads/ 和 backups/ 可由 PHP 运行用户写入；使用分片上传时还需要 storage/。正常安装不需要开放整个项目根目录的写权限。

• 文章地址 404：检查 Nginx 的 try_files 或 Apache 的 mod_rewrite；也可以暂时关闭伪静态。

• 安装后样式丢失：检查站点根目录是否指向项目根目录，以及静态资源路径是否被 Web 服务器拦截。

• 无法安装主题或插件：检查 zip 扩展、上传限制和站点目录权限。