mula
/
nex_docus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NEX Docus
90 Commits
1 Branch
0 Tags
78 MiB
JavaScript 69.6%
Python 23.5%
CSS 5.7%
Shell 1%
Dockerfile 0.2%
 
 
 
 
 
Go to file
mula.liu f1ba8949f6 优化了编辑模式 2026-10-04 02:16:13 +08:00
backend 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
docs 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
frontend 优化了编辑模式 2026-10-04 02:09:28 +08:00
scripts 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
.dockerignore Stage 2 & 3: Remove Graphy, integrate ZVec vectorization, and add knowledge base chat 2026-06-23 21:58:16 +08:00
.env.example 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
.gitignore 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
README.md 解决编辑模式的问题 2026-10-01 15:21:38 +08:00
docker-compose.yml 解决编辑模式的问题 2026-10-01 15:21:38 +08:00

README.md

NEX Docus 文档管理平台

轻量、可自托管的团队文档中心：文件系统存储内容，数据库管理权限，内置 AI 知识库问答。

v1.0.0 · FastAPI + React 18 + MySQL 8 + Redis

✨ 核心特性

  • 📁 文件即真理：文档正文以 Markdown 文件形式存放在磁盘（storage/projects/<uuid>/…），数据库只保存权限与元数据，备份/迁移只需拷目录。
  • 📝 Markdown 编辑：基于 ByteMD 的编辑器，支持 编辑 / 分栏 / 预览 三态切换，右侧悬浮目录（TOC）在纯编辑模式下同样可用；支持 GFM、代码高亮、Frontmatter、emoji、图片上传。
  • 🌲 无限层级目录树：文件/文件夹创建、重命名、拖拽移动、排序。
  • 👥 团队协作：项目成员与项目内角色（admin / editor / viewer），公开项目与「参与项目」列表。
  • 🔎 双引擎检索：本地全文检索（Whoosh + jieba 中文分词）＋ 向量检索（ZVec / 远程 Embedding）。
  • 🤖 AI 知识库问答：基于项目文档的 RAG 对话，返回引用文件与命中片段，可中断、可回看思考过程与耗时。
  • 🧩 模型配置中心：在系统管理里维护 Chat / Embedding 模型（OpenAI 兼容接口、本地 sentence-transformers），运行时热切换。
  • 🔗 分享与预览：项目/单文件分享链接（可带访问密码）、Markdown / PDF / 图片预览，PDF 支持服务端导出。
  • 🔐 RBAC：用户 / 角色 / 菜单与按钮级权限点，侧边栏按授权动态生成。
  • 📄 通知与审计：站内通知中心、全量操作日志检索。
  • 🔄 Git 双向同步：项目可绑定 Git 仓库，按目录同步文档。
  • 🛰️ MCP 接入：为 MCP Bot 提供凭证与文档读写能力。
  • 🌗 明暗双主题：全站统一设计令牌（styles/design-tokens.css + antd 主题），跟随系统或手动切换。

🏗️ 技术栈

后端

组件 选型
Web 框架 FastAPI 0.109 + Uvicorn（全异步）
ORM SQLAlchemy 2.0（asyncio + aiomysql）
数据库 MySQL 8.0（utf8mb4）
缓存/队列 Redis 7
认证 JWT（python-jose）＋ bcrypt 密码哈希
检索 Whoosh3 + jieba（全文）、ZVec + sentence-transformers / 远程 Embedding（向量）
文档处理 markdown、weasyprint（PDF）、python-magic
集成 OpenAI 兼容 LLM 接口、系统 git 命令（subprocess 调用）、MCP SDK

前端

组件 选型
框架 React 18 + React Router v6
构建 Vite 5（manualChunks 分包、全部路由 lazy 加载）
UI Ant Design 5 ＋ 自研设计令牌（无 Tailwind / postcss）
状态 Zustand ＋ Axios 统一封装
Markdown ByteMD（@bytemd/react + gfm/highlight/frontmatter/breaks/gemoji）＋ react-markdown 渲染
其它 react-pdf / pdfjs-dist、react-virtuoso、antd-img-crop

📦 项目结构

NexDocus/
├── backend/                # FastAPI 后端
│   ├── app/
│   │   ├── api/v1/         # API 路由（认证/项目/文件/检索/对话/分享/系统…）
│   │   ├── core/           # 配置、数据库、安全、依赖注入、幂等迁移
│   │   ├── models/         # SQLAlchemy 模型（18 张表）
│   │   ├── schemas/        # Pydantic Schema
│   │   ├── services/       # 业务逻辑（存储、检索、向量化、RAG、Git、导出…）
│   │   └── mcp/            # MCP Streamable HTTP 接入（凭证鉴权 + 工具注册）
│   ├── scripts/            # 数据库初始化脚本（随代码走，Docker 构建上下文需要）
│   ├── tests/              # pytest 用例
│   └── main.py             # 应用入口
│
├── frontend/               # React 前端
│   └── src/
│       ├── api/            # 接口封装
│       ├── components/     # 通用组件（Feedback 统一提示、MainLayout…）
│       ├── data/           # 静态配置数据
│       ├── pages/          # 页面（全部 lazy 加载）
│       ├── stores/         # Zustand
│       ├── styles/         # design-tokens.css 等全局样式
│       ├── theme/          # antd 主题（明/暗）
│       └── utils/
│
├── scripts/                # 运维/开发脚本（start / stop / deploy）
├── docs/                   # 全部文档（见 docs/README.md）
├── storage/                # 运行期文件存储（已 gitignore）
├── backup/                 # 数据库备份产物（已 gitignore）
├── .run/                   # 本地 pid / 日志（已 gitignore）
├── docker-compose.yml      # 容器编排
└── .env.example            # Docker 部署环境变量模板

🚀 快速开始

环境要求

  • Python 3.10+（推荐 3.12）
  • Node.js 18+
  • MySQL 8.0、Redis 7（已有实例亦可，Docker 部署会自动拉起）
  • 启用 Git 同步时需要本机存在 git 可执行文件（后端镜像已内置）

方式一：一键启动（本地开发，推荐）

./scripts/start.sh

首次运行会：创建 backend/venv → 生成 backend/.env 模板（此时会停下，请填好 MySQL/Redis 连接信息后重新执行）→ 安装前后端依赖 → 真实校验 MySQL/Redis 连通性 → 幂等初始化数据库 → 拉起后端与前端。

./scripts/start.sh --backend     # 只启动后端
./scripts/start.sh --frontend    # 只启动前端
./scripts/start.sh --install     # 只准备环境，不启动服务
./scripts/start.sh --init-db     # 强制重跑数据库初始化
./scripts/start.sh --port 8001   # 换端口（环境变量优先，不改 .env）
./scripts/start.sh --daemon      # 启动后立即返回（后台常驻）
./scripts/stop.sh                # 停止

启动完成后：前端 http://localhost:5173 · 后端 http://localhost:8000 · 接口文档 http://localhost:8000/docs

方式二：Docker Compose（服务器部署）

cp .env.example .env      # 按注释修改密码/端口/存储路径
./scripts/deploy.sh init  # 生成配置、构建镜像、初始化数据库
./scripts/deploy.sh start
./scripts/deploy.sh status

细节见 docs/deploy/README.md。

默认账号

场景 用户名 密码
scripts/start.sh / backend/scripts/init_db.py admin admin@123
Docker 部署（.env.example 默认值） admin Admin@123456

可用 ADMIN_USERNAME / ADMIN_PASSWORD / ADMIN_EMAIL / ADMIN_NICKNAME 覆盖；首次登录后请立即修改密码。

📖 文档索引

文档 内容
docs/README.md 文档地图（从这里开始）
docs/quickstart.md 开发环境快速上手、常见启动问题
docs/deploy/README.md Docker 部署、升级、备份与恢复
docs/database.md 数据库 18 张表结构与初始化链路
docs/manual/user-guide.md 面向使用者的功能手册
docs/sdd/ 规格驱动开发文档：愿景、架构、ADR、DV 规格、发布记录
scripts/README.md 脚本清单与约定

🧪 开发与质量

# 前端：静态检查与构建
cd frontend && npm run lint && npm run build

# 后端：pytest（用例较少，见发布报告 OI 清单）
cd backend && ./venv/bin/pip install -r requirements-dev.txt
cd backend && ./venv/bin/python -m pytest
  • 前端统一使用 @/ 别名指向 frontend/src；新页面必须在 App.jsx 用 lazy() 注册。
  • 交互提示统一走 components/Feedback 的 Toast（Toast.confirm 替代 Modal.confirm）。
  • 颜色/圆角/间距一律取 styles/design-tokens.css 与 antd token，禁止硬编码色值。
  • 数据库结构变更：改 app/models/，并在 app/core/migrations.py 增加幂等补列逻辑；不要再往仓库里追加一次性 .sql。

🔒 安全要点

  • 密码 bcrypt 存储；JWT 过期时间由 ACCESS_TOKEN_EXPIRE_MINUTES 控制。
  • 文件路径全部经过规范化校验，拒绝路径穿越；上传大小与类型受限。
  • DEBUG=True 会打印全量 SQL，生产必须关闭。
  • SECRET_KEY、数据库/Redis 密码、Git Token 必须由环境注入，禁止提交到仓库；backend/.env、.env 已在 .gitignore 中。
  • 分享链接的访问密码当前为明文存储于 share_links.access_pass，见发布报告 P2 项。

📄 许可证

Copyright © 2026 Mula.liu

Made with ❤️ by Mula.liu