8.9 KiB

Raw Blame History

快速上手（开发环境）

本文面向本地开发。服务器部署请看 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. 一键启动（推荐）

./scripts/start.sh

脚本按顺序执行：环境检查 → 创建 backend/venv → 生成 backend/.env → 安装前后端依赖 → 真实校验 MySQL/Redis → 幂等初始化数据库 → 启动后端与前端。

首次执行会因为需要填写连接信息而主动中断：

! 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 启动的进程

启动成功输出：

✓ 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. 手动启动（不使用脚本时）

# 后端
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）
`ZVEC_DATA_DIR` / `ZVEC_EMBEDDING_DIM`	`STORAGE_ROOT/vector_index` / `1536`	向量库目录与维度（维度必须与所选 embedding 模型一致）
`DISABLE_SSL_VERIFY`	`false`	仅当 LLM/Embedding 服务使用自签名证书时开启

Docker 部署用的是仓库根目录 .env（键名不同，见 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. 自检清单

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. 常用开发命令

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。仓库不再接收散落的 *.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`

8.9 KiB Raw Blame History Unescape Escape