QiLog 用户手册

面向站点使用者：安装、登录、写文章、管评论、换主题、装插件、备份、升级、排错。

不需要懂 PHP。所有操作都在浏览器里完成。需要开发主题或插件，请看配套的《主题开发手册》和《插件开发手册》。

1. 认识 QiLog

QiLog 是一个零依赖的 PHP 博客系统：只要主机支持 PHP + MySQL，把整包解压上传就能跑，不需要 Composer、Node、也不占用常驻进程。

组成部分：

2. 安装

2.1 环境要求

2.2 安装向导

1. 把安装包整包解压到站点根目录。运行目录就是站点根，没有 public/。
2. 浏览器打开 http://你的域名/install.php。
3. 按向导填写： - 数据库地址（虚拟主机常给内部主机名，解析不了就填 localhost 或 127.0.0.1）； - 数据库名、账号、密码； - 表前缀（默认 qilog_，同一库放多个站点时必须改）； - 管理员账号、密码、邮箱。
4. 向导会写 data/config.php 与 data/installed.lock。

2.3 安装后必做的三件事

1. 删掉根目录的 install.php（系统已写 installed.lock 防重装，但删掉更干净）。
2. 确认 data/ 可写：属主应是 PHP-FPM 用户，权限 755。
3. 到后台「设置 → 基本信息」填站点名称和站点地址——地址填错会导致前台链接、RSS、sitemap 全部指向错误域名。

3. 登录与账号

• 后台地址：http://你的域名/admin
• 默认账号密码是你安装时设的那组。
• 登录页可开验证码（后台「设置 → 全局设置 → 登录验证码」）。
• 连续错误、会话闲置超时由「会话闲置超时」（分钟）控制，超时后需重新登录。

忘记密码：QiLog 没有自助找回。用数据库客户端打开 qilog_users 表，用下面的 PHP 片段生成一段新密码哈希再写回 password 字段：

php -r "echo password_hash('你的新密码', PASSWORD_DEFAULT), PHP_EOL;"

4. 后台界面导览

4.1 侧栏（5 组 16 项）

• 分组默认折叠，所在页面所属分组自动展开；
• 权限不足的菜单项直接不显示（整组都无权限时，连组标题一起隐藏）；
• 侧栏左上角按钮可折叠成图标条，标题栏左侧按钮可重新展开。

4.2 顶栏与铃铛

右侧依次是：

• 铃铛：徽标数字 = 待审文章 + 待审评论 +（有新版本时算 1）。点开可直达对应列表。
• 地球图标：新窗口打开站点首页。
• 侧栏底部是你的头像、昵称、角色徽章与退出按钮。

4.3 手机 / 窄屏

窄屏下侧栏变成抽屉，点顶栏左侧的汉堡按钮展开，点遮罩收起。

5. 仪表盘

仪表盘是概览页：

• 站点概况、内容统计（文章数、评论数、待审数等）；
• 系统环境卡片：PHP 版本、MySQL 版本、内核版本、计划任务上次运行时间；
• 「待审核」快捷入口；
• 区块设置：点右上角可以显示/隐藏或排序仪表盘区块（保存为你的个人偏好）；
• 插件可以通过钩子往仪表盘注入自己的面板（例如 dashboard-widgets 插件）。

6. 撰写与发布文章

6.1 编辑器

「撰写文章」打开的是 Markdown 编辑器，左右/上下分栏或纯编辑模式由编辑器自身决定：

• 标题、正文（Markdown）、摘要、Slug、分类、标签、封面图、模板、评论开关、置顶、定时发布、状态；
• 右上角有预览；
• 写完点「发布」，或点「保存草稿」。

编辑器可以被插件替换（例如 wangEditor 富文本插件）。替换后正文改存 content_html、Markdown 源字段 content_md 留空；两种编辑器混用于同一站点是安全的。

⚠️ 用富文本写的文章，在 Markdown 编辑器里看不到正文（那里只读 content_md）。若此时强行保存，系统会阻止并提示，以免清空正文——请改用富文本编辑器编辑，或先把正文转换为 Markdown 再保存。

6.2 Slug 与固定链接

Slug 是这篇文章在 URL 里的短名。留空会自动用标题生成。URL 结构由「设置 → 固定链接」决定，可选：

可用占位符：{slug}、{id}、{year}、{month}。

改固定链接结构不会自动重定向旧地址——已发布文章的外部链接会失效。决定结构前想清楚。

6.3 分类与标签

• 分类：层级化、每篇最多一个（category_id）。分类在「管理 → 分类」里维护。
• 标签：扁平、每篇多个、逗号分隔。

6.4 封面图

在编辑器右侧上传封面（thumbnail）。主题可在列表页或文章页展示它。上传后会进媒体库。

6.5 摘要

不填摘要时，前台会自动截取正文前若干字（长度由「设置 → 阅读 → 摘要长度」控制）。

6.6 置顶

勾选「置顶」后该文章在列表里优先展示（列表项字段 is_pinned）。主题需要自己消费这个字段——部分主题可能仅做排序、不额外加标记。

6.7 定时发布

填了未来时间的「定时发布」后，文章状态会保持在待发布队列，到点由系统的自动维护任务翻牌为「已发布」。

⚠️ 这套系统没有常驻定时进程。翻转依赖「有人访问站点」或「外部定时任务」（见 §19.1）。长期没有访客的站点，定时发布会延后——这是唯一需要配置外部计划任务的场景。

6.8 状态与回收站

删除文章是移到回收站，不是立刻物理删除。回收站里 30 天前的文章会被自动清理（由自动维护任务执行）。

6.9 批量操作

列表页支持勾选多篇后批量处理（删除等）。列表上方可按状态筛选，也可搜索。

7. 单页

「发布单页」与文章几乎一样，区别是：单页不进分类、不进标签、不参与列表分页，通常用于「关于」「联系方式」这类固定页面。

单页另有 page_path：可以给它指定一个自定义路径。

模板下拉里会出现主题提供的「单页变体模板」（文件名 page-*.php），例如内置主题自带的「友情链接」模板。选了就用那套版式渲染。

友情链接功能已在 1.4.1 从核心移除，后续以插件形式提供。「友情链接」模板现在渲染为空列表，等插件接入数据。

8. 分类与标签

「管理 → 分类」：新建、改名、设父级（层级）、设 slug、删除。

「管理 → 标签」：新建、改名、设 slug、删除。

分类/标签是有层级的组织方式，删除前确认没有文章在用——被引用的分类删除后，那些文章会失去归属。

9. 评论管理

「管理 → 评论」列表按状态分组：

单条操作：通过 / 待审核 / 垃圾 / 删除（可恢复）。列表支持多选批量删除。

后台可配置（「设置 → 评论」）：

• 全局关闭评论；
• 允许游客评论；
• 昵称 / 邮箱必填；
• 评论倒序显示；
• 每页条数；
• 单条评论最大链接数（超出的游客评论会被拦下，防垃圾）；
• 蜜罐字段（对访客不可见的输入框，被填写即判为机器人）。

防垃圾建议：保持「蜜罐」开启，并合理设置「单条评论最大链接数」。这两项能挡掉绝大多数机器评论。

10. 媒体库

「管理 → 媒体库」统一管理上传的图片与文件。

• 上传：拖拽或选择，支持多选；上传时可批量选择目标用途；
• 浏览：网格/列表视图，可按类型筛选；
• 重命名；
• 复制链接；
• 删除（多选批量）。

删除前会检查引用：如果某个文件正被文章封面、正文或插件表引用，系统会提示，避免出现前台裂图。插件可以通过钩子登记自己的引用源。

上传限制在「设置 → 上传」里配：

11. 菜单

「扩展 → 菜单」管理导航。

• 可以建多个菜单，每个菜单绑定一个位置：

• 菜单项支持两级（父项 + 子项），可拖拽/箭头排序。
• 菜单项来源：分类、单页、自定义 URL。
• 同一位置全局唯一——把菜单 A 指派给 header 时，原来占着 header 的菜单会自动解除。

如果前台页头没显示你配的菜单，检查该菜单是否绑定到了 header。

12. 主题

「扩展 → 主题」：

• 启用：点「启用」即可切换，不需要重启；
• 设置：有可配置项的主题会显示「设置」，里面是主题作者定义的选项（强调色、宽度、页脚文案等）；
• 小部件：管理侧栏/页脚等坑位里的组件与顺序；
• 上传主题：上传 zip 安装；
• 删除：删除非当前启用的主题。

上传 zip 的规则（系统强制校验）：

1. zip 里只能有一个顶层目录，目录名即主题名；
2. 目录名只允许字母、数字、_、-；
3. 装的时候会先删旧版再放新版（覆盖安装）；
4. 不能覆盖正在启用的主题，要先切到别的主题。

站点升级不会动 data/themes/，你的主题是安全的。

13. 插件

「扩展 → 插件」：

• 启用 / 停用：停用后插件的钩子立即失效；
• 设置：插件自定义的配置面板（API Key、开关等）；
• 上传插件：上传 zip 安装（规则同主题）；
• 删除。

启用插件时系统会顺带跑一次该插件的「数据表自检」，把插件需要的表建好。已启用的插件不能被覆盖安装，要先停用。

内置自带一个 qilog-dashboard-widgets（仪表盘组件），可在仪表盘里添加各种区块。

14. 用户与权限

「系统 → 用户」管理账号。五个角色：

规则与保护：

• 保留最后一个管理员：不能降级、不能删除最后一个管理员账号；
• 不能自己改自己的角色（个人设置里没有角色字段，防自提权）；
• 删除用户时可以把 TA 的内容转交给另一个账号（transfer_to），避免文章变孤儿。

15. 备份与恢复

「系统 → 备份」：

注意：

• 备份只包数据库，不含上传的媒体文件与主题。要完整留档，请额外下载 data/uploads/ 目录。
• 恢复是整库覆盖，会丢掉恢复点之后的内容。恢复前建议先做一次当前备份。
• 备份文件命名带时间戳；旧版本（更名前）产生的 qiblog-*.sql 备份仍能被识别与恢复。

16. 检查更新与一键升级

「系统 → 检查更新」：

1. 列表顶部显示更新检查结果，三种状态可区分： - 已是最新； - 有更新（显示版本号与更新说明）； - 检查失败：原因（不会显示成「已是最新」——失败时也不会写缓存，可重试）。
2. 有更新时可以做： - 查看更新说明：了解这个版本改了什么； - 差异预览：列出将要被覆盖的文件，先看再决定； - 一键升级：下载、校验、覆盖、自检、必要时自动回滚。
3. 如果站点版本低于该版本的最低可升级版本，会给出对应提示： - 目标版本更高 → 「请先升级到 X，再升级到 Y」； - 目标版本本身即下限 → 「请下载完整安装包手动覆盖升级」。
4. 覆盖过程中若出问题，页面提供自救入口：清理临时文件、重新进入升级、回滚到覆盖前。

自动更新策略（「设置 → 全局设置」）：

自动策略不会跳过人工确认，只是增强「覆盖失败时自愈」的能力。 自检若连不上本站（虚拟主机常见）一律按「不确定」处理，绝不回滚。 （历史版本曾有「小版本 / 全部」两档，二者实现上完全等价，已合并为单一开关。）

17. 设置

「系统 → 设置」共 7 个标签。

17.1 基本信息

站点名称、副标题（slogan）、站点描述、关键词、站点地址。

站点地址必须填对（含 https://），否则前台链接、RSS、sitemap、邮件里的链接都会错。

17.2 全局设置

时区、登录验证码开关、站点关闭模式、会话闲置超时、自动更新策略。

站点关闭模式开启后，非管理员访客看到维护页；/admin/*、/assets、/feed、/sitemap.xml、/robots.txt、/favicon.ico 不受影响。

17.3 评论

全局关闭、游客评论、昵称/邮箱必填、蜜罐、倒序显示、每页条数、单条最大链接数、评论策略（comment_policy 文本，用于声明审核规则并向访客展示）。

17.4 上传

上传大小上限、扩展名白名单、缩略图宽 / 高。

17.5 固定链接

四种结构（简洁 / 日期 / ID / 自定义），见 §6.2。

17.6 阅读

首页每页文章数、RSS 条数、摘要长度。

17.7 邮件通知

• 开关：启用邮件通知；
• 发件人：邮箱与显示名；
• SMTP：主机、端口、加密方式、账号、密码；
• 管理员邮箱：接收通知的地址；
• 通知事件：新评论、新投稿、评论回复；
• 邮件模板：评论 / 投稿 / 回复三类，各有主题与正文模板。支持占位符：

{site_name} {post_title} {author} {content} {post_url} {time} {excerpt} {parent_content}

• 投递队列（面板末尾）：显示待发邮件数，提供「立即发送队列邮件」按钮与计划任务地址。

邮件默认异步投递（响应返回后再发）。在支持 fastcgi_finish_request 的主机上基本无感；不支持时由自动维护任务以每 5 分钟一封的节奏走完。待发数长期不降时，点一下「立即发送队列邮件」。

18. 个人设置

修改昵称、邮箱、头像、密码。不能改自己的角色（这是防自提权的设计）。

19. 站点维护

19.1 计划任务与自动维护

QiLog 没有常驻定时进程，维护任务（定时发布、回收站清理、访问统计、邮件投递）采用「请求驱动自愈」：

每个访客请求都会顺带检查一次节流（默认 60 秒一轮；上一轮被中断则退避到 300 秒），到点就跑一轮轻量维护。

这意味着：

需要加速时，把下面这个地址加到主机面板的计划任务里（类型选「访问 URL」，周期 5 分钟）：

https://你的域名/cron/{随机key}

不支持伪静态的主机，把 /cron/ 换成 ?cron= 也一样有效：

https://你的域名/?cron={随机key}

地址（含随机 key）在「设置 → 邮件通知 → 投递队列」面板里可以看到并复制。key 等同于密码，请勿公开。

注意：后台「站点设置」里已经没有单独的「计划任务」标签——投递队列与定时地址都归在「邮件通知」面板末尾。

19.2 邮件队列

见 §17.7。待发数就是队列长度；点「立即发送队列邮件」立刻排空。

19.3 上线检查清单

• [ ] 删除根目录 install.php
• [ ] data/ 属主是 PHP-FPM 用户、权限 755
• [ ] 「设置 → 基本信息 → 站点地址」填写正确
• [ ] 关掉调试开关（配置文件里的 debug）
• [ ] Nginx 用户：已加 ^~ /assets/ 伪静态并重载（见 §19.4）
• [ ] 验证插件资源：curl -I https://你的域名/assets/plugin/wangeditor/index.js 返回 200
• [ ] 做过一次数据库备份并下载到本地
• [ ] 前台首页 / 分类 / 标签 / 搜索 / 文章 / 单页 / 404 各看一遍

19.4 Nginx 伪静态（Nginx 用户必看）

Nginx 不读 .htaccess，要手写伪静态。最关键的一条：

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

为什么必须加 ^~ /assets/：插件的静态资源是由 PHP 分发的虚拟路径（项目根目录并没有 assets/plugin/ 这个物理目录）。而宝塔默认站点配置里有匹配静态扩展名的正则 location（如 location ~ .*\.(js|css)?$），正则 location 优先级高于普通前缀 location，会直接按磁盘路径取文件 → 404 → 请求根本到不了 index.php。

症状：启用 wangEditor 之类的插件后编辑器空白，浏览器控制台报 style.css / index.js 404。

安全加固（可选，屏蔽 data/ 下的敏感文件）：

location ~ ^/data/(config\.php|installed\.lock|backups/|cache/|logs/|sessions/) { return 404; }
location ~ /\.(git|svn|env) { return 404; }

20. 常见问题与排错

21. 角色能力对照表

对应 QiLog v1.5.0。文档与代码不一致时以代码为准。