# My.Doc **Repository Path**: hotangenl/my.doc ## Basic Information - **Project Name**: My.Doc - **Description**: My.Doc是一个适合于个人和中小型团队的在线共享文档、知识库 - **Primary Language**: C# - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-10-19 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # My.Doc 文档协作平台 My.Doc(前端品牌名「梦瑶文档」)是一个面向团队与个人的文档协作平台,支持 Markdown 编写、文档库与树形目录管理、成员权限、历史版本、评论讨论、全文检索以及 Markdown / Word / PDF 的导入导出。 后端基于 **.NET 8 + SqlSugar + MySQL + JWT**,前端为随 WebApi 一同托管的原生 HTML / CSS / JavaScript 单页应用,无需单独构建。 ## 功能特性 - **文档库**:以文档库为组织单元,支持公开 / 私有两种可见性;公开文档库允许未登录访客浏览。 - **树形目录**:目录与文档统一为节点,支持无限层级、新建、重命名、移动、排序与删除。 - **协作权限**:成员角色分为管理员、编辑者、只读;文档库与文档均可单独设置公开 / 私有。 - **版本历史**:每次保存自动生成历史版本,支持查看版本详情与一键回滚。 - **评论讨论**:文档下的评论列表、发表与删除。 - **全文检索**:按标题与正文纯文本内容检索文档,并提供公开文档检索入口。 - **标签体系**:标签管理、文档打标、按标签浏览与标签合并。 - **收藏与统计**:文档收藏、阅读量(带去重窗口)、收藏数与评论数统计。 - **文件与图片**:附件上传 / 下载 / 删除,Markdown 内嵌图片上传。 - **导入导出**:单篇或整库导出 Markdown / Word / PDF(整库打包为 Zip);支持导入 Markdown Zip、单个 Markdown 文件与 Word 文档。 - **后台管理**:用户列表、创建用户、修改用户、重置密码、删除用户。 - **系统接口**:版本信息与健康检查接口,便于部署排查与存活探测。 > 说明:当前的「协作」是**保存式协作**——多人共享文档库、按角色控制读写、保存留痕并可回滚。项目尚未接入 WebSocket / SignalR,因此不包含多人实时同步编辑。 ## 技术栈 | 类别 | 选型 | | --- | --- | | 运行时 / 框架 | .NET 8、ASP.NET Core Web API(MVC Controller) | | ORM | SqlSugarCore 5.1.x(CodeFirst、SqlSugarScope) | | 数据库 | MySQL(`Database:Type` 可切换 SqlSugar 支持的其他数据库,默认 MySql) | | 认证 | JWT Bearer(`Microsoft.AspNetCore.Authentication.JwtBearer`) | | 接口文档 | Swashbuckle / Swagger UI(含 Bearer 鉴权配置) | | 文档导出 | DocumentFormat.OpenXml(Word)、QuestPDF(PDF,Community License) | | 缓存 | `IMemoryCache`(阅读量去重) | | 前端 | 原生 HTML + CSS + JavaScript,Markdown 编辑器与渲染 | ## 项目结构 ``` My.Doc ├── Core/ # 公共基础层:常量、枚举、异常、工具类、统一返回模型、JWT 选项 ├── Entity/ # 实体与 DTO 层:SqlSugar 实体、请求/响应 DTO ├── Business/ # 业务层:数据库初始化、仓储、业务服务、导入导出、访问控制 ├── WebApi/ # 接口与前端托管层:控制器、中间件、wwwroot 静态站点、配置 ├── Directory.Build.props # 统一版本号与程序集元信息 └── My.Doc.slnx # 解决方案文件 ``` 分层依赖方向为 `WebApi → Business → Entity → Core`。 ### 核心目录 | 路径 | 说明 | | --- | --- | | `Business/Database/DbInitializer.cs` | 自动建库建表(CodeFirst)与初始数据写入 | | `Business/Database/SqlSugarFactory.cs` | SqlSugar 客户端工厂与 SQL 日志 | | `Business/Repositories/` | 泛型仓储与各业务仓储 | | `Business/Services/` | 用户、文档库、文档、评论、标签、文件、导入导出服务 | | `Business/Extensions/DocAccessHelper.cs` | 文档库 / 文档的可见性与角色校验 | | `Business/Extensions/MarkdownImageMigrator.cs` | 导入时外链图片迁移入库 | | `WebApi/Controllers/` | 各业务 REST 接口 | | `WebApi/Middleware/ExceptionHandlingMiddleware.cs` | 全局异常处理 | | `WebApi/wwwroot/` | 前端页面、脚本、样式与上传目录 | ### 数据模型 | 实体 | 表名 | 说明 | | --- | --- | --- | | `User` | `my_user` | 用户账号与资料,含管理员标记 | | `Workspace` | `my_workspace` | 文档库,含公开 / 私有可见性与统计数 | | `WorkspaceMember` | `my_workspace_member` | 文档库成员及角色 | | `DocItem` | `my_doc` | 文档 / 目录节点,含 Markdown 内容与纯文本检索字段 | | `DocVersion` | `my_doc_version` | 历史版本快照 | | `DocStar` | `my_doc_star` | 文档收藏 | | `DocComment` | `my_doc_comment` | 文档评论 | | `Tag` / `DocTag` | `my_tag` / `my_doc_tag` | 标签与文档标签关联 | | `FileItem` | `my_file_item` | 上传附件元数据 | ## 快速开始 ### 1. 环境要求 - .NET SDK 8.0 - MySQL 5.7 / 8.0(无需手动建库,首次启动会自动创建) ### 2. 配置数据库 编辑 [My.Doc/WebApi/appsettings.json](My.Doc/WebApi/appsettings.json) 中的连接字符串: ```json "ConnectionStrings": { "MySql": "Server=localhost;Port=3306;Database=my_doc;Uid=root;Pwd=你的密码;CharSet=utf8mb4;SslMode=None;AllowPublicKeyRetrieval=True;" }, "Database": { "Type": "MySql" } ``` 同时请在部署前替换 `Jwt.SecretKey`(长度需大于 32 字节),不要沿用仓库中的示例密钥。 ### 3. 还原与启动 ```bash dotnet restore My.Doc/WebApi/WebApi.csproj dotnet run --project My.Doc/WebApi/WebApi.csproj ``` > 解决方案文件使用较新的 `.slnx` 格式,建议使用较新版本的 .NET SDK / Visual Studio 打开;也可以直接按上面的方式以 WebApi 项目为单位构建运行。 默认监听 **http://localhost:5080**(见 `appsettings.json` 的 `Kestrel` 配置)。 - 站点首页: - 接口文档: - 健康检查: 首次启动会依次执行:创建数据库 → 建表 → 写入初始账号、示例文档库与示例文档。 ### 4. 初始账号 | 账号 | 密码 | 角色 | | --- | --- | --- | | `admin` | `123456` | 系统管理员 | | `demo` | `123456` | 演示用户(示例文档库编辑者) | > 初始密码仅用于本地体验,登录后请立即修改。 ## 页面入口 | 页面 | 路径 | 说明 | | --- | --- | --- | | 公开首页 | `/index.html` | 公开文档库与文档的搜索、浏览 | | 登录 / 注册 | `/login.html` | 账号登录与注册 | | 文档工作台 | `/home.html` | 我的文档库、收藏、搜索等 | | 文档详情 / 编辑 | `/doc.html` | Markdown 编辑、目录树、评论、版本历史 | ![输入图片说明](image1.png) ![输入图片说明](132088e965e15fa4716c0195cf1b9f2a.png) ![输入图片说明](image.png) ![输入图片说明](b6904cb9abb86f4ffe93f839bb67e89f.png) ![输入图片说明](a882254c7dc968e72714773ff1df3f01.png) ## 接口约定 ### 统一返回结构 所有接口返回 `ApiResult`: ```json { "code": 200, "message": "操作成功", "data": { }, "success": true } ``` - `code = 200` 表示成功,其余为业务失败。 - 未登录或令牌失效时,HTTP 状态码仍为 `200`,业务 `code` 为 `401`,由前端统一跳转登录。 - 请求参数校验失败返回 `code = 400` 与首条错误信息。 ### 鉴权方式 除登录、注册、公开浏览与系统接口外,均需在请求头携带 JWT: ``` Authorization: Bearer {token} ``` ### 接口分组 | 前缀 | 控制器 | 主要职责 | | --- | --- | --- | | `/api/auth` | `AuthController` | 注册、登录、当前用户、退出 | | `/api/user` | `UserController` | 个人资料、修改密码、用户检索 | | `/api/workspace` | `WorkspaceController` | 文档库增删改查、目录树、成员管理、退出文档库 | | `/api/doc` | `DocController` | 文档树、详情、创建、保存、重命名、移动、排序、删除、版本、回滚、收藏 | | `/api/comment` | `CommentController` | 评论列表、发表、删除 | | `/api/tag` | `TagController` | 标签管理、文档打标、按标签浏览、合并 | | `/api/search` | `SearchController` | 全文检索、公开检索、工作台看板 | | `/api/file` | `FileController` | 附件列表、上传、下载、删除 | | `/api/upload` | `UploadController` | Markdown 图片上传 | | `/api/export` | `ExportController` | Markdown / Word / PDF 导出与导入 | | `/api/admin` | `AdminController` | 后台用户管理 | | `/api/system` | `SystemController` | 版本信息、健康检查 | ## 权限模型 - **文档库可见性**:`Private` 仅成员可见;`Public` 所有人(含访客)可浏览,仅成员可编辑。 - **成员角色**:`Admin` 管理文档库与成员;`Editor` 可编写文档;`Reader` 仅可浏览。 - **文档可见性**:在文档库可见性基础上再做一层公开 / 私有控制,创建时默认继承所处文档库。 - **文档状态**:`Draft`(草稿)与 `Published`(已发布)。 ## 版本管理 版本号以 [My.Doc/Directory.Build.props](My.Doc/Directory.Build.props) 中的 `ProductVersion` 为唯一来源(当前 `1.0.0`),并同步前端 `wwwroot/js/common.js` 的 `APP_VERSION`。前端启动时会与 `/api/system/version` 比对,不一致会在控制台告警。 遵循语义化版本:主版本用于不兼容变更,次版本用于向后兼容的新功能,修订号用于缺陷修复。 ## 开发约定 - 新增控制器请继承 `BaseApiController`,复用统一路由、鉴权与返回结构。 - 业务异常统一抛出 `BusinessException`,由全局异常中间件转换为统一返回结构。 - 数据库结构由 `DbInitializer` 的 CodeFirst 同步,新增实体后需加入 `EntityTypes` 列表。 - 上传文件默认存放于 `wwwroot/uploads`,仅图片扩展名(`jpg/jpeg/png/gif/webp/bmp/svg`)允许上传,大小上限 10 MB。 ## 许可证 本项目采用 [MIT License](LICENSE)。 如果有什么问题或建议,提issue或加QQ:36815696