Raneto 0.18.1 常用操作与排障指南

Raneto 0.18.1 日常内容操作与编辑器端点实测：rn-login/rn-add-page/rn-edit/rn-delete 请求字段与响应、status 语义坑点、sitemap 核查、备份迁移与八则排障实录（无 REST API，篇型为 D1）。

Raneto知识库自托管MarkdownNodejsRaneto2026/10/30

Raneto 0.18.1 常用操作与排障指南

目标：汇总 Raneto 0.18.1 的日常内容操作与编辑器接口实测用法，并沉淀部署运维中的真实排障记录。Raneto 没有对外 REST API——/rn-* 系列端点是 Web 编辑器内部使用的表单接口，本文按「能独立执行的 curl 请求」口径逐个实测其字段与响应，作为脚本化批量操作的依据。篇型说明：因产品无 API 体系，本篇为常用操作与排障（D1）而非 API 篇。部署与环境准备见 《Raneto 0.18.1 npm 裸机安装部署指南》，配置语义见 《Raneto 0.18.1 配置参数详解》，选型背景见 《Raneto 0.18.1 介绍与选型指南》。

一、操作总览

Raneto 的日常操作分两层：Web 界面层（浏览器内完成浏览、搜索、登录、建页、编辑、删除）与文件系统层（直接读写 content/pages/，每次请求实时读盘、改完即生效、无需重启）。两层是同一份数据的两个视图：Web 编辑器保存的每一个页面，落盘就是 content/pages/ 下一个带元信息头的 .md 文件；反过来手工放入的 Markdown 文件也会立刻出现在站点导航里。这一特性决定了 Raneto 的运维习惯：批量操作走文件层（脚本/rsync/Git），单页微调走 Web 层。

本文示例统一使用演示账号 admin / q1w2e3r4，服务地址 http://127.0.0.1:8128（端口按实际部署替换）。

二、Web 界面日常操作

2.1 登录与登出

登录页地址 /login（表单 action 为 /rn-login，字段 username/password）。登录成功后右上角出现 Edit 与 New Page 入口；登出直接访问 /logout（实测 HTTP 302 回首页）。会话以 Cookie raneto.sid 标识，有效期 24 小时，会话数据落盘在安装目录的 ./sessions/（文件存储，重启服务不丢登录态）。

2.2 建页、编辑、删除

  • 建页：右上角 New Page，输入页面名（即文件名），保存后进入编辑器。命令行等价操作见第三节 /rn-add-page。
  • 编辑：页面上点 Edit，编辑器为纯 Markdown 文本框，顶部三个元信息字段 Title（页面标题）、Sort（排序值）、描述；保存即写盘。
  • 删除：编辑页内 Delete 按钮。注意 v0.18.1 的删除是软删除：源码把文件重命名为 <原文件名>.del（源码注释原话 "Don't Delete / Rename to remove from listing"），页面立即从导航与 sitemap 消失，但磁盘上 .del 文件仍占空间——真正的清除需要手工 rm content/pages/**/*.del（建议纳入定期巡检），恢复误删页也只需把 .del 后缀改回来。
  • 建分类：New Category 输入目录名，落盘为 content/pages/<目录名>/。

2.3 搜索与导航

首页顶部搜索框提交为 GET /?search=<关键词>，结果页列出文件名与内容命中项，每条带摘要（命中词高亮、超长截断，摘要长度由配置 excerpt_length 控制）。侧边菜单树按「分类 → 页面」两级组织，分类排序读分类目录内 sort 文件、页面排序读元信息 Sort 字段（默认配置下，语义详见配置篇 4.2 节）。

2.4 备份习惯

所有操作最终落盘，日常备份一条命令覆盖全部状态（会话目录可排除）：

tar czf /backup/raneto-$(date +%F).tar.gz -C /opt/raneto content config

三、编辑器接口实测

说明：以下接口是 Web 编辑器内部端点，格式随版本可能变化（本文对准 0.18.1）；成功响应里的 status 字段与登录接口语义相反，见 3.6 节坑点。

3.1 登录换取会话（实测）

$ curl -s -c /tmp/rn-cookies.txt -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=q1w2e3r4' http://127.0.0.1:8128/rn-login
{"status":1,"message":"Login Successful"}

口令错误（实测）：{"status":0,"message":"Invalid Username/Password Combination"}。后续请求全部携带 -b /tmp/rn-cookies.txt。

3.2 创建页面 /rn-add-page（实测）

$ curl -s -b /tmp/rn-cookies.txt -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'category=&name=s9-experiment-page' http://127.0.0.1:8128/rn-add-page
{"status":0,"message":"Page Created"}

字段：category 为目标分类目录名（根目录传空），name 为页面文件名（无需带 .md）。创建的是一个仅含文件头的空页，接着用 /rn-edit 填内容。

3.3 保存页面 /rn-edit（实测）

$ curl -s -b /tmp/rn-cookies.txt -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'file=s9-experiment-page.md' \
    --data-urlencode 'meta_title=S9 实验页' \
    --data-urlencode 'meta_sort=1' \
    --data-urlencode 'content=# S9 实验页
这是 Raneto 0.18.1 编辑器实测内容。' \
    http://127.0.0.1:8128/rn-edit
{"status":0,"message":"Page Saved"}

保存后落盘内容（实测逐字）：

---
Title: S9 实验页
Sort: 1
---
# S9 实验页
这是 Raneto 0.18.1 编辑器实测内容。

即引擎把 meta_title/meta_sort 写成元信息头再拼正文，页面 URL 为文件相对路径（本例 /s9-experiment-page），浏览器标题变为「S9 实验页 - Raneto Docs」。

3.4 创建分类 /rn-add-category（实测）

$ curl -s -b /tmp/rn-cookies.txt -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'category=s9-cat' http://127.0.0.1:8128/rn-add-category
{"status":0,"message":"Category Created"}

3.5 删除页面 /rn-delete（实测）

$ curl -s -b /tmp/rn-cookies.txt -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'file=s9-experiment-page.md' http://127.0.0.1:8128/rn-delete
{"status":0,"message":"Page Deleted"}

同时可验证路径穿越防护（实测）：传 file=../../package.json 时返回 {"status":1,"message":"Invalid file path"}，文件不会被触碰——0.18.1 的路径修复逻辑对 .. 与绝对路径一律拒绝。另外实测删除 s9-experiment-page.md 后，磁盘上出现的是 s9-experiment-page.md.del（重命名软删，非物理删除），印证 2.2 节的删除语义。

3.6 坑点：status 字段语义相反

实测对比发现两组接口的 status 语义相反：/rn-login 成功是 status:1，而四个编辑端点成功是 status:0、失败是 status:1。写批量脚本时不能套用同一判定式，建议统一按 HTTP 状态码（200/302/404）+ message 内容双重判断。

3.7 权限与开关对接口的影响（实测）

  • 未登录调用编辑端点：HTTP 302 重定向到 /login；
  • allow_editing: false 时：四个 /rn-* 编辑端点整体不注册，登录与否均 HTTP 404；
  • authentication_for_read: true 时：阅读接口（GET /、页面路由、/sitemap.xml）也要求登录，未登录 HTTP 302 到 /login。

四、站点地图与批量核查

/sitemap.xml 输出全站页面清单（含每页 lastmod、changefreq、priority），是批量核查「内容是否都被引擎识别」的快捷手段（实测片段）：

<url><loc>https://127.0.0.1:8128/usage/sorting</loc><lastmod>2026-03-11T00:00:00.000Z</lastmod><changefreq>weekly</changefreq><priority>0.8</priority></url>

注意 loc 的主机部分取自请求头推断（配置 base_url 留空时），生产环境应配好 base_url 以免提交给搜索引擎的地址带错域名。新放入 content/pages/ 的文件无需重启即可出现在 sitemap 与导航中。

五、备份、恢复与迁移操作

# 备份（内容 + 配置）
tar czf /backup/raneto-$(date +%F).tar.gz -C /opt/raneto content config

# 恢复：解包覆盖后重启服务
tar xzf /backup/raneto-2026-10-30.tar.gz -C /opt/raneto
systemctl restart raneto

# 迁移：新机装好 Node 24 与源码目录后，还原 content/ 与 config/ 即完成

进一步把 content/ 纳入 Git 仓库即可获得页面级版本历史与回滚能力（git -C /opt/raneto/content log -- pages/usage/sorting.md），这是文件型知识库相对数据库型引擎最大的运维红利；需要引擎内置版本历史的场景请回看 《Raneto 0.18.1 介绍与选型指南》 的对比结论。

六、排障实录

以下条目均为本机 0.18.1 实例部署运维过程中实际遇到或验证过的问题，按「现象 → 定位 → 处置」记录。

6.1 启动即崩：TypeError: Cannot read properties of null (reading 'port')

现象（实测完整回显）：

file:///opt/raneto/server.js:17
  console.log(`HTTP server listening on port ${server.address().port}`);
                                                               ^

TypeError: Cannot read properties of null (reading 'port')
    at Server.<anonymous> (file:///opt/raneto/server.js:17:64)

定位：监听失败导致回调里 server.address() 为 null，根因九成是端口被占（真实错误 EADDRINUSE 被空指针报错掩盖，这是 0.18.1 的报错体验问题）。处置：ss -ltnp | grep <端口> 查占用方，换端口或停对方；用 systemd 管理时 journalctl -u raneto -n 50 看到的也是同一报错。

6.2 启动即崩：Config validation failed

现象（实测回显，多错并列）：

Error: Config validation failed:
  - config.secret must be at least 16 characters
  - config.content_dir "/opt/raneto/content/nonexist" does not exist or is not accessible
  - config.credentials must be a non-empty array when authentication is enabled

处置：按报错逐项补齐——secret 加长到 16 字符以上、content_dir 指向真实存在的目录、authentication: true 时 credentials 至少一组账号。校验规则全集见配置篇 1.2 节。

6.3 本机能开、远程打不开

定位（实测）：不带 HOST 环境变量启动时默认只绑回环地址，ss -ltn 显示 LISTEN 127.0.0.1:8136。处置：启动环境显式加 HOST=0.0.0.0（systemd 单元 Environment=HOST=0.0.0.0），重启后监听地址变 0.0.0.0:<PORT>。

6.4 登录成功但不保持会话

现象：/rn-login 返回成功，刷新仍是未登录。定位：NODE_ENV=production 下会话 Cookie 带 Secure 属性（源码 app/index.js，secure: process.env.NODE_ENV === 'production'），浏览器在纯 HTTP 页面不保存不回传该 Cookie。处置：上 HTTPS 反代（推荐）；或内网裸 HTTP 场景去掉 production 环境变量。辅助核查：curl -i 看登录响应 Set-Cookie 是否含 Secure；确认 systemd 注入的 SESSION_SECRET 与配置文件 secret 一致（密钥变更会使既有会话全部失效）。

6.5 编辑接口被拒：先分清三种拒绝

返回原因处置
302 → /login未登录（或会话过期）先 /rn-login 换会话 Cookie
404allow_editing: false，编辑路由未注册配置篇 6.2 节，按需改回 true 并重启
{"status":1,"message":"Invalid file path"}目标路径含 ../绝对路径，被安全防护拦截传相对 content/pages 的常规路径

6.6 突发 HTTP 429

v0.18.1 内建全局限速：每 IP 每分钟 200 次请求（源码常量 RATE_LIMIT_MAX_REQUESTS = 200），超限返回 429。被限速多半意味着前置有高并发抓取或监控探测频率过高，调整探测方频率或在前置反代层分流，不建议动源码阈值。

6.7 页面改了不生效

按顺序排查：确认改的是 config.content_dir 指向的目录（生产上常见多套目录并存）；确认文件扩展名为 .md；浏览器强刷（主题静态资源有缓存）；若用了 show_on_home_default: false 且页面未写 ShowOnHome，首页不展示但直接访问 URL 仍可达——这是配置行为而非故障。

6.8 界面语言没变中文

locale: 'zh' 改后需重启进程；app/translations/zh.json 控制界面文案，正文内容语言与该配置无关；目录标题 "Table of Contents" 来自 markdown-toc 组件，当前版本不随 locale 翻译（实测确认）。

七、日常巡检清单

ss -ltnp | grep <端口>          # 监听存在
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<端口>/   # 首页 200
systemctl is-active raneto      # 服务活跃
journalctl -u raneto -n 50 --no-pager   # 近期日志无异常栈
find /opt/raneto/content/pages -name '*.del' -mtime +30 -delete   # 清理超期软删文件
tar czf /backup/raneto-$(date +%F).tar.gz -C /opt/raneto content config   # 每日备份

以上四篇构成 Raneto 的完整交付链路。需要横向了解其他轻量知识库的命令行与 API 形态，可对照 《flatnotes v5.5.5 常用工具与 API 详解》、《Otter Wiki 2.26.1 常用命令与页面语法详解》 与 《Wiki.js 2.5 API 使用详解》——三者均有正式 API 或 CLI 体系，而 Raneto 的可编程界面就是本文第三节的编辑器端点加文件系统本身。