# 如何部署 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 启动服务

在 **`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.3 验证

- 健康：查看启动日志中是否有「数据库健康检查通过」
- API 文档：浏览器打开 `http://<主机>:<端口>/docs`（根路径 `/` 会重定向到 Swagger）
- 管理端接口：前缀为 `/api/admin/...`，需 `role=admin` 用户登录后携带 JWT

---