122 lines
3.8 KiB
Markdown
122 lines
3.8 KiB
Markdown
# 如何部署 Backend
|
||
|
||
本仓库的 HTTP API 由 `backend/` 目录下的 **FastAPI** 服务提供，`frontend` 与 `admin-frontend` 均请求同一套后端接口。
|
||
|
||
---
|
||
|
||
## 一、环境准备
|
||
|
||
### 1.1 运行环境
|
||
|
||
| 组件 | 版本 / 说明 |
|
||
|------|-------------|
|
||
| Python | **3.11**（与 `backend/pyproject.toml` 中 `requires-python` 一致） |
|
||
| 包管理 | 推荐 [uv](https://docs.astral.sh/uv/)（项目含 `uv.lock`） |
|
||
| PostgreSQL | **14+**（主库，必选） |
|
||
| Redis | **6+**（短信验证码、图形验证码等，可选） |
|
||
| ChromaDB | 向量检索（知识库 RAG，按业务需要部署，必选） |
|
||
| Neo4j | 知识图谱（按业务需要部署，必选） |
|
||
|
||
|
||
---
|
||
|
||
## 二、数据库初始化
|
||
|
||
后端依赖 PostgreSQL。首次部署请在**空库**上执行项目根目录的初始化脚本：
|
||
|
||
|
||
`ddl-init.sql` 会创建完整表结构
|
||
|
||
初始化完成后，在 `backend/.env` 中配置与上述库一致的数据库连接（见下文）。
|
||
|
||
---
|
||
|
||
## 三、配置环境变量
|
||
|
||
在 `backend/` 目录复制示例配置并修改：
|
||
|
||
```bash
|
||
cd backend
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少修改以下项（生产环境务必使用强密码与随机 `JWT_SECRET_KEY`）：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `API.HOST` / `API.PORT` | 监听地址与端口（默认 `0.0.0.0:7862`） |
|
||
| `DB_HOST`、`DB_PORT`、`DB_NAME`、`DB_USER`、`DB_PASSWORD` | PostgreSQL，需与 `ddl-init.sql` 执行的库一致 |
|
||
| `JWT_SECRET_KEY` | JWT 签名密钥 |
|
||
| `REDIS_HOST`、`REDIS_PORT` | Redis（未在 `.env.example` 列出时，默认 `127.0.0.1:6379`，可在 `.env` 中显式配置） |
|
||
| `CHROMA_HOST`、`CHROMA_PORT` | ChromaDB 地址（启用知识库向量检索时） |
|
||
| `NEO4J_URI`、`NEO4J_USER`、`NEO4J_PASSWORD` | Neo4j（启用知识图谱时） |
|
||
| `DASHSCOPE_API_KEY` / `DEEPSEEK_API_KEY` 等 | 大模型与 Embedding（聊天、RAG 必需） |
|
||
| `OSS_*` | 阿里云 OSS（文件上传，按需） |
|
||
| `MODERATION_ENABLED` | 内容审核；关闭时可不配置阿里云审核密钥 |
|
||
|
||
完整字段说明见 `backend/.env.example` 与 `backend/core/config.py`。
|
||
|
||
---
|
||
|
||
## 四、本地部署（推荐开发 / 单机生产）
|
||
|
||
### 4.1 安装依赖
|
||
|
||
```bash
|
||
cd backend
|
||
uv sync --frozen
|
||
```
|
||
|
||
仅安装生产依赖（与 Docker 构建一致）：
|
||
|
||
```bash
|
||
uv sync --frozen --no-dev
|
||
```
|
||
|
||
### 4.2 初始化网页抓取浏览器（crawl4ai，首次必做）
|
||
|
||
知识库支持提交 URL 自动抓取网页内容，底层通过 crawl4ai 驱动 Playwright Chromium 完成。
|
||
Playwright 是**进程内库**，不需要独立服务——程序运行时会直接 fork 一个 Chromium 子进程，通过本机 CDP 通信。
|
||
|
||
首次部署或新环境克隆后，需安装 Chromium 浏览器及系统依赖（**只需执行一次**）：
|
||
|
||
```bash
|
||
cd backend
|
||
uv run crawl4ai-setup
|
||
# 若上面命令失败，手动执行：
|
||
uv run playwright install chromium
|
||
uv run playwright install-deps chromium
|
||
```
|
||
|
||
> Docker 环境无需手动执行，Dockerfile 中已包含这两步。
|
||
|
||
### 4.3 启动服务
|
||
|
||
在 **`backend` 目录**下执行（会读取 `backend/.env` 中的 `API.HOST` / `API.PORT`）：
|
||
|
||
```bash
|
||
uv run python -m main
|
||
```
|
||
|
||
开发热重载（同样需在 `backend` 目录）：
|
||
|
||
```bash
|
||
uv run python -m main
|
||
# 或显式指定端口（须与 .env 中 API.PORT 一致）
|
||
uv run uvicorn main:app --reload --host 0.0.0.0 --port 7862
|
||
```
|
||
|
||
> **注意**：若直接运行 `uvicorn main:app` 且未传 `--port`，默认端口为 **8000**，不会自动读取 `.env` 中的 `API.PORT`。生产环境请使用 `python -m main` 或显式传入 `--port`。
|
||
|
||
### 4.4 验证
|
||
|
||
- 健康：查看启动日志中是否有「数据库健康检查通过」
|
||
- API 文档：浏览器打开 `http://<主机>:<端口>/docs`（根路径 `/` 会重定向到 Swagger）
|
||
- 管理端接口：前缀为 `/api/admin/...`，需 `role=admin` 用户登录后携带 JWT
|
||
|
||
---
|
||
|
||
|
||
管理员密码
|
||
admin1 Test@123456
|