16 KiB
NEX Docus 使用手册
面向使用者与项目管理员的功能说明（v1.0.0）。 部署/运维请看
docs/deploy/README.md，本地跑起来请看docs/quickstart.md。
目录
- 1. 认识 NEX Docus
- 2. 登录与账号
- 3. 界面总览
- 4. 项目空间
- 5. 文档浏览页
- 6. 编辑模式（编辑 + 文档索引）
- 7. 成员、角色与分享
- 8. Git 仓库同步
- 9. 知识库对话（AI 问答）
- 10. 个人桌面、通知与个人设置
- 11. 系统管理（管理员）
- 12. 快捷键与交互约定
- 13. 常见问题
1. 认识 NEX Docus
NEX Docus 是一个团队文档管理平台，把三件事放在一起：
- 文档管理：以「项目」为单位组织 Markdown / PDF / 图片等文件，支持目录树、在线编辑、版本化的 Git 同步。
- 知识检索：文档可被切块并向量化，配合自研的全文检索 + 向量检索双引擎。
- AI 问答：在知识库对话中基于你自己的文档回答，并给出可点击的引用来源。
三类典型角色：
| 角色 | 主要动作 | 常用入口 |
|---|---|---|
| 读者 | 浏览、搜索、问答 | 项目空间 → 文档浏览页 / 知识库对话 |
| 编辑者 | 新建、编辑、整理目录、分享 | 编辑模式 |
| 管理员 | 用户/角色/权限、模型配置、系统日志 | 系统管理 |
2. 登录与账号
访问前端地址（默认开发 http://localhost:5173，Docker http://<服务器>:8080），未登录会自动跳转 /login。
- 输入用户名 + 密码登录，令牌默认有效期 24 小时，过期后需重新登录。
- 首次部署的默认管理员账号取决于部署方式（本地开发与 Docker 默认密码不同，详见
docs/deploy/changelog.md§5）。 - 登录后请立即修改密码：右上角头像 → 个人设置 → 修改密码。
- 被管理员重置密码后，新密码为系统默认密码（同样在个人设置中改为自己的密码）。
登录失败排查：提示「用户名或密码错误」时先确认部署方式对应的默认密码；提示网络错误则先确认后端 /health 是否可访问（curl http://<后端地址>:8000/health）。
3. 界面总览
登录后左侧为功能导航，内容由服务端下发的菜单权限决定，常见结构：
| 菜单 | 路径 | 用途 |
|---|---|---|
| 个人桌面 | /desktop |
个人工作台：常用项目、最近文档、我的动态 |
| 管理面板 | /dashboard |
管理员统计视图（用户、项目、文档、活动） |
| 项目空间 → 我的项目 | /projects/my |
我拥有/参与的项目 |
| 项目空间 → 分享给我的 | /projects/share |
别人分享给我的项目 |
| 知识库空间 | /chat |
AI 问答会话列表与对话界面 |
| 系统管理 | /system/* |
权限管理 / 用户管理 / 角色管理 / 模型配置 / 系统日志 |
顶部栏右侧提供：主题切换（浅色/深色）、通知入口、用户菜单（个人设置、退出登录）。
菜单可见性由「系统管理 → 权限管理」控制。看不到某个入口通常是没有该菜单权限，而不是功能坏了。 旧版本的知识库路径
/knowledge、/knowledge/my会自动重定向到/chat。
4. 项目空间
项目是文档的容器，一个项目对应磁盘上的一份文件目录。
4.1 创建项目
「我的项目」→ 右上角「创建项目」→ 填写项目名称、描述。创建者自动成为所有者。
4.2 项目卡片操作
每个项目卡片右上角提供：
| 图标 | 名称 | 说明 |
|---|---|---|
| ✏️ / 卡片本身 | 打开 | 进入文档浏览页 |
| ⚙️ | 项目设置 | 修改名称、描述、是否公开项目、是否允许公开分享 |
| 🗄 | 知识库向量化 | 打开向量化弹窗，见 §9.1 |
| 👥 | 成员管理 | 添加/移除成员、调整角色、转移所有权 |
| 🗑 | 删除项目 | 仅所有者/管理员，操作不可逆 |
卡片下方展示文档数量、最后更新时间、参与人数量。
4.3 项目可见性
- 私有项目：仅所有者与成员可见。
- 公开项目：全站登录用户可见（列表只读，编辑仍需 editor/admin 角色）。
- 项目公开分享：开启后才能生成对外分享链接（见 §7.3）。
5. 文档浏览页
路径：/projects/<项目ID>/docs。这是阅读与整理的主界面，左侧目录树 + 右侧渲染区。
5.1 目录树
- 点击文件：右侧渲染 Markdown / PDF / 图片 / 代码等。
- 右键节点（或节点右侧的更多按钮）：新建文件、新建文件夹、重命名、移动、删除。
- 拖拽：把文件或文件夹拖到目标文件夹即可移动，拖到根目录即移到顶层。
- 目录树支持折叠全部/展开全部，并展示非文档类文件（可通过筛选开关隐藏）。
5.2 页内操作
顶部面包屑右侧：
| 入口 | 说明 |
|---|---|
| 搜索文档内容 | 在项目内按关键词搜索文档正文，结果点击后直接跳到目标文件并高亮关键词 |
| 编辑 | 进入编辑模式（§6），并带上当前选中的文件 |
| 分享 | 生成该文件或项目的分享链接，可设置访问密码（§7.3） |
| 刷新 | 重新拉取目录树（外部改动、Git 同步后使用） |
| Git Pull / Git Push | 与远端仓库同步，可选择同步范围（仅某个目录）；见 §8 |
6. 编辑模式（编辑 + 文档索引）
路径：/projects/<项目ID>/editor。从文档浏览页点「编辑」进入，会保留当前选中的文件。
6.1 三种视图模式
编辑器工具栏右侧的分段控件在三种模式间切换，与「全屏」按钮同排，默认只打开编辑区：
| 模式 | 图标 | 内容 | 适用场景 |
|---|---|---|---|
| 编辑（默认） | 笔 | 只有 Markdown 源码编辑区，占满整个内容宽度 | 专注写作 |
| 分栏 | 双栏 | 左编辑 + 右实时预览 | 检查排版、表格、图片 |
| 预览 | 眼睛 | 只渲染结果 | 交付前自查 |
- 三个按钮只显示图标，鼠标悬停显示「编辑 · 仅编辑区」等说明文字，与同行其他图标保持一致。
- 选择会被记住（写入浏览器本地存储），下次进入编辑模式沿用；不再强制并排打开预览。
- 只有在分栏模式下才会出现「同步滚动」开关；纯编辑 / 纯预览时没有左右对照，该开关自动隐藏。
6.2 文档索引（Table of Contents）
编辑区右侧悬浮「文档索引」面板列出当前文档的标题层级：
- 目录来自 Markdown 源码解析，因此在纯编辑模式下同样可用，不依赖预览区是否打开。
- 点击条目：编辑器滚动到对应标题并把光标定位过去（编辑模式下不会跳走页面）。
- 文档没有标题时面板显示为空；标题层级过深时按层级缩进。
6.3 保存、重置与未保存保护
- 保存：把编辑区内容写回服务器文件。快捷键
Ctrl/Cmd + S（弹窗打开或正在保存时不会触发）。 - 未保存标记：内容与服务端版本不一致时，内容区右上角显示「未保存」标记。
- 退出保护：点「退出编辑」时，只有在确有未保存改动才弹确认框（「放弃修改并退出 / 继续编辑」）；关闭浏览器标签或刷新页面时，浏览器也会给出挽留提示。
- 重置：放弃本地改动，重新加载服务器上最后一次保存的版本（同样需要确认）。
6.4 编辑区的其他能力
- 上传文件：把本地文件（含图片）上传到当前目录，图片自动写入相对路径引用。
- 插入链接：支持页内链接（选择本文标题生成锚点）与页间链接（选择项目内其他文件）。
- 新建/重命名/移动/删除：与浏览页一致的目录树右键菜单。
- 大文档模式：超大 Markdown 自动切换为轻量编辑器（此时不提供分栏/预览），避免卡顿。
- 全屏：点工具栏右侧的全屏图标把编辑器铺满整个窗口，左侧项目树的操作按钮不会浮现在编辑器上；再点一次该图标或按
Esc退出全屏。
7. 成员、角色与分享
7.1 项目角色
| 角色 | 能做什么 |
|---|---|
| 所有者 owner | 全部权限，含删除项目、转移所有权 |
| 管理员 admin | 管理成员与全部文档，可转让所有权以外的操作 |
| 编辑者 editor | 新建/编辑/删除文档、上传、Git 同步 |
| 查看者 viewer | 只读浏览、搜索、参与 AI 问答 |
7.2 管理成员
项目卡片 → 成员管理 → 按用户名搜索添加，并为成员指定角色；也可以在此转移项目所有权。移除成员不会删除其创建的文档。
7.3 分享链接
- 项目分享：项目设置里开启「项目公开分享」后生成链接，形如
/share/project/<分享码>。 - 文件分享：文档浏览页对单个文件点「分享」，形如
/share/file/<分享码>。 - 可设置访问密码，访问时需先输入密码。
- 分享页只读，不提供编辑入口；关闭「公开分享」会让既有链接失效。
安全提示：分享链接无需登录即可访问，请勿把含敏感信息的文档设为公开分享；管理员应定期清理不再使用的分享。
8. Git 仓库同步
用于把项目目录和一个 Git 仓库对接（适合团队用 IDE/命令行协作，同时保留 Web 编辑）。
配置：项目卡片 → 成员管理旁的 Git 仓库管理入口 → 填写仓库别名、Git 仓库地址、分支、用户名、Token/密码。
使用：文档浏览页顶部「Git Pull / Git Push」，两者都可选择同步范围（只同步某个子目录），避免大仓一次性同步。
前提与注意：
- 服务端所在主机必须安装
git命令（后端通过命令行调用 git，不是内置实现）。 - 私有仓库请优先使用 Access Token 而不是账号密码。
- 冲突时同步会失败并返回 git 的原始报错，请在本地仓库解决冲突后重试。
- 同步完成后点「刷新」重载目录树。
9. 知识库对话（AI 问答）
路径：/chat（新建会话 /chat/new）。左侧会话列表，右侧对话区。
9.1 先决条件：模型配置 + 向量化
- 管理员在「系统管理 → 模型配置」中启用至少一个 chat 模型（回答用）和一个 embedding 模型（向量化用）。
- 项目卡片 → 「知识库向量化」→ 选择增量向量化（只处理新增/变更文档）或全量向量化（重建索引）。弹窗展示最近任务的状态、进度与已向量化数量。
若弹窗提示「尚未配置可用的向量模型」，说明 embedding 模型未启用，或向量维度与模型实际输出不一致（
ZVEC_EMBEDDING_DIM）。
9.2 提问
- 新建对话时选择要检索的项目/知识库，可以选择多个。
- 答案以流式返回，过程中可点停止中断生成。
- 回答下方展示引用来源（命中的文档与片段），点击可跳转到原文档位置。
- 界面给出耗时等运行信息，便于判断是检索慢还是模型慢。
9.3 检索行为
问答走双引擎：关键词（全文）检索 + 向量（语义）检索，合并后交给模型。因此：
- 精确术语/代码标识符命中靠全文检索；换词、口语化提问靠向量检索。
- 文档改了但答案还是旧的 → 通常是忘了做增量向量化。
- 没向量化过的项目只能靠全文检索，质量会明显下降。
10. 个人桌面、通知与个人设置
- 个人桌面
/desktop：个人工作台，快速进入常用项目与最近编辑的文档。 - 通知中心
/notifications：查看项目邀请、文档变更、向量化/同步任务结果等站内通知，支持标记已读。
10.1 个人设置（/profile）
| 标签页 | 内容 |
|---|---|
| 个人资料 | 修改昵称、邮箱、头像（图片不超过 1MB） |
| 修改密码 | 校验原密码后设置新密码，修改后需重新登录 |
| MCP 接入 | 查看/复制本人的 X-Bot-Id 与 X-Bot-Secret，可重新生成 Secret |
重新生成 MCP Secret 会立即让旧的 Secret 失效，用旧凭证配置的 MCP 客户端（如 IDE、机器人）需要同步更新。MCP 的接入方式与可用工具见
docs/sdd/integrations/mcp.md。
11. 系统管理（管理员）
| 页面 | 路径 | 作用 |
|---|---|---|
| 权限管理 | /system/permissions |
维护菜单与权限点，并给角色授权；决定用户能看到哪些入口 |
| 用户管理 | /system/users |
新增用户、启停用、重置密码、分配角色 |
| 角色管理 | /system/roles |
新增角色、改名与描述、绑定权限 |
| 模型配置 | /system/model-configs |
维护 LLM 服务：类型分 chat / embedding，配置名称、服务地址、API Key、模型名、维度，并设为默认/启用 |
| 系统日志 | /system/logs |
查看操作与系统日志，用于排查问题 |
模型配置注意：
- embedding 模型一旦用于向量化，维度就不能随意改；换模型需同时更新
ZVEC_EMBEDDING_DIM并做全量向量化。 - 使用自签名 HTTPS 的私有模型服务时，需要
DISABLE_SSL_VERIFY=true（仅该场景，生产保持false）。 - API Key 属于敏感信息，只有管理员可维护，界面上会做掩码处理。
12. 快捷键与交互约定
| 场景 | 操作 |
|---|---|
| 保存当前文档 | Ctrl/Cmd + S（编辑模式） |
| 打开文件/目录操作菜单 | 目录树节点右键 |
| 移动文件/目录 | 目录树中拖拽到目标文件夹 |
| 返回上一级视图 | 面包屑点击，或浏览器后退 |
| 深浅色切换 | 顶部栏主题开关，选择会被记住 |
统一交互约定：
- 危险操作（删除项目/文件/成员、Git 推送等）一律先弹确认框，确认后才执行。
- 操作结果用轻提示反馈（不打断操作）；表单错误就近显示在字段下方。
- 列表/树加载时显示骨架或加载态；空数据统一显示空状态占位与下一步引导。
- 只读角色（viewer）不会看到编辑、删除类按钮。
13. 常见问题
Q：打开项目只有阅读区，找不到编辑按钮？ A：当前账号在该项目中是「查看者」。让所有者/管理员在成员管理里把角色提升为「编辑者」或「管理员」。
Q：编辑模式右边没有预览，是不是坏了？ A：不是。v1.0.0 起默认只打开编辑区，点编辑器工具栏右侧的分段控件切到「分栏」或「预览」即可；选择会被记住。
Q：文档索引（TOC）里是空的？
A：目录来自 Markdown 标题（#/##…）。文档没有标题，或超大文档走了大文档模式时，索引可能为空或受限。
Q：AI 问答说「文档里没有相关内容」，但文档确实存在？ A：按顺序检查：① 会话是否选中了正确的项目；② 该项目是否做过（增量）向量化；③ 模型配置里 chat / embedding 模型是否都已启用。
Q：向量化一直不动或失败？
A：先看弹窗里最近任务的报错，再看「系统日志」和后端日志。常见原因是 embedding 服务不可达、维度不匹配，或 Redis 拒绝写入（MISCONF，见 docs/quickstart.md FAQ）。
Q：Git 同步报错 git: command not found？
A：后端主机未安装 git。容器部署时需要在镜像内提供 git（docs/deploy/README.md 有说明）。
Q：分享链接打不开？ A：确认项目设置里「项目公开分享」仍为开启状态；文件分享需对应文件仍存在；有密码的要先输密码。
Q：左侧菜单少了一块？ A：菜单由权限控制，见「系统管理 → 权限管理」中该角色的菜单授权。