Wiki.js

关键初始配置

• 站点 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 — 路径中包含特殊字符，建议使用小写字母和数字
• 导入后变慢 — 正在进行搜索重新索引，可等待或检查管理员 > 工具菜单