Raneto 0.18.1 配置参数详解

目标：逐项讲清 Raneto 0.18.1 的配置文件 config/config.js 全部参数：默认值、作用机制、改动后的实测行为，覆盖站点信息、内容组织、搜索、认证安全、主题界面五大类共三十余项，并给出服务端环境变量与启动校验规则的完整清单。本文所有「实测」条目均在 0.18.1 真实实例上执行验证；安装过程见 《Raneto 0.18.1 npm 裸机安装部署指南》，选型背景见 《Raneto 0.18.1 介绍与选型指南》。

一、配置文件与加载机制

1.1 配置的加载路径

Raneto 没有独立的配置文件格式：server.js 直接 import config from './config/config.js'，也就是说配置本身就是一个 ES Module，可以写任意 JS 表达式（例如用 new Date().getFullYear() 生成版权年份、用 path.join 拼路径）。改动配置后需重启进程生效（无热加载）。

入口函数收到 config 后第一件事是调用 app/core/configValidation.js 做启动校验，校验失败直接抛错退出（实测回显，多项错误一次性列出）：

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

1.2 校验规则全集（v0.18.1）

二、参数总表

按 config/config.js 中出现顺序整理（默认值即官方出厂值）：

另有三个不在 config.js、但同样可配的键与四个环境变量：prefix_url（路由挂载前缀，见 3.2）、HOST、PORT、SESSION_SECRET、NODE_ENV（见第八节）。

三、站点信息与多语言类

3.1 site_title：页面标题拼接（实测）

site_title 出现在浏览器标签与页头 logo。页面标题按「页面 Title 元信息 - site_title」拼接，实测（content 目录放一个 Title: S9 实验页 的页面）：

<title>S9 实验页 - Raneto Docs</title>

3.2 base_url / path_prefix / prefix_url：三个前缀的分工

• base_url：站点对外完整地址（如 https://kb.example.com），注入模板供 %base_url% 占位符与登录跳转使用，不要带尾斜杠；留空则按请求头推断。
• path_prefix：站点挂在域名子路径时填写（如 /kb）。
• prefix_url：Express 路由的挂载点（源码 app.use(config.prefix_url || '/', router)），三者中只有它真正改变路由挂载位置；子路径场景三者往往要一起改。
• nowrap：base_url 非空时源码会用一个包装应用把请求挂到 base_url 路径下；nowrap: true（默认）跳过该包装，交给外层反向代理处理路径。经反向代理统一转发路径的部署，保持默认 nowrap: true 即可。

3.3 locale：一键中文（实测）

改为 locale: 'zh' 后界面文案切换为简体中文，登录失败等 API 消息同步变化（实测回显）：

$ curl -s -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=bad' http://127.0.0.1:8128/rn-login
{"status":0,"message":"不正确的用户名或密码"}

内置翻译共 17 种（da/de/en/es/fa/fi/fr/hu/ja/no/pl/ptbr/ro/ru/sv/tr/zh），对应文件在 app/translations/。注意 table_of_contents 生成的目录标题 "Table of Contents" 来自 markdown-toc，不随 locale 变化（实测仍为英文）。

3.4 datetime_format / rtl_layout / copyright / support_email / analytics

datetime_format 用 moment 语法控制页面日期展示；rtl_layout: true 为 RTL（从右到左）布局切换；copyright 支持写 HTML 实体（默认值里的 © 即版权符号）；support_email 非空时页脚出现 mailto 链接；analytics 直接把统计代码（含 <script> 标签）注入页面，注意 v0.18.1 的 CSP 仅放行自身与 cdnjs.cloudflare.com 的脚本，第三方统计域名需要自行在 app/index.js 的 CSP 指令中放行。

四、内容组织与排序类

4.1 content_dir 与 image_url

content_dir 指向 Markdown 内容目录，源码有两点硬约束：其一注释明确 "Cannot be an absolute path"，应以配置文件位置为基准用 path.join(__dirname, '..', 'content', 'pages') 相对拼出；其二引擎会在加载时自动补尾部路径分隔符（无需手写）。image_url（默认 /images）注册了 content_dir + image_url 的静态路由：把图片放 content/pages/images/，Markdown 里直接 ![](/images/foo.png) 或用 %image_url% 占位符引用。

4.2 排序三件套：page_sort_meta / category_sort / sort 文件

• 页面排序：读页面元信息中 page_sort_meta（默认 sort）字段，数值小者靠前；未写该字段的页面按字母序。
• 分类排序：category_sort: true 时读分类目录内的纯文本 sort 文件（内容为整数）；false 则按目录名字母序。
• 首页与菜单默认可见性：show_on_home_default / show_on_menu_default 控制未写 ShowOnHome / ShowOnMenu 元信息的页面是否出现在首页与侧边菜单，配合页面元信息可实现「部分页面仅搜索可达」的效果。

4.3 home_meta

home_meta: { title: '…', description: '…' } 覆盖首页的 <title> 与 meta description，做 SEO 或让首页标题区别于 site_title 时使用。

五、搜索类

5.1 excerpt_length（实测）

搜索结果列表中每条带一段命中摘要（page-excerpt 区块，命中词加 search-query 高亮），摘要按 excerpt_length（默认 400）截断，实测超长部分以 ... 结尾。改小可让结果列表更紧凑，改大可看更多上下文。

5.2 searchExtraLanguages 与 lunr

搜索由 lunr 2.3.9 承担，索引对象是文件名 + 全文内容；searchExtraLanguages: ['ru'] 为索引追加 lunr-languages 的语言分词器（默认俄语，可按需追加）。中文内容在默认分词下以子串匹配兜底，中小规模文档实测可用；若对中文召回率要求高，可评估追加 lunr 中文分词方案或换用数据库型引擎（对比见选型篇）。

六、认证与安全类

6.1 三态认证开关语义矩阵（实测）

这是 Raneto 配置里最容易误读的部分。三个开关的真实语义（0.18.1 源码 authenticate.mw.js 判定式为 required || config.authentication === true，配合实测验证）：

未登录直接 POST 编辑端点的回显（实测）：HTTP 302 重定向到 /login。

6.2 allow_editing：编辑器总开关（实测）

allow_editing: false 时四个编辑路由（/rn-edit、/rn-add-page、/rn-add-category、/rn-delete）根本不注册，无论是否登录一律 404（实测登录前后均 404），阅读完全不受影响。纯发布型站点（内容只走 Git 提交）建议直接关闭，攻击面最小化。

6.3 credentials 与 secret

credentials 是账号数组，支持多账号；0.18.1 起比较口令用 crypto.timingSafeEqual（防时序攻击），但口令仍为配置文件明文，务必控制文件权限并配合系统用户隔离。secret 为会话签名密钥，推荐用 process.env.SESSION_SECRET 从环境注入（systemd Environment= 行），校验要求 ≥16 字符。

6.4 Google OAuth 三件套

googleoauth: true 后登录改走 Google OAuth2（passport-google-oauth20）：oauth2.callback 是授权回调地址（需与 Google 控制台登记一致），oauth2.hostedDomain 限定组织域名，google_group_restriction.enabled: true 时额外校验调用者是否属于 group_name 指定的 Google Group（api_key 为 Admin SDK 密钥）。启用 OAuth 后编辑端点的认证中间件自动切换为 OAuth 强制模式（源码逻辑），本地 credentials 同时保留可作为兜底。

七、主题与界面类

7.1 theme_dir / theme_name / public_dir

默认使用 npm 包 @raneto/theme-default 的 dist 子目录。自定义主题两种方式：本地目录主题（theme_dir 指向自定义目录、theme_name 指向其子目录名）或直接发布 npm 主题包。public_dir 默认取 theme_dir + theme_name + public，主题的 CSS/JS 静态资源由该目录提供。

7.2 table_of_contents 与 menu_on_pages（实测）

table_of_contents: true 后引擎按页面标题层级在正文开头注入目录（实测注入片段）：

<h4 id="table-of-contents">Table of Contents</h4>
<ul>
  <li><a href="#第一节-标题">第一节 标题</a>…</li>
</ul>

table_of_contents_options 透传给 markdown-toc，常用 maxdepth（目录深度）、firsth1（是否收录一级标题）、append（目录标题文案）。menu_on_pages: true（默认）在页面左侧渲染全站菜单树，menu_on_page_collapsible: true 让分类可折叠——窄屏文档站可把两者关掉换取阅读宽度。

7.3 variables：全站 Markdown 变量（实测）

variables 数组定义 {name, content} 对，之后全站 Markdown 中的 %name% 会被替换为 content。实测定义 support_email: 'admin@example.com' 后，页面里的 %support_email% 渲染为 admin@example.com。适合统一维护邮箱、内网跳板地址、版本号等重复信息。

八、服务端环境变量

九、生产推荐配置骨架

把以上实测结论收敛为一份可直接落地的 config/config.js 骨架（生产环境）：

const config = {
  site_title: 'MyTeam KB',
  base_url: 'https://kb.example.com',   // 反代对外域名，无尾斜杠
  nowrap: true,                          // 路径由反代处理
  path_prefix: '',
  support_email: 'ops@example.com',
  copyright: 'Copyright © 2026 MyTeam',
  excerpt_length: 400,
  page_sort_meta: 'sort',
  category_sort: true,
  show_on_home_default: true,
  show_on_menu_default: true,
  theme_dir: path.join(__dirname, '..', 'node_modules', '@raneto/theme-default'),
  theme_name: 'dist',
  content_dir: path.join(__dirname, '..', 'content', 'pages'),
  public_dir: path.join(theme_dir, theme_name, 'public'),
  image_url: '/images',
  analytics: '',
  allow_editing: true,                   // 纯发布站改 false
  authentication: true,
  authentication_for_edit: true,
  authentication_for_read: false,        // 全私库改 true
  googleoauth: false,                    // 有 Google Workspace 建议启用
  secret: process.env.SESSION_SECRET,
  credentials: [
    { username: 'admin', password: 'q1w2e3r4' },  // 演示口令，上线必须更换
  ],
  locale: 'zh',
  searchExtraLanguages: ['ru'],
  datetime_format: 'YYYY-MM-DD',
  rtl_layout: false,
  home_meta: {},
  variables: [
    { name: 'support_email', content: 'ops@example.com' },
  ],
  table_of_contents: true,
  table_of_contents_options: { maxdepth: 3 },
  menu_on_pages: true,
  menu_on_page_collapsible: true,
};

对应的环境变量（systemd 注入）：NODE_ENV=production、HOST=0.0.0.0、PORT=8080、SESSION_SECRET=<32+ 位随机串>。配置改动的行为语义拿不准时，直接回到本文对应小节对照实测结论；编辑器接口的具体请求格式与更多运维排障见 《Raneto 0.18.1 常用操作与排障指南》。

同类产品的配置体系可横向参考 《Wiki.js 2.5 配置参数详解》、《flatnotes v5.5.5 配置参数详解》 与 《Otter Wiki 2.26.1 配置参数详解》——三者分别代表「环境变量为主」「环境变量+YAML」「Web 管理界面」三种配置风格，Raneto 则是其中「配置即代码」路线的最典型实现。