Skip to content
Snow leopard edited this page Jul 16, 2026 · 1 revision

Deployment

Deploying CogitoAgent to Production

将 CogitoAgent 部署到生产环境


This guide covers deployment options for CogitoAgent, including Docker deployment, production configuration, and development setup. Choose the approach that best fits your environment.

本指南涵盖了 CogitoAgent 的部署选项,包括 Docker 部署、生产环境配置和开发环境设置。选择最适合您环境的方式。


Deployment Options | 部署选项

flowchart TB
    subgraph OPTIONS["Deployment Options | 部署选项"]
        DOCKER["🐳 Docker<br/>Containerized"]
        NATIVE["🖥️ Native<br/>Direct Installation"]
        DEV["⚙️ Development<br/>Local Setup"]
    end

    subgraph ENV["Environments | 环境"]
        PROD["Production<br/>生产环境"]
        DEV_ENV["Development<br/>开发环境"]
        TEST["Testing<br/>测试环境"]
    end

    DOCKER --> PROD
    DOCKER --> TEST
    NATIVE --> PROD
    DEV --> DEV_ENV

    classDef docker fill:#1a2332,stroke:#5eead4,color:#5eead4
    classDef native fill:#1a2332,stroke:#38bdf8,color:#38bdf8
    classDef dev fill:#1a2332,stroke:#fbbf24,color:#fbbf24
    classDef env fill:#1a2332,stroke:#94a3b8,color:#94a3b8

    class DOCKER docker
    class NATIVE native
    class DEV dev
    class PROD,DEV_ENV,TEST env
Loading

1. Docker Deployment | Docker 部署

Docker deployment is the recommended approach for production environments and server deployments.

Docker 部署是生产环境和服务器部署的推荐方式。

Prerequisites | 前置要求

  • Docker Engine 20.10+

  • Docker Compose v2.0+

  • Minimum 2GB available RAM

  • Docker Engine 20.10+

  • Docker Compose v2.0+

  • 最低 2GB 可用内存

Quick Start | 快速开始

# Clone the repository | 克隆仓库
git clone https://github.com/SnowLeopard-io/CogitoAgent.git
cd cogito-agent

# Start with Docker Compose | 使用 Docker Compose 启动
docker-compose up -d

# Check status | 检查状态
docker-compose ps

Docker Compose Configuration | Docker Compose 配置

version: '3.8'

services:
  cogito-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: cogito-agent
    restart: unless-stopped
    ports:
      - "9527:9527"           # WebSocket port | WebSocket 端口
      - "3001:3001"           # MCP port (optional) | MCP 端口(可选)
    environment:
      - NODE_ENV=production
      - COGITO_API_KEY=${COGITO_API_KEY}
      - COGITO_API_BASE_URL=${COGITO_API_BASE_URL}
      - COGITO_MODEL=${COGITO_MODEL}
      - COGITO_WORKSPACE=/app/workspace
      - COGITO_MODE=${COGITO_MODE:-desktop}
    volumes:
      - ./config.json:/app/config.json:ro
      - cogito-data:/app/data
      - ${COGITO_WORKSPACE:-./workspace}:/app/workspace
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9527/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  cogito-data:
    driver: local

Environment Variables for Docker | Docker 环境变量

Variable Required Default Description
COGITO_API_KEY Yes — API key
COGITO_API_BASE_URL Yes — API base URL
COGITO_MODEL Yes — Model name
COGITO_MODE No desktop Mode: desktop or dashboard
COGITO_WORKSPACE No /app/workspace Workspace path
COGITO_THINKING_INTERVAL No 3000 Thinking interval (ms)
变量 必需 默认值 说明
COGITO_API_KEY 是 — API 密钥
COGITO_API_BASE_URL 是 — API 基础地址
COGITO_MODEL 是 — 模型名称
COGITO_MODE 否 desktop 模式:desktop 或 dashboard
COGITO_WORKSPACE 否 /app/workspace 工作区路径
COGITO_THINKING_INTERVAL 否 3000 思考间隔(毫秒)

Manual Build | 手动构建

# Build image | 构建镜像
docker build -t cogito-agent:latest .

# Run container | 运行容器
docker run -d \
  --name cogito-agent \
  -p 9527:9527 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/workspace:/app/workspace \
  -e COGITO_API_KEY="your-api-key" \
  -e COGITO_API_BASE_URL="https://api.openai.com/v1" \
  -e COGITO_MODEL="gpt-4o" \
  cogito-agent:latest

2. Native Installation | 原生安装

For direct installation on bare metal or virtual machines.

用于直接在物理机或虚拟机上安装。

Prerequisites | 前置要求

# Node.js 22.12 or higher | Node.js 22.12 或更高版本
node --version

# npm 9.x or higher | npm 9.x 或更高版本
npm --version

# Python 3.x (optional) | Python 3.x(可选)
python3 --version

Installation Steps | 安装步骤

# Clone repository | 克隆仓库
git clone https://github.com/SnowLeopard-io/CogitoAgent.git
cd cogito-agent

# Install dependencies | 安装依赖
npm install

# Copy environment file | 复制环境文件
cp .env.example .env

# Edit .env with your configuration | 编辑 .env 填写配置
vim .env

# Start in production mode | 以生产模式启动
npm run electron:dashboard

Production Mode | 生产模式

# For headless servers | 无头服务器
npm run cli

# With WebSocket enabled | 启用 WebSocket
COGITO_MODE=dashboard npm run electron

3. Development Setup | 开发环境设置

For developers who want to contribute or customize CogitoAgent.

适用于希望贡献或自定义 CogitoAgent 的开发者。

Development Environment | 开发环境

# Clone and install | 克隆并安装
git clone https://github.com/SnowLeopard-io/CogitoAgent.git
cd cogito-agent
npm install

# Run in development mode | 以开发模式运行
npm run cli

# Or with Electron | 或使用 Electron
npm run electron:desktop

Development Commands | 开发命令

Command Description 说明
npm run cli CLI mode with hot reload CLI 模式,带热重载
npm run electron:desktop Desktop mode with hot reload 桌面模式,带热重载
npm run electron:dashboard Dashboard mode with hot reload 仪表盘模式,带热重载
npm run typecheck TypeScript type checking TypeScript 类型检查
npm test Run unit tests 运行单元测试
npm run test:e2e Run end-to-end tests 运行端到端测试
npm run build Build Electron app 构建 Electron 应用

Type Checking | 类型检查

# Check types without emitting | 检查类型但不输出
npm run typecheck

# Watch mode | 监听模式
npx tsc --noEmit --watch

Configuration for Production | 生产环境配置

.env File | 环境变量文件

# .env for production | 生产环境 .env

# Required | 必需
COGITO_API_KEY=your-production-api-key
COGITO_API_BASE_URL=https://api.openai.com/v1
COGITO_MODEL=gpt-4o

# Optional | 可选
COGITO_MODE=dashboard
COGITO_WORKSPACE=/data/workspace
COGITO_THINKING_INTERVAL=3000
COGITO_DATABASE_PATH=/data/example.db
COGITO_CONFIRM_DANGEROUS=true
COGITO_SANDBOX_MODE=true

# Logging | 日志
LOG_LEVEL=info
ENABLE_TRACING=true

Security Considerations | 安全考虑

Item Recommendation
API Keys Store in .env, never commit to version control
Workspace Restrict to a dedicated directory
Network Use firewall rules to limit access
Dangerous Operations Keep COGITO_CONFIRM_DANGEROUS=true
Sandbox Keep COGITO_SANDBOX_MODE=true
项目 建议
API 密钥 存储在 .env 中,切勿提交到版本控制
工作区 限制在专用目录中
网络 使用防火墙规则限制访问
危险操作 保持 COGITO_CONFIRM_DANGEROUS=true
沙箱 保持 COGITO_SANDBOX_MODE=true

Deployment Checklist | 部署清单

flowchart TB
    subgraph CHECKLIST["Deployment Checklist | 部署清单"]
        C1["✅ Code pulled<br/>代码已拉取"]
        C2["✅ Dependencies installed<br/>依赖已安装"]
        C3["✅ Environment configured<br/>环境已配置"]
        C4["✅ Configuration validated<br/>配置已验证"]
        C5["✅ Workspace created<br/>工作区已创建"]
        C6["✅ Database initialized<br/>数据库已初始化"]
        C7["✅ Service started<br/>服务已启动"]
        C8["✅ Health check passed<br/>健康检查通过"]
    end

    C1 --> C2 --> C3 --> C4 --> C5 --> C6 --> C7 --> C8

    classDef checklist fill:#1a2332,stroke:#5eead4,color:#5eead4

    class C1,C2,C3,C4,C5,C6,C7,C8 checklist
Loading

Monitoring & Health | 监控与健康检查

Health Check | 健康检查

# WebSocket health endpoint | WebSocket 健康端点
curl http://localhost:9527/health

# MCP server health | MCP 服务器健康
curl http://localhost:3001/health

Logs | 日志

# Docker logs | Docker 日志
docker logs -f cogito-agent

# Native logs | 原生日志
tail -f data/logs/agent.log

Monitoring Dashboard | 监控面板

The built-in monitoring dashboard provides real-time visibility:

内置监控面板提供实时可见性:

  • Thought Chain — Real-time thinking process | 实时思考过程
  • Tool Statistics — Usage metrics | 使用指标
  • Cluster Status — Agent topology | 智能体拓扑

Troubleshooting | 故障排除

Common Issues | 常见问题

Issue Solution
Port 9527 already in use Kill the process: npx kill-port 9527
WebSocket connection failed Check firewall, verify port is open
Docker container won't start Check logs: docker logs cogito-agent
API connection timeout Verify COGITO_API_BASE_URL and network
Workspace permission denied Check volume permissions in Docker
问题 解决方案
端口 9527 已被占用 结束进程:npx kill-port 9527
WebSocket 连接失败 检查防火墙,确认端口已开放
Docker 容器无法启动 检查日志:docker logs cogito-agent
API 连接超时 验证 COGITO_API_BASE_URL 和网络
工作区权限被拒绝 检查 Docker 中的卷权限

Next Steps | 下一步


Previous: WeChat Integration →

Next: FAQ →

上一篇: 微信集成 →

下一篇: 常见问题 →

Clone this wiki locally