# 快速上手(开发环境) 本文面向**本地开发**。服务器部署请看 [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. 前端约定 - 前端为 **TypeScript**(`strict` + `noUnusedLocals` + `noUnusedParameters`),源码只有 `.ts` / `.tsx`。 - 开发端口 `5173`,`vite.config.ts` 已把 `/api` 代理到 `http://localhost:8000`,因此**前端不需要配置后端地址**。 - 路径别名 `@` → `frontend/src`(`tsconfig.json` 的 `paths` 与 Vite `resolve.alias` 保持一致)。 - 页面一律在 `src/App.tsx` 中用 `lazy()` 注册,路由级懒加载。 - 主题/颜色取自 `src/styles/design-tokens.css` 与 `src/theme/antdTheme.ts`(唯一 Token 源),不要写死色值。 - 全局提示统一 `@/components/Toast/Toast`(含 `Toast.confirm`),不要散用 `Modal.confirm` / `message.*`。 - 后端接口的请求/响应类型集中在 `src/types/api.ts`,新增接口时先补契约再写页面。 - 接口错误取值统一走 `@/utils/apiError`(`getApiErrorDetail` / `getApiErrorMessage`),不要写 `error.response?.data?.detail`。 - 用 `div`/`span` 承载点击时,必须用 `@/utils/a11yActivation` 的 `keyboardActivation()` 补 `role`/`tabIndex`/`onKeyDown`, 并给控件可访问名称(`aria-label` 或可见文案);优先直接用原生 `