# Interactive Mindmap 宝塔面板部署指南

## 1. 部署原则

这份文档按“尽可能使用宝塔面板现成功能”的思路编写：

- 前端优先使用宝塔的 `网站 -> Node 项目`
- 后端优先使用宝塔的 `Python 项目`
- 如果你的面板版本里没有合适的 Python 项目入口，再退回 `进程守护`
- 如果你不想改访问端口，可以直接保留 `3000/8000`
- 如果你后续想统一入口，再用宝塔 `网站 + 反向代理`

对这个项目来说，最省事的顺序是：

1. 先用宝塔把前端跑在 `3000`
2. 再把后端跑在 `8000`
3. 先直接通过 `公网IP:端口` 验证
4. 跑通后，再决定要不要加网站反向代理

## 2. 先确认项目的真实配置

这个仓库里有几个关键点，部署时必须按代码真实行为来：

- 后端环境变量名是 `BOT_APP_KEY`
- 后端还要配置 `FRONTEND_BASE_URL`
- 前端环境变量名是 `NEXT_PUBLIC_API_BASE_URL`
- 前端主要页面是 `/` 和 `/mindmap/[id]`
- 后端接口前缀是 `/api`
- `/api/chat` 是 SSE 流式接口

对应文件：

- [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. 宝塔里建议安装的软件

在宝塔 `软件商店` 里优先安装：

- `Node.js`
- `PM2 管理器`
- `Python 3.11`
- `Nginx`

按你的面板版本，下面二选一：

- 如果有 `Python 项目` 或 `Python 项目管理器`，优先用它
- 如果没有，就安装或使用 `进程守护 / Supervisor`

建议版本：

- `Node.js 20`
- `Python 3.11`

## 4. 上传项目

建议上传到：

```bash
/www/wwwroot/mindmap
```

推荐做法：

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
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```

这里必须写公网 IP + `8000`，因为你当前是让前端直接访问后端原始端口。

### 6.2 安装依赖并构建

宝塔终端执行：

```bash
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`

这样前端就可以直接通过：

```text
http://公网IP:3000
```

访问。

### 6.5 检查前端是否正常

在宝塔里查看：

- `Node 项目` 状态是否为运行中
- `PM2 管理器` 里是否有 `mindmap-frontend`

也可以访问：

```text
http://公网IP:3000
```

## 7. 后端：优先使用宝塔 `Python 项目`

### 7.1 先准备后端环境变量

在宝塔 `文件` 里进入：

```bash
/www/wwwroot/mindmap/backend
```

复制 `.env.example` 为 `.env`，并写成：

```env
BOT_APP_KEY=你的腾讯云智能体AppKey
FRONTEND_BASE_URL=http://你的公网IP:3000
```

说明：

- `BOT_APP_KEY`：腾讯云智能体平台 AppKey
- `FRONTEND_BASE_URL`：因为你前端直接跑在 `3000`，所以这里必须写 `:3000`

### 7.2 如果你的宝塔有 `Python 项目`

优先这样做：

- 打开 `Python 项目`
- `添加项目`
- 选择 Python 版本：`3.11`
- 项目目录：`/www/wwwroot/mindmap/backend`
- 监听地址：`0.0.0.0`
- 监听端口：`8000`

如果界面支持自定义启动命令，建议填：

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers
```

如果界面要求你选择虚拟环境，就让它在项目目录里创建并使用虚拟环境，然后安装：

```bash
pip install -r requirements.txt
```

### 7.3 如果你的宝塔没有合适的 `Python 项目` 入口

就用宝塔的 `进程守护` 或 `Supervisor 管理器`，不要自己后台挂命令。

先在宝塔终端执行：

```bash
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 检查后端是否正常

访问：

```text
http://公网IP:8000
```

或：

```bash
curl http://公网IP:8000/
```

正常应返回：

```json
{"message":"Interactive Mindmap API is running"}
```

## 8. 防火墙与安全组

如果你现在采用“保留原始端口”的方案，必须在宝塔防火墙和云安全组中放行：

- `3000`
- `8000`

否则面板里虽然显示运行中，但公网访问不到。

## 9. 先做一次完整验证

### 9.1 打开首页

浏览器访问：

```text
http://公网IP:3000
```

### 9.2 验证接口

```bash
curl http://公网IP:8000/api/mindmaps/not-found
```

正常结果应该是后端返回的 `404 JSON`，而不是超时或 HTML 页面。

### 9.3 创建一条测试思维导图

```bash
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`，类似：

```text
http://公网IP:3000/mindmap/xxxxxx
```

直接访问这个地址，能看到脑图页就说明前后端链路已经通了。

## 10. 如果你后面想用宝塔 `添加网站`

等你先跑通后，再考虑这一步。

### 10.1 什么时候需要 `添加网站`

只有在你想把访问地址收敛成一个入口时，才建议加网站：

- 例如从 `http://公网IP:3000`
- 改成 `http://公网IP`
- 或 `http://公网IP:8080`

### 10.2 这种情况下怎么用宝塔

推荐做法：

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
npm run build
```

然后在宝塔里重启 Node 项目或 PM2。

### 11.2 后端能运行，但返回链接不对

检查：

```env
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. 你现在最该怎么做

按下面顺序走最稳：

1. 用宝塔 `Node 项目` 跑前端到 `3000`
2. 用宝塔 `Python 项目` 或 `进程守护` 跑后端到 `8000`
3. 放行 `3000/8000`
4. 先通过 `http://公网IP:3000` 和 `http://公网IP:8000` 验证
5. 等功能确认无误后，再决定要不要加 `网站 + 反向代理`

这样基本不需要先折腾复杂的 Nginx 配置，也最符合你现在“原端口能跑就不改”的目标。