278 lines
5.6 KiB
Markdown
278 lines
5.6 KiB
Markdown
# reader MCP Docker 部署计划
|
||
|
||
## 1. 目标
|
||
|
||
将 reader 作为正式 MCP workflow service 以 Docker 方式部署，满足以下原则：
|
||
|
||
1. 服务运行在容器内
|
||
2. 运行态与产物必须外置挂载，不闷在容器内
|
||
3. 配置统一记录在 `.env`
|
||
4. 读写行为与当前仓库约定保持一致
|
||
5. OpenClaw 后续可将该服务作为正式上游 MCP 使用
|
||
|
||
---
|
||
|
||
## 2. 部署原则
|
||
|
||
### 2.1 容器职责
|
||
|
||
容器只负责：
|
||
|
||
- 提供 reader MCP 服务运行环境
|
||
- 加载 reader 代码与依赖
|
||
- 读取挂载进来的配置与状态目录
|
||
- 对外暴露 MCP 服务入口
|
||
|
||
### 2.2 宿主机职责
|
||
|
||
宿主机负责持久化：
|
||
|
||
- 配置文件
|
||
- 运行态
|
||
- outputs 产物
|
||
- 数据目录
|
||
- configs
|
||
|
||
### 2.3 配置收口原则
|
||
|
||
所有环境配置统一放在 `.env`，避免：
|
||
|
||
- 零散写在 compose 内
|
||
- 零散写在 shell 命令里
|
||
- 零散写在 OpenClaw skill 里
|
||
|
||
---
|
||
|
||
## 3. 建议部署目录
|
||
|
||
建议在 reader 仓库内准备标准部署结构：
|
||
|
||
```text
|
||
/home/ubuntu/zhu/github/reader/
|
||
Dockerfile
|
||
docker-compose.yml
|
||
.env
|
||
outputs/
|
||
data/
|
||
configs/
|
||
knowledge-base/
|
||
```
|
||
|
||
说明：
|
||
|
||
- `Dockerfile`：构建 reader MCP 服务镜像
|
||
- `docker-compose.yml`：单服务部署编排
|
||
- `.env`：统一环境变量
|
||
- `outputs/`：产物、run-state、digest、payload 等外置持久化
|
||
- `data/`：term index 等数据外置持久化
|
||
- `configs/`：reader 运行配置外置持久化
|
||
- `knowledge-base/`：如当前 reader/skill 仍会依赖本地知识目录，可继续挂载
|
||
|
||
---
|
||
|
||
## 4. 必须挂载的目录 / 文件
|
||
|
||
### 必须挂载
|
||
|
||
- `.env`
|
||
- `outputs/`
|
||
- `data/`
|
||
- `configs/`
|
||
|
||
### 建议挂载
|
||
|
||
- `knowledge-base/`
|
||
|
||
### 通常不必挂载
|
||
|
||
- `docs/`
|
||
- `plans/`
|
||
- `.git/`
|
||
|
||
---
|
||
|
||
## 5. `.env` 统一配置建议
|
||
|
||
至少应包含以下配置：
|
||
|
||
### FreshRSS
|
||
|
||
- `FRESHRSS_API_BASE_URL`
|
||
- `FRESHRSS_USERNAME`
|
||
- `FRESHRSS_API_PASSWORD`
|
||
|
||
### 主 LLM
|
||
|
||
- `LLM_API_URL`
|
||
- `LLM_API_KEY`
|
||
- `LLM_MODEL`
|
||
|
||
### 单篇总结专用 LLM（如已使用）
|
||
|
||
- `ARTICLE_SUMMARY_API_URL`
|
||
- `ARTICLE_SUMMARY_API_KEY`
|
||
- `ARTICLE_SUMMARY_MODEL`
|
||
|
||
### IMA（如 reader / skill 仍依赖这些配置约定）
|
||
|
||
- `IMA_DAILY_KNOWLEDGE_BASE_ID`
|
||
- `IMA_DAILY_KNOWLEDGE_BASE_NAME`
|
||
|
||
### 运行控制
|
||
|
||
- `PYTHONUNBUFFERED=1`
|
||
- 视需要增加日志级别等配置
|
||
|
||
原则：
|
||
|
||
- 所有会影响服务行为的环境项，都优先进入 `.env`
|
||
- compose 文件只引用 `.env`，不在 compose 里硬编码业务参数
|
||
|
||
---
|
||
|
||
## 6. Dockerfile 设计建议
|
||
|
||
### 目标
|
||
|
||
- 使用 Python 3.11
|
||
- 安装 reader 依赖
|
||
- 默认启动 MCP 服务入口
|
||
|
||
### 建议思路
|
||
|
||
1. 基于 `python:3.11-slim`
|
||
2. 设置工作目录到 `/app`
|
||
3. 复制仓库代码
|
||
4. 安装依赖（如 `pip install -e .`）
|
||
5. 默认启动 reader MCP 服务
|
||
|
||
### 启动入口
|
||
|
||
优先使用当前正式服务入口，例如：
|
||
|
||
- `summary-mcp`
|
||
|
||
如果后续 reader 明确切换到别的稳定入口，再同步更新。
|
||
|
||
---
|
||
|
||
## 7. docker-compose 设计建议
|
||
|
||
建议先保持单服务简单结构，例如：
|
||
|
||
- service 名称：`reader-mcp`
|
||
- `env_file: .env`
|
||
- 挂载：
|
||
- `./outputs:/app/outputs`
|
||
- `./data:/app/data`
|
||
- `./configs:/app/configs`
|
||
- `./knowledge-base:/app/knowledge-base`（如需要）
|
||
- `./.env:/app/.env:ro`（可选，若程序直接读取文件）
|
||
- `restart: unless-stopped`
|
||
|
||
如果当前 MCP 服务是 stdio 型而不是 HTTP 型，需要进一步明确：
|
||
|
||
- 它是由 OpenClaw 以本地进程方式拉起
|
||
- 还是以常驻 sidecar / gateway adapter 方式挂接
|
||
|
||
因此 compose 的最终 command 需要结合实际接入方式确认。
|
||
|
||
---
|
||
|
||
## 8. 部署前确认项
|
||
|
||
在正式执行前，需要先确认以下问题：
|
||
|
||
### 8.1 MCP 连接方式
|
||
|
||
必须确认 reader MCP 服务的正式接入方式是：
|
||
|
||
1. **stdio 型**：OpenClaw/调用方本地拉起进程
|
||
2. **HTTP/SSE 型**：服务常驻监听端口，OpenClaw 远程连接
|
||
|
||
这会直接影响：
|
||
|
||
- Docker command
|
||
- 是否需要端口映射
|
||
- OpenClaw 接入配置
|
||
|
||
### 8.2 当前 `summary-mcp` 的服务形态
|
||
|
||
需要确认：
|
||
|
||
- 现有 `summary-mcp` 是 FastMCP stdio 默认模式
|
||
- 还是已有可直接 HTTP 化的运行方式
|
||
|
||
在这点没确认前，不要盲目写死端口暴露方案。
|
||
|
||
### 8.3 OpenClaw 侧接入点
|
||
|
||
部署完成后，还需要明确 OpenClaw 将如何引用该 MCP 服务：
|
||
|
||
- 本机命令型 MCP
|
||
- Docker 内服务桥接
|
||
- 或其它现有 OpenClaw MCP 配置方式
|
||
|
||
---
|
||
|
||
## 9. 执行顺序（建议）
|
||
|
||
### Phase A：部署方案落地
|
||
|
||
1. 确认 MCP 服务连接方式（stdio / HTTP）
|
||
2. 确认最终 Dockerfile 启动命令
|
||
3. 确认 compose 结构与挂载目录
|
||
4. 整理 `.env` 字段
|
||
|
||
### Phase B：容器化实现
|
||
|
||
1. 新建/更新 `Dockerfile`
|
||
2. 新建/更新 `docker-compose.yml`
|
||
3. 检查 `.dockerignore`
|
||
4. 核对路径是否与仓库内当前代码一致
|
||
|
||
### Phase C：本地部署验证
|
||
|
||
1. `docker compose build`
|
||
2. `docker compose up -d`
|
||
3. 验证服务启动
|
||
4. 验证容器外 `outputs/`、`data/` 等是否正常落盘
|
||
|
||
### Phase D：OpenClaw 接入验证
|
||
|
||
1. 让 OpenClaw 通过正式 MCP 路径连接 reader
|
||
2. 真跑一轮：
|
||
- run
|
||
- status
|
||
- payload
|
||
- report
|
||
3. 如有需要，验证一次最小 `resume_run`
|
||
|
||
---
|
||
|
||
## 10. 当前不在本轮范围内的事
|
||
|
||
本轮部署计划不直接处理：
|
||
|
||
- `rerun_stage`
|
||
- 更复杂的后台任务系统
|
||
- 多实例部署
|
||
- 横向扩展
|
||
- 生产告警体系
|
||
|
||
本轮只做：
|
||
|
||
- 单实例
|
||
- Docker 化
|
||
- 配置收口
|
||
- 挂载持久化
|
||
- OpenClaw 可正式接入
|
||
|
||
---
|
||
|
||
## 11. 一句话结论
|
||
|
||
reader 的下一步不是继续堆内部接口，而是：
|
||
|
||
**以 Docker 正式部署成 MCP workflow service，配置进 `.env`，状态和产物目录挂载到宿主机，然后由 OpenClaw 按正式 MCP 编排路径真实接入和验证。**
|