7.8 KiB
7.8 KiB
Interactive Mindmap 宝塔部署指南
1. 当前部署形态
这份文档按当前实际部署方式整理：
- 前端放在宝塔
Node 项目 - 后端放在宝塔
Python 项目 - 当前直接通过公网 IP + 原始端口访问
- 前端地址：
http://公网IP:3000 - 后端地址：
http://公网IP:8000
以下示例以当前服务器目录为例：
/mindmap/minimap
如果你的实际目录不同，把文档里的路径替换成你的真实路径即可。
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] - 后端创建脑图接口是
POST /api/mindmaps - 后端对话接口是
POST /api/chat
对应代码文件：
4. 前端部署到宝塔 Node 项目
4.1 前端目录
前端目录：
/mindmap/minimap/frontend
4.2 前端环境变量
在前端目录创建或修改 .env.production：
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
说明：
- 当前前端直接访问后端
8000端口，所以这里不能留空 - 只要改过这个值，就必须重新构建前端
4.3 安装依赖和构建
宝塔终端执行：
cd /mindmap/minimap/frontend
npm ci
rm -rf .next
npm run build
如果构建失败，先看本文末尾的“常见问题”。
4.4 在宝塔中配置 Node 项目
进入宝塔：
网站Node 项目- 找到或新建前端项目
建议配置：
- 项目名称：
mindmap-frontend - 项目目录：
/mindmap/minimap/frontend - Node 版本：
20 - 运行端口：
3000 - 启动方式：
PM2
如果界面需要填写启动命令，建议使用：
npm run start -- -p 3000
如果界面要求先执行构建，请先完成：
npm run build
4.5 前端验证
浏览器访问：
http://公网IP:3000
如果首页能打开，说明 Node 项目启动正常。
5. 后端部署到宝塔 Python 项目
5.1 后端目录
后端目录：
/mindmap/minimap/backend
5.2 后端环境变量
复制配置文件：
cd /mindmap/minimap/backend
cp .env.example .env
然后将 .env 改成类似这样：
BOT_APP_KEY=你的腾讯云智能体AppKey
FRONTEND_BASE_URL=http://你的公网IP:3000
说明：
BOT_APP_KEY是腾讯云智能体平台 AppKeyFRONTEND_BASE_URL必须指向前端真实访问地址- 当前前端在
3000端口，所以这里必须带:3000
5.3 在宝塔中配置 Python 项目
进入宝塔：
Python 项目- 找到或新建后端项目
建议配置：
- 项目名称：
mindmap-backend - 项目目录：
/mindmap/minimap/backend - Python 版本：
3.11 - 监听地址：
0.0.0.0 - 监听端口：
8000
如果界面支持自定义启动命令，建议填写：
uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers
如果宝塔 Python 项目需要先准备虚拟环境和依赖，执行：
cd /mindmap/minimap/backend
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
5.4 后端验证
浏览器访问：
http://公网IP:8000
或在终端执行：
curl http://公网IP:8000/
正常应返回：
{"message":"Interactive Mindmap API is running"}
6. 宝塔防火墙与云安全组
当前部署方式需要对公网放行：
30008000
必须同时检查两层：
- 宝塔防火墙
- 云服务器安全组
只放行其中一层是不够的。
7. 当前部署方式下的验证步骤
7.1 验证首页
http://公网IP:3000
7.2 验证后端接口
curl http://公网IP:8000/api/mindmaps/not-found
这里预期是后端返回 404 JSON，而不是超时或 HTML 页面。
7.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
直接打开该链接，能正常看到脑图页，说明前后端都通了。
8. 后续如果想切到宝塔网站统一入口
你当前不需要这一步，但后续可以这样演进：
- 前端 Node 项目改为监听
127.0.0.1:3000 - 后端 Python 项目改为监听
127.0.0.1:8000 - 再使用宝塔
网站 -> 添加站点 - 用站点反向代理把
/转到前端，把/api/转到后端
如果切到这种模式：
- 前端
.env.production应改为NEXT_PUBLIC_API_BASE_URL= - 后端
.env中FRONTEND_BASE_URL应改成统一入口地址 - 前端需要重新构建
9. 常见问题
9.1 前端能打开，但接口请求错地址
检查：
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
只要这个值改过，就重新执行：
cd /mindmap/minimap/frontend
rm -rf .next
npm run build
然后在宝塔里重启 Node 项目。
9.2 后端返回的脑图链接不对
检查：
FRONTEND_BASE_URL=http://你的公网IP:3000
如果这里错了，API 返回的 url 就会错。
9.3 前端构建时报 Can't resolve ../lib/api
这通常不是 Next.js 本身问题，而是服务器代码不完整。
先确认这些文件在服务器上存在：
/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/一起忽略掉
正确写法应该是：
/lib/
/lib64/
这样只忽略仓库根目录的 lib，不会误伤 frontend/lib。
9.5 公网访问不到
优先检查：
- 宝塔防火墙是否放行
3000和8000 - 云安全组是否放行
3000和8000 - Node 项目是否运行中
- Python 项目是否运行中
9.6 浏览器提示不安全
当前是：
- 公网 IP
- HTTP
- 非 80/443 端口
浏览器提示“不安全”是正常现象，不代表服务没有跑起来。
10. 当前最稳的运维方式
按你现在的实际情况，最稳的方式就是保持：
- 前端继续放在宝塔
Node 项目 - 后端继续放在宝塔
Python 项目 - 继续用
3000/8000直接验证 - 等功能稳定后，再考虑加宝塔网站做统一入口