您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 綜合教學

Raneto 開源知識庫搭建全攻略：Node.js + Markdown 靜態站點，零數據庫、支援在線編輯、權限控制、自定義排序

編輯：Java 綜合教學

Raneto 知識庫從部署到進階配置：Markdown 驅動、無數據庫、團隊協作首選

Raneto 是基於 Node.js + Express + Markdown 的輕量級知識庫系統，「文件即內容、目錄即結構」，無需 MySQL/PostgreSQL，部署極簡，原生支援在線編輯、頁面排序、訪問認證、多主題切換。本文記錄在 CentOS 7/8 上從零搭建、配置自有內容、啟用編輯權限、添加登錄保護的完整實戰流程，並解決首頁亂序、靜態資源 404、後台常駐等工程化痛點。

一、架構特性速覽

特性	說明
存儲	.md 文件 + 目錄結構，Git 友好，可直接版本控制
渲染	Marked.js 服務端渲染，支援 GitHub Flavored Markdown (表格、代碼高亮、任務列表)
搜索	Lunr.js 全文索引，毫秒級響應
認證	單用戶 Basic Auth (配置文件明文/環境變量)，可擴展 OAuth/LDAP
編輯	瀏覽器端編輯器 (CodeMirror)，實時預覽，保存即生成 .md
排序	目錄下 `sort` 文件存數字權重，數字越小越靠前
主題	Handlebars 模板，可自定義 layouts/partials

二、環境準備與 Node.js 安裝 (CentOS 7/8)

# 1. 創建工作目錄
mkdir -p /usr/local/kencery/nodejs /usr/local/kencery/raneto
cd /usr/local/kencery/nodejs

# 2. 下載 Node.js 18 LTS (二進制包，無需編譯)
wget https://nodejs.org/dist/v18.20.0/node-v18.20.0-linux-x64.tar.xz
tar -xf node-v18.20.0-linux-x64.tar.xz
mv node-v18.20.0-linux-x64 node

# 3. 配置環境變量
cat >> /etc/profile <<'EOF'
export NODE_HOME=/usr/local/kencery/nodejs/node
export PATH=$PATH:$NODE_HOME/bin
export NODE_PATH=$NODE_HOME/lib/node_modules
EOF
source /etc/profile

# 4. 驗證
node -v   # v18.20.0
npm -v    # 10.8.0

三、Raneto 安裝與首啟

cd /usr/local/kencery/raneto
wget https://github.com/gilbitron/Raneto/archive/refs/tags/v0.9.0.tar.gz -O Raneto-0.9.0.tar.gz
tar -zxf Raneto-0.9.0.tar.gz
mv Raneto-0.9.0 raneto
cd raneto

# 安裝依賴 (國內鏡像加速)
npm config set registry https://registry.npmmirror.com
npm install   # 耗時 1-3 分鐘

# 首次啟動驗證
npm start
# 輸出: Raneto running on port 3000
# 瀏覽器訪問 https://:3000 應看到默認文檔站點

四、靜態資源 404 修復 (關鍵坑點)

首啟常見現象：頁面樣式全無、JS 報錯，原因是 themes/default/public/lib 目錄 (Bootstrap、jQuery、Highlight.js 等) 未隨 npm install 生成。

# 方案 A: 從 GitHub Release 下載完整包 (含 public/lib)
wget https://github.com/gilbitron/Raneto/releases/download/v0.9.0/Raneto-0.9.0-full.tar.gz
tar -zxf Raneto-0.9.0-full.tar.gz -C /tmp
cp -r /tmp/Raneto-0.9.0/themes/default/public/lib /usr/local/kencery/raneto/raneto/themes/default/public/

# 方案 B: 手動下載缺失庫 (文章提供百度網盤鏈接)
# 解壓後放入 themes/default/public/lib/

# 重啟驗證
npm start

五、配置自有知識庫內容

# 1. 創建自定義內容目錄
cd /usr/local/kencery/raneto/raneto
mkdir -p kencery/content

# 2. 複製默認配置文件到自定義目錄
cp example/server.js example/package.json example/config.default.js kencery/

# 3. 修改 package.json 指向自定義啟動腳本
# 編輯 /usr/local/kencery/raneto/raneto/package.json
"scripts": {
  "start": "node kencery/server.js"
}

# 4. 編輯 kencery/config.default.js 核心配置
module.exports = {
  // 站點基本信息
  site_title: '團隊知識庫',
  site_description: '內部技術規範、架構決策、最佳實踐',
  base_url: '/',                    # 反向代理子路徑時修改
  
  # 內容目錄 (關鍵)
  content_dir: 'kencery/content',
  
  # 啟用在線編輯
  allow_editing: true,
  
  # 頁面排序依據文件
  page_sort_meta: 'sort',
  
  # 權限控制 (單用戶)
  authentication: true,
  credentials: {
    username: 'admin',
    password: 'strong_password_123'  # 生產環境建議用環境變量
  },
  
  # 主題與樣式
  theme: 'default',
  google_analytics: '',
  
  # 其他
  show_git_revision: false,
  edit_github_link: ''
};

六、內容組織與排序實戰

# 目錄結構示例
kencery/content/
├── 00-首頁.md                    # 數字前綴也可排序，但 sort 文件優先級更高
├── 01-開發規範/
│   ├── sort                      # 內容: 1  → 第一組
│   ├── 01-Java編碼規範.md
│   ├── 02-Git提交規範.md
│   └── 03-代碼評審清單.md
├── 02-架構決策/
│   ├── sort                      # 內容: 2
│   ├── ADR-001-微服務拆分原則.md
│   └── ADR-002-緩存策略選型.md
└── 03-運維手冊/
    ├── sort                      # 內容: 3
    ├── 部署清單.md
    └── 故障應急預案.md

# 首頁特殊處理：不想顯示默認首頁，刪除 content/00-首頁.md，
# 在 content/ 創建 _home.md 或配置 home_page: 'custom-home' (需模板支持)

七、在線編輯與權限控制

啟用編輯：allow_editing: true 重啟後，頁面右側出現「+ 新建」、「✏ 編輯」、「🗑 刪除」按鈕。
登錄保護：配置 authentication: true + credentials，訪問任意頁面彈出 Basic Auth 對話框。
模板注入登出鏈接 (可選)：編輯 themes/default/templates/layout.hbs，在 <body> 後添加：
```
{{#if config.authentication}}
  {{#if loggedIn}}
    登出
  {{/if}}
{{/if}}
```

八、生產環境部署優化

優化項	方案
進程守護	PM2: `pm2 start kencery/server.js --name raneto --watch`，開機自啟 `pm2 startup && pm2 save`
反向代理	Nginx 代理 3000 端口，配置 SSL、Gzip、靜態資源緩存、客戶端最大體積
域名與 HTTPS	Let's Encrypt 自動續期證書，Nginx 配置 HTTP→301 HTTPS
內容版本控制	`kencery/content` 初始化 Git 倉庫，提交歷史即文檔變更記錄，可接 Webhook 觸發 CI 部署
備份策略	每日打包 `kencery/content` 上傳至對象存儲 (S3/OSS/COS)
監控告警	PM2 + Prometheus + Grafana 監控進程存活、CPU/內存、請求延遲、錯誤率

九、Nginx 反向代理標準配置

server {
    listen 80;
    server_name wiki.yourcompany.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name wiki.yourcompany.com;
    ssl_certificate /etc/letsencrypt/live/wiki.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.yourcompany.com/privkey.pem;

    client_max_body_size 10M;
    gzip on; gzip_types text/plain application/javascript text/css application/json;

    location / {
        proxy_pass https://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # 靜態資源直接由 Nginx 服務，減輕 Node.js 壓力
    location /public/ {
        alias /usr/local/kencery/raneto/raneto/themes/default/public/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

十、總結

Raneto 以 極簡部署、Markdown 原生、Git 友好、功能完備 (編輯/搜索/排序/認證) 成為中小團隊內部知識庫的性價比之選。關鍵成功因子：Node.js 版本鎖定 LTS、靜態資源 lib 目錄補全、PM2 守護 + Nginx 代理 + HTTPS、內容目錄 Git 管理。若團隊規模擴大需多用戶、細粒度權限、評論協作，可平滑遷移至 Outline、Wiki.js、Confluence 等重型方案。