9.5 KiB
Interactive Mindmap 宝塔面板部署指南
1. 部署原则
这份文档按“尽可能使用宝塔面板现成功能”的思路编写：
- 前端优先使用宝塔的
网站 -> Node 项目 - 后端优先使用宝塔的
Python 项目 - 如果你的面板版本里没有合适的 Python 项目入口，再退回
进程守护 - 如果你不想改访问端口，可以直接保留
3000/8000 - 如果你后续想统一入口，再用宝塔
网站 + 反向代理
对这个项目来说，最省事的顺序是：
- 先用宝塔把前端跑在
3000 - 再把后端跑在
8000 - 先直接通过
公网IP:端口验证 - 跑通后，再决定要不要加网站反向代理
2. 先确认项目的真实配置
这个仓库里有几个关键点，部署时必须按代码真实行为来：
- 后端环境变量名是
BOT_APP_KEY - 后端还要配置
FRONTEND_BASE_URL - 前端环境变量名是
NEXT_PUBLIC_API_BASE_URL - 前端主要页面是
/和/mindmap/[id] - 后端接口前缀是
/api /api/chat是 SSE 流式接口
对应文件：
3. 宝塔里建议安装的软件
在宝塔 软件商店 里优先安装：
Node.jsPM2 管理器Python 3.11Nginx
按你的面板版本，下面二选一：
- 如果有
Python 项目或Python 项目管理器，优先用它 - 如果没有，就安装或使用
进程守护 / Supervisor
建议版本：
Node.js 20Python 3.11
4. 上传项目
建议上传到：
/www/wwwroot/mindmap
推荐做法：
- 宝塔
文件里上传项目压缩包 - 在宝塔里解压到
/www/wwwroot/mindmap
如果你是从本地 Windows 机器直接传上来的，先在宝塔终端执行：
cd /www/wwwroot/mindmap/frontend
rm -rf node_modules .next
这是为了避免把 Windows 的前端依赖直接拿到 Linux 里运行。
5. 推荐方案：先保留原始端口跑通
这是当前最推荐你的做法，因为最少折腾。
最终访问方式：
- 前端：
http://公网IP:3000 - 后端：
http://公网IP:8000
这一步不需要先配网站反向代理。
6. 前端：优先使用宝塔 网站 -> Node 项目
6.1 先准备前端环境变量
在宝塔 文件 里进入：
/www/wwwroot/mindmap/frontend
新建文件 .env.production，内容写成：
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
这里必须写公网 IP + 8000，因为你当前是让前端直接访问后端原始端口。
6.2 安装依赖并构建
宝塔终端执行：
cd /www/wwwroot/mindmap/frontend
npm ci
npm run build
6.3 在宝塔里创建 Node 项目
进入宝塔：
网站Node 项目添加 Node 项目
建议填写：
- 项目名称：
mindmap-frontend - 项目目录：
/www/wwwroot/mindmap/frontend - Node 版本：
20 - 启动方式：
PM2 - 端口：
3000 - 启动命令：
start -p 3000
如果界面要求你选择启动文件，按 Next.js 方式选择项目启动即可；面板不同版本字段名称会略有区别，但核心是让它执行 next start -p 3000。
6.4 是否开启外网映射
如果你想直接通过公网访问：
- 开启
外网映射 - 确认映射端口是
3000
这样前端就可以直接通过：
http://公网IP:3000
访问。
6.5 检查前端是否正常
在宝塔里查看：
Node 项目状态是否为运行中PM2 管理器里是否有mindmap-frontend
也可以访问：
http://公网IP:3000
7. 后端：优先使用宝塔 Python 项目
7.1 先准备后端环境变量
在宝塔 文件 里进入：
/www/wwwroot/mindmap/backend
复制 .env.example 为 .env，并写成：
BOT_APP_KEY=你的腾讯云智能体AppKey
FRONTEND_BASE_URL=http://你的公网IP:3000
说明：
BOT_APP_KEY：腾讯云智能体平台 AppKeyFRONTEND_BASE_URL：因为你前端直接跑在3000，所以这里必须写:3000
7.2 如果你的宝塔有 Python 项目
优先这样做：
- 打开
Python 项目 添加项目- 选择 Python 版本：
3.11 - 项目目录：
/www/wwwroot/mindmap/backend - 监听地址：
0.0.0.0 - 监听端口：
8000
如果界面支持自定义启动命令，建议填：
uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers
如果界面要求你选择虚拟环境，就让它在项目目录里创建并使用虚拟环境，然后安装：
pip install -r requirements.txt
7.3 如果你的宝塔没有合适的 Python 项目 入口
就用宝塔的 进程守护 或 Supervisor 管理器，不要自己后台挂命令。
先在宝塔终端执行：
cd /www/wwwroot/mindmap/backend
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
然后进入：
进程守护- 或
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 检查后端是否正常
访问：
http://公网IP:8000
或：
curl http://公网IP:8000/
正常应返回：
{"message":"Interactive Mindmap API is running"}
8. 防火墙与安全组
如果你现在采用“保留原始端口”的方案，必须在宝塔防火墙和云安全组中放行：
30008000
否则面板里虽然显示运行中，但公网访问不到。
9. 先做一次完整验证
9.1 打开首页
浏览器访问：
http://公网IP:3000
9.2 验证接口
curl http://公网IP:8000/api/mindmaps/not-found
正常结果应该是后端返回的 404 JSON，而不是超时或 HTML 页面。
9.3 创建一条测试思维导图
curl -X POST http://公网IP:8000/api/mindmaps \
-H "Content-Type: application/json" \
-d '{
"session_id": "deploy-test-session",
"mindmap_json": {
"id": "node_0",
"label": "部署测试",
"parent_id": null,
"level": 0,
"is_leaf": false,
"children": [
{
"id": "node_1",
"label": "前端",
"parent_id": "node_0",
"level": 1,
"is_leaf": true,
"children": []
},
{
"id": "node_2",
"label": "后端",
"parent_id": "node_0",
"level": 1,
"is_leaf": true,
"children": []
}
]
}
}'
成功后会返回 url，类似：
http://公网IP:3000/mindmap/xxxxxx
直接访问这个地址，能看到脑图页就说明前后端链路已经通了。
10. 如果你后面想用宝塔 添加网站
等你先跑通后，再考虑这一步。
10.1 什么时候需要 添加网站
只有在你想把访问地址收敛成一个入口时，才建议加网站：
- 例如从
http://公网IP:3000 - 改成
http://公网IP - 或
http://公网IP:8080
10.2 这种情况下怎么用宝塔
推荐做法：
- 前端 Node 项目继续跑在
127.0.0.1:3000 - 后端 Python 项目继续跑在
127.0.0.1:8000 - 再去宝塔
网站 -> 添加站点 - 用站点的
反向代理把/转给前端，把/api/转给后端
也就是说：
网站负责对外入口Node 项目负责前端运行Python 项目负责后端运行
这是更符合宝塔使用习惯的结构。
10.3 如果要切换到统一入口，环境变量也要改
如果外部地址改成：
http://公网IP
那么后端 .env 要改成：
FRONTEND_BASE_URL=http://你的公网IP
前端 .env.production 要改成：
NEXT_PUBLIC_API_BASE_URL=
改完后要重新构建前端，并重启前后端项目。
11. 常见问题
11.1 前端能打开，但接口请求错地址
先看前端环境变量：
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
只要改过这个值，就必须重新执行：
cd /www/wwwroot/mindmap/frontend
npm run build
然后在宝塔里重启 Node 项目或 PM2。
11.2 后端能运行，但返回链接不对
检查：
FRONTEND_BASE_URL=http://你的公网IP:3000
如果这里没写对，接口返回的 url 就会不对。
11.3 SSE 对话接口不稳定
/api/chat 是 SSE。
如果你当前还没上反向代理，先直接用原始端口跑通最稳。
等后面加网站代理时，再专门处理 /api/chat 的代理缓冲设置。
11.4 公网访问不到
优先检查：
- 宝塔防火墙是否放行了
3000和8000 - 云安全组是否放行了
3000和8000 - 前端是否真的监听在
3000 - 后端是否真的监听在
8000
11.5 浏览器提示不安全
如果你现在使用的是：
- 公网 IP
- HTTP
- 非 80/443 标准端口
浏览器提示“不安全”是正常现象，不代表项目没跑起来。
12. 你现在最该怎么做
按下面顺序走最稳：
- 用宝塔
Node 项目跑前端到3000 - 用宝塔
Python 项目或进程守护跑后端到8000 - 放行
3000/8000 - 先通过
http://公网IP:3000和http://公网IP:8000验证 - 等功能确认无误后，再决定要不要加
网站 + 反向代理
这样基本不需要先折腾复杂的 Nginx 配置，也最符合你现在“原端口能跑就不改”的目标。