VuePress vdoing 私密文章权限控制：可见性收敛与路由门禁-北京尧图网络

1. 保密文章这件事先想清楚要防谁我最近在整理一套基于vuepress-theme-vdoing的内部知识库里面混着一批不该公开的页面——报价表、内部复盘、几个还没上线的方案草稿。这些页面和普通文章一起躺在docs目录里靠主题自动生成侧边栏和分类结果就是一构建完谁打开站点都能在目录里看见标题点进去全文都在。这时候我才认真去研究“保密文章”到底该怎么在 vdoing 里做尤其是能不能不碰主题源码、只在 vue 配置层面解决。结论先放这儿完全可以通过配置一个enhanceApp.js搞定但不存在“配一行就安全”的方案。前端站点的本质决定了任何“保密”都只是访问门槛不是真正的内容隔离。想清楚这一点后面的技术选型才不会走偏。这篇文章适合三类人看正在用 vdoing 写内部文档的、想把部分文章藏起来不给外人看的、以及已经试过加密插件但被各种边角问题搞烦的。我会把三种方案的取舍、具体配置、以及我踩过的坑一次讲清楚你照着抄基本能跑通。先厘清一个前提“保密”在静态站点里至少有三个不同强度混在一起谈就会做出错误决策。1.1 三种强度对应三种成本第一种强度是“别让人顺手看见”。比如首页文章流、侧边栏目录、分类归档页里不出现但知道 URL 的人能直接打开。这种需求其实占大多数实现成本最低几个配置字段就够了。第二种强度是“知道 URL 也得先输密码”。这是绝大多数人真正想要的也是本文的主线。它在客户端做路由拦截加密码校验能挡住 99% 的随手翻看但挡不住会看源码的人。第三种强度是“源码里也不能有明文”。这就要求内容在构建阶段就变成密文页面上只输出一段加密字符串靠密码在浏览器里解开。成本最高而且会牺牲搜索、目录、SEO 这些能力。我最后的方案是第二种为主、辅以第一种的可见性收敛同时把第三种作为可选增强。为什么这么选下一节说。1.2 为什么我没把“内容加密插件”当主线市面上针对 VuePress 1.x 的内容加密方案比较常见的是vuepress-plugin-md-enhance里的encrypt能力。它在config.js的plugins字段里配置支持全局密码、管理员密码、以及按路径配置不同口令还能给每个路径配一句提示文案。思路是把 markdown 正文加密成一段密文页面渲染时先弹密码框密码正确再解密渲染。听起来很完美但我实际用下来有几个现实阻力。一是版本差异大不同小版本的字段名和密文生成方式都动过网上抄来的配置经常报一堆看不懂的错二是密文得手动生成插件配套提供了生成入口但每改一次文章就得重新走一遍流程写文档的节奏会被打断三是它对 vdoing 的目录体系不感知侧边栏、分类页、标签页该显示还是显示标题照样泄露你还是得做第一层收敛。所以我的做法是把可见性收敛第一层和路由门禁第二层做扎实内容加密作为可选叠加。这样即使你不用任何加密插件也能得到一个 90 分的结果而且完全不依赖第三方插件的版本兼容性。1.3 三条路线的成本收益对照路线实现位置挡住谁动手成本主要副作用可见性收敛config.js frontmatter顺手翻目录的人低半小时需要手动维护侧边栏路由门禁enhanceApp.js知道 URL 的人中一到两小时产物里仍有明文内容加密插件配置会看源码的人高且需反复加密搜索、目录基本失效构建期隔离环境变量双份构建所有人最高流程重发布流程复杂化这张表建议你贴在自己的规划文档里。我见过太多人一上来就奔着“最安全”去结果流程复杂到自己都不想更新文档最后整个知识库烂尾。能长期维护的方案才是好方案这句话在文档系统里比在任何地方都成立。2. 改哪一层才不会把站点搞崩在动手之前必须搞明白 vdoing 的运行链路。很多人一出问题就去改主题源码改完本地能跑下次升级主题全丢还找不回改了哪儿。我 generally 的原则是能放在项目配置目录里的绝不放进node_modules。2.1 config.js、enhanceApp.js、组件层三层各管什么docs/.vuepress/config.js是构建期的大脑。它决定加载哪些插件、主题配置长什么样、导航和侧边栏怎么排。改这里的效果是“生成的产物本身就不一样”比如某个页面压根不进侧边栏。docs/.vuepress/enhanceApp.js是运行期的入口。它接收{ Vue, options, router, siteData, isServer }这几个参数在应用实例创建之前执行。改这里的效果是“产物一样但跑起来的行为不一样”比如路由跳转时先拦一道。注意它在服务端渲染阶段也会执行一次这个特性后面会用到也是很多人踩坑的地方。组件层是指.vuepress/components/下的自定义组件VuePress 1.x 会自动全局注册这个目录里的东西markdown 里直接写标签名就能用。密码输入框这类交互放这儿最合适不用改主题布局。三层各司其职我的分工是可见性交给config.js和 frontmatter拦截交给enhanceApp.js交互界面交给组件。一条线都不越界。2.2 一个关键发现siteData 是可以动的这是整个方案的基石值得单独说。enhanceApp.js拿到的siteData不是只读快照它就是应用渲染时用的那份站点数据this.$site指的就是它。你在里面改pages数组页面组件读到的就是改完的结果。// docs/.vuepress/enhanceApp.js export default ({ Vue, options, router, siteData, isServer }) { if (siteData Array.isArray(siteData.pages)) { siteData.pages siteData.pages.filter( (page) !(page.frontmatter page.frontmatter.private true) ) } }这段代码把带private: true的页面从站点数据里摘掉。副作用是首页文章流、归档列表、基于$site.pages做遍历的组件全都看不到这些页面了。而且因为 SSR 阶段这段也会跑连构建出来的静态 HTML 里也不会出现这些条目。这个方法的好处是零侵入——主题组件照常工作只是它们拿到的数据变少了。比去改主题的列表组件强太多。2.3 版本对齐别拿 2.x 的文档硬套 vdoingvuepress-theme-vdoing主流版本是跑在 VuePress 1.x 上的这决定了你能用的插件生态、enhanceApp的签名、以及路由实例的行为。VuePress 2 是另一套东西客户端配置文件名都变了插件体系也重写了。我见过有人照着 2.x 的教程往 1.x 项目里塞client.ts然后纳闷为什么完全不生效。判断方法很简单看package.json里vuepress的版本号1 开头就是本文适用的场景另外看项目根目录有没有docs/.vuepress/enhanceApp.js这个文件如果有基本可以确定是 1.x。还有一个容易忽略的点主题本身可能有自己的enhanceApp.js。如果你在主题目录里看到同名文件项目根目录的那个不会覆盖它两者是各自独立加载的。所以放心在项目目录里写不会打架。3. 第一步把私密页面从“能看见”变成“看不见”这一层的目标是普通访客翻遍导航、分类、归档、搜索都不会发现这些页面存在。做完这一步保密工作已经完成了一大半。3.1 目录结构和 frontmatter 约定先说目录。我的习惯是给私密内容单独开一个顶层目录别和公开文章混在一起docs/ ├── .vuepress/ ├── notes/ # 公开笔记 │ ├── frontend/ │ └── backend/ └── vault/ # 私密内容独立目录 ├── pricing-2024.md └── retro-q3.md独立目录的好处是便于整体排除、整体迁移、整体改前缀。混在公开目录里的私密文章将来清理起来会非常痛苦。然后是 frontmatter。我给每个私密页面加一个自定义字段--- title: 某季度复盘 date: 2024-09-12 permalink: /pages/8f3a2c/ private: true sidebar: false --- 正文……三个字段各有作用。private: true是我自己的约定用来做数据过滤和路由判断sidebar: false告诉 vdoing 这个页面不要出现在自动生成的侧边栏里不写categories和tags它就不会进分类页和标签页。注意permalink是必须的vdoing 默认会给每篇文章生成一个形如/pages/xxxxxx/的短链如果你自己指定了URL 就和文件路径完全脱钩——这一点在做路由拦截时是个大坑后面细说。3.2 用 permalink 建立私密路径集合很多人写路由拦截时会用path.startsWith(/vault/)这种判断在 vdoing 里这是错的。因为开启了 permalink 之后访问/vault/pricing-2024.md对应的实际 URL 是/pages/8f3a2c/跟你想象的完全不一样。正确做法是从 siteData 里反查。先算出私密页面的真实路径集合再做判断// docs/.vuepress/enhanceApp.js const isPrivatePage (page) page.frontmatter page.frontmatter.private true export default ({ Vue, options, router, siteData, isServer }) { if (!siteData || !Array.isArray(siteData.pages)) return // 1. 先收集私密页面真实路径 const privatePaths new Set( siteData.pages.filter(isPrivatePage).map((page) page.path) ) // 2. 再把它们从站点数据里摘掉让导航看不见 siteData.pages siteData.pages.filter((page) !isPrivatePage(page)) // 3. 客户端才挂路由守卫 if (!isServer router) { router.beforeEach((to, from, next) { if (!privatePaths.has(to.path)) return next() const passed sessionStorage.getItem(vault-gate) 1 if (passed) return next() // 记住来路方便验证后跳回去 sessionStorage.setItem(vault-redirect, to.fullPath) next(/gate/) }) } }顺序很重要先收集、后过滤。反过来的话过滤完就找不到私密路径了路由守卫形同虚设。这个细节我第一次写的时候也栽过页面在导航里消失了但直接输 URL 照样能进。还有一点next(/gate/)我特意没带查询参数。带?redirect/pages/8f3a2c/的话私密路径会出现在地址栏和浏览器历史里等于把线索写在了脸上。改成sessionStorage中转干净得多。3.3 侧边栏、分类页、归档页的联动收尾做完上面两步首页和归档基本干净了但侧边栏还有可能出现漏网之鱼。原因在于 vdoing 的侧边栏生成模式有好几种如果你用的是按目录自动生成那一档它会扫描文件系统不看你过滤后的数据。两个处理方向。一是把themeConfig.sidebar从自动模式改成一个手写的对象只把想公开的目录列进去// docs/.vuepress/config.js module.exports { themeConfig: { sidebar: { /notes/frontend/: [vuepress-basic, markdown-tips], /notes/backend/: [node-env], }, }, }手写侧边栏确实要维护但换来的是绝对的可见性控制。我个人认为对于有保密需求的站点这个交换是值得的。二是如果你实在想保留自动生成就把私密目录整个移出docs放到一个不参与构建的地方需要时再拷进来——这就是“构建期隔离”的思路后面第 5 节会讲。分类页和归档页相对简单只要私密页不写categories和tags并且从siteData.pages里被摘掉了这些聚合页自然就不会收录它们。vdoing 的归档页是按$site.pages里的日期排序渲染的过滤后自然就没了。3.4 改完必须验证的四个页面每次改完这套配置我都会按固定顺序点一遍这四个地方缺一个都不算完成首页文章流往下滚到底确认私密文章标题不出现侧边栏展开所有分组确认没有私密目录或条目/categories/和/tags/页面逐个分类点进去看直接手输permalink地址确认被弹到密码页。第三个最容易被跳过但恰恰是信息泄露的重灾区——分类名本身就可能是敏感信息“某季度复盘”这种分类挂在公网上标题藏不藏已经没意义了。4. 第二步路由门禁和密码页的完整实现可见性问题解决后剩下的就是“知道 URL 怎么办”。这一层的核心逻辑很朴素没验过证就跳走验过了放行一段时间。4.1 密码页该做成什么样密码页本身是站点里的一个普通页面放在docs/gate/README.mdfrontmatter 里加上permalink: /gate/和article: false后者让 vdoing 别把它当文章收录。页面正文只放一个自定义组件--- title: 内容受保护 permalink: /gate/ article: false sidebar: false --- PasswordGate /组件放在docs/.vuepress/components/PasswordGate.vueVuePress 1.x 会自动把它注册成全局组件markdown 里直接写标签就行。组件逻辑包含三件事输入框、异步校验、验证成功后跳回原地址。template div classgate h2该内容需要口令访问/h2 p v-iferror classerr{{ error }}/p input v-modelpwd typepassword placeholder请输入访问口令 keyup.entersubmit / button :disabledloading clicksubmit {{ loading ? 校验中… : 进入 }} /button /div /template script const SALT vault-2024-vdoing const PASS_HASH 把下面那段脚本算出来的哈希粘到这里 async function sha256(text) { const data new TextEncoder().encode(text) const buf await crypto.subtle.digest(SHA-256, data) return Array.from(new Uint8Array(buf)) .map((b) b.toString(16).padStart(2, 0)) .join() } export default { name: PasswordGate, data() { return { pwd: , error: , loading: false } }, methods: { async submit() { if (!this.pwd) return this.loading true this.error try { const hash await sha256(SALT this.pwd) if (hash PASS_HASH) { sessionStorage.setItem(vault-gate, 1) const back sessionStorage.getItem(vault-redirect) || / sessionStorage.removeItem(vault-redirect) this.$router.replace(back) } else { this.error 口令不正确 } } catch (e) { this.error 当前环境不支持校验请换用现代浏览器 } finally { this.loading false } }, }, } /script哈希值怎么来在你的构建机器上跑一段 Node 脚本node -e const c require(crypto); const SALT vault-2024-vdoing; const pwd 你想设的口令; console.log(c.createHash(sha256).update(SALT pwd).digest(hex)); 把输出粘进PASS_HASH明文口令就不出现在任何产物文件里了。这个做法的价值不在于密码学强度前端校验本来就谈不上强而在于避免“打开开发者工具搜索一下就看到密码”这种尴尬。4.2 Web Crypto 的两个必须知道的坑第一个坑是crypto.subtle只在安全上下文可用。通过file://打开、或者部署在内网的http://地址上window.crypto.subtle直接是undefined代码会在digest那一步抛错。我最早在内网测试机上用 http 部署折腾了半小时以为是哈希算错了最后发现是 API 根本不存在。应对方法有两个。一是部署上 https现在证书成本基本为零二是在catch里给一个降级提示别让页面白屏。我上面的代码就是第二种用户体验至少是“告诉我为什么进不去”而不是“点了没反应”。第二个坑是TextEncoder的兼容性。虽然现代浏览器都支持但如果你站点的访问者里还在用很老的浏览器得加个判断。不过考虑到 vdoing 本身的 Vue 依赖能正常打开站点的浏览器基本都支持这个坑实际影响很小知道就行。4.3 会话保持存哪儿、存多久我用的是sessionStorage关掉标签页就失效。理由很实际这个门槛是防误闯不是做用户体系。用localStorage永久记住等于给自己挖坑——某台公用电脑上验证过一次之后就永远能进。如果你们的场景需要更细的粒度比如“每个私密目录单独口令、各自记住”那就把sessionStorage的键改成一个对象按目录前缀存不同的通行标记。实现上不复杂但配置维护成本会上升。我的建议是别过度设计一个口令覆盖所有私密页够用。还有一个细节跳走之前要记住来路。前面代码里我用sessionStorage存了vault-redirect验证成功后$router.replace回去。如果用户在密码页刷新了一下来路还在体验就顺如果直接用localStorage一起存就更不丢了。注意用replace而不是push否则浏览器后退键会把用户退回密码页体验很怪。5. 把剩下的泄露面再收一圈到这里主体功能已经能用但静态站点还有几个隐蔽的泄露通道不处理的话前面的活儿会打折扣。5.1 搜索索引是最大的漏点vdoing 通常会配一个搜索插件。如果是全文搜索类插件它在构建阶段就把所有页面的正文抽出来生成索引写死在 JS 文件里。你在enhanceApp.js里过滤siteData.pages对它是无效的——索引早就生成好了用户在搜索框里输入关键词私密页的摘要照样弹出来。我处理这个问题的做法分两步。第一步是先确认你的项目到底用了哪个搜索插件别猜。打开docs/.vuepress/config.js看plugins里有没有fulltext-search之类的名字或者在构建产物里做一次实证检查# 构建完执行把关键词换成私密文章里的独特词 grep -rn 私密文章里的独特词 docs/.vuepress/dist/assets/js/ | head -20有结果就说明词被写进了前端产物得处理。第二步看插件本身有没有排除配置很多全文搜索插件支持exclude或searchPaths之类的字段把私密目录排除掉即可。如果它不支持我的选择是直接关掉全文搜索换成只索引标题的轻量方案或者干脆用导航侧边栏找文章。这里要提醒一句只索引标题的方案并不能完全解决问题。如果私密文章的标题本身就包含敏感词标题索引照样会出现在搜索建议里。所以标题命名也要注意别用“2024年XX产品报价”这种一看就懂的词。5.2 爬虫指令和站点地图私密页虽然加了门禁但页面的 HTML 是照常生成的链接也可能从别处漏出来。给私密页加个noindex是个成本很低的补充措施!-- docs/.vuepress/config.js 的 head -- [meta, { name: robots, content: noindex }]不过这个是对全站生效的。想精准控制的话在私密页 frontmatter 里加meta字段VuePress 1.x 会把它注入到该页的 head 里--- title: 某季度复盘 permalink: /pages/8f3a2c/ private: true meta: - name: robots content: noindex, nofollow ---另外如果你的项目启用了站点地图插件记得把它也排除掉不然私密页的 URL 会明晃晃地写进sitemap.xml——那玩意儿就是给爬虫看的目录。5.3 构建产物里的明文以及部署层面的取舍必须坦诚说清楚经过这套配置私密文章正文的明文仍然在构建产物里。enhanceApp只是让它在正常浏览路径上不出现但一个会用浏览器开发者工具的人完全可以在 JS 资源里翻到内容。这个限制无法通过前端手段消除。真要做到“源码里也没有明文”只有两条路一是前面提到的内容加密插件把正文变成密文二是构建期隔离——把私密内容放在独立目录用一个环境变量控制是否参与构建公开版本根本不打包这些页面内部版本单独构建、部署到不同的访问入口。后者的流程大概是这样# 公开构建不包含 vault 目录 VAULT0 npx vuepress build docs # 内部构建包含 vault 目录 VAULT1 npx vuepress build docs然后在config.js里根据process.env.VAULT动态拼接pagePatterns或主题的sidebar配置。这套流程最安全代价是发布变复杂、两个版本容易不同步。我自己是这么权衡的真正机密的内容根本不该放在静态站点里该进权限系统的地方就进权限系统静态站点上的“保密”定位就是“不方便公开但也不至于要人命”的东西。想清楚这条线你对方案强度的预期就会合理很多。6. 踩坑实录和问题速查下面这些是我和几个同行在实际项目里真踩过的按出现频率排。6.1 白屏、水合不一致、404 三连改完enhanceApp.js整个站点白屏。八成是过滤逻辑写在了siteData.pages为undefined的时候直接抛错把整个应用挂掉了。加个判空就能解决我在示例里已经写了if (!siteData || !Array.isArray(siteData.pages)) return。SSR 报错提示某个页面在服务端不存在。这种情况通常是你在服务端阶段也修改了路由或者做了依赖浏览器 API 的操作。记住原则router相关的操作要放在if (!isServer)分支里sessionStorage、window、crypto.subtle这些东西服务端一个都没有。直接访问私密页返回 404。如果只是你本地vuepress dev时报的可能是permalink写错或者页面路径没有对应的静态文件。VuePress 1.x 生成的是静态文件dev模式下路由是动态的build之后才是真实文件路径。先跑一遍build再验证。开发环境正常构建后失效。这是最常见的形态。原因是开发模式下enhanceApp跑在浏览器里构建时还要 SSR 跑一遍两个阶段的siteData状态可能不同。我的调试方法是构建完直接开浏览器无痕窗口打开首页因为缓存会把旧版本的行为混进来非常容易误判。6.2 常见问题速查表现象最可能的原因处理方式导航里看不到但直连 URL 能进忘了挂router.beforeEach检查守卫是否在!isServer分支内守卫写了但直连仍能进路径集合用了目录前缀而非 permalink从siteData.pages反查真实path密码页输对了不跳转redirect键名不一致或已被清掉校验前后统一键名注意replace与push搜索仍能搜到私密内容全文搜索索引在构建期生成配置插件排除项或更换搜索方案分类页出现私密分类frontmatter 里写了categories删掉字段或过滤分类源数据内网 http 下点验证没反应crypto.subtle需要安全上下文上 https或加降级提示改了配置没生效浏览器缓存或构建缓存残留删dist和node_modules/.cache重构建密码改了但旧口令还能用产物里还是旧哈希确认构建成功且部署的是新产物6.3 我自己的几条操作习惯第一每加一篇私密文章立刻跑一次全链路验证别攒着。攒到十几篇再验证出了问题你根本不知道是哪次改动引入的。第二给私密页面的permalink建一个清单文件就放在项目根目录不参与构建。因为一旦permalink和文件对不上排查会非常痛苦有个清单能省很多时间。第三别把口令硬编码在组件里当常量反复引用。我现在是把哈希值放到config.js里通过definePlugin注入成全局常量组件只读常量。这样将来换口令只改一处不用在两个文件之间来回对。第四构建完一定 grep 一遍。前面那条grep -rn 关键词 dist/的命令我已经写成了package.json里的一个脚本每次发布前自动跑输出为空才允许上线。这个习惯帮我挡住过一次搜索索引泄露非常值。最后分享一个小技巧如果你的私密页面不多其实可以把private字段的值设计成一个字符串而不是布尔值比如private: vault-a然后在路由守卫里按这个值区分不同的通行标记。这样一套代码就能支持“不同人看不同内容”的轻量场景不用改架构。这套机制我用了大半年配合前面说的哈希口令和会话控制在一台普通静态服务器上稳稳跑着维护成本几乎为零。真正需要重新审视方案的时机只有一个——当你开始想在静态站点里做“用户登录”的时候那就该换系统了别硬扛。

VuePress vdoing 私密文章权限控制：可见性收敛与路由门禁

相关推荐

Windows x64下libhackrf静态编译与USB信号链路稳定实践

开发者如何高效记忆编程语法：认知科学与实战技巧

单链表数据结构：原理、实现与优化技巧

更多资讯

WIZnet IO模块选型指南：工业自动化与物联网通信

XGP会员状态与购买故障分诊：授权票据、支付回调与资格校验

Jev不该被问什么？技术协作中的提问边界与高效沟通指南

Jev不该被问什么？人际沟通中的边界感与高情商提问指南

大模型入门全路径：从机器学习到Transformer与微调部署

加密资产价值投资：策略、模型与风险管理

今日更新

PLFM_RADAR：从被动告警到主动感知的微服务健康监控系统

SPI隔离设计实战：MAX14431BAEE+与STM32F407工业级应用

数字隔离器如何根治SPI通信地环路干扰：MAX14431与TM4C129实战

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？