为什么又造一个文档工具
市面上的文档产品很多,但真正用起来,总会卡在几个地方。
资料太散
团队方案散落在聊天记录、网盘和邮件里,找一份半年前的技术文档要翻很久。
数据不放心
内部资料放在第三方在线文档上,总担心权限、导出和长期可用性。
自部署太重
开源方案要么是重型微服务全家桶,要么依赖一堆中间件,光跑环境就要一天。
改起来费劲
纯前端单机版没法多人协作,功能全的项目结构复杂,二次开发成本高。
所以 My.Doc 的取舍是:单服务、少依赖、可维护。把团队真正高频用到的能力做扎实,把部署和二次开发的门槛降下来。
核心能力
从文档组织、权限协作到导入导出,覆盖团队文档沉淀的主要环节。
文档库与可见性
以文档库为一级组织单元,支持公开 / 私有;公开库允许未登录访客浏览,适合对外知识库与产品手册。
树形目录
目录与文档统一为节点,无限层级嵌套。新建、重命名、移动、排序、删除全部在左侧树完成。
成员与角色
管理员、编辑者、只读三种角色,叠加文档库与文档各自的公开 / 私有开关,形成两级权限控制。
版本历史
每次保存自动生成历史版本,记录标题、正文、编辑人与时间,支持查看详情与一键回滚。
Markdown 编辑
实时预览,支持标题、列表、表格、代码块、引用与图片;兼容 Typora、Word 粘贴的常见格式问题。
全文检索
标题与正文纯文本同时检索,公开文档提供独立入口,未登录也能搜索。
评论与标签
文档下直接评论讨论;自定义标签、文档打标、按标签浏览,并支持重复标签合并。
导入导出
单篇或整库导出 Markdown / Word / PDF;支持导入 Markdown 压缩包、单文件与 Word,自动重建目录结构。
后台管理
用户列表、创建账号、修改资料、重置密码与删除用户,配合公开首页形成最小可用的对外站点。
四层结构,依赖单向
没有为了分层而分层。每一层职责直白,新人接手能快速找到要改的位置。
控制器、中间件、JWT 鉴权、Swagger、wwwroot 静态站点
数据库初始化、仓储、用户 / 文档 / 评论 / 标签服务、导入导出
SqlSugar 实体、请求响应模型、枚举与映射
统一返回模型、异常、常量、工具类、JWT 选项
几个值得说的设计细节
首次启动自动建库建表
启动时检查数据库、同步表结构;如果库中没有用户,自动写入管理员、演示账号、公开文档库与示例文档。拉下项目配好连接就能登录看到内容,而不是面对空白系统。
统一返回结构 + 全局异常
所有接口统一返回 code / message / data。业务异常由全局中间件转换;令牌失效时 HTTP 仍为 200、业务 code 返回 401,前端拦截逻辑只需一处。
版本号单一源
版本号只写在 Directory.Build.props 的 ProductVersion,四个项目共享,前端页面加载时自动比对并提示不一致,避免「线上到底是哪个版本」。
阅读量去重
按「用户 + 文档」与「IP + 文档」设置短窗口,窗口内重复访问不计数。不引入 Redis,单机场景够用。
导入时迁移外链图片
扫描 Markdown 中的外链图片,下载后存入本地 uploads 目录并替换正文地址,避免原站点失效后文档变成一片红叉。
五分钟跑起来
环境要求只有两个:.NET 8 SDK 与 MySQL 5.7+。
配置数据库连接
编辑 My.Doc/WebApi/appsettings.json,顺手替换 Jwt.SecretKey。
"ConnectionStrings": {
"MySql": "Server=localhost;Port=3306;Database=my_doc;Uid=root;Pwd=你的密码;CharSet=utf8mb4;"
}
启动服务
数据库不用手动创建,首次启动会自动建库建表并写入示例数据。
dotnet run --project My.Doc/WebApi/WebApi.csproj
打开浏览器
站点首页 http://localhost:5080,接口文档 http://localhost:5080/swagger。
默认账号:admin / 123456、demo / 123456,首次登录请修改密码。
边界说明
当前是「保存式协作」,不是多人实时协同:多人可以共享文档库、按角色读写、每次保存留痕可回滚,但尚未接入 WebSocket / SignalR,不会出现对方光标实时跳动的体验。后续计划包括实时协同、文档内链与反向链接、带有效期的分享链接,以及中文分词检索。