Raneto 0.18.1 npm 裸机安装部署指南

目标：在一台 Linux 服务器上以 npm 裸机形态（官方 Get Started 主推方式）从零部署 Raneto 0.18.1 Markdown 知识库：环境要求与 Node.js 24 准备、源码获取、依赖安装、最小配置、启动验证、systemd 常驻、生产加固与排障实录。文中命令均在本机实测执行，输出为实测回显；为什么选 Raneto 以及与其他知识库的量化对比见 《Raneto 0.18.1 介绍与选型指南》。

一、部署规划与环境要求

1.1 形态决策

Raneto 官方提供两种安装形态：一是源码安装（git clone 仓库 → npm install → npm start，官网 Get Started 给出的默认路径），二是官方发布的预构建运行包。本文采用源码 + npm 裸机形态，理由有三：其一，这是官网首推的入门路径，文档与示例均以此为准；其二，裸机形态下 content/、config/ 目录就是全部状态，备份与版本管理最直接；其三，便于后续按 C1 篇逐项调试配置。预构建包形态的 Compose 部署叙事可参考同类产品的 《Otter Wiki Docker Compose 部署指南》 与 《Wiki.js Docker Compose 部署指南》 对照使用。

1.2 硬性环境要求（v0.18.1）

1.3 实测环境说明

本文实测环境为 Linux 服务器（x86_64），Node.js 与 npm 版本如下（实测回显）：

$ node -v
v24.22.1
$ npm -v
11.19.1

若服务器尚无 Node.js 24，两种常见获取路径任选其一：一是发行版包管理之外用 NodeSource 官方仓库脚本安装 Node 24 LTS（curl -fsSL https://deb.nodesource.com/setup_24.x | bash - 后 apt-get install -y nodejs）；二是从 nodejs.org 下载对应架构的 .tar.xz 二进制包解压到 /usr/local。两种方式完成后都务必用 node -v 确认版本号 ≥ v24.0.0——Raneto 0.18.1 已全面转向 ES Modules，低版本 Node 会在启动阶段直接报语法/模块错误，无法运行。

⚠️ 网络说明：本实验所在的网络环境访问国外源不稳定，文中 npm install 全程使用国内 npmmirror 镜像源（--registry=https://registry.npmmirror.com）实测可用；直连 npmjs.com 或 GitHub 下载缓慢时，也可为 npm/git 配置代理后再走官方源。

二、获取源码

2.1 下载方式

优先使用官方 GitHub 仓库的 tag 压缩包（不携带 Git 历史，体积小，1.09 MB）：

$ curl -sL -o raneto-0.18.1.tar.gz https://codeload.github.com/ryanlelek/Raneto/tar.gz/refs/tags/0.18.1
$ ls -l raneto-0.18.1.tar.gz
-rw-r--r-- 1 root root 1092623 Oct 30 14:44 raneto-0.18.1.tar.gz

习惯用 Git 的也可直接克隆主分支（注意 0.18.0 起默认分支已从 master 改为 main）：

$ git clone https://github.com/ryanlelek/Raneto.git raneto-0.18.1

2.2 解压与目录结构

$ tar xzf raneto-0.18.1.tar.gz
$ mv Raneto-0.18.1 /opt/raneto
$ ls /opt/raneto
CHANGELOG.md  CONTRIBUTING.md  Dockerfile  LICENSE  Makefile  README.md  SECURITY.md
app  config  content  eslint.config.js  logo  package-lock.json  package.json  server.js  test

关键目录职责：

三、安装依赖

进入安装目录执行 npm install，生产服务器可加 --omit=dev 跳过测试/检查类开发依赖（官方预构建包的构建即采用 npm install --omit=dev）。本文为保留完整开发工具链，按默认全量安装（实测回显）：

$ cd /opt/raneto
$ npm install --registry=https://registry.npmmirror.com --no-audit --no-fund
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated glob@7.2.3: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
npm warn deprecated glob@10.5.0: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me

added 680 packages in 3s
npm warn install-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn install-scripts   unrs-resolver@1.11.1 (postinstall: napi-postinstall unrs-resolver 1.11.1 check)

回显解读：若干 deprecated 警告来自深层依赖的旧版 glob/inflight，属上游已知情况，不影响运行；added 680 packages 说明依赖树共 680 个包，npmmirror 源下 3 秒完成。若漏装依赖直接启动，会得到模块加载器报错（实测关键行）：

node:internal/modules/cjs/loader:1568
  throw err;

此时回到 npm install 补装依赖即可。

四、最小配置

4.1 必改项：登录口令与会话密钥

编辑 config/config.js。v0.18.1 起启动时会做配置校验，以下三项不过校验直接拒绝启动：

1. secret（会话签名密钥）必须 ≥ 16 字符；
2. credentials 必须是非空数组且每项都有 username/password；
3. content_dir 指向的目录必须存在。

官方默认配置自带 admin/password 弱口令，必须修改。本文示例使用演示账号 admin / q1w2e3r4（生产环境请换成强口令并考虑叠加 Google OAuth）：

  secret: 'change-me-to-a-long-random-string-32chars',

  credentials: [
    {
      username: 'admin',
      password: 'q1w2e3r4',
    },
  ],

💡 技术拓展：secret 用于 express-session 的会话 Cookie 签名（HMAC），泄露或过短都会让会话可被伪造；生产环境更推荐不写死在配置文件里，而是 secret: process.env.SESSION_SECRET，由 systemd 的 Environment= 行注入。v0.18.1 的登录口令比较已改用 crypto.timingSafeEqual 防时序侧信道，但口令本身仍以明文存于配置文件，这是 Raneto 的设计取舍——文件即配置，务必把 config/ 纳入最小权限管理。

4.2 站点信息与监听

站点标题改为自己团队的名字即可（影响浏览器标签与页头）：

  site_title: 'MyTeam Knowledgebase',

服务监听由环境变量控制而非配置文件：PORT（默认 8080）、HOST（默认 127.0.0.1）。特别提醒：默认只绑定回环地址，远程浏览器将无法访问，对外服务必须显式 HOST=0.0.0.0（见第六节实测）。端口规划上，若 8080 已被占用可换任意空闲端口，本文实测使用 8128。

五、首次启动与验证

5.1 启动

$ cd /opt/raneto
$ HOST=0.0.0.0 PORT=8128 node server.js
HTTP server listening on port 8128

HTTP server listening on port 8128 即启动成功。此时另开终端验证监听与页面：

$ ss -ltn | grep 8128
LISTEN 0      511         0.0.0.0:8128        0.0.0.0:*    users:(("node",pid=1570136,fd=20))
$ curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8128/
HTTP 200
$ curl -s http://127.0.0.1:8128/ | grep -oE '<title>[^<]*</title>'
<title>Raneto Docs</title>

morgan 访问日志会同步打印到前台（实测回显）：

GET / 200 21.525 ms - 8770

5.2 登录验证

浏览器访问 http://<服务器IP>:8128/login，输入 admin / q1w2e3r4 登录；命令行等价验证（实测回显）：

$ curl -s -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"}

口令错误时的回显（实测）：

$ curl -s -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'username=admin&password=wrongpass' http://127.0.0.1:8128/rn-login
{"status":0,"message":"Invalid Username/Password Combination"}

登录态建立后，自带示例文档（What is Raneto、Getting Started、usage 分类等）应全部可读，右上角出现 Edit 入口即编辑器可用。

5.3 停止与前台运行说明

前台运行按 Ctrl+C 即停。生产环境不要用前台会话跑服务，进入下一节用 systemd 常驻。

六、systemd 常驻与生产加固

6.1 创建 systemd 单元

新建 /etc/systemd/system/raneto.service（用户、路径按实际调整）：

[Unit]
Description=Raneto Markdown Knowledgebase
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/raneto
Environment=NODE_ENV=production
Environment=HOST=0.0.0.0
Environment=PORT=8080
Environment=SESSION_SECRET=change-me-to-a-long-random-string-32chars
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=5
User=raneto
Group=raneto

[Install]
WantedBy=multi-user.target

要点：WorkingDirectory 必须是安装目录（会话文件写入其下 ./sessions/，相对路径依赖工作目录）；SESSION_SECRET 与 config.js 中 secret: process.env.SESSION_SECRET 的写法配合，避免密钥落盘。创建专用系统用户并赋权后，启用并启动：

useradd -r -s /usr/sbin/nologin raneto
chown -R raneto:raneto /opt/raneto
systemctl daemon-reload
systemctl enable --now raneto
systemctl status raneto

常用运维命令：systemctl restart raneto、journalctl -u raneto -f（跟踪启动日志，应看到 HTTP server listening on port 8080）。

6.2 生产模式与会话 Cookie 的 HTTPS 要求

NODE_ENV=production 时，v0.18.1 的会话 Cookie 会带上 Secure 属性（源码 app/index.js 中 secure: process.env.NODE_ENV === 'production'）。这意味着纯 HTTP 访问下浏览器将拒绝保存会话 Cookie——表现为登录接口返回成功但刷新后仍是未登录状态。因此生产模式必须由反向代理终结 TLS 提供 HTTPS（Nginx/Caddy 均可），或在确定内网裸 HTTP 运行时保持 NODE_ENV 为非 production 并接受 Cookie 不带 Secure 的代价。其余生产安全基线 v0.18.1 已内建：helmet 安全响应头与 CSP、每 IP 每分钟 200 次的接口限速、登录口令时序安全比较、路径穿越防护。

6.3 资源基线（实测）

加载首页并完成一次全文搜索后，进程资源占用实测（ps -o pid,rss,vsz,etime,comm 回显）：

    PID   RSS    VSZ     ELAPSED COMMAND
1572953 116044 1764800     00:02 MainThread

RSS ≈ 113 MB，1C1G 规格即可稳定承载一个中小型文档站；内存基线随内容量缓增（搜索索引在请求期构建），大文档量场景建议 2 GB 起步。

七、内容管理与备份

7.1 内容目录即知识库

所有页面都在 content/pages/：目录即分类（分类内放纯文本 sort 文件写整数控制排序），.md 文件即页面，文件头 --- 块内写 Title/Sort 元信息。上线时删除自带示例、放入自己的 Markdown：

rm /opt/raneto/content/pages/*.md
rm -rf /opt/raneto/content/pages/usage /opt/raneto/content/pages/tutorials
cp /path/to/your-docs/*.md /opt/raneto/content/pages/
chown -R raneto:raneto /opt/raneto/content

图片等附件放 content/pages/images/ 子目录（该路径已被注册为 /images 静态路由）。页面、分类的日常增删改既可在 Web 编辑器完成，也可直接操作文件后无需重启（Raneto 每次请求实时读盘，改完即生效）。

7.2 备份与迁移

Raneto 的全部状态只有三处：content/（内容）、config/config.js（配置）、sessions/（可丢弃的会话缓存）。备份与迁移因此简单到只需一次拷贝：

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

迁移到新服务器 = 安装 Node 24 + 拷贝源码目录 + 还原 content/ 与 config/ + npm install + 启动，无任何数据导出导入步骤。

八、升级方法

小版本升级（如 0.18.x 内）流程：下载新 tag 压缩包 → 覆盖 app/、server.js、package.json（保留自己的 config/、content/）→ npm install → 重启。跨大版本务必先读 CHANGELOG.md：0.17 → 0.18 是破坏性升级（默认端口 3000 改 8080、ES Modules 化、pm2/bin/raneto 入口被移除、Node 最低版本两连跳至 v24、分支更名 main），旧版自定义主题与 bin/raneto 启动脚本需按新版重做。

九、排障实录

以下问题均在本机部署过程中实际遇到并定位，按「现象 → 定位 → 处置」沉淀。

9.1 端口被占用：启动即报 TypeError

现象：启动进程立刻崩溃，报错如下（实测完整回显）：

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 <端口> 找到占用进程换端口或停掉对方；同机多实例时为每个实例分配独立 PORT。

9.2 配置校验失败：拒绝启动

现象：启动即抛错退出（实测回显，多项错误会一次性列出）：

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（目录需真实存在）、credentials（至少一组账号密码）后重启即可。

9.3 远程无法访问：默认只绑回环

现象：本机 curl 正常、远程浏览器打不开。定位（实测）：不带 HOST 启动后 ss -ltn 显示监听地址为回环：

LISTEN 0      511        127.0.0.1:8136       0.0.0.0:*

处置：启动环境补 HOST=0.0.0.0（systemd 单元中已含），重启后监听地址变为 0.0.0.0:<PORT>。

9.4 登录成功但不保持会话

现象：/rn-login 返回成功、刷新页面仍是未登录。定位：NODE_ENV=production 下会话 Cookie 带 Secure 属性，浏览器在纯 HTTP 页面上不保存不回传。处置：给站点配置 HTTPS 反代（推荐），或内网环境临时去掉 production 标识。关联排查手段：curl -i 看登录响应的 Set-Cookie 行是否带 Secure，以及 config.js 的 secret 是否与 systemd 注入的 SESSION_SECRET 不一致（签名密钥变化会使旧会话全部失效）。

9.5 Node 版本过低无法启动

现象：启动报 ES Modules 语法/加载错误。定位：0.18.1 要求 Node ≥ v24 LTS（package.json engines 为 node >=23.14.0，且 type: module）。处置：升级 Node 24 后重试，勿用旧版 Node 硬跑。

至此一台 Raneto 知识库服务器已就绪。下一步建议通读 《Raneto 0.18.1 配置参数详解》 把 config/config.js 的三十余个参数按需调优，再通过 《Raneto 0.18.1 常用操作与排障指南》 掌握编辑器接口与日常内容运维；选型背景可回看 《Raneto 0.18.1 介绍与选型指南》。