Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

docs: clarify frontend development proxy configuration (#4171)

Jarvis24b5ca3f2325
diff --git a/website-docs/06-development/01-dev-guide.md b/website-docs/06-development/01-dev-guide.md
index 3e81b2cb0..876aabad2 100644
--- a/website-docs/06-development/01-dev-guide.md
+++ b/website-docs/06-development/01-dev-guide.md
@@ -56,7 +56,24 @@ make dev-stop # 停止
make dev-restart # 重启
```
-前端 dev server 监听 `5173`(`frontend/vite.config.ts` 中 `server.port: 5173`),并把 `/api` 与 `/files` 代理到本地后端(`DEV_PROXY_TARGET`)。`vite preview`(端口 `4173`)用生产构建产物起服务,是最接近 release 镜像的验证环境。
+前端 dev server 监听 `5173`(`frontend/vite.config.ts` 中 `server.port: 5173`),把 `/api`、`/files` 与 `/mcp/` 代理到后端。代理目标依次取进程环境变量 `VITE_DEV_PROXY_TARGET`、`FRONTEND_BACKEND_URL`,两者都未设置或为空时使用 `http://localhost:8080`。`DEV_PROXY_TARGET` 是配置文件中的内部常量,不是环境变量。
+
+连接远程后端时,可在仓库根目录的 `.env.local` 中设置(将示例地址替换为实际后端地址):
+
+```bash
+VITE_DEV_PROXY_TARGET=https://kb.example.com
+```
+
+然后在仓库根目录运行 `make dev-frontend`;脚本会先加载根目录 `.env`,再用 `.env.local` 覆盖,并将变量导出给 Vite。修改代理目标后需要重启前端开发服务器。
+
+如果直接在 `frontend/` 目录运行 npm 命令,应显式传入环境变量;该方式不会经过脚本加载仓库根目录的环境文件:
+
+```bash
+cd frontend
+VITE_DEV_PROXY_TARGET=https://kb.example.com npm run dev
+```
+
+`vite preview`(端口 `4173`)用生产构建产物起服务,是最接近 release 镜像的验证环境。它使用相同的代理路径和目标选择规则,可在 `frontend/` 目录执行 `npm run build` 后,用 `VITE_DEV_PROXY_TARGET=https://kb.example.com npm run preview` 连接远程后端。
### docker-compose.dev.yml 服务清单 {#_2-1-docker-compose-dev-yml-服务清单}