Wiki.js

帮助用户部署和管理 Wiki.js 文档站点,避开常见配置陷阱。

已扫描
适合谁
技术团队负责人、知识库管理员
不适合谁
无服务器部署经验的初学者、仅需简单笔记记录的个人用户
国内可用性
需网络配置。可能需要网络配置或第三方服务可访问。
安装难度
新手友好(★☆☆)。基于终端操作、依赖、API Key 和本地环境要求的初步判断。

安装与下载

openclaw skills install @ivangdavila/wiki-js

Skill 说明

命令、参数、文件名以原文为准

关键初始配置

  • 站点 URL 必须在首次设置时就正确配置 — 后期修改会导致所有内部链接失效,无法轻松修复
  • 多用户环境请使用 PostgreSQL 而非 SQLite — SQLite 在并发写入时会加锁
  • HTTPS 由反向代理终止 — Wiki.js 内部运行 HTTP,不要在 Wiki.js 中配置 SSL

编辑器陷阱

  • 可视化编辑器底层使用 HTML — 从 Markdown 切换回可视化会丢失格式,无法干净地切换回来
  • Markdown 编辑器是安全的默认选择 — WYSIWYG 编辑器存在渲染异常和同步问题
  • 内部链接必须包含语言前缀 — 使用 [链接](/en/path/to/page),而非仅 /path/to/page

权限陷阱

  • 拒绝规则优先于允许规则 — 重叠的规则模式可能导致意外的访问封锁
  • 页面权限规则使用路径模式匹配 — /engineering/* 匹配子页面,而 /engineering 仅为精确匹配
  • 默认的“用户”组会应用于所有新账户 — 邀请用户前请先完成配置

存储与同步

  • Git 同步默认为单向 — 仅支持 Wiki.js 向 Git 推送,外部对 Git 的修改不会同步回系统
  • 媒体文件存储在数据库中会增大备份体积 — 大型 Wiki 建议使用 S3/GCS 存储图片
  • 数据库备份即完整备份 — 所有内容、用户、权限均存储在数据库中

搜索行为

  • 搜索尊重权限控制 — 用户无法找到其无权访问的页面(可能造成困惑)
  • 搜索索引会自动重建 — 大量导入后需耐心等待,手动触发无效
  • Elasticsearch 为可选组件 — 内置数据库搜索可用,但缺乏相关性排序能力

故障排查要点

  • 登录重定向循环 — 几乎总是站点 URL 配置中的 HTTPS/HTTP 不匹配导致
  • 资源无法加载 — 站点 URL 与实际访问地址不一致
  • 创建页面后显示 404 — 路径中包含特殊字符,建议使用小写字母和数字
  • 导入后变慢 — 正在进行搜索重新索引,可等待或检查管理员 > 工具菜单
I
@ivangdavila

已收录 7 个 Skill

相关推荐