163 lines
8.9 KiB
Markdown
163 lines
8.9 KiB
Markdown
# 快速上手（开发环境）
|
||
|
||
本文面向**本地开发**。服务器部署请看 [deploy/README.md](deploy/README.md)。
|
||
|
||
## 1. 前置要求
|
||
|
||
| 依赖 | 版本 | 说明 |
|
||
| --- | --- | --- |
|
||
| Python | 3.10+（推荐 3.12） | 后端运行时 |
|
||
| Node.js | 18+ | 前端构建（vite 5） |
|
||
| MySQL | 8.0（utf8mb4） | 元数据/权限；5.7 未纳入支持范围 |
|
||
| Redis | 5+ | 会话缓存、索引同步信号 |
|
||
| git | 任意新版 | 仅在使用「Git 仓库同步」功能时需要 |
|
||
|
||
## 2. 一键启动（推荐）
|
||
|
||
```bash
|
||
./scripts/start.sh
|
||
```
|
||
|
||
脚本按顺序执行：环境检查 → 创建 `backend/venv` → 生成 `backend/.env` → 安装前后端依赖 → **真实校验** MySQL/Redis → 幂等初始化数据库 → 启动后端与前端。
|
||
|
||
首次执行会因为需要填写连接信息而**主动中断**：
|
||
|
||
```text
|
||
! backend/.env 不存在，正在从模板创建（请填写数据库/Redis 连接信息）
|
||
✗ 请编辑 backend/.env 填写数据库与 Redis 连接信息后重新运行
|
||
```
|
||
|
||
填好 `DB_HOST/DB_USER/DB_PASSWORD/DB_NAME`、`REDIS_HOST/REDIS_PASSWORD/REDIS_DB` 后再次运行即可。
|
||
|
||
常用参数：
|
||
|
||
| 命令 | 作用 |
|
||
| --- | --- |
|
||
| `./scripts/start.sh` | 启动后端 + 前端（前台运行，Ctrl+C 全停） |
|
||
| `./scripts/start.sh --backend` | 只启动后端 |
|
||
| `./scripts/start.sh --frontend` | 只启动前端 |
|
||
| `./scripts/start.sh --install` | 只准备环境（venv / npm 依赖 / 建表），不启动服务 |
|
||
| `./scripts/start.sh --init-db` | 强制重跑一次数据库初始化（幂等） |
|
||
| `./scripts/start.sh --port 8001` | 换后端端口（用环境变量覆盖，不改 `backend/.env`） |
|
||
| `./scripts/start.sh --docker` | 转交 `scripts/deploy.sh start` |
|
||
| `./scripts/start.sh --daemon` | 启动后立即返回（服务后台常驻，用 `stop.sh` 停止） |
|
||
| `./scripts/stop.sh` | 停止由 start.sh 启动的进程 |
|
||
|
||
启动成功输出：
|
||
|
||
```text
|
||
✓ MySQL 连接正常（MySQL 8.0.37）
|
||
✓ Redis 连接正常
|
||
✓ 后端健康检查通过（/health）
|
||
✓ NEX Docus 已启动
|
||
后端 API http://localhost:8000 文档 http://localhost:8000/docs
|
||
前端页面 http://localhost:5173
|
||
```
|
||
|
||
进程 pid 与日志在 `.run/`（`backend.log`、`frontend.log`），该目录已被 gitignore。
|
||
|
||
## 3. 手动启动（不使用脚本时）
|
||
|
||
```bash
|
||
# 后端
|
||
cd backend
|
||
python3 -m venv venv && source venv/bin/activate
|
||
pip install -r requirements.txt # 国内网络可加 -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||
cp -n .env.example .env 2>/dev/null || true # 没有模板时按下一节的键自行创建 .env
|
||
python scripts/init_db.py # 建表 + 种子数据（幂等）
|
||
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||
|
||
# 前端（另一个终端）
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
> `requirements.txt` 含 `sentence-transformers`（会拉取 PyTorch，体积以 GB 计）与 `zvec`。若只用远程 OpenAI 兼容 Embedding 接口，可以只装它们之外的依赖；`sentence_transformers` 是延迟导入的，不装也能启动。
|
||
|
||
## 4. `backend/.env` 配置项
|
||
|
||
后端配置由 `app/core/config.py` 用 pydantic-settings 读取 `.env`（同名环境变量优先级更高）。
|
||
|
||
| 键 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `APP_NAME` | `NEX Docus` | 标题 |
|
||
| `APP_VERSION` | `1.0.0` | 出现在根路径 `GET /` 的 `version`、`/docs` 标题与 `/openapi.json` |
|
||
| `DEBUG` | `True` | **为 True 时 SQLAlchemy 打印全量 SQL，生产必须关闭** |
|
||
| `HOST` / `PORT` | `0.0.0.0` / `8000` | 监听地址（`uvicorn` 命令行参数优先） |
|
||
| `DB_HOST` `DB_PORT` `DB_USER` `DB_PASSWORD` `DB_NAME` `DB_CHARSET` | — / 3306 / — / — / — / utf8mb4 | MySQL 连接；密码会自动做 URL 编码 |
|
||
| `REDIS_HOST` `REDIS_PORT` `REDIS_PASSWORD` `REDIS_DB` | — / 6379 / — / 8 | Redis 连接 |
|
||
| `SECRET_KEY` | — | JWT 签名密钥，务必随机化；仍为模板占位值或长度 <16 时启动会打「安全自检」告警 |
|
||
| `ALGORITHM` / `ACCESS_TOKEN_EXPIRE_MINUTES` | `HS256` / `1440` | Token 配置 |
|
||
| `DEFAULT_USER_PASSWORD` | `User@123456` | 管理员新建用户时的初始密码；仍为默认值时启动会打「安全自检」告警 |
|
||
| `STORAGE_ROOT` `PROJECTS_PATH` `USERS_PATH` `TEMP_PATH` | `/data/nex_docus_store/...` | 文件存储根目录与各子目录；本地开发通常指向 `./storage/...` |
|
||
| `AVATAR_MAX_SIZE` | `1048576` | 头像上传上限（字节） |
|
||
| `CHUNK_SIZE` / `CHUNK_OVERLAP` | `800` / `150` | RAG 分块字符数与重叠 |
|
||
| `CORS_ORIGINS` | `["http://localhost:5173","http://localhost:3000"]` | JSON 数组字符串 |
|
||
| `LOG_LEVEL` / `LOG_PATH` | `INFO` / `logs` | 日志 |
|
||
| `ADMIN_USERNAME` `ADMIN_PASSWORD` `ADMIN_EMAIL` `ADMIN_NICKNAME` | `admin` / `admin@123` / `admin@example.com` / `系统管理员` | 仅 `init_db.py` 首次创建管理员时读取（Docker 部署由 compose 注入，默认口令见 [deploy/changelog.md](deploy/changelog.md#5-两套默认密码并存重要易踩坑)） |
|
||
| `ZVEC_DATA_DIR` / `ZVEC_EMBEDDING_DIM` | `STORAGE_ROOT/vector_index` / `1536` | 向量库目录与维度（维度必须与所选 embedding 模型一致） |
|
||
| `DISABLE_SSL_VERIFY` | `false` | 仅当 LLM/Embedding 服务使用自签名证书时开启 |
|
||
|
||
> Docker 部署用的是仓库根目录 `.env`（键名不同，见 [deploy/README.md](deploy/README.md) 与 `.env.example`），与 `backend/.env` 是两套配置，别混用。
|
||
|
||
## 5. 默认账号
|
||
|
||
`backend/scripts/init_db.py` 首次创建管理员时使用：
|
||
|
||
- 用户名 `admin`
|
||
- 密码 `admin@123`
|
||
|
||
已存在同名用户时不会重置密码。生产环境请用 `ADMIN_PASSWORD` 覆盖并在首次登录后立即修改。
|
||
|
||
## 6. 前端约定
|
||
|
||
- 开发端口 `5173`，`vite.config.js` 已把 `/api` 代理到 `http://localhost:8000`，因此**前端不需要配置后端地址**。
|
||
- 路径别名 `@` → `frontend/src`。
|
||
- 页面一律在 `src/App.jsx` 中用 `lazy()` 注册，路由级懒加载。
|
||
- 主题/颜色取自 `src/styles/design-tokens.css` 与 `src/theme/antdTheme.js`，不要写死色值。
|
||
- 全局提示统一 `@/components/Toast`（含 `Toast.confirm`），不要散用 `Modal.confirm` / `message.*`。
|
||
|
||
## 7. 自检清单
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8000/health # {"status":"healthy"}
|
||
curl -s http://127.0.0.1:8000/openapi.json | head -c 120 # version 应为 1.0.0
|
||
open http://127.0.0.1:8000/docs # Swagger
|
||
open http://localhost:5173 # 登录页
|
||
```
|
||
|
||
## 8. 常用开发命令
|
||
|
||
```bash
|
||
cd frontend && npm run lint # ESLint（当前基线：0 error / 25 warning）
|
||
cd frontend && npm run lint:strict # 警告也视为失败
|
||
cd frontend && npm run build # 生产构建
|
||
|
||
cd backend && ./venv/bin/pip install -r requirements-dev.txt # 安装 pytest 等开发依赖
|
||
cd backend && ./venv/bin/python -m pytest # 当前基线：40 passed
|
||
```
|
||
|
||
> 注意：`npx eslint src` 会**秒退且全通过**——ESLint 8 对目录默认只收 `.js`，必须写 `eslint "src/**/*.{js,jsx}"` 或用 `npm run lint`（已带 `--ext js,jsx`）。
|
||
|
||
## 9. 数据库结构与迁移
|
||
|
||
- 建表：`init_db.py` 调 `Base.metadata.create_all`，表结构来自 `app/models/`；**新增模型必须在 `app/models/__init__.py` 里导入**，否则该表不会被创建（历史事故：`notifications`、`project_git_repos` 曾因此在新库缺失）。
|
||
- 种子数据：角色（super_admin / admin / user）、系统菜单、管理员账号，全部幂等增量。
|
||
- 补列：`app/core/migrations.py::migrate_schema()` 在服务启动前/初始化时执行，只补已知缺失列。
|
||
- 变更流程：改模型 → 本地重跑 `./scripts/start.sh --init-db` → 若是老库需要的列，补进 `migrations.py` → 更新 [database.md](database.md)。仓库不再接收散落的 `*.sql` 补丁。
|
||
|
||
## 10. 常见问题
|
||
|
||
| 现象 | 原因 / 处理 |
|
||
| --- | --- |
|
||
| `✗ Redis 连接失败：AUTH 失败` | `REDIS_PASSWORD` 与服务端不一致；服务端未设密码时留空 |
|
||
| `Redis 拒绝写入：MISCONF Redis is configured to save RDB snapshots` | 服务端 RDB/AOF 落盘失败（磁盘满或目录无权限）。**先修磁盘**；应急可 `redis-cli CONFIG SET stop-writes-on-bgsave-error no`，但该配置重启即失效，不是修复 |
|
||
| `✗ MySQL 连接失败：Access denied` | 用户/密码/授权主机不匹配；确认对 `DB_NAME` 有权限 |
|
||
| 后端起来了但某些表不存在 | 模型未在 `app/models/__init__.py` 注册；补 import 后 `--init-db` |
|
||
| 前端 401 后一直跳登录页 | Token 过期（`ACCESS_TOKEN_EXPIRE_MINUTES`），或 `SECRET_KEY` 改过导致旧 Token 失效 |
|
||
| 前端请求 404 | 后端未启动/端口不是 8000（改了 `--port` 就要同步改 `vite.config.js` 的 proxy target） |
|
||
| `pip install` 卡在 torch | 网络问题；用清华源，或临时跳过 `sentence-transformers`（仅本地 Embedding 需要） |
|
||
| 控制台刷屏 SQL | `DEBUG=True` 的正常行为，关掉即止 |
|
||
| 端口被占用 | `lsof -ti:8000 \| xargs kill`；后端也可 `./scripts/start.sh --port 8001` |
|