zhangyonghao/minimap
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新各类文档

Browse Source
This commit is contained in:
zhangyonghao
2026-03-21 10:11:14 +08:00
parent 190cee20bd
commit 0c3166060d
3 changed files with 868 additions and 338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

448
宝塔面板部署指南.md
View File

@@ -1,177 +1,157 @@
# Interactive Mindmap 宝塔面板部署指南
# Interactive Mindmap 宝塔部署指南
## 1. 部署原则
## 1. 当前部署形态
这份文档按“尽可能使用宝塔面板现成功能”的思路编写：
这份文档按当前实际部署方式整理：
- 前端优先使用宝塔的 `网站 -> Node 项目`
- 后端优先使用宝塔的 `Python 项目`
- 如果你的面板版本里没有合适的 Python 项目入口，再退回 `进程守护`
- 如果你不想改访问端口，可以直接保留 `3000/8000`
- 如果你后续想统一入口，再用宝塔 `网站 + 反向代理`
- 前端放在宝塔 `Node 项目`
- 后端放在宝塔 `Python 项目`
- 当前直接通过公网 IP + 原始端口访问
- 前端地址：`http://公网IP:3000`
- 后端地址：`http://公网IP:8000`
对这个项目来说，最省事的顺序是：
以下示例以当前服务器目录为例：
1. 先用宝塔把前端跑在 `3000`
2. 再把后端跑在 `8000`
3. 先直接通过 `公网IP:端口` 验证
4. 跑通后，再决定要不要加网站反向代理
```bash
/mindmap/minimap
```
## 2. 先确认项目的真实配置
如果你的实际目录不同，把文档里的路径替换成你的真实路径即可。
这个仓库里有几个关键点，部署时必须按代码真实行为来：
## 2. 当前推荐结构
### 前端
- 项目目录：`/mindmap/minimap/frontend`
- 运行方式：宝塔 `Node 项目`
- 运行端口：`3000`
- Node 版本：建议 `20`
- 启动命令：`npm run start -- -p 3000`
### 后端
- 项目目录：`/mindmap/minimap/backend`
- 运行方式：宝塔 `Python 项目`
- Python 版本：建议 `3.11`
- 运行端口：`8000`
- 启动命令：`uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers`
### 数据库
- 使用 SQLite
- 数据文件：`/mindmap/minimap/backend/data/mindmap.db`
## 3. 部署前需要确认的代码行为
这个项目里有几个配置不能写错：
- 后端环境变量名是 `BOT_APP_KEY`
- 后端还要配置 `FRONTEND_BASE_URL`
- 前端环境变量名是 `NEXT_PUBLIC_API_BASE_URL`
- 前端主要页面是 `/` 和 `/mindmap/[id]`
- 后端接口前缀是 `/api`
- `/api/chat` 是 SSE 流式接口
- 后端返回脑图链接依赖 `FRONTEND_BASE_URL`
- 前端请求后端依赖 `NEXT_PUBLIC_API_BASE_URL`
- 前端详情页路径是 `/mindmap/[id]`
- 后端创建脑图接口是 `POST /api/mindmaps`
- 后端对话接口是 `POST /api/chat`
对应文件：
对应代码文件：
- [config.py](E:/code/mindmap/backend/app/config.py)
- [mindmaps.py](E:/code/mindmap/backend/app/routers/mindmaps.py)
- [api.ts](E:/code/mindmap/frontend/lib/api.ts)
## 3. 宝塔里建议安装的软件
## 4. 前端部署到宝塔 Node 项目
在宝塔 `软件商店` 里优先安装：
## 4.1 前端目录
- `Node.js`
- `PM2 管理器`
- `Python 3.11`
- `Nginx`
按你的面板版本，下面二选一：
- 如果有 `Python 项目` 或 `Python 项目管理器`，优先用它
- 如果没有，就安装或使用 `进程守护 / Supervisor`
建议版本：
- `Node.js 20`
- `Python 3.11`
## 4. 上传项目
建议上传到：
前端目录：
```bash
/www/wwwroot/mindmap
/mindmap/minimap/frontend
```
推荐做法：
## 4.2 前端环境变量
1. 宝塔 `文件` 里上传项目压缩包
2. 在宝塔里解压到 `/www/wwwroot/mindmap`
如果你是从本地 Windows 机器直接传上来的，先在宝塔终端执行：
```bash
cd /www/wwwroot/mindmap/frontend
rm -rf node_modules .next
```
这是为了避免把 Windows 的前端依赖直接拿到 Linux 里运行。
## 5. 推荐方案：先保留原始端口跑通
这是当前最推荐你的做法，因为最少折腾。
最终访问方式：
- 前端：`http://公网IP:3000`
- 后端：`http://公网IP:8000`
这一步不需要先配网站反向代理。
## 6. 前端：优先使用宝塔 `网站 -> Node 项目`
### 6.1 先准备前端环境变量
在宝塔 `文件` 里进入：
```bash
/www/wwwroot/mindmap/frontend
```
新建文件 `.env.production`，内容写成：
在前端目录创建或修改 `.env.production`：
```env
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```
这里必须写公网 IP + `8000`，因为你当前是让前端直接访问后端原始端口。
说明：
### 6.2 安装依赖并构建
- 当前前端直接访问后端 `8000` 端口，所以这里不能留空
- 只要改过这个值，就必须重新构建前端
## 4.3 安装依赖和构建
宝塔终端执行：
```bash
cd /www/wwwroot/mindmap/frontend
cd /mindmap/minimap/frontend
npm ci
rm -rf .next
npm run build
```
### 6.3 在宝塔里创建 Node 项目
如果构建失败，先看本文末尾的“常见问题”。
## 4.4 在宝塔中配置 Node 项目
进入宝塔：
- `网站`
- `Node 项目`
- `添加 Node 项目`
- 找到或新建前端项目
建议填写：
建议配置：
- 项目名称：`mindmap-frontend`
- 项目目录：`/www/wwwroot/mindmap/frontend`
- 项目目录：`/mindmap/minimap/frontend`
- Node 版本：`20`
- 运行端口：`3000`
- 启动方式：`PM2`
- 端口：`3000`
- 启动命令：`start -p 3000`
如果界面要求你选择启动文件，按 Next.js 方式选择项目启动即可；面板不同版本字段名称会略有区别，但核心是让它执行 `next start -p 3000`。
### 6.4 是否开启外网映射
如果你想直接通过公网访问：
- 开启 `外网映射`
- 确认映射端口是 `3000`
这样前端就可以直接通过：
```text
http://公网IP:3000
```
访问。
### 6.5 检查前端是否正常
在宝塔里查看：
- `Node 项目` 状态是否为运行中
- `PM2 管理器` 里是否有 `mindmap-frontend`
也可以访问：
```text
http://公网IP:3000
```
## 7. 后端：优先使用宝塔 `Python 项目`
### 7.1 先准备后端环境变量
在宝塔 `文件` 里进入：
如果界面需要填写启动命令，建议使用：
```bash
/www/wwwroot/mindmap/backend
npm run start -- -p 3000
```
复制 `.env.example` 为 `.env`，并写成：
如果界面要求先执行构建，请先完成：
```bash
npm run build
```
## 4.5 前端验证
浏览器访问：
```text
http://公网IP:3000
```
如果首页能打开，说明 Node 项目启动正常。
## 5. 后端部署到宝塔 Python 项目
## 5.1 后端目录
后端目录：
```bash
/mindmap/minimap/backend
```
## 5.2 后端环境变量
复制配置文件：
```bash
cd /mindmap/minimap/backend
cp .env.example .env
```
然后将 `.env` 改成类似这样：
```env
BOT_APP_KEY=你的腾讯云智能体AppKey
@@ -180,70 +160,50 @@ FRONTEND_BASE_URL=http://你的公网IP:3000
说明：
- `BOT_APP_KEY`：腾讯云智能体平台 AppKey
- `FRONTEND_BASE_URL`：因为你前端直接跑在 `3000`，所以这里必须写 `:3000`
- `BOT_APP_KEY` 是腾讯云智能体平台 AppKey
- `FRONTEND_BASE_URL` 必须指向前端真实访问地址
- 当前前端在 `3000` 端口，所以这里必须带 `:3000`
### 7.2 如果你的宝塔有 `Python 项目`
## 5.3 在宝塔中配置 Python 项目
优先这样做：
进入宝塔：
- 打开 `Python 项目`
- `添加项目`
- 选择 Python 版本：`3.11`
- 项目目录：`/www/wwwroot/mindmap/backend`
- `Python 项目`
- 找到或新建后端项目
建议配置：
- 项目名称：`mindmap-backend`
- 项目目录：`/mindmap/minimap/backend`
- Python 版本：`3.11`
- 监听地址：`0.0.0.0`
- 监听端口：`8000`
如果界面支持自定义启动命令，建议填：
如果界面支持自定义启动命令，建议填写：
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers
```
如果界面要求你选择虚拟环境，就让它在项目目录里创建并使用虚拟环境，然后安装：
如果宝塔 Python 项目需要先准备虚拟环境和依赖，执行：
```bash
pip install -r requirements.txt
```
### 7.3 如果你的宝塔没有合适的 `Python 项目` 入口
就用宝塔的 `进程守护` 或 `Supervisor 管理器`，不要自己后台挂命令。
先在宝塔终端执行：
```bash
cd /www/wwwroot/mindmap/backend
cd /mindmap/minimap/backend
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```
然后进入：
## 5.4 后端验证
- `进程守护`
- 或 `Supervisor 管理器`
- `添加守护进程`
建议填写：
- 名称：`mindmap-backend`
- 运行目录：`/www/wwwroot/mindmap/backend`
- 启动用户：`www`
- 启动命令：`/www/wwwroot/mindmap/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers`
- 自启动：开启
- 自动重启：开启
### 7.4 检查后端是否正常
访问：
浏览器访问：
```text
http://公网IP:8000
```
或：
或在终端执行：
```bash
curl http://公网IP:8000/
@@ -255,34 +215,37 @@ curl http://公网IP:8000/
{"message":"Interactive Mindmap API is running"}
```
## 8. 防火墙与安全组
## 6. 宝塔防火墙与云安全组
如果你现在采用“保留原始端口”的方案，必须在宝塔防火墙和云安全组中放行：
当前部署方式需要对公网放行：
- `3000`
- `8000`
否则面板里虽然显示运行中，但公网访问不到。
必须同时检查两层：
## 9. 先做一次完整验证
- 宝塔防火墙
- 云服务器安全组
### 9.1 打开首页
只放行其中一层是不够的。
浏览器访问：
## 7. 当前部署方式下的验证步骤
## 7.1 验证首页
```text
http://公网IP:3000
```
### 9.2 验证接口
## 7.2 验证后端接口
```bash
curl http://公网IP:8000/api/mindmaps/not-found
```
正常结果应该是后端返回的 `404 JSON`，而不是超时或 HTML 页面。
这里预期是后端返回 `404` JSON，而不是超时或 HTML 页面。
### 9.3 创建一条测试思维导图
## 7.3 创建一条测试思维导图
```bash
curl -X POST http://公网IP:8000/api/mindmaps \
@@ -317,85 +280,50 @@ curl -X POST http://公网IP:8000/api/mindmaps \
}'
```
成功后会返回 `url`，类似：
成功后返回的 `url` 应类似：
```text
http://公网IP:3000/mindmap/xxxxxx
```
直接访问这个地址，能看到脑图页就说明前后端链路已经通了。
直接打开该链接，能正常看到脑图页，说明前后端都通了。
## 10. 如果你后面想用宝塔 `添加网站`
## 8. 后续如果想切到宝塔网站统一入口
等你先跑通后，再考虑这一步。
你当前不需要这一步，但后续可以这样演进：
### 10.1 什么时候需要 `添加网站`
1. 前端 Node 项目改为监听 `127.0.0.1:3000`
2. 后端 Python 项目改为监听 `127.0.0.1:8000`
3. 再使用宝塔 `网站 -> 添加站点`
4. 用站点反向代理把 `/` 转到前端，把 `/api/` 转到后端
只有在你想把访问地址收敛成一个入口时，才建议加网站：
如果切到这种模式：
- 例如从 `http://公网IP:3000`
- 改成 `http://公网IP`
- 或 `http://公网IP:8080`
- 前端 `.env.production` 应改为 `NEXT_PUBLIC_API_BASE_URL=`
- 后端 `.env` 中 `FRONTEND_BASE_URL` 应改成统一入口地址
- 前端需要重新构建
### 10.2 这种情况下怎么用宝塔
## 9. 常见问题
推荐做法：
## 9.1 前端能打开，但接口请求错地址
1. 前端 Node 项目继续跑在 `127.0.0.1:3000`
2. 后端 Python 项目继续跑在 `127.0.0.1:8000`
3. 再去宝塔 `网站 -> 添加站点`
4. 用站点的 `反向代理` 把 `/` 转给前端，把 `/api/` 转给后端
也就是说：
- `网站` 负责对外入口
- `Node 项目` 负责前端运行
- `Python 项目` 负责后端运行
这是更符合宝塔使用习惯的结构。
### 10.3 如果要切换到统一入口，环境变量也要改
如果外部地址改成：
```text
http://公网IP
```
那么后端 `.env` 要改成：
```env
FRONTEND_BASE_URL=http://你的公网IP
```
前端 `.env.production` 要改成：
```env
NEXT_PUBLIC_API_BASE_URL=
```
改完后要重新构建前端，并重启前后端项目。
## 11. 常见问题
### 11.1 前端能打开，但接口请求错地址
先看前端环境变量：
检查：
```env
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```
只要改过这个值，就必须重新执行：
只要这个值改过，就重新执行：
```bash
cd /www/wwwroot/mindmap/frontend
cd /mindmap/minimap/frontend
rm -rf .next
npm run build
```
然后在宝塔里重启 Node 项目或 PM2。
然后在宝塔里重启 Node 项目。
### 11.2 后端能运行，但返回链接不对
## 9.2 后端返回的脑图链接不对
检查：
@@ -403,41 +331,63 @@ npm run build
FRONTEND_BASE_URL=http://你的公网IP:3000
```
如果这里没写对，接口返回的 `url` 就会不对。
如果这里错了，API 返回的 `url` 就会错。
### 11.3 SSE 对话接口不稳定
## 9.3 前端构建时报 `Can't resolve ../lib/api`
`/api/chat` 是 SSE。
如果你当前还没上反向代理，先直接用原始端口跑通最稳。
等后面加网站代理时，再专门处理 `/api/chat` 的代理缓冲设置。
这通常不是 Next.js 本身问题，而是服务器代码不完整。
### 11.4 公网访问不到
先确认这些文件在服务器上存在：
```text
/mindmap/minimap/frontend/lib/api.ts
/mindmap/minimap/frontend/lib/tencentSse.ts
/mindmap/minimap/frontend/lib/treeToGraph.ts
/mindmap/minimap/frontend/types/mindmap.ts
```
如果缺文件，优先检查 Git 同步是否完整。
## 9.4 Git push 后服务器代码不完整
这个项目之前踩过一个典型问题：
- 根目录 `.gitignore` 中如果写了 `lib/`
- 会把 `frontend/lib/` 一起忽略掉
正确写法应该是：
```gitignore
/lib/
/lib64/
```
这样只忽略仓库根目录的 `lib`，不会误伤 `frontend/lib`。
## 9.5 公网访问不到
优先检查：
- 宝塔防火墙是否放行了 `3000` 和 `8000`
- 云安全组是否放行了 `3000` 和 `8000`
- 前端是否真的监听在 `3000`
- 后端是否真的监听在 `8000`
- 宝塔防火墙是否放行 `3000` 和 `8000`
- 云安全组是否放行 `3000` 和 `8000`
- Node 项目是否运行中
- Python 项目是否运行中
### 11.5 浏览器提示不安全
## 9.6 浏览器提示不安全
如果你现在使用的是：
当前是：
- 公网 IP
- HTTP
- 非 80/443 标准端口
- 非 80/443 端口
浏览器提示“不安全”是正常现象，不代表项目没跑起来。
浏览器提示“不安全”是正常现象，不代表服务没有跑起来。
## 12. 你现在最该怎么做
## 10. 当前最稳的运维方式
按下面顺序走最稳：
按你现在的实际情况，最稳的方式就是保持：
1. 用宝塔 `Node 项目` 跑前端到 `3000`
2. 用宝塔 `Python 项目` 或 `进程守护` 跑后端到 `8000`
3. 放行 `3000/8000`
4. 先通过 `http://公网IP:3000` 和 `http://公网IP:8000` 验证
5. 等功能确认无误后，再决定要不要加 `网站 + 反向代理`
这样基本不需要先折腾复杂的 Nginx 配置，也最符合你现在“原端口能跑就不改”的目标。
1. 前端继续放在宝塔 `Node 项目`
2. 后端继续放在宝塔 `Python 项目`
3. 继续用 `3000/8000` 直接验证
4. 等功能稳定后，再考虑加宝塔网站做统一入口