diff --git a/.env.example b/.env.example
index 78a3b72c07..ad6da008c7 100644
--- a/.env.example
+++ b/.env.example
@@ -13,4 +13,12 @@ ZEP_API_KEY=your_zep_api_key_here
 # 注意如果不使用加速配置，env文件中就不要出现下面的配置项
 LLM_BOOST_API_KEY=your_api_key_here
 LLM_BOOST_BASE_URL=your_base_url_here
-LLM_BOOST_MODEL_NAME=your_model_name_here
\ No newline at end of file
+LLM_BOOST_MODEL_NAME=your_model_name_here
+
+# ===== 远程/VPS 部署配置（可选）=====
+# 将 MiroFish 部署在远程服务器（VPS/云主机）时必须设置此项。
+# 本地开发时 Vite 代理会将 /api 请求转发到 localhost:5001，无需设置。
+# 远程部署时浏览器直接访问服务器，无法使用 Vite 代理，需将此变量设置为
+# 你的服务器公网 IP 或域名（含协议和端口），例如：
+# VITE_API_BASE_URL=http://your_server_ip:5001
+# 修改后需重新构建前端镜像：docker compose down && docker compose up --build -d
\ No newline at end of file
diff --git a/README-ZH.md b/README-ZH.md
index 0b20424d3a..b888caa7db 100644
--- a/README-ZH.md
+++ b/README-ZH.md
@@ -176,6 +176,26 @@ docker compose up -d
 
 > 在 `docker-compose.yml` 中已通过注释提供加速镜像地址，可按需替换
 
+#### ⚠️ 远程/VPS 部署注意事项
+
+将 MiroFish 部署在远程服务器上时，需要额外设置 `VITE_API_BASE_URL`。
+
+**原因：** Vite 的开发代理仅在本地开发时有效。远程访问时，浏览器会尝试连接**用户本机**的 `localhost:5001`，而非服务器，导致前端报"网络错误"。
+
+**解决方法：** 在 `.env` 中添加：
+
+```env
+VITE_API_BASE_URL=http://your_server_ip:5001
+```
+
+然后重新构建并启动容器：
+
+```bash
+docker compose down && docker compose up --build -d
+```
+
+> **提示：** 请确保服务器防火墙已开放 `5001` 端口。
+
 ## 📬 更多交流
 
 <div align="center">
diff --git a/README.md b/README.md
index 4b8369f4cf..0eae408cfd 100644
--- a/README.md
+++ b/README.md
@@ -176,6 +176,26 @@ Reads `.env` from root directory by default, maps ports `3000 (frontend) / 5001
 
 > Mirror address for faster pulling is provided as comments in `docker-compose.yml`, replace if needed.
 
+#### ⚠️ Remote / VPS Deployment Note
+
+When deploying MiroFish on a remote server, you must set the `VITE_API_BASE_URL` environment variable.
+
+**Why:** Vite's development proxy only works during local development. When accessing the app remotely, the browser tries to reach `localhost:5001` on the **user's own machine** rather than the server, causing a "Network error" on the frontend.
+
+**Fix:** Add the following to your `.env` file:
+
+```env
+VITE_API_BASE_URL=http://your_server_ip:5001
+```
+
+Then rebuild and restart the containers:
+
+```bash
+docker compose down && docker compose up --build -d
+```
+
+> **Tip:** Make sure your server firewall allows inbound traffic on port `5001`.
+
 ## 📬 Join the Conversation
 
 <div align="center">