Repository navigation
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 部署、生产环境配置和开发环境设置。选择最适合您环境的方式。
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
Docker deployment is the recommended approach for production environments and server deployments.
Docker 部署是生产环境和服务器部署的推荐方式。
-
Docker Engine 20.10+
-
Docker Compose v2.0+
-
Minimum 2GB available RAM
-
Docker Engine 20.10+
-
Docker Compose v2.0+
-
最低 2GB 可用内存
# 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 psversion: '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| 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 |
思考间隔(毫秒) |
# 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:latestFor direct installation on bare metal or virtual machines.
用于直接在物理机或虚拟机上安装。
# 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# 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# For headless servers | 无头服务器
npm run cli
# With WebSocket enabled | 启用 WebSocket
COGITO_MODE=dashboard npm run electronFor developers who want to contribute or customize CogitoAgent.
适用于希望贡献或自定义 CogitoAgent 的开发者。
# 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| 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 应用 |
# Check types without emitting | 检查类型但不输出
npm run typecheck
# Watch mode | 监听模式
npx tsc --noEmit --watch# .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| 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
|
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
# WebSocket health endpoint | WebSocket 健康端点
curl http://localhost:9527/health
# MCP server health | MCP 服务器健康
curl http://localhost:3001/health# Docker logs | Docker 日志
docker logs -f cogito-agent
# Native logs | 原生日志
tail -f data/logs/agent.logThe built-in monitoring dashboard provides real-time visibility:
内置监控面板提供实时可见性:
- Thought Chain — Real-time thinking process | 实时思考过程
- Tool Statistics — Usage metrics | 使用指标
- Cluster Status — Agent topology | 智能体拓扑
| 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 中的卷权限 |
-
FAQ — Common questions and answers
-
Development Guide — Contributing to CogitoAgent
-
常见问题 — 常见问题与解答
-
开发指南 — 为 CogitoAgent 做贡献
Previous: WeChat Integration →
Next: FAQ →
上一篇: 微信集成 →
下一篇: 常见问题 →