231 lines
4.6 KiB
Markdown
231 lines
4.6 KiB
Markdown
# NEX Docus 快速启动指南
|
||
|
||
欢迎使用 NEX Docus！这是一个完整的快速启动指南，帮助你在 5 分钟内运行整个项目。
|
||
|
||
---
|
||
|
||
## 📋 前置要求
|
||
|
||
确保已安装以下软件：
|
||
|
||
- **Python**: 3.9.6+
|
||
- **Node.js**: 16+
|
||
- **MySQL**: 5.7.5+
|
||
- **Redis**: 最新稳定版
|
||
- **Git**: 最新版本
|
||
|
||
---
|
||
|
||
## 🚀 快速启动（3 步）
|
||
|
||
### Step 1: 初始化数据库
|
||
|
||
```bash
|
||
# 1. 连接到 MySQL
|
||
mysql -h10.100.51.51 -uroot -pUnis@321
|
||
|
||
# 2. 执行初始化脚本
|
||
source backend/scripts/init_database.sql
|
||
|
||
# 或使用命令行直接执行
|
||
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql
|
||
```
|
||
|
||
### Step 2: 启动后端服务
|
||
|
||
```bash
|
||
# 1. 进入后端目录
|
||
cd backend
|
||
|
||
# 2. 激活虚拟环境
|
||
source venv/bin/activate # macOS/Linux
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 3. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 4. 启动服务
|
||
python main.py
|
||
```
|
||
|
||
后端服务将在 http://localhost:8000 启动
|
||
|
||
### Step 3: 启动前端服务
|
||
|
||
```bash
|
||
# 1. 打开新终端，进入前端目录
|
||
cd frontend
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
# 或
|
||
pnpm install
|
||
|
||
# 3. 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
前端应用将在 http://localhost:5173 启动
|
||
|
||
---
|
||
|
||
## 🎉 开始使用
|
||
|
||
### 1. 登录系统
|
||
|
||
访问 http://localhost:5173，使用默认管理员账号登录：
|
||
|
||
- **用户名**: `admin`
|
||
- **密码**: `admin123`
|
||
|
||
### 2. 创建项目
|
||
|
||
- 点击「创建项目」按钮
|
||
- 填写项目名称和描述
|
||
- 提交创建
|
||
|
||
### 3. 编辑文档
|
||
|
||
- 点击项目卡片进入项目
|
||
- 在左侧目录树中选择文件
|
||
- 在右侧编辑器中编辑 Markdown
|
||
- 点击「保存」按钮保存更改
|
||
|
||
---
|
||
|
||
## 📚 目录结构
|
||
|
||
```
|
||
NEX Docus/
|
||
├── backend/ # 后端服务（FastAPI）
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ ├── core/ # 核心配置
|
||
│ │ ├── models/ # 数据库模型
|
||
│ │ ├── schemas/ # Pydantic Schemas
|
||
│ │ ├── services/ # 业务逻辑
|
||
│ │ └── middleware/ # 中间件
|
||
│ ├── scripts/ # 脚本文件
|
||
│ ├── main.py # 应用入口
|
||
│ └── requirements.txt # 依赖包
|
||
│
|
||
├── frontend/ # 前端应用（React + Vite）
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 请求
|
||
│ │ ├── components/ # 通用组件
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ └── utils/ # 工具函数
|
||
│ ├── package.json
|
||
│ └── vite.config.js
|
||
│
|
||
├── DATABASE.md # 数据库设计文档
|
||
├── IMPLEMENTATION_PLAN.md # 实施计划
|
||
├── PROJECT.md # 项目技术方案
|
||
└── DEPLOYE.md # 部署配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常见问题
|
||
|
||
### 1. 后端启动失败
|
||
|
||
**问题**: `ModuleNotFoundError: No module named 'xxx'`
|
||
|
||
**解决**:
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 数据库连接失败
|
||
|
||
**问题**: `Can't connect to MySQL server`
|
||
|
||
**解决**:
|
||
- 检查 `backend/.env` 中的数据库配置
|
||
- 确认 MySQL 服务已启动
|
||
- 测试数据库连接：
|
||
```bash
|
||
mysql -h10.100.51.51 -uroot -pUnis@321 -e "SELECT 1"
|
||
```
|
||
|
||
### 3. 前端请求 404
|
||
|
||
**问题**: API 请求返回 404
|
||
|
||
**解决**:
|
||
- 确认后端服务已启动
|
||
- 检查 `frontend/.env` 中的 API 地址配置
|
||
- 检查浏览器控制台的网络请求
|
||
|
||
### 4. 文件上传/保存失败
|
||
|
||
**问题**: 文件操作失败
|
||
|
||
**解决**:
|
||
- 确保文件存储目录存在并有写权限：
|
||
```bash
|
||
mkdir -p /data/nex_docus_store/{projects,temp}
|
||
chmod 755 /data/nex_docus_store
|
||
```
|
||
- 或修改 `backend/.env` 中的存储路径为当前用户有权限的目录
|
||
|
||
---
|
||
|
||
## 📖 API 文档
|
||
|
||
启动后端服务后，访问以下地址查看 API 文档：
|
||
|
||
- **Swagger UI**: http://localhost:8000/docs
|
||
- **ReDoc**: http://localhost:8000/redoc
|
||
|
||
---
|
||
|
||
## 🔐 安全提醒
|
||
|
||
⚠️ **生产环境部署前请务必修改：**
|
||
|
||
1. 修改默认管理员密码
|
||
2. 修改 `backend/.env` 中的 `SECRET_KEY`
|
||
3. 配置 HTTPS
|
||
4. 限制 CORS 允许的域名
|
||
5. 配置防火墙规则
|
||
|
||
---
|
||
|
||
## 📞 技术支持
|
||
|
||
如果遇到问题，请查看：
|
||
|
||
1. **PROJECT.md** - 完整技术方案
|
||
2. **DATABASE.md** - 数据库设计文档
|
||
3. **IMPLEMENTATION_PLAN.md** - 实施计划
|
||
|
||
或联系技术负责人：Mula.liu
|
||
|
||
---
|
||
|
||
## ⚡️ 快速命令参考
|
||
|
||
```bash
|
||
# 后端
|
||
cd backend && source venv/bin/activate && python main.py
|
||
|
||
# 前端
|
||
cd frontend && npm run dev
|
||
|
||
# 数据库初始化
|
||
mysql -h10.100.51.51 -uroot -pUnis@321 < backend/scripts/init_database.sql
|
||
|
||
# 查看日志
|
||
tail -f backend/logs/app.log
|
||
```
|
||
|
||
---
|
||
|
||
**祝你使用愉快！🎊**
|