先说一件我被烦到很多次的小事
我要把一份技术文档发给别人。
对方不是我团队里的人，不需要协作，不需要评论，也不需要长期待在我这套系统里。他只是想看那几页内容，看完就走。
但为了这几页内容，流程往往是这样的：
- 发 Notion 链接 —— 对方打开先看到登录页
- 发语雀 —— 要注册，还得我手动加权限
- 发飞书文档 —— 得是同一个组织的人
- 干脆截图发微信 —— 三十页截图，谁看谁崩溃
这就是"太重"的那一档：文档明明是我的，门槛却是对方的。
那换静态文档站呢？docsify、VitePress 那一套我熟，写起来也算顺手。可它们是纯静态产物：加一篇要 commit、要重新构建、要部署；没有权限、没有多人维护、没有访问统计，也没法临时给某个客户开一个带口令的链接。想改正文里的一个错字，得走一遍完整的发版流程。
这就是"太糙"的那一档：改一篇文章的成本，比写一篇文章还高。
一头太重，一头太糙。中间那一档——写作要像 CMS 一样顺手，分享要像发链接一样轻，数据还得攥在自己手里——好像一直缺个东西。
所以我自己写了一个：极简智库 MiniDocs。
一句话概括：写作在后台，阅读在链接里，数据在自己的服务器上。
标题里我用了"完美替代"这个词，它需要一点解释。
不是说它功能更多——恰恰相反，它比这几家都少。我说"替代"，是因为这三者缺的那一块，正好是彼此的另一半：Notion 的编辑体验很好，但分享要先过注册墙；docsify / VitePress 零依赖、够轻快，可加一篇文档要发一次版；而它们的数据都不真正属于你——一个在别人的云上，另一个虽然产物是你自己的，但本质上只是一堆构建出来的 HTML，改不了、管不了、也统计不了谁看过。
MiniDocs 想同时拿到三样：像 CMS 一样写、像静态站一样快、像自建服务一样归你。
至于"完美"，它有前提。文末我列了它不适合的场景，那几条比优点更值得先看。
- 开源仓库：github.com/cosolar/min…
- 在线体验：docs.minims.cn（可以直接注册，也可以只看不注册）
我想清楚的三件事
在动手之前，我先把"不要什么"写下来了。知识库这个品类已经很拥挤，前面点到的那些名字，任何一个都比我功能全、团队大。再造一个"功能更少的别人"没有意义。
所以 MiniDocs 只围绕三个判断来做取舍。
一、分享是核心功能，不是附属开关
大多数知识库的分享只有两档：公开，或者不公开。
但真实场景里，我需要的是更细的那一层：这条链接给谁、能看多久、能不能收回。
于是 MiniDocs 里每一次分享都是一个独立对象：
- 范围可以是整库，也可以是单篇
- 可设访问口令，通过后 12 小时内免密
- 可设有效期，到期自动失效
- 短链可以自己定，6–32 位，全局唯一，随时能换（换之前会二次确认：旧链接立即失效）
- 链接随时可撤销
- 访问量按"访问会话"统计：30 分钟内同一个访客只算一次，独立访客按天去重
对方什么都不用装、不用注册，拿到链接就能读。
二、权限只需要四根轴
企业级权限系统能做出几十个开关，但绝大多数团队根本配不明白，最后所有文档都变成了"全员可见"。
我只留了四个维度：
| 维度 | 取值 | 管的是什么 |
|---|---|---|
| 库可见性 | public / org / private | 谁能看到这个库 |
| 维护范围 | owner_only / members / org_all | 谁算这个库的维护者 |
| 成员角色 | OWNER / EDITOR / VIEWER | 读 / 写 / 治理 / 分享 |
| 分享 | 独立于上面三条 | 一条链接发给谁 |
规则只有一处实现——permission/AccessService。业务代码里不允许自己比较角色或 owner，测试里有静态守卫会拦住这种写法。
这种"只有一个裁判"的设计，短期看是限制，长期看是省命。半年之后你不会想知道"这个接口到底是谁在判权限"。
三、部署要能被一个运维小白完成
很多开源项目的 README 写到 docker-compose up 就结束了，然后你打开浏览器，看到一堆配置项报错。
MiniDocs 的目标是：一个容器、一个端口、一个数据卷，起来就能用。
export ADMIN_PASS='换成强密码'
export JWT_SECRET="$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 48)"
cd deploy
docker compose -f docker-compose.standalone.yml up -d
打开 http://服务器IP:9098，默认管理员是 admin / admin123（第一次登录请立刻改掉）。数据默认落在 Docker 卷 minidocs-data 里，用的是内置 SQLite，不需要另起一个数据库容器。
真的要用 MySQL，把 SPRING_PROFILES_ACTIVE 改成 prod、补三个连接参数就行 —— 同一份 jar，SQLite / MySQL 双方言，建表和内容迁移脚本随启动自动执行。
它到底能干什么
功能列在这里，你可以对照自己的场景挑。
写作
Markdown（GFM）编辑加实时预览，这些是基本盘：表格、任务列表、代码块语法高亮加一键复制。
在此之上补了几样让"写"这件事更顺手的东西：
- Mermaid 图与 KaTeX 公式，直接写在正文里
- 提示块：
> [!NOTE]/[!WARNING]/[!TIP]，不用记 HTML - 行内高亮：
==这几个字要重读== - 目录树与左侧文档层级一一对应，支持 frontmatter 写标题和标签
- 正文大纲（TOC）与锚点跳转，长文不迷路
- 目录 / ZIP 导入，带解压体积和条目数两道安全阀，迁移旧笔记不用一篇篇粘
多人同时改一篇怎么办？两道保险：编辑锁（60 秒续期，超时自动让位，人走了不会把文档锁死）加乐观并发（基线带 size 和 mtime，冲突返回 412，不会静默覆盖别人的修改）。
阅读
阅读页和分享页共用同一条渲染管线，所以"我看到的"和"发出去的"永远一致 —— 这一点很多产品做不到，编辑端预览好好的，分享出去样式就散了。
- 明亮 / 暗黑主题，内置九套阅读主题包
- 正文字号、字体可调（思源黑体、霞鹜文楷、站酷快乐体等），分享页还能调正文宽度
- 站内全文检索，内存倒排索引，命中直接跳到标题
- 上 / 下一篇导航
分享
上面讲过了，补两个细节：
- 分享页顶栏的导航菜单由分享者自己勾选，可以只给对方看一个库，也可以让他顺着摸到你整个门户
- 越权访问统一返回 404，不泄露"这个东西存在但你没权限"
组织与治理
- 多租户：注册即自动创建一个个人组织，小团队直接拉人进来
- 维护名单、入组申请、操作审计（留痕，但不记录 token 和密码）
- 平台治理：用户管理、站点名称与 Logo
几个我比较满意的技术决定
如果你也是写后端的，这一段可能比功能列表更有意思。
一次渲染，两处复用。 渲染缓存键是 kbId + path + mtime + size，门户视图和分享视图复用同一份 HTML。不是两份模板各自渲染，是同一份产物两个入口。
零外部依赖的全文检索。 没引 Elasticsearch，没引 Lucene，就是一个内存倒排索引，上限约 2000 篇，命中直接给出标题链接。对"个人博客 / 小型团队"这个体量，多一个中间件就是多一个运维事故源。
管理端按需加载。 Element Plus 只在进入 /console/**、/login、/platform/** 时才动态载入。门户和阅读页的产物里没有组件库，首屏因此很轻 —— 一个知识库最常被访问的是阅读页，不该为后台的表格组件付代价。
安全默认收紧。 严格 CSP 与安全响应头；分享 Cookie 用 HMAC 签名、作用域为根；越权一律 404。这些不是加在最后的功能，是从第一版就在的约束。
技术栈：后端 Spring Boot 3 + MyBatis-Plus + Druid + Sa-Token + flexmark，前端 Vue 3 + Vite + Pinia，单 SPA 一次构建。
三分钟跑起来
最快的路：先看线上。 docs.minims.cn
演示站里现在就挂着 6 个知识库、243 篇文档 —— 《动手学大模型》《AI Agent HandBook》《深入理解 AI Agent》《技术面试笔记》《极简简历文档中心》等等。这些不是填充数据的假文章，是我自己真实在维护的内容。你可以直接注册一个账号，也可以完全不注册，只看分享出去的库。
本地跑： 需要 JDK 17+、Maven 3.9+、Node.js 20+。
cd front && npm install && npm run build
cd ../backend && mvn spring-boot:run
打开 http://localhost:9098。dev profile 下用 SQLite，开箱即用，不用配任何数据库。
小坑提前说：如果环境变量
NODE_ENV=production，npm install会跳过 devDependencies，装依赖时要显式带上--include=dev。
上线： 用上面的 Docker 命令；要前后端分离，前端产物交给任意静态服务器，后端只提供接口。Nginx 只需要两段 —— 一段 try_files 做 SPA 深链接回退，一段把 /minidocs/ 反代到后端。完整配置、systemd、备份升级、故障排查都在部署指南里。
- 部署指南：
docs/DEPLOYMENT.md - 使用手册（含权限模型细则）：
docs/USAGE.md - 设计取舍（为什么长这样，含试过但走不通的做法）：
docs/DESIGN.md
它不适合谁
标题里那句"完美替代"，到这里该打个折了。
它不是所有场景的替代品。下面这几种情况，我建议你直接用原来的方案，别折腾——
如果你要的是"团队协作 + 即时通讯 + 日历 + 审批"一体的办公套件，去用飞书或钉钉，MiniDocs 不解决这个。
如果你要的是"纯静态、零后端、推到 GitHub Pages"的文档站，docsify 或 VitePress 更轻，你不需要一个数据库。
如果你的文档量在十万篇量级、需要复杂的检索排序和聚合分析，那你该上 Elasticsearch 那一套，MiniDocs 的内存索引会先撞到上限。
如果你的团队需要精细到段落级别的评论、@提醒、审批流，现在的版本没有。
反过来说，只要你的场景落在这句话里，它大概率能替掉你现在那套：你维护着一批 Markdown 文档，需要把它们结构化地组织起来（多库、树形目录、标签），团队内部要有权限边界，对外要能把某一部分干净地分享出去。
个人博主、小型工作室、技术团队、开源项目的文档中心 —— 这是我设计时脑子里想的那几类人。
现在是什么状态
项目 9 月底开源，当前版本 v1.2.11，Apache-2.0，可商用。
说白了，它还很年轻。一个多月，代码是我一个人在一行行写，很多边角是我自己踩着坑补的。这意味着两件事：
一是别指望它什么都有。缺什么功能，你可以直接开 issue 说，我大概率会回。
二是现在提的意见最有用。等它长到一万 star 的时候，你说的话就没有现在这么管用了 —— 这话所有开源作者都这么说，但它是真的。
如果你觉得这个东西有点用：
- Star 一下：github.com/cosolar/min… —— 这不是客套，star 数是这类小项目能不能被更多人看见的唯一通道
- 跑一遍，然后把卡住你的地方告诉我（部署踩坑最欢迎，那说明我的文档没写清楚）
- 想加功能，先读
CONTRIBUTING.md；安全问题请走私密渠道，别开公开 issue
如果你只是想看看别人怎么用：演示站里那几个库，都是真实在跑的内容，随便翻。
链接汇总
- 开源仓库：github.com/cosolar/min…
- 在线 Demo：docs.minims.cn
- Docker 镜像：hub.docker.com/r/minimscn/…
- 许可：Apache License 2.0
