简介：一套基于 C# 与 ASP.NET 构建的 Web 文档管理系统源码，面向希望掌握在线文档创建、编辑、存储与共享实现的中级开发者，可用于课程设计、毕业设计或企业文档协作原型参考。压缩包共 98 个文件，约 1.31MB，内含 32 个 cs 服务端源码、14 个 aspx 页面、7 个 js 与 4 个 css 前端资源，并配有界面图片、SQL Server 的 mdf/ldf 数据库、程序集及 doc/txt 说明，覆盖表示层、业务逻辑与数据存储。系统涉及在线编辑、权限管理、版本控制和操作日志，适合对照源码梳理页面交互、表结构与角色访问控制。目前已有 558 人学习下载，可作为中小型文档管理项目的结构范例与二次开发起点。

1. 从一份"找不到的合同"说起：文档管理系统到底要解决什么

很多团队的文件管理现状是：共享盘里躺着十几个版本的合同、标书、会议纪要，命名从"最终版"到"最终版修改再改"，找一份三天前确认过的文档要翻半小时聊天记录。更麻烦的是，多人协作时只能靠"你改完发我"来串行，谁改了什么、什么时候改的，全凭记忆。文档管理系统要解决的正是这类协作失序问题——把散落在个人电脑和聊天工具里的文件收拢到统一平台，让版本可追溯、权限可控制、编辑可并发。

这套基于 C# 和 ASP.NET 的实现方案，面向的是需要交课程设计或毕业设计的同学，以及要给中小团队搭内部文档平台的后端开发者。核心诉求可以归为四条：文档的集中存储与分类管理、浏览器内的在线编辑与多人在线协作、基于角色的细粒度权限控制、完整的操作审计与版本回溯。相比直接上第三方网盘，自建系统的价值在于数据完全自主可控，权限模型可以贴合组织架构定制，这是很多现成工具给不了的。

2. 技术选型与总体架构：为什么是 ASP.NET Core 三层结构

2.1 选型权衡：为什么不用纯前端方案

文档管理系统的技术选型，最容易踩的坑是一上来就想着"前端富文本编辑器+后端存 HTML"。这种思路处理纯文本还行，一旦文档里带复杂表格、批注、修订记录，HTML 的语义丢失会让你做版本比对时痛不欲生。所以这套方案在选型上做了两个关键决定：

后端选用 ASP.NET Core 而不是老版 ASP.NET MVC。差别不只是性能，更重要的是依赖注入和中间件管道是一等公民，权限校验、审计日志这类横切逻辑可以用中间件统一处理，不用在每个 Controller 里重复写。对于文档系统这种"每个接口都要鉴权"的场景，这个差异会随着接口数量增长被急剧放大。

文档的底层格式选用Office Open XML（OOXML）而不是 HTML 或 Markdown。docx 本质是个 zip 包，里面用 XML 描述内容，用 C# 的DocumentFormat.OpenXml库可以直接操作段落、表格、批注这些结构化元素，版本比对时能精确到"第 3 段第 2 句话改了"，而不是整篇 diff。代价是学习曲线陡一些，后面第 4 章会讲具体怎么操作。

存储层用 SQL Server 存元数据（文档信息、权限、版本索引），文件实体走对象存储或本地文件系统，两者用文档 ID 关联。这个拆分很重要——千万别把文件二进制直接塞进数据库的varbinary(max)字段，备份恢复和迁移时会让你怀疑人生。

2.2 三层架构与模块职责

整体架构按经典三层组织，每层的职责边界要划清楚，不然后期改一处牵动全身。

// 表现层：Controller 只负责参数校验和响应封装，不写业务逻辑 [ApiController] [Route("api/[controller]")] public class DocumentController : ControllerBase { private readonly IDocumentService _documentService; public DocumentController(IDocumentService documentService) { _documentService = documentService; } [HttpGet("{id}")] public async Task<IActionResult> GetDocument(Guid id) { // 当前登录用户从 HttpContext 提取，交给 Service 层做权限判断 var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value; var doc = await _documentService.GetDocumentAsync(id, userId); return doc == null ? NotFound() : Ok(doc); } }

表现层（Controller）只做三件事：接收参数、调用 Service、包装返回值。业务逻辑全部下沉到 Service 层，这样单元测试可以直接针对 Service 写，不用起 HTTP 服务。数据访问层用 EF Core，但涉及复杂权限查询时允许直接写 SQL——ORM 不是信仰，性能瓶颈处该绕就绕。

模块划分上，系统拆成五个核心模块：文档管理（增删改查、分类、标签）、在线编辑（OOXML 读写、协同锁）、权限控制（RBAC 模型、文档级授权）、版本管理（快照、比对、回滚）、审计日志（操作记录、查询导出）。前两个是业务主干，后三个是质量保障，很多学生项目只做前两个，答辩时被问"两个人同时编辑怎么办"就答不上来，所以这套方案把后三个模块也做实。

2.3 数据库核心表设计

元数据表设计直接决定了权限和版本功能能不能做顺，这里给出关键表的结构。

-- 文档主表：只存元数据，文件实体存文件系统 CREATE TABLE Documents ( Id UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(), Title NVARCHAR(200) NOT NULL, CategoryId INT NOT NULL, CurrentVersionId UNIQUEIDENTIFIER NULL, -- 指向当前生效版本 OwnerId NVARCHAR(64) NOT NULL, StoragePath NVARCHAR(500) NOT NULL, -- 文件相对路径 CreatedAt DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME(), IsDeleted BIT NOT NULL DEFAULT 0 -- 软删除，回收站用 ); -- 版本表：每次保存生成一条快照，不覆盖历史 CREATE TABLE DocumentVersions ( Id UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(), DocumentId UNIQUEIDENTIFIER NOT NULL, VersionNo INT NOT NULL, -- 从 1 递增 StoragePath NVARCHAR(500) NOT NULL, CreatedBy NVARCHAR(64) NOT NULL, CreatedAt DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME(), ChangeSummary NVARCHAR(500) NULL ); -- 权限表：文档级 + 角色级双维度授权 CREATE TABLE DocumentPermissions ( DocumentId UNIQUEIDENTIFIER NOT NULL, PrincipalType TINYINT NOT NULL, -- 1=用户 2=角色 3=部门 PrincipalId NVARCHAR(64) NOT NULL, PermissionLevel TINYINT NOT NULL, -- 1=只读 2=可编辑 3=可管理 PRIMARY KEY (DocumentId, PrincipalType, PrincipalId) );

Documents表里CurrentVersionId是冗余字段，指向当前生效版本，目的是查"最新版"时不用对DocumentVersions做 max 聚合。IsDeleted走软删除，配合定时任务清理，比物理删除安全。权限表用PrincipalType区分用户、角色、部门三种授权主体，实际鉴权时取三者权限的最大值，这个设计能覆盖"某部门全员可读、指定两人可编辑"这种常见需求。

3. 在线编辑模块实现：OOXML 操作与并发控制

3.1 用 OpenXml 读写文档内容

在线编辑的第一步是能解析和修改 docx。DocumentFormat.OpenXml是微软官方库，操作的是文档的 XML 结构，下面这段代码演示如何读取文档所有段落文本、并替换其中某个关键词：

using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Wordprocessing; public class DocumentEditor { // 读取所有段落文本，带段落索引 public List<(int Index, string Text)> ReadParagraphs(string filePath) { var result = new List<(int, string)>(); using var doc = WordprocessingDocument.Open(filePath, false); var body = doc.MainDocumentPart?.Document?.Body; if (body == null) return result; int index = 0; foreach (var para in body.Descendants<Paragraph>()) { var text = string.Concat(para.Descendants<Text>().Select(t => t.Text)); result.Add((index++, text)); } return result; } // 全文替换关键词，返回替换次数 public int ReplaceText(string filePath, string oldText, string newText) { int count = 0; using var doc = WordprocessingDocument.Open(filePath, true); var body = doc.MainDocumentPart?.Document?.Body; if (body == null) return 0; foreach (var text in body.Descendants<Text>()) { if (text.Text.Contains(oldText)) { count += text.Text.Split(oldText).Length - 1; text.Text = text.Text.Replace(oldText, newText); } } doc.MainDocumentPart!.Document.Save(); return count; } }

Open(filePath, false)第二个参数是isEditable，读取时传 false 避免文件被锁定。真正容易被忽略的坑是：docx 里的文本可能被拆散在多个Text节点里，比如"文档管理"四个字可能是两个 run 分别存"文档"和"管理"，直接对单个Text做 replace 会漏替换。稳妥的做法是先合并段落内所有 Text 再处理，或者用更上层的Paragraph级操作。上面代码演示的是简单场景，生产环境建议按段落聚合后处理。

3.2 并发编辑的锁策略

浏览器内多人同时编辑同一文档，如果不加控制，后保存的人会覆盖前一个人的修改，这是协同编辑里最经典的翻车现场。彻底解决要靠 OT（Operational Transformation）或 CRDT 这类协同算法，实现复杂度对学生项目来说偏高，这套方案采用折中的悲观锁 + 版本乐观校验组合：

public class EditLockService { private static readonly ConcurrentDictionary<Guid, (string UserId, DateTime ExpireAt)> _locks = new(); // 申请编辑锁，成功返回 true public bool TryAcquireLock(Guid documentId, string userId, TimeSpan ttl) { var now = DateTime.UtcNow; // 锁过期视为无主，允许抢占 if (_locks.TryGetValue(documentId, out var existing) && existing.ExpireAt > now) return existing.UserId == userId; _locks[documentId] = (userId, now.Add(ttl)); return true; } // 保存时校验：携带的 versionNo 必须等于当前最新版本，否则拒绝 public void ValidateVersion(Guid documentId, int clientVersionNo, int latestVersionNo) { if (clientVersionNo != latestVersionNo) throw new ConcurrencyException("文档已被他人修改，请刷新后重试"); } }

锁的 TTL 设为 5 分钟，前端每 2 分钟发心跳续期，用户关掉页面后锁自然过期，不会出现"某人锁死文档一下午"的情况。保存接口校验客户端版本号，版本不一致直接返回 409，前端提示用户刷新。这套机制不追求真正的实时协同，但能保证数据不丢，对多数内部文档场景够用。如果答辩时被追问协同算法，能说清 OT 和 CRDT 的适用边界就是加分项。

3.3 编辑锁与权限的联动

编辑锁不能孤立存在，必须和权限模块联动：只读用户根本不该走到加锁逻辑。实际处理顺序是——先查DocumentPermissions确认有编辑权限，再尝试加锁，最后才允许进入编辑态。这个顺序反了会导致"没权限的人占着锁"的尴尬情况。另外锁的粒度建议按文档整体锁，而不是按段落锁，段落级锁需要前端编辑器深度配合，投入产出比不划算。

4. 权限控制与版本管理：RBAC 落地与快照策略

4.1 权限校验的中间件实现

权限模块如果散落在各个接口里手动判断，迟早会漏。正确做法是用 ASP.NET Core 的授权过滤器统一拦截，下面是一个基于自定义策略的实现：

public class DocumentPermissionHandler : AuthorizationHandler<DocumentPermissionRequirement> { private readonly IPermissionService _permissionService; public DocumentPermissionHandler(IPermissionService permissionService) { _permissionService = permissionService; } protected override async Task HandleRequirementAsync( AuthorizationHandlerContext context, DocumentPermissionRequirement requirement) { // 从路由参数拿文档 ID if (context.Resource is HttpContext httpContext) { var docIdStr = httpContext.Request.RouteValues["id"]?.ToString(); if (!Guid.TryParse(docIdStr, out var docId)) return; var userId = context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value; if (userId == null) return; // 权限判定：用户直授权 > 角色授权 > 部门授权，取最高 var level = await _permissionService.GetEffectiveLevelAsync(docId, userId); if (level >= requirement.RequiredLevel) context.Succeed(requirement); } } }

GetEffectiveLevelAsync内部按用户直授权、角色、部门三个维度分别查表，取最大值返回。这样"张三被单独授予可编辑、但他所在部门只有只读"这种场景，张三拿到的是编辑权限，符合"个人授权优先"的直觉。所有需要鉴权的接口打上[Authorize(Policy = "DocEdit")]这类特性，漏写一处就是越权漏洞，所以代码审查时要重点看 Controller 上的特性标注。

4.2 版本快照的触发时机

版本管理的核心决策是"什么时候生成快照"。每敲一个字符存一个版本，存储会爆；只在用户手动点"保存版本"时才存，又可能丢失中间过程。这套方案的做法是三个触发点：用户手动保存、编辑锁释放、定时自动保存（间隔 10 分钟且有改动时）。

public async Task<DocumentVersion> CreateSnapshotAsync(Guid documentId, string userId, string summary) { var doc = await _db.Documents.FindAsync(documentId); var latestNo = await _db.DocumentVersions .Where(v => v.DocumentId == documentId) .MaxAsync(v => (int?)v.VersionNo) ?? 0; // 新版本文件写到独立路径，绝不覆盖旧文件 var newPath = $"storage/{documentId}/{latestNo + 1}.docx"; File.Copy(doc.StoragePath, newPath, overwrite: false); var version = new DocumentVersion { Id = Guid.NewGuid(), DocumentId = documentId, VersionNo = latestNo + 1, StoragePath = newPath, CreatedBy = userId, ChangeSummary = summary }; _db.DocumentVersions.Add(version); doc.CurrentVersionId = version.Id; await _db.SaveChangesAsync(); return version; }

关键点在于新版本写到独立路径，绝不覆盖旧文件。存储成本确实会涨，按每个 docx 平均 200KB、单文档 50 个版本算，一个文档占 10MB，对内部系统可以接受。真要省空间，可以对超过 30 天的旧版本做冷存储归档，但归档逻辑本身也可能出 bug，学生项目建议先不折腾。

4.3 版本比对与回滚

版本比对不需要自己写 diff 算法，直接对比两个版本的段落文本列表，用最长公共子序列找出差异段落即可。回滚操作要谨慎——回滚不是删除新版本，而是把目标版本的StoragePath复制成新版本，追加到版本链末尾。这样历史永远可追溯，用户回滚后悔了还能再回滚回去，相当于给操作留了后悔药。

5. 部署与避坑：静态资源、大文件与异步处理

5.1 部署清单与关键配置

系统部署到 IIS 时，web.config里有两个配置常被忽略却影响很大：

<configuration> <system.webServer> <security> <requestFiltering> <!-- 上传文件大小上限，默认 30MB，按需放大 --> <requestLimits maxAllowedContentLength="104857600" /> </requestFiltering> </security> <!-- 关闭目录浏览，防止 storage 目录被直接访问 --> <directoryBrowse enabled="false" /> </system.webServer> </configuration>

maxAllowedContentLength默认 4MB 左右，文档稍微带点图片就超限，表现为上传接口返回 404.13，排查半天以为是路由问题。storage目录必须放在站点根目录之外，或者用HttpHandler鉴权后再输出文件流，否则别人猜到路径就能绕过权限直接下载，这是文档系统最常见的安全漏洞。

5.2 避坑清单

现象：保存文档后版本号错乱，出现两个相同 VersionNo。原因是并发请求同时查max(VersionNo)拿到相同值。解决：给(DocumentId, VersionNo)加唯一索引，冲突时捕获异常重试一次，让数据库兜底比应用层加锁更可靠。

现象：在线编辑时中文乱码。通常是读取文件时用了错误的编码，或者前端编辑器把内容按 Latin-1 提交。解决：全程用 UTF-8，涉及 Base64 传输时明确编码声明，别让默认编码背锅。

现象：用户关闭浏览器后文档一直显示"被编辑中"。锁没有正确释放。解决：锁必须带 TTL 且依赖心跳续期，不能依赖用户显式"退出编辑"的动作，因为用户永远会直接关标签页。

现象：大文档（超过 50MB）打开时页面卡死。一次性把整个文档内容加载到前端。解决：分页加载段落，首屏只渲染前 50 页，滚动时按需请求后续内容。

现象：权限修改后不生效，用户仍能看到文档。权限查询走了缓存但更新时没失效。解决：权限变更时主动清缓存，或者缓存 key 里带用户+文档 ID 的版本号，从根上避免脏读。

6. 验收与答辩：怎么证明这套系统真的能用

验收环节最容易出问题的地方是：演示时只走"正常路径"，被问一个边界场景就现原形。我给自己的验收清单是这样的：准备两个不同角色的账号，A 编辑文档、B 同时打开，验证锁机制和 409 冲突提示；上传一个超限文件验证错误提示是否友好；连续保存五次验证版本链完整性；回滚到第三版再回滚回最新版，验证历史不丢。这几步走完，系统的基本可信度就建立起来了。

答辩时老师最爱追问的通常是三处：一是并发冲突怎么处理，答"悲观锁 + 版本号校验，冲突时返回 409 让用户刷新"要有底气，最好能现场演示；二是权限模型为什么这么设计，能画出用户、角色、文档三者的关系图就赢一半；三是文件存储为什么不用数据库，答"备份迁移成本和性能考虑"即可，别展开成大论战。数据指标上可以主动报一下：单文档 50 个版本下查询耗时、100 并发下的接口响应时间，有数字比形容词有说服力。

从那以后我每次做带权限和版本的系统，都会先把"两个人同时改会怎样"这个场景在纸上推演一遍，再动手写代码。很多设计缺陷不是写出来的，是推演阶段就能发现的。希望这套结构能帮到你，少走一遍我踩过的弯路。

本文还有配套的精品资源，点击获取