# NEX Docus 文档管理平台

<div align="center">

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

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

</div>

---

## ✨ 核心特性

- 📁 **文件即真理**：文档正文以 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` 可执行文件（后端镜像已内置）

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

```bash
./scripts/start.sh
```

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

```bash
./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（服务器部署）

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

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

## 🧪 开发与质量

```bash
# 前端：静态检查与构建
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

---

<div align="center">

**Made with ❤️ by Mula.liu**

</div>