185 lines
4.1 KiB
Markdown
185 lines
4.1 KiB
Markdown
# NexDocs v0.9.6 升级日志
|
||
|
||
## 版本信息
|
||
|
||
- 版本号：`v0.9.6`
|
||
- 更新时间：`2026-03-11`
|
||
|
||
|
||
## 本次升级摘要
|
||
|
||
`v0.9.6` 主要完成了以下升级：
|
||
|
||
1. 新增后端内集成的 MCP Server 能力
|
||
2. 新增用户级 MCP 凭证管理
|
||
3. 打通通过 Nginx 统一入口访问 MCP
|
||
4. 调整部署运行环境到 Python 3.12
|
||
5. 将 MySQL、Redis 数据目录改为项目根目录 `storage/` 持久化
|
||
6. 优化个人中心与文档页面部分交互体验
|
||
|
||
|
||
## 功能升级
|
||
|
||
### 1. MCP Server 内集成
|
||
|
||
系统已支持直接在 backend 中提供 MCP `streamableHttp` 服务，不再依赖项目根目录下的独立 `mcp_server/` 进程。
|
||
|
||
当前 MCP 入口：
|
||
|
||
```text
|
||
/mcp/
|
||
```
|
||
|
||
当前支持的工具：
|
||
|
||
1. `list_created_projects`：列出当前用户的项目
|
||
2. `get_project_tree`：列出项目文件树结构
|
||
3. `get_file`：获取指定文件
|
||
4. `create_file`：在项目中创建新文件
|
||
5. `update_file`：修改指定文件
|
||
6. `delete_file`：删除指定文件
|
||
|
||
|
||
### 2. MCP 认证与用户凭证管理
|
||
|
||
新增基于 `X-Bot-Id` 和 `X-Bot-Secret` 的 MCP 认证模型。
|
||
|
||
能力包括：
|
||
|
||
- 每个用户可拥有自己的 MCP 凭证
|
||
- 通过数据库表 `mcp_bots` 维护 bot 与用户的映射
|
||
- 支持在个人中心查看和重新生成凭证
|
||
- 服务端自动按凭证映射到对应 NexDocs 用户身份执行工具
|
||
|
||
相关接口：
|
||
|
||
- `GET /api/v1/auth/mcp-credentials`
|
||
- `POST /api/v1/auth/mcp-credentials/rotate-secret`
|
||
|
||
|
||
### 3. Nginx 统一入口支持 MCP
|
||
|
||
前端 Nginx 已新增 `/mcp/` 反向代理配置。
|
||
|
||
现在在只暴露一个公网入口端口的部署模式下，可以通过统一入口访问：
|
||
|
||
```text
|
||
http(s)://<host>/mcp/
|
||
```
|
||
|
||
不再要求调用端直连 backend 容器端口。
|
||
|
||
|
||
## 前端与交互优化
|
||
|
||
### 1. 个人中心布局调整
|
||
|
||
个人中心由上下结构调整为左右结构：
|
||
|
||
- 左侧为纵向导航
|
||
- 右侧为内容区域
|
||
- 移动端会自动回退为上下布局
|
||
|
||
|
||
### 2. 文档浏览/编辑切换优化
|
||
|
||
本轮已对项目文档页做过一组交互统一：
|
||
|
||
- 浏览/编辑模式切换样式统一
|
||
- 页面头部高度与操作区对齐
|
||
- 切换时保留当前文件上下文
|
||
- 登录跳转回原目标页的逻辑补齐
|
||
|
||
|
||
### 3. 认证异常提示优化
|
||
|
||
对未登录和 token 失效场景做了重复错误提示抑制：
|
||
|
||
- 避免并发请求弹出多条重复 Toast
|
||
- 统一 401 处理与跳转逻辑
|
||
|
||
|
||
## 部署与运行环境变更
|
||
|
||
### 1. Python 运行环境升级
|
||
|
||
backend 运行环境已调整为：
|
||
|
||
```text
|
||
Python 3.12
|
||
```
|
||
|
||
原因：
|
||
|
||
- MCP Python SDK 需要 Python 3.10+
|
||
- 当前版本已按 Python 3.12 完成调试与验证
|
||
|
||
|
||
### 2. Docker 构建链调整
|
||
|
||
backend Docker 镜像构建已做以下处理：
|
||
|
||
- 基础镜像切换为 `python:3.12-slim`
|
||
- 增加 pip 构建工具升级
|
||
- pip 安装支持国内源失败后回退官方源
|
||
- Nginx 已补充 `/mcp/` 代理配置
|
||
|
||
|
||
### 3. 数据持久化目录调整
|
||
|
||
本次升级将 MySQL、Redis 的数据目录改为挂载到项目根目录下的 `storage/`：
|
||
|
||
```text
|
||
storage/
|
||
├── mysql/
|
||
├── redis/
|
||
├── projects/
|
||
└── temp/
|
||
```
|
||
|
||
当前挂载关系：
|
||
|
||
- `storage/mysql -> /var/lib/mysql`
|
||
- `storage/redis -> /data`
|
||
- `storage -> /data/nex_docus_store`
|
||
|
||
这样做的目的：
|
||
|
||
- 宿主机可直接看到数据库与缓存数据目录
|
||
- 便于整体备份
|
||
- 避免数据只留在 Docker named volume 中
|
||
|
||
|
||
## 升级迁移注意事项
|
||
|
||
### 1. MCP 调用地址调整
|
||
|
||
如果原先通过 backend 端口直连 MCP，可以继续使用。
|
||
|
||
如果当前部署是通过前端 Nginx 暴露统一入口，推荐改为：
|
||
|
||
```text
|
||
http(s)://<host>/mcp/
|
||
```
|
||
|
||
调用头保持不变：
|
||
|
||
- `X-Bot-Id`
|
||
- `X-Bot-Secret`
|
||
|
||
|
||
### 部署与文档
|
||
|
||
- [docker-compose.yml](/Users/jiliu/工作/projects/NexDocus/docker-compose.yml)
|
||
- [MCP_HTTP_INTEGRATION.md](/Users/jiliu/工作/projects/NexDocus/docs/MCP_HTTP_INTEGRATION.md)
|
||
|
||
|
||
## 升级建议
|
||
|
||
建议升级到 `v0.9.6` 后按以下顺序验证：
|
||
|
||
1. 验证 backend `/health` 是否正常
|
||
2. 验证统一入口 `/api/` 与 `/mcp/` 是否可访问
|
||
3. 验证 MCP client 是否能正常完成 `initialize`
|
||
4. 验证个人中心的 MCP 凭证展示与轮换功能
|