WiKiss 0.3 核心使用与鉴权配置详解

WiKiss 0.3 装好后怎么用？本文基于 Ubuntu 22.04 + PHP 8.1 实测环境（安装与兼容修复见《Ubuntu 22.04 安装 WiKiss 0.3 指南（PHP 8.1 兼容修复实录）》），把页面生命周期（浏览 → 创建 → 编辑 → 删除 → 历史）、单口令鉴权机制、搜索/最近更改/RSS 三大辅助功能一次讲透，全部行为均有 HTTP 状态码与落盘验证。

一、URL 路由与页面模型

WiKiss 是单入口应用，一切 URL 都打到 index.php，用查询串路由：

URL	动作
`./?page=页面名`	浏览页面（默认动作）
`./?page=页面名&action=edit`	编辑表单
`./?action=recent`	最近更改
`./?action=search&query=关键词`	全文搜索
`./?page=页面名&action=history`	页面历史版本列表
`./?action=list`	全站页面列表（并显示已加载插件）
`/rss.xml`	最近更改的 RSS 订阅

页面模型极简：页面名 = pages/ 目录下的文件名（去掉 .txt）。访问 ./?page=FooBar 就是读写 pages/FooBar.txt。三条安全约束（index.php 源码级防护）：

页面名中的 / 与 \ 被剥离，无法目录穿越；
页面内容中的 < 一律替换为 <，HTML 不透传；
$ 与 \ 渲染时转义为 HTML 实体，避免与后续替换逻辑冲突。

二、页面创建与编辑（实测）

创建：访问一个不存在的页面名（如 ./?page=SandBox），WiKiss 显示配置项 $DEFAULT_CONTENT 的占位文本（默认法语 La page %page% est vide.，意为"页面 X 是空的"），其中 %page% 会被替换为页面名；页面上有编辑入口，写入内容保存即完成创建。

编辑保存（HTTP 层实测）：编辑表单 POST 三个字段到首页 URL——

curl -s -X POST 'http://wiki.example.com/' \
  --data-urlencode 'page=SandBox' \
  --data-urlencode 'content=这是正文，支持 ^b 块引用等语法' \
  --data-urlencode 'sc=Q1w2E3r4T!' \
  -o /dev/null -w '%{http_code}\n'
# 实测输出：302（成功后 302 跳转到 ./?page=SandBox）

保存成功：302 → 页面视图，pages/SandBox.txt 落盘，同时 historique/SandBox/<日期>-<时分>.bak 写入历史备份（实测备份文件 20261030-0502.bak 生成）；
口令错误：302 → ./?page=SandBox&action=edit&error=1 回到编辑表单，文件不落盘（实测验证）；
内容为空提交：等价于删除页面，pages/页面名.txt 被 unlink（实测创建 TestDel 再以空内容提交，文件消失）。

保存流程有个值得知道的细节：落盘前会 trim() 内容，所以页面文件首尾无空白行；写文件用的 fopen("w") 整体覆盖，不存在追加模式。

编辑表单还带一个恢复入口：./?page=页面名&action=edit&time=<时间戳>&restore=1 可从指定历史版本回填编辑框（数据源是 historique/ 的 .bak 文件）。

三、单口令鉴权机制（实测）

0.3 没有用户体系，整个 wiki 一个口令 $PASSWORD（_config.php），三种通过方式（authentified() 源码逻辑）：

口令直通车：保存请求的 POST 字段 sc 与 $PASSWORD 相等 → 通过，同时种 Cookie AutorisationWiKiss = md5($PASSWORD)，有效期一年；
Cookie 通行证：后续请求只要 Cookie 值等于 md5($PASSWORD) 即视为已登录（同一浏览器编辑多页无需重复输口令）；
匿名模式：$PASSWORD 为空串时任何人都可编辑（默认值！装完立即设置强口令）。

实测矩阵（$PASSWORD="test" 时）：

请求	结果
POST `sc=test` + 非空内容	302 → 视图，文件落盘 ✓
POST `sc=错误值`	302 → `action=edit&error=1`，文件不动
POST `sc=`（空）	同上，鉴权失败
已种 Cookie 后再保存	无需再带 sc

安全口径：口令即全站编辑权，无失败锁定、无 ACL、无用户隔离；Cookie 是 md5(口令) 的明文等价物，拿到 Cookie 即拿到编辑权，生产环境务必走 HTTPS。示例口令 Q1w2E3r4T!（大小写+数字+符号 10 位）是本文实测采用的强度基线。

四、搜索（实测）

./?action=search&query=关键词 对 pages/ 下所有页面做全文正则匹配（大小写不敏感），页面名也参与匹配。实测搜 Aide：结果页标题为 Résultats de recherche pour Aide，正文列出 Accueil、Aide、AideTables 三个命中页的链接。

搜索框内嵌在页面模板底部（表单 {SEARCH} 占位符），accesskey=q 可快捷聚焦。注意一个坑：搜索动作会把页面标题临时置为"搜索结果 + 关键词"，0.3 源码在这条路径上有 PHP 8 兼容问题（fread 空句柄致命错误），未打补丁的安装搜索即 500——见安装篇修复 5/7。

五、最近更改与页面历史（实测）

最近更改 ./?action=recent：按文件 mtime 倒序列出全部页面与最后修改时间（实测 HTTP 200），是全站的内容更新入口。每页右侧还带历史（history）链接。

页面历史 ./?page=页面名&action=history：列出 historique/<页面名>/ 下全部 .bak 备份（文件名即时间戳 YYYYMMDD-HHMM），每条备份提供两个操作：

查看：渲染该历史版本内容（只读）；
恢复：&time=<时间戳>&restore=1，把历史版本回填进编辑框，人工确认后再保存（不是一键覆盖，防误恢复）。

备份时机：每次保存自动写一份；删除页面不清理备份，误删可从 historique/ 找回（运维细节见本专栏《WiKiss 0.3 常用 CLI 命令与运维实操》）。备份开关 $BACKUP_DIR 置空可关闭备份（不建议）。

六、RSS 订阅（wkp_Rss 插件，实测）

访问 /rss.xml 输出 RSS 0.91 格式的最近更改流（实测 HTTP 200），频道标题取 $WIKI_TITLE，条目含页面名、修改时间与摘要。模板 <head> 里已带 <link rel="alternate" type="application/rss+xml">，阅读器可自动发现。该能力由插件 wkp_Rss.php 提供——0.3 的插件机制非常朴素：plugins/ 目录下所有 wkp_*.php 自动 require 并实例化，插件通过钩子方法（如 formatBegin 渲染前处理、writedPage 保存后处理）介入流程。

用 ./?action=list 可看当前加载的插件清单，0.3 自带三个：

插件	职责
`wkp_ListPlugins`	渲染插件列表页（action=list）
`wkp_Rss`	生成 rss.xml
`wkp_Tables`	表格语法（对齐/合并单元格，详见语法篇）

装第三方插件 = 把 wkp_名字.php 丢进 plugins/ 目录即可，无需注册。

七、日常使用速查

想做什么	怎么做
新建页面	浏览器直接访问 `./?page=页面名`，点编辑写入保存
改页面	页面右上角"编辑"（或 `&action=edit`）
删页面	编辑框清空后保存（备份仍在 historique/）
回滚到旧版本	action=history → 找到时间戳 → 恢复 → 保存
全站搜索	底部搜索框或 `?action=search&query=词`
看最近谁改了什么	`?action=recent`
订阅更新	`/rss.xml`
换全站编辑口令	改 `_config.php` 的 `$PASSWORD` 后所有人重新登录（旧 Cookie 失效）

值得强调：页面名即文件名，中文页面名完全可用（文件系统存 页面名.txt，URL 里自动 URL 编码），实测中文标题页创建、浏览、搜索均正常。

八、与同族产品的使用差异

对比《Otter Wiki 2.26.1 配置参数详解》（环境变量/界面/配置文件三层配置 + 独立用户体系），WiKiss 把一切压到一个 _config.php 和一个共享口令；
对比《PmWiki 2.3.38 配置参数详解》（数百个配置参数 + 组级权限），WiKiss 的可配置面只有十来个变量——这是它的"Kiss"哲学，也是 2007 年代码的局限。

排版能力的边界（粗体/斜体/表格/标题）在下一篇展开：本专栏《WiKiss 0.3 语法与表格插件详解》。