countly/countly-mcp-server

Docker部署指南

本指南涵盖在多种环境下使用Docker部署Countly MCP服务器的方法。

目录

• 快速开始
• Docker Hub
• 本地构建
• Docker Compose
• Docker Swarm
• Kubernetes
• 配置
• 健康检查
• 故障排除
• 最佳实践
• 安全考虑
• 监控
• 支持

快速开始

最快的启动方式：

bash
# 1. 克隆仓库并进入目录
git clone https://github.com/countly/countly-mcp-server.git
cd countly-mcp-server

# 2. 运行快速启动脚本
./docker-start.sh

脚本将引导您完成：

• 创建环境配置
• 设置认证令牌
• 构建并启动服务器

Docker Hub

从Docker Hub拉取镜像

bash
docker pull countly/countly-mcp-server:latest

从Docker Hub运行镜像

bash
docker run -d \
  --name countly-mcp-server \
  -p 3000:3000 \
  -e COUNTLY_SERVER_URL=https://your-countly-instance.com \
  -e COUNTLY_AUTH_TOKEN=your-token-here \
  countly/countly-mcp-server:latest

本地构建

构建镜像

bash
# 带标签构建
docker build -t countly-mcp-server:local .

# 带特定版本构建
docker build -t countly-mcp-server:1.0.0 .

运行本地镜像

bash
docker run -d \
  --name countly-mcp-server \
  -p 3000:3000 \
  -e COUNTLY_SERVER_URL=https://your-countly-instance.com \
  -e COUNTLY_AUTH_TOKEN=your-token-here \
  countly-mcp-server:local

Docker Compose

基础设置

1. 创建令牌文件：

   bash
   echo "your-auth-token" > countly_token.txt
   chmod 600 countly_token.txt
   

2. 创建/编辑.env文件：

   bash
   cp .env.example .env
   # 在.env中编辑COUNTLY_SERVER_URL
   

3. 启动服务：

   bash
   docker-compose up -d
   

开发环境设置（热重载）

yaml
# docker-compose.dev.yml
version: '3.8'
services:
  countly-mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./src:/app/src:ro
      - ./package.json:/app/package.json:ro
    environment:
      - COUNTLY_SERVER_URL=${COUNTLY_SERVER_URL}
      - COUNTLY_AUTH_TOKEN=${COUNTLY_AUTH_TOKEN}
    ports:
      - "3000:3000"
    command: npm run dev

运行命令：

bash
docker-compose -f docker-compose.dev.yml up

生产环境设置（使用Secrets）

提供的docker-compose.yml使用Docker Secrets：

bash
# 启动带Secrets的服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 检查状态
docker-compose ps

# 停止服务
docker-compose down

Docker Swarm

初始化Swarm

bash
docker swarm init

创建Secret

bash
echo "your-auth-token" | docker secret create countly_token -

部署Stack

bash
# 更新docker-compose.yml以使用外部Secret
# 然后部署
docker stack deploy -c docker-compose.yml countly

管理Stack

bash
# 列出服务
docker service ls

# 查看日志
docker service logs countly_countly-mcp-server

# 扩展服务
docker service scale countly_countly-mcp-server=3

# 删除Stack
docker stack rm countly

Kubernetes

创建命名空间

bash
kubectl create namespace countly-mcp

创建Secret

bash
kubectl create secret generic countly-token \
  --from-literal=token=your-auth-token \
  -n countly-mcp

部署配置

yaml
# kubernetes-deployment.yml
apiVersion: v1
kind: ConfigMap
metadata:
  name: countly-mcp-config
  namespace: countly-mcp
data:
  COUNTLY_SERVER_URL: "https://your-countly-instance.com"
  COUNTLY_TIMEOUT: "30000"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: countly-mcp-server
  namespace: countly-mcp
  labels:
    app: countly-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: countly-mcp-server
  template:
    metadata:
      labels:
        app: countly-mcp-server
    spec:
      containers:
      - name: countly-mcp-server
        image: countly/countly-mcp-server:latest
        imagePullPolicy: Always
        ports:
        - containerPort: 3000
          name: http
        env:
        - name: COUNTLY_SERVER_URL
          valueFrom:
            configMapKeyRef:
              name: countly-mcp-config
              key: COUNTLY_SERVER_URL
        - name: COUNTLY_TIMEOUT
          valueFrom:
            configMapKeyRef:
              name: countly-mcp-config
              key: COUNTLY_TIMEOUT
        - name: COUNTLY_AUTH_TOKEN_FILE
          value: "/run/secrets/countly_token"
        volumeMounts:
        - name: token
          mountPath: /run/secrets
          readOnly: true
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi
      volumes:
      - name: token
        secret:
          secretName: countly-token
          items:
          - key: token
            path: countly_token
---
apiVersion: v1
kind: Service
metadata:
  name: countly-mcp-server
  namespace: countly-mcp
spec:
  selector:
    app: countly-mcp-server
  ports:
  - name: http
    port: 3000
    targetPort: 3000
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: countly-mcp-server
  namespace: countly-mcp
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - host: countly-mcp.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: countly-mcp-server
            port:
              number: 3000

部署到Kubernetes

bash
kubectl apply -f kubernetes-deployment.yml

# 检查状态
kubectl get pods -n countly-mcp
kubectl get svc -n countly-mcp

# 查看日志
kubectl logs -f deployment/countly-mcp-server -n countly-mcp

配置

环境变量

卷挂载

用于令牌文件或自定义配置：

bash
docker run -d \
  -v $(pwd)/countly_token.txt:/run/secrets/countly_token:ro \
  -v $(pwd)/custom.env:/app/.env:ro \
  -e COUNTLY_AUTH_TOKEN_FILE=/run/secrets/countly_token \
  countly-mcp-server

健康检查

内置健康检查

Docker镜像包含健康检查：

bash
# 检查容器健康状态
docker ps

# 手动健康检查
curl http://localhost:3000/health

响应：

json
{
  "status": "healthy",
  "timestamp": "2025-10-10T12:00:00.000Z"
}

自定义健康检查

覆盖默认健康检查：

yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

故障排除

容器无法启动

bash
# 查看日志
docker logs countly-mcp-server

# 检查端口是否被占用
lsof -i :3000

# 前台运行以调试
docker run -it --rm \
  -p 3000:3000 \
  -e COUNTLY_SERVER_URL=https://your-instance.com \
  -e COUNTLY_AUTH_TOKEN=your-token \
  countly-mcp-server

认证错误

bash
# 验证令牌
docker exec countly-mcp-server cat /run/secrets/countly_token

# 手动测试令牌
curl "https://your-instance.com/o/apps/mine?auth_token=your-token"

连接问题

bash
# 从容器内部测试
docker exec countly-mcp-server wget -O- http://localhost:3000/health

# 检查网络
docker network ls
docker network inspect bridge

性能问题

bash
# 检查资源使用情况
docker stats countly-mcp-server

# 增加内存限制
docker run -m 1g countly-mcp-server

# 或在docker-compose.yml中设置
deploy:
  resources:
    limits:
      memory: 1G

调试模式

启用详细日志运行：

bash
docker run -it --rm \
  -e NODE_ENV=development \
  -e DEBUG=* \
  countly-mcp-server

最佳实践

1. 生产环境使用Secrets存储令牌
2. 启用健康检查实现自动恢复
3. 设置资源限制防止资源耗尽
4. 使用只读挂载处理敏感文件
5. 以非root用户运行（镜像内置）
6. 启用日志并配置适当的轮转策略
7. 生产环境使用特定镜像标签而非latest
8. 实施配置备份策略
9. 使用外部工具监控容器健康
10. 定期更新镜像获取安全补丁

安全考虑

文件权限

bash
# 保护令牌文件
chmod 600 countly_token.txt
chown 1001:1001 countly_token.txt  # 匹配容器用户

网络隔离

bash
# 创建隔离网络
docker network create --internal countly-network

docker run --network countly-network countly-mcp-server

只读文件系统

bash
docker run --read-only \
  --tmpfs /tmp \
  countly-mcp-server

监控

Prometheus指标

扩展服务器添加指标端点：

yaml
# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
  
  grafana:
    image: grafana/grafana
    ports:
      - "3001:3000"

日志聚合

yaml
logging:
  driver: "fluentd"
  options:
    fluentd-address: localhost:24224
    tag: countly-mcp-server

支持

• 问题反馈：https://github.com/countly/countly-mcp-server/issues
• 社区支持：Countly Community
• 文档参考：README.md