🔧 维护指南

一、系统要求

💡 推荐：使用 nvm install 18 && nvm use 18 安装 Node.js，避免全局污染。

二、日常使用流程

2.1 完整开发流程（推荐）

# 1. 拉取最新代码
    git pull origin source
    
    # 2. 编辑 Wiki 文件
    #    - 编辑 .wiki/concepts/xxx.md
    #    - 或新建文件
    
    # 3. 一键同步 + 预览
    wiki-sync.bat
    
    # 4. 访问 http://localhost:4000 确认效果
    
    # 5. 推送（CI 自动部署）
    git add -A
    git commit -m "feat: 更新 xxx"
    git push origin source
    

2.2 仅预览（不修改文件）

wiki-sync.bat --dry-run
    

2.3 仅本地构建

# 不执行 git 操作
    node scripts/wiki-to-hexo.js
    hexo generate
    hexo server
    

三、Wiki 编辑规范

3.1 新建 Wiki 文章

Step 1：在 .wiki/ 对应目录下创建文件

.wiki/
    ├── concepts/       ← 技术概念
    ├── entities/       ← 实体随笔
    ├── comparisons/     ← 对比分析
    ├── queries/        ← 查询结果
    └── raw/            ← 原始存档（不发布）
    

Step 2：填写 frontmatter（必须完整）

---
    title: RAG检索增强生成        # 页面标题（必填）
    type: concepts                # 固定为所在目录名（必填）
    tags: [AI, LLM, RAG]         # 标签（必填）
    created: 2025-09-12          # 创建日期（必填，YYYY-MM-DD）
    updated: 2025-09-12          # 更新日期（必填，YYYY-MM-DD）
    summary: 一句话描述           # 摘要（可选）
    aliases: [别名1, 别名2]      # 别名（可选）
    related: [相关页面1, 相关页面2] # 关联页面（可选）
    ---
    

⚠️ **日期格式必须为 YYYY-MM-DD**，不能写成 YYYY/MM/DD，否则 hexo generate 无法生成文章！

Step 3：使用 WikiLink 链接相关内容

## RAG 简介
    
    RAG（检索增强生成）结合了 [[信息检索]] 和 [[大语言模型]] 的优势...
    
    ## 相关技术
    
    - [[向量数据库]]
    - [[Embedding模型]]
    

3.2 WikiLink 语法

匹配优先级：

1. 精确匹配文件名（不含扩展名）
2. 大小写不敏感匹配
3. 前缀模糊匹配
4. 降级为路径搜索

3.3 编辑规则

四、Dify 知识库管理

4.1 本地访问 Dify

4.2 同步 Wiki 到 Dify

# 方式一：使用脚本（推荐）
    node tools/sync-wiki-to-dify.js
    
    # 方式二：手动同步
    # 1. 打开 http://localhost/v1/datasets
    # 2. 进入知识库 "mmo的知识库"
    # 3. 点击「同步」按钮
    

💡 同步后 Dify 会自动重新索引，约需 1-2 分钟。

4.3 Dify 应用信息

五、Pagefind 搜索

5.1 工作原理

Pagefind 在 public/ 目录中建立静态全文索引，支持模糊搜索、分词搜索。

5.2 构建时机

5.3 验证搜索

1. 访问 https://mornikar.github.io/pagefind/
2. 输入关键词测试搜索
3. 确认 Wiki 文章能被检索到

六、Tailscale 公网访问

6.1 设备信息

6.2 使用条件

1. 电脑和手机都安装 Tailscale
2. 都登录同一个 GitHub 账号
3. 双方设备都显示「Connected」

6.3 访问方式

手机访问博客：https://mornikar.tail7ee4f8.ts.net
    手机访问 Dify：http://mornikar.tail7ee4f8.ts.net:18789
    

七、GitHub Pages 部署状态

手动触发 CI

如果 CI 未自动触发：

1. 打开 https://github.com/mornikar/mornikar.github.io/actions
2. 点击「Wiki-Hexo 自动部署」
3. 点击「Run workflow」→ 选择 source 分支 → 运行

八、Giscus 评论系统维护

8.1 评论数据位置

评论存储在 GitHub Discussions 中：

• 仓库地址：https://github.com/mornikar/mornikar.github.io/discussions
• 每个页面自动对应一个 Discussion

8.2 管理评论

1. 打开仓库 Discussions 页面
2. 可以对评论进行编辑、删除、置顶等操作
3. 可以设置分类、添加标签

8.3 修改 Giscus 配置

编辑 themes/arknights/_config.yml 中的 giscus 配置：

giscus:
      enable: true
      repo: mornikar/mornikar.github.io
      repo_id: R_xxxxxxxxxxxxx
      category: Announcements
      category_id: DIC_xxxxxxxxxxxxx
      mapping: pathname
      input_position: top
      theme: preferred_color_scheme
    

8.4 常见问题

九、CMS 管理面板

9.1 访问方式

访问 https://mornikar.github.io/admin/ 进入自定义 CMS 面板（GitHub OAuth 登录）。

9.2 文章集合

9.3 Wiki 集合（v4.2 新增）

9.4 保存逻辑差异

十、URL 卫生规范（v4.2 新增）

10.1 slugify 自动清洗

wiki-to-hexo.js 的 slugify() 函数会自动执行以下清洗：

10.2 WikiLink URL 来源

重要变更：WikiLink 的 URL 现在统一使用 wiki-index.json 中的 url 字段，不再客户端拼接。

旧流程：wiki-chat.js 中 slugify(title) → 拼 URL（可能和服务端不一致）
    新流程：wiki-to-hexo.js 生成 wiki-index.json（含 url 字段）→ wiki-chat.js 读取 url
    

10.3 URL 格式

正确格式：/YYYY/MM/DD/Category/YYYY-MM-DD-标题/
    错误格式：/YYYY/MM/DD/Category/--标题-/    ← 双横线+尾横线
    错误格式：/YYYY/MM/DD/Category/标题\_转义/  ← 下划线转义残留
    

10.4 定期数据质量检查

# 1. 检查 wiki-index.json 中有无 URL 异常
    node scripts/wiki-to-hexo.js --test
    
    # 2. 检查 hexo generate 文件数是否稳定（约 240）
    npx hexo clean && npx hexo generate 2>&1 | Select-String "files generated"
    
    # 3. 强制重建（自动清理含双横线的旧文件）
    node scripts/wiki-to-hexo.js --force
    

十一、本地命令速查