njupt-mcp/DEPLOY.md

NJUPT MCP Server - Docker 部署指南

🚀 快速开始

方式一：使用 Docker Compose（推荐）

# 1. 构建并启动
docker-compose up -d

# 2. 查看日志
docker-compose logs -f

# 3. 停止服务
docker-compose down

方式二：使用 Docker 命令

# 1. 构建镜像
docker build -t njupt-mcp:latest .

# 2. 运行容器
docker run -d \
  --name njupt-mcp \
  -p 8000:8000 \
  -e COURSE_SCHEDULE=/app/data/course_schedule.html \
  -v $(pwd)/src/njupt_mcp/resources/course_schedule/B240423-22.html:/app/data/course_schedule.html:ro \
  --restart unless-stopped \
  njupt-mcp:latest

# 3. 查看日志
docker logs -f njupt-mcp

# 4. 停止并删除
docker stop njupt-mcp
docker rm njupt-mcp

⚙️ 配置说明

环境变量

变量名	说明	默认值
COURSE_SCHEDULE	课表 HTML 文件路径（容器内）	/app/data/course_schedule.html

传输模式

容器默认使用 SSE 模式 运行，可通过修改 docker-compose.yml 或启动命令切换：

# stdio 模式（主要用于调试）
command: ["--transport", "stdio"]

# streamable-http 模式
command: ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]

📁 数据挂载

课表文件通过 Docker Volume 挂载到容器内，这样无需重新构建镜像即可更新课表：

volumes:
  - /主机/路径/到/课表.html:/app/data/course_schedule.html:ro

:ro 表示只读挂载，增加安全性。

🔒 安全建议

1. 使用非 root 用户：Dockerfile 已配置使用 appuser (UID 1000) 运行
2. 只读挂载：课表文件以只读方式挂载
3. 资源限制：docker-compose.yml 中配置了 CPU 和内存限制
4. 健康检查：自动检测服务状态，失败时重启

🌐 访问方式

启动后，MCP 服务器在以下地址可用：

• SSE 端点: http://<服务器IP>:8000/sse
• 消息端点: http://<服务器IP>:8000/messages

在 MCP Inspector 中配置服务器 URL：

http://your-server-ip:8000/sse

🐛 常见问题

1. 课表文件找不到

确保挂载路径正确：

# 检查容器内文件是否存在
docker exec njupt-mcp ls -la /app/data/

2. 端口冲突

修改 docker-compose.yml 中的端口映射：

ports:
  - "8080:8000"  # 主机8080映射到容器8000

3. 权限问题

如果课表文件权限不足：

chmod 644 /path/to/course_schedule.html

4. 查看详细日志

# 调试模式启动
docker run -e DEBUG=1 njupt-mcp:latest

# 或修改 docker-compose.yml
environment:
  - DEBUG=1

🔄 更新部署

更新代码后重新构建：

# 拉取最新代码后
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📊 监控

查看容器状态：

docker ps
docker stats njupt-mcp

查看资源使用：

docker system df