从 GitHub 部署到使用：MiniBlog 单文件博客完整教程

简介

MiniBlog 是一个单文件 PHP 博客系统：整个程序只有一个 index.php，编辑器、字体、示例文章全部内嵌，数据库使用 SQLite，不需要 MySQL、不需要 Composer、不需要 Node.js，上传即可运行。

• GitHub 仓库：<https://github.com/amw1933/miniblog-single>


• 技术栈：PHP + SQLite（PDO）


• 部署方式：上传一个文件 → 打开网址初始化 → 开始写文章


主要特性：


• 单文件自包含，一条 index.php 完成全部功能


• SQLite 数据库自动创建，零配置


• Markdown 编辑器：表格粘贴、代码块、图片/文件上传、视频嵌入


• 多分类、多标签、草稿/定时发布、回收站、文章置顶


• 文件管理：引用自动识别、手动锁定、一键清理未引用文件


• 多套主题（蓝色经典/暖色/明亮/暗色）和多款手写字体


• 访问统计：总访问人数、今日访问、近 14 天趋势、最近访问 IP


• 评论系统：审核、IP 拉黑、敏感词过滤


• 备份与恢复：下载完整 ZIP 或服务器增量快照


• 文章链接导入：粘贴其它网站文章链接，自动生成草稿并下载图片


• SEO 完备：物理 robots.txt、自动更新的 sitemap.xml、RSS、OG、JSON-LD




一、环境要求




• PHP 7.4 以上（推荐 PHP 8.1 / 8.2）


• 必需扩展：pdo_sqlite、mbstring、fileinfo


• 推荐扩展：curl（抓取远程图片/文章）、gd（图片压缩和缩略图）、openssl


• Web 服务器：Apache、Nginx、宝塔面板、群晖 Web Station 均可


• 不需要 MySQL，不需要 Composer，不需要 Node




二、从 GitHub 获取源码






方式一：git clone



git clone https://github.com/amw1933/miniblog-single.git
cd miniblog-single



方式二：直接下载 ZIP

打开 GitHub 仓库页面 → 绿色 Code 按钮 → Download ZIP → 解压。

最终只需要一个文件：index.php。其它文件（README、截图等）可传可不传。



三、部署








3.1 通用部署（宝塔 / Apache / 虚拟主机）




• 在网站根目录（或子目录，例如 /blog）新建目录


• 上传 index.php 到该目录


• 确保目录可写（PHP 需要自动创建 data/、uploads/ 和 data/blog.db）


• 用浏览器访问网站地址


Linux 权限参考：



chown -R www:www /www/wwwroot/你的站点
chmod -R 755 /www/wwwroot/你的站点
chmod -R 775 /www/wwwroot/你的站点/data /www/wwwroot/你的站点/uploads





3.2 群晖 NAS（Web Station）




• 打开群晖「控制面板 → Web Station」


• 新建一个网页服务，PHP 版本选 8.x，启用 SQLite 支持


• 文档根目录指向存放 index.php 的文件夹


• 访问 http://NAS地址/你的路径 即可初始化




3.3 Nginx 注意事项



程序不需要伪静态，文章链接就是 ?slug=文章名，开箱即用。但 Nginx 不解析 .htaccess，请务必在配置里屏蔽 data 目录，防止数据库被直接下载：



location ~ ^/blog/data/ {
    deny all;
}





四、首次初始化



第一次打开网站，会自动进入安装页面（只出现一次）：


• 填写管理员用户名


• 填写管理员密码


• 保存后自动登录，并自动创建「默认分类」


首次部署还会自动生成两篇示例文章（Alpine NPS、Alpine Sing-box），方便你直接查看文章排版效果，不需要可以删掉。



五、后台使用






进入网站后，点击右上角「管理」；未登录时显示「登录」，用刚才设置的管理员账号登录。



5.1 文章管理




• 写文章：Markdown 编辑器，支持实时预览


• 上传图片：工具栏上传按钮，图片自动保存到 uploads，并压缩为 WebP


• 粘贴表格：直接把 Excel / 网页里的表格复制进编辑器，自动转换成 Markdown 表格


• 代码块：点击代码块按钮插入，默认语言为 bash，支持语法高亮


• 分类：支持多选分类，第一个勾选的为主分类


• 标签：自由添加，文章页自动展示标签


• 状态：发布 / 草稿 / 定时发布


• 置顶：文章列表点击「置顶」，首页置顶优先显示并带橙色标记


• 回收站：删除的文章先进回收站，可恢复、可修改，也可以永久删除




5.2 文件管理




• 上传任意允许后缀的文件（默认 jpg/png/zip 等，可在设置中修改）


• 被文章引用的文件自动显示「引用中」，不可删除


• 未引用的文件可以手动「锁定」，锁定后单个删除、批量删除、一键清理都会跳过


• 「一键清理全部未引用」按钮可以清理所有孤儿文件


• 按类型汇总显示：png / jpeg / zip / bin / webp 等




5.3 统计




• 总访问人数、今日访问人数（每天按会话去重）


• 近 14 天 PV / UV 趋势


• 热门文章 Top 10


• 最近访问 IP 列表（近 90 天，含访问次数和浏览器 UA）




5.4 系统设置




• 站点信息：站点名称、描述、页脚版权、站点字体


• 主题：蓝色经典（默认）/ 暖色 / 明亮 / 暗色，管理员可切换


• 作者信息：作者名称、简介、头像（上传新头像自动覆盖旧头像）


• 管理员密码：随时修改


• 上传设置：大小限制、允许上传的后缀


• 备份与恢复：下载完整 ZIP 备份、服务器增量快照、一键恢复


• 文章链接导入：粘贴其它网站的文章链接，自动抓取标题、正文、表格和图片，生成草稿，并在文末追加原文链接


• 操作日志：记录登录、发文、备份、删除等后台操作




六、主题与字体



内置 4 套主题，默认「蓝色经典」：


• 蓝色经典（默认）


• 暖色（柔和浅杏 → 浅粉）


• 明亮


• 暗色


字体内置马善政、Great Vibes、Allura、Dancing Script 等多款手写字体，全站生效，手机端同样有效。站点名称和文章封面文字都会自动使用所选字体。



七、SEO 收录



系统已经内置完整的 SEO 基础：


• 物理 robots.txt（允许抓取、屏蔽后台和数据目录）


• 物理 sitemap.xml（发布/修改/删除文章时自动更新）


• 每篇文章自带 title、description、canonical、Open Graph、JSON-LD 结构化数据


• RSS 订阅：?action=rss


• 后台页面自动 noindex，不会被搜索引擎收录


提交收录步骤：


• Google：打开 Google Search Console，验证域名，提交站点地图 https://你的域名/blog/sitemap.xml


• 百度：打开百度搜索资源平台，验证站点，提交同一个 sitemap 地址


提交后一般几天到几周内开始收录；使用自己的正式域名会比内网穿透域名收录更快、更稳定。



八、备份与恢复




• 数据库文件：data/blog.db（文章、评论、设置全部在里面）


• 完整备份：后台「备份与恢复 → 下载备份」，得到包含 index.php、数据库、上传文件、字体的 ZIP


• 服务器快照：后台「立即备份到服务器」，增量保存，可在列表里随时恢复


• 升级版本：先备份旧 index.php，再上传新 index.php 覆盖即可，数据不受影响




九、常见问题




• 打开白屏 / 500：检查 PHP 版本和扩展（pdo_sqlite、mbstring），查看 PHP 错误日志


• 上传失败：uploads 目录没有写权限


• 文章里的图片显示不出来：到文件管理确认文件是否存在、是否被引用；文章里路径应为 uploads/文件名


• Nginx 下担心数据库泄露：按 3.3 节加上 deny all 规则


• 忘记管理员密码：备份后删除 data/blog.db 重新初始化，站点会重新走安装流程（会丢失原数据，务必先备份）


• 主题/字体在手机端没变化：浏览器缓存导致，刷新或清除缓存即可




十、总结



MiniBlog 的核心思路是「单文件 + SQLite」，特别适合：


• 群晖 NAS / 家用服务器


• 轻量 VPS


• 不想维护 MySQL 和复杂框架的个人博客

从 GitHub 拉取 → 上传一个文件 → 初始化账号 → 开始写作，整个过程五分钟就能完成。数据完全掌握在自己手里，备份恢复也很简单。

---

🖥️ 群晖（Synology）NAS 部署补充说明

把 MiniBlog 部署到群晖 Web Station（例如 http://10.10.10.3/blog/）后，如果打开提示「安装错误」，绝大多数是下面两个原因。

1️⃣ 启用 SQLite 驱动（报错：could not find driver）

MiniBlog 使用 SQLite 数据库，群晖 Web Station 的 PHP 默认可能没有启用 pdo_sqlite 扩展。

操作步骤：

打开群晖主菜单 → Web Station

左侧点击 脚本语言设置（Script Language Settings） → PHP

找到当前站点使用的 PHP 版本（如 PHP 8.2），点击 编辑（铅笔图标）

在 扩展（Extensions） 中勾选 pdo_sqlite（如有 sqlite3 也一并勾选）

点击 保存，Web Station 会自动重启 PHP

刷新博客地址，could not find driver 错误即消失

2️⃣ 给网站目录写入权限（报错：unable to open database file）

即使启用了 SQLite 驱动，如果 Web 服务器用户（http）没有网站目录的写入权限，就无法创建 data 数据库目录，SQLite 会提示无法打开数据库文件。

操作步骤：

打开群晖 File Station

进入 web，右键你的博客目录（如 blog）→ 属性 → 权限

添加用户 http，权限选择 可读写

应用到「此文件夹、子文件夹及文件」

点击 保存，然后刷新博客页面

也可以使用 SSH 快速授权：

sudo chmod -R 775 /volume1/web/blog
sudo chown -R http:http /volume1/web/blog

✅ 完成安装

浏览器打开 http://群晖IP/博客目录/

首次访问会进入「🚀 安装 MiniBlog」页面，设置管理员账号

保存后自动创建数据库，并自动生成两篇种子文章（NPS 穿透、Sing-box 代理教程）

错误提示	原因	解决办法
could not find driver	PHP 缺少 pdo_sqlite 扩展	Web Station 中启用 pdo_sqlite
unable to open database file	网站目录无写入权限	File Station 给 http 用户可读写权限