如何部署 Backend

本仓库的 HTTP API 由 backend/ 目录下的 FastAPI 服务提供，frontend 与 admin-frontend 均请求同一套后端接口。

---

一、环境准备

1.1 运行环境

组件	版本 / 说明
Python	3.11（与 backend/pyproject.toml 中 requires-python 一致）
包管理	推荐 uv（项目含 uv.lock）
PostgreSQL	14+（主库，必选）
Redis	6+（短信验证码、图形验证码等，可选）
ChromaDB	向量检索（知识库 RAG，按业务需要部署，必选）
Neo4j	知识图谱（按业务需要部署，必选）

---

二、数据库初始化

后端依赖 PostgreSQL。首次部署请在空库上执行项目根目录的初始化脚本：

ddl-init.sql 会创建完整表结构

初始化完成后，在 backend/.env 中配置与上述库一致的数据库连接（见下文）。

---

三、配置环境变量

在 backend/ 目录复制示例配置并修改：

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 安装依赖

cd backend
uv sync --frozen

仅安装生产依赖（与 Docker 构建一致）：

uv sync --frozen --no-dev

4.2 初始化网页抓取浏览器（crawl4ai，首次必做）

知识库支持提交 URL 自动抓取网页内容，底层通过 crawl4ai 驱动 Playwright Chromium 完成。 Playwright 是进程内库，不需要独立服务——程序运行时会直接 fork 一个 Chromium 子进程，通过本机 CDP 通信。

首次部署或新环境克隆后，需安装 Chromium 浏览器及系统依赖（只需执行一次）：

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）：

uv run python -m main

开发热重载（同样需在 backend 目录）：

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