minimap/宝塔面板部署指南.md

# Interactive Mindmap 宝塔部署指南

## 1. 当前部署形态

这份文档按当前实际部署方式整理：

- 前端放在宝塔 `Node 项目`
- 后端放在宝塔 `Python 项目`
- 当前直接通过公网 IP + 原始端口访问
- 前端地址：`http://公网IP:3000`
- 后端地址：`http://公网IP:8000`

以下示例以当前服务器目录为例：

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

对应代码文件：

- [backend/app/config.py](./backend/app/config.py)
- [backend/app/routers/mindmaps.py](./backend/app/routers/mindmaps.py)
- [frontend/lib/api.ts](./frontend/lib/api.ts)

## 4. 前端部署到宝塔 Node 项目

## 4.1 前端目录

前端目录：

```bash
/mindmap/minimap/frontend
```

## 4.2 前端环境变量

在前端目录创建或修改 `.env.production`：

```env
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```

说明：

- 当前前端直接访问后端 `8000` 端口，所以这里不能留空
- 只要改过这个值，就必须重新构建前端

## 4.3 安装依赖和构建

宝塔终端执行：

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

如果界面需要填写启动命令，建议使用：

```bash
npm run start -- -p 3000
```

如果界面要求先执行构建，请先完成：

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

说明：

- `BOT_APP_KEY` 是腾讯云智能体平台 AppKey
- `FRONTEND_BASE_URL` 必须指向前端真实访问地址
- 当前前端在 `3000` 端口，所以这里必须带 `:3000`

## 5.3 在宝塔中配置 Python 项目

进入宝塔：

- `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
cd /mindmap/minimap/backend
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```

## 5.4 后端验证

浏览器访问：

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

或在终端执行：

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

正常应返回：

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

## 6. 宝塔防火墙与云安全组

当前部署方式需要对公网放行：

- `3000`
- `8000`

必须同时检查两层：

- 宝塔防火墙
- 云服务器安全组

只放行其中一层是不够的。

## 7. 当前部署方式下的验证步骤

## 7.1 验证首页

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

## 7.2 验证后端接口

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

这里预期是后端返回 `404` JSON，而不是超时或 HTML 页面。

## 7.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
```

直接打开该链接，能正常看到脑图页，说明前后端都通了。

## 8. 后续如果想切到宝塔网站统一入口

你当前不需要这一步，但后续可以这样演进：

1. 前端 Node 项目改为监听 `127.0.0.1:3000`
2. 后端 Python 项目改为监听 `127.0.0.1:8000`
3. 再使用宝塔 `网站 -> 添加站点`
4. 用站点反向代理把 `/` 转到前端，把 `/api/` 转到后端

如果切到这种模式：

- 前端 `.env.production` 应改为 `NEXT_PUBLIC_API_BASE_URL=`
- 后端 `.env` 中 `FRONTEND_BASE_URL` 应改成统一入口地址
- 前端需要重新构建

## 9. 常见问题

## 9.1 前端能打开，但接口请求错地址

检查：

```env
NEXT_PUBLIC_API_BASE_URL=http://你的公网IP:8000
```

只要这个值改过，就重新执行：

```bash
cd /mindmap/minimap/frontend
rm -rf .next
npm run build
```

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

## 9.2 后端返回的脑图链接不对

检查：

```env
FRONTEND_BASE_URL=http://你的公网IP:3000
```

如果这里错了，API 返回的 `url` 就会错。

## 9.3 前端构建时报 `Can't resolve ../lib/api`

这通常不是 Next.js 本身问题，而是服务器代码不完整。

先确认这些文件在服务器上存在：

```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`
- Node 项目是否运行中
- Python 项目是否运行中

## 9.6 浏览器提示不安全

当前是：

- 公网 IP
- HTTP
- 非 80/443 端口

浏览器提示“不安全”是正常现象，不代表服务没有跑起来。

## 10. 当前最稳的运维方式

按你现在的实际情况，最稳的方式就是保持：

1. 前端继续放在宝塔 `Node 项目`
2. 后端继续放在宝塔 `Python 项目`
3. 继续用 `3000/8000` 直接验证
4. 等功能稳定后，再考虑加宝塔网站做统一入口