# 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 编辑、目录树、评论、版本历史 |





## 接口约定
### 统一返回结构
所有接口返回 `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