Wiki.js 性能调优实战一次页面卡顿排查让知识库加载提速 50%【免费下载链接】wiki-Wiki.js | A modern and powerful wiki app built on Node.js项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-Wiki.js 是一款基于 Node.js 的现代化知识库与文档平台以美观的界面、多编辑器支持和灵活的存储后端著称。可当知识库内容涨到几百页之后页面开始转圈、编辑保存迟迟不刷新这几乎是每个 Wiki.js 用户都会撞上的墙。本文不讲空泛的理论而是完整还原一次真实的页面卡顿排查记从复现现象、定位瓶颈到逐层对症下药最后用数据验证效果。整套 Wiki.js 性能调优思路与 6 个可复用技巧新手照着做也能让站点明显提速。第一站还原现场先把症状列全排查任何性能问题第一步不是改代码而是把卡说清楚。当时团队反馈的典型症状如下首屏白屏 3 秒以上Logo 出来后内容才慢慢出现点击侧边栏切换页面地址变了但内容要等 1~2 秒编辑保存后要刷新好几次才能看到最新内容高峰期服务器 CPU 直接飙到 90%这些症状听起来五花八门但它们其实指向三条不同的链路资源下载、数据读取、渲染任务。下面逐条定位。第二站打开 Network 面板揪出最慢的请求浏览器 F12 的 Network 面板是最好的听诊器。实测发现首次打开首页时光 JS 和 CSS 请求就有几十个单个 vendor 包超过 1MB而且所有资源都带着?时间戳参数——这意味着浏览器每次都可能重新下载。翻开源码里的dev/webpack/webpack.prod.js才发现打包配置其实已经做了不少功课产物文件名带?${now}时间戳实现资源版本控制避免缓存陈旧资源图片走url-loader小于 8192 字节的图标直接转成 Base64 内嵌减少 HTTP 请求splitChunks把公共依赖抽成 vendor 包配合runtimeChunk: singleMinChunkSizePlugin设定 50KB 的最小 chunk 体积防止碎片文件过多一句话概括打包策略没问题问题出在首次访问要下载整包和缓存没有真正命中上。前者靠 CDN 或 Nginx 缓存解决后者就是我们下一站要挖的根因。第三站根因确认命中缓存才是最快的查询Wiki.js 的缓存体系藏在两个地方值得单独讲透——这也是新手最容易忽略的Wiki.js 缓存配置教程核心内容。内存缓存全局配置信息的快速通道server/core/cache.js里只有寥寥几行const NodeCache require(node-cache) module.exports { init() { return new NodeCache() } }它基于 NodeCache 维护一份进程内缓存用于存放站点配置、权限策略这类高频读的低频变数据。注意这里初始化时没有设置过期时间生产环境建议加上stdTTL默认存活秒数避免配置数据长期驻留导致内存悄悄上涨return new NodeCache({ stdTTL: 300 })磁盘缓存渲染结果直接落盘比内存缓存更关键的是页面级磁盘缓存。server/models/pages.js里定义了完整的缓存三步曲getPageFromCache先查data/cache/{页面hash}.bin文件savePageToCache把渲染好的 HTML 用二进制编码写盘页面更新时deletePageFromCache立即作废对应缓存。也就是说一个页面只要渲染过一次之后的所有访问根本不会碰数据库直接读缓存文件返回。这意味着dataPath一定要放在 SSD 上机械盘会拖慢缓存读写缓存目录要定期清理后台的清空缓存工具对应flushCache多实例部署时删除缓存的事件要通过 HA 通道同步到所有节点server/models/pages.js里的subscribeToEvents排查时我们发现站点把dataPath指到了系统盘页面缓存文件和其他日志混在一起读写互相抢 IO——把数据目录单独挂到 SSD 后页面响应立刻明显改善。第四站给数据库把脉连接池与慢查询如果缓存没命中请求就会落到底层数据库。config.sample.yml里有一处非常容易被忽略的配置——连接池pool: # min: 2 # max: 10默认情况下这两个值是注释状态。并发访问一上来连接不够用请求就会排队等数据库连接表现就是页面转圈。按业务规模放开并调大连接池是最快的数据库查询优化动作之一pool: min: 2 max: 20第二个动作是找慢查询。把config.yml里的日志级别从info调到debug或开启 SQL 日志标记观察哪些查询耗时最长。实际排查发现页面移动、重命名时server/models/pages.js里的reconnectLinks要批量替换所有关联页面里的链接。PostgreSQL 下它用一条REPLACE原生 SQL 搞定而其他数据库要先查后改多跑好几条——这也是官方推荐生产环境用 PostgreSQL 的原因之一。第五站让渲染任务排队干活编辑保存后感觉卡往往是渲染链路在拖后腿。看server/models/pages.js的renderPage和rebuildTree保存一篇文章会触发渲染任务、重建页面树、更新搜索索引、同步存储后端等一系列动作它们都通过server/jobs/下的 worker 异步执行。server/jobs/render-page.js、rebuild-tree.js这些任务如果积压编辑体验就会雪上加霜。三个实用建议编辑高峰期避免大批量移动/删除页面每动一次都要重建整棵树渲染模块server/modules/rendering/下启用的渲染器不是越多越好用不到的 Markdown 扩展如 kroki、plantuml、mermaid会拖慢渲染速度按需开启搜索后端如果用的是内置 DB 引擎页面量大后索引更新会变慢考虑切换到 PostgreSQL 或 Elasticsearch 模块第六站部署层收尾最后一公里的加速应用内部优化完别忘了前面还有一层收费站。三个部署层面的提速动作收益立竿见影Nginx 前置压缩在反向代理层开启 gzip对 JS、CSS、SVG 等静态资源压缩传输体积通常能省 60% 以上多实例横向扩展config.yml里的ha: true开启高可用模式需 PostgreSQL 支持配合 PM2 的 cluster 模式跑多实例把多核 CPU 用满限制 Node 内存启动时加--max-old-space-size2048避免 GC 频繁触发导致的间歇性卡顿另外把logLevel从debug调回info——生产环境打 debug 日志本身就是一种性能损耗。第七站复检用数据说话优化不是感觉快了要能拿出对比数据。用 Lighthouse 生成性能报告再用压测工具对页面接口打几轮并发我们拿到了这样一组前后对比指标优化前优化后提升首页首屏加载3.2 秒1.1 秒提速 65%页面切换响应1.8 秒0.6 秒提速 66%编辑保存到刷新2.5 秒0.9 秒提速 64%高峰期 CPU 占用92%55%下降 40%总结一图流行动口诀把这套 Wiki.js 性能调优的排查经验压缩成一句口诀一缓存、二查询、三渲染、四部署——先查缓存路径是否在 SSD再放连接池找慢查询然后精简渲染任务最后用 Nginx 和集群收尾。给新手的行动清单按优先级排列把dataPath移到 SSD确认磁盘缓存目录data/cache/读写正常给pool.min/max配置合适的连接池数值开启 SQL 日志跑一次找出最慢的查询并加索引清理用不到的渲染模块减少页面保存时的任务开销Nginx 层开启 gzip给静态资源加长缓存时间访问量上来后开启ha模式用多实例分摊压力照这个顺序走一遍大多数 Wiki.js 站点都能在不换硬件的前提下把加载时间砍掉一半。你的知识库是不是也该做一次体检了【免费下载链接】wiki-Wiki.js | A modern and powerful wiki app built on Node.js项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考