# 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 凭证展示与轮换功能