• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用

导读：本文围绕 DooTask「文件」模块的入口与基本使用，完整说明桌面端 Web / Electron、移动端以及直接 URL 四种进入方式，梳理「我的文件 / 共享文件 / 协作文件」三大板块的默认视图与权限规则，并给出上传、新建、共享、预览、搜索、WebDAV 挂载等常见操作的高频要点。阅读后你可以快速定位文件入口、理解文件树的底层数据结构（pid/pids/pshare字段），并掌握 DooTask 文件功能的能力边界。

一、文件入口在哪：四条路径对照

在 DooTask 中，「文件」是一级导航（系统级入口），集中展示个人文件、共享文件和协作场景中的文件，它的定位接近内置网盘。进入方式共有四种，覆盖桌面端、桌面客户端与移动端：

几个容易混淆的细节：

• 快捷键：文件入口本身没有快捷键；但选中文件后，重命名支持F2、删除支持Delete键（见下文「高频操作」）。
• 不可隐藏、不可改顺序：文件菜单是系统级一级入口，前端无法隐藏或调整顺序（参见 入口详解 的 negative 说明）。
• 不支持挂载外部网盘：如百度网盘、OneDrive 等第三方网盘均不支持挂载，DooTask 文件功能是独立的内部存储体系。
• 访客（游客 token）限制：所有登录用户都能看到「文件」入口，但游客只能访问被显式标记guest_access的链接，无法进入文件管理页。

前端路由resources/assets/js/routes.js中注册了/manage/file对应页面组件./pages/manage/file.vue，与文档中的 URL 入口相互印证。

二、默认视图：三大板块与面包屑

进入「文件」页后，顶部是板块 Tab，主区域按板块展示内容：

• 我的文件：我拥有的全部文件（含已共享出去的；共享不会让文件从「我的文件」消失）。
• 共享文件：双向共享聚合——既包含「我共享出去的」，也包含「别人共享给我的」，可用「全部 / 我共享的 / 共享给我的」二次筛选；我共享出去的文件会同时出现在「我的文件」与「共享文件」两个板块。
• 协作文件：汇总当前用户有权访问的私聊、普通群聊、项目群聊和任务聊天中的文件，可按会话或项目继续筛选。

进入子文件夹后，Tab 下方出现面包屑路径（以板块名为起点，可点击回到板块根目录）；根目录不显示重复标题。主区域列出当前文件夹下的文件与文件夹，单次最多展示 500 条，超出部分滚动加载。板块选择会记住上次停留的 Tab。

权限要求

• 所有登录用户可见，无管理员限制。
• 看到的内容范围 = 自己创建的 + 他人共享给我的，不包含全公司维度浏览所有人文件（出于隐私设计，这是明确的限制项）。
• 对某个文件的具体操作权限分为四级，由File::getPermission()计算（详见 File.php）：

三、核心入口之「上传」：分片、断点续传与秒传

桌面端 Web 进入「文件」页任意文件夹，点顶部「+」→「上传文件 / 上传文件夹」，或直接把文件拖入页面任意位置（Electron 可拖入应用窗口）；移动端在「文件」页右上角「+」→「上传文件」（受系统相册 / 文件选择器限制）。

上传时系统按扩展名自动识别类型（word / excel / picture / archive 等），保存路径为uploads/file/<type>/<年月>/<id>/；同名同后缀文件已存在时，可选「保留两个」（默认）或「覆盖」（cover参数为 1）。

上传文件夹：拖入整个文件夹时，系统按webkitRelativePath重建文件夹结构，路径中每一级文件夹自动创建（已存在则复用）；空目录会被忽略，只创建有文件的层级。该逻辑在File::contentUploadPrep()（File.php）中实现：逐级拆分路径、按pid + type=folder + name查询或创建中间文件夹，并利用lockForUpdate()防止并发竞态。

大文件 / 断点续传 / 秒传（实现在 ChunkUpload.php）：

• ≥10MB 自动分片：文件切成 5MB 分片（CHUNK_SIZE = 5 * 1024 * 1024），3 路并发上传；前端先在 Web Worker 中计算 md5，不阻塞 UI。
• 断点续传：上传中刷新页面或断网后，重新选择同一文件会跳过已上传分片，从中断处继续。服务端用 Redisupload:*key 保存分片索引与元数据，TTL 24 小时（STATE_TTL = 86400）；浏览器侧用localStorage的chunked_upload:<hash>索引（同样 24 小时）定位续传点。
• 秒传：同一用户上传过相同 md5 的文件（命中files.hash字段）时，目标文件夹立即出现新记录，零传输。ChunkUpload::trySecondPass()会在 merge 前按hash + userid反查复用已有内容。
• 残留清理：uploads/tmp/chunks/{userid}/{upload_id}/中超过 24 小时的残留分片由DeleteTmpTask定时任务兜底清除。

限制：单文件夹直接子项上限 300（超出拒绝）；续传索引存于 localStorage，跨设备 / 跨浏览器无效（服务端可按 hash+userid 反查兜底）；移动端切后台可能中断上传。

四、核心入口之「新建」：文件夹与在线文档类型

「文件」页内任意文件夹点顶部「+」，可新建以下类型：

命名规则：文件名必填，长度 2–100 字符，不能包含\ / : * ? " < > |；同名冲突时系统自动追加(2)、(3)后缀（File::handleDuplicateName()实现，见 File.php）。文档类型创建后自动打开编辑器，可立即编辑。

默认字段：拥有者为所在文件夹的拥有者（共享文件夹内则归文件夹所有者），创建人为当前用户，父目录为当前文件夹。不支持新建 PDF / 图片 / 压缩包等二进制类型（只能上传），不支持批量新建，不支持复制文件夹。

五、文件树结构：pid / pids / pshare 的底层模型

DooTask 文件以树形结构组织（详见 tree.md），每个文件或文件夹（type=folder）都是files表的一条记录，通过字段描述层级与共享归属：

saveBeforePP()（File.php）在保存前递归向上重建pids与pshare链，并在祖先变化时向下级联更新子树，保证路径与共享信息的强一致。

与「项目任务文件」的区别：文件树是用户的网盘（独立功能）；项目任务文件是附在任务下的附件，存于project_task_files表，两者完全隔离、互不可见。

容量限制：单文件夹直接子项上限 300（含子文件夹）；整树深度无强制上限但不推荐超过 10 层；共享文件夹最多 100 个共享成员。

六、共享与他人协作：权限两档与数据结构

入口：桌面端 Web 选中文件 / 文件夹 → 右键 /「···」→「共享设置」；或在文件列表「共享」段点开已共享项 → 设置图标。

操作三步：进入共享设置弹窗 → 搜索框添加协作成员（可多选）→ 选择权限并确定。权限只有两档：

• 只读（permission=0）：只能浏览 / 下载。
• 读写（permission=1）：可编辑 / 上传 / 在共享文件夹内新建。

共享数据结构（与 FileUser.php 及 File.php 对应）：

• 共享记录存于file_users表，每条 = 一个文件 × 一个用户 × 一个权限。
• 文件的share字段标记自身是否为共享根，pshare指向其所在共享根 ID。
• 共享根之下的所有子文件、子文件夹自动继承共享（getShareInfo()沿pid链向上找到共享根，scopeSharedToUser按pshare+file_users筛选“别人共享给我的”文件）。

共享后读写成员可以在共享文件夹内创建 / 上传新文件；成员看到的拥有者仍是原拥有者；被共享方可在自己文件页对该文件「退出共享」。

限制：不能嵌套共享（已在共享文件夹内的子项不能单独再共享）；共享给「所有人」（userid=0）的链接，被共享方不能退出；单个共享最多 100 个成员；没有「评论」「仅看链接」「下载禁止」等中间档。

七、公开访问链接与游客访问

选中文件 → 右键 /「···」→「分享链接 / 获取链接」，或从文件预览页右上角「分享」按钮进入。

• 首次获取时系统生成一条file_links记录，链接形如https://your-domain.com/single/file/<base64-code>；code由file_id + userid + 随机串经 base64 编码得到（见 FileLink.php），请勿泄露。
• 同一用户对同一文件只有一个链接，再次获取返回同一个 code；勾选「刷新链接」可重新生成，旧 code 立即作废，无过渡期。
• 登录用户点链接进入文件预览页，受文件本身权限校验；游客访问仅当guest_access=1时可直接预览，否则跳登录（校验逻辑在FileController::one()，FileController.php）。
• 每次访问num计数 +1，可在分享设置看到累计访问数。

不支持：设置过期时间（除非手动刷新或删文件）、访问密码、总访问次数上限。给 MCP / AI 使用时，可用api/file/fetch按文件路径分页获取文本内容（offset/limit参数，默认 50000 字符、最大 200000）。

八、在线预览与编辑：插件依赖一览

文件预览指在浏览器内不下载即可查看的能力（详见 preview.md），不同文件类型走不同预览管线：

• 浏览器直接预览（无需插件）：document（内置 Markdown 渲染）、txt / code（纯文本与代码高亮，代码预览限制 2M 内）、picture（jpg / png / webp / gif / bmp）、mind（需 minder 插件，但随包默认提供）、drawio（需 drawio 插件）。
• 需安装插件预览：word / excel / ppt 由 OnlyOffice 渲染（office 插件）；pdf / cad / ofd / tif / wps 由 fileview 插件提供。
• 不支持预览：archive（zip / rar / 7z 只能下载，无在线解压）、media（mp3 / mp4 / mov 直接下载，预览依赖浏览器原生）、axure（rp 仅记录类型，需用 Axure 客户端查看）。

在线编辑类型：document、word/excel/ppt（office 插件）、mind、drawio；仅预览类型：pdf 及其他 fileview 支持的类型。编辑权限受 FileUser 权限位（读写 / 只读）控制。未安装对应插件时打开会提示「未安装」，但仍可下载。

九、搜索与协作文件：能力边界

文件名搜索（文件页内置）：文件页顶部搜索框输入即筛选，按name LIKE %关键词%包含匹配（不分词）；关键词为纯数字时同时按文件 ID 精确匹配（File::scopeSearchByKeyword，见 File.php）。搜索范围 = 自己的文件 + 他人共享给我的文件，单次最多返回 100 条。搜索框也可粘贴分享链接，系统会解析 code 反查文件。

文件内容搜索（全局搜索）：走全局搜索（Manticore 索引），仅文档类（document / txt / code / pdf 抽取出的文本）被索引；office 文件（doc / xls / ppt）索引后可按内容关键词命中；图片不参与内容索引（需理解图中文字可交给 AI 助手多模态识别）。

协作文件：「文件」→ 顶部「协作文件」，可看会话、项目和任务中的文件，支持按「会话 / 项目 / 任务」筛选，也可按文件类型、成员、发送人筛选，可搜索文件名、会话名、项目名、任务名。一条聊天消息含多张图片时每张独立展示；Electron 客户端会同步本地下载状态（未下载 / 下载中 / 已下载可定位）。协作文件只展示当前仍有权限的来源；已撤回或删除的文件消息不显示；遵循任务可见性规则。

限制：协作文件是只读聚合视图，不支持新建、上传、移动、删除；不汇总以文本链接分享的个人文件。

十、WebDAV：把 DooTask 文件挂载到本机

管理员已启用 WebDAV 并允许当前用户时，可在「文件」页右上角「···」→「WebDAV」创建连接凭据：

1. 停留在「我的文件」或「共享文件」板块，点右上角加号右侧的圆形「···」→「WebDAV」。
2. 点「新建」，填写设备名称与有效期。
3. 创建后立即保存弹窗中的连接地址、用户名和应用密码（应用密码只显示一次，关闭后不可再查看，只能撤销后重建）。

连接后的目录：files/为「我的文件」（允许按权限新建、读取、修改、移动、删除）；shared/为共享给我的文件（共享顶层名称带[#文件ID]标识，用于避免重名，勿手工删除）。只读共享只能浏览下载，读写共享可保存修改与新建。

连接采用 HTTP Basic 应用密码认证，但服务端只允许通过 HTTPS 传输，因此必须使用弹窗给出的三项信息，并确保当前页面为 HTTPS。设备管理支持查看名称、状态、凭据尾号、有效期、最近使用时间，可撤销或永久删除凭据（撤销后设备立即认证失败；永久删除不影响既有 WebDAV 操作审计日志）。

常见问题：看不到入口 = 管理员未开启或不在成员范围；无法创建密码 = 非 HTTPS 或达到每人应用密码数量上限；密码忘记不可找回（撤销重建）；保存失败需检查共享权限、文件锁、名称合法性及大小限制。

十一、移动 / 重命名 / 删除与恢复：高频操作要点

删除会走File::deleteFile()事务（File.php）：软删自身 → 推送删除消息 → 清共享配置与分享链接 → 递归删除子项。注意：任务里引用了该文件的「关联文件」不会自动清理，会显示「文件不存在或已被删除」。

十二、文件版本历史：谁改过、怎么回滚

对支持在线编辑的文件，每次保存都会在file_contents表插入新记录（FileContent），文件本身（File 表）只指向最新版，通过whereFid + orderByDesc('id')可查出全部历史（详见 version.md 与 FileContent.php）。

file_contents关键字段：fid（所属文件 ID）、content（JSON 元数据，含真实存储路径 url、类型 type、扩展 ext）、text（提取的纯文本，用于全文检索）、size（本版本字节数）、userid（本次保存人）、created_at（保存时间）。

有版本的类型：document、word / excel / ppt（OnlyOffice 在线编辑）、mind、drawio。无版本的类型：上传的二进制文件（pdf / archive / picture / media 等覆盖上传只保留最新一版）；folder 本身无内容无版本。

查看与恢复：文件预览页 / 编辑页 → 顶部菜单「历史记录」，列表显示每一版的保存人头像 + 时间 + 大小；选某一版可「预览」或「恢复」（恢复 = 把该历史版复制为新的最新版，保留中间版本）。多人协作时由 OnlyOffice 自身协同逻辑保证一致性，并在最后一个编辑者关闭后回写一版到 FileContent。

十三、能力边界速查（来自官方文档的 negative 声明）

• 「文件」入口不能隐藏 / 改顺序；不支持挂载外部网盘（百度网盘 / OneDrive）。
• 不支持按全公司维度浏览所有人文件（隐私设计）。
• 单文件夹直接子项上限 300；单次上传/移动/删除最多 100 项。
• 不支持软链接 / 快捷方式（一个文件只能在一个位置）。
• 版本历史仅对在线编辑类有效，无「版本备注」字段。
• 共享没有「评论」「仅看链接」等中间档；嵌套共享被拒绝；单个共享最多 100 成员。
• 链接不支持期限 / 密码 / 访问次数上限；刷新后旧链接立即失效。
• 文件页内置搜索只匹配文件名与文件 ID，不搜内容；内容搜索需 Manticore 索引，二进制文件（压缩包 / 视频）不参与。
• 删除无前端回收站 UI，普通用户无法自助恢复。

相关文档延伸阅读

• 文件入口详解
• 上传文件操作
• 共享与协作权限
• 协作文件聚合视图
• 公开访问链接
• 文件预览类型 ｜ 文件树结构 ｜ 版本历史
• WebDAV 访问文件
• 底层实现：核心模型 File.php、FileContent.php、FileUser.php、FileLink.php，分片上传 ChunkUpload.php，接口控制器 FileController.php，路由入口 routes.js

• 后端
• 前端
• 协同办公
• 即时通讯
• 企业应用