部署到服务器

v2 中所有组件运行在同一 Python 进程中，部署得到极大简化。

环境变量配置

复制 .env.example 到 .env，配置以下关键项：

# LLM 配置（必填）
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-v4-flash

# 认证（必填，生产环境必须修改默认值）
WEB_PASSWORD=your-strong-admin-password
JWT_SECRET=your-random-256bit-secret
JWT_EXPIRE_MINUTES=480
API_KEY=your-api-key-for-external-access

# 工作目录（可选，默认项目根目录）
COCOCAT_WORKSPACE=/opt/cococat

# 安全
EXEC_COMMAND_ALLOWED_MODES=WORKSPACE_WRITE,FULL_ACCESS
LINUX_NAMESPACE_SANDBOX=false
LINUX_NETWORK_ISOLATION=false

认证配置说明

变量	用途	安全要求
WEB_PASSWORD	Web 面板登录密码	至少 12 位，含特殊字符
JWT_SECRET	JWT Token 签名密钥	随机 32 字节以上，可用 openssl rand -hex 32 生成
API_KEY	外部服务访问 API Key	随机字符串，用于自动化集成

启动应用

v2 中 FastAPI 后端和 Agent 运行时在同一进程中，使用 gunicorn + uvicorn 启动：

# 安装生产依赖
pip install gunicorn uvicorn

# 启动（推荐 4 workers）
gunicorn cococat.app:app \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000 \
  --timeout 120 \
  --access-logfile /var/log/cococat/access.log \
  --error-logfile /var/log/cococat/error.log

Nginx 反向代理

server {
    listen 443 ssl;
    server_name cococat.example.com;

    ssl_certificate /etc/ssl/certs/cococat.crt;
    ssl_certificate_key /etc/ssl/private/cococat.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

构建 Web 前端

cd web-ui
npm install
npm run build
# 构建产物在 web-ui/dist/

将 dist/ 目录配置为 FastAPI 的静态文件目录，或通过 Nginx 直接 serve。

使用 systemd 管理

[Unit]
Description=CocoCat Server
After=network.target

[Service]
Type=simple
User=cococat
WorkingDirectory=/opt/cococat
EnvironmentFile=/opt/cococat/.env
ExecStart=/opt/cococat/.venv/bin/gunicorn cococat.app:app \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000
Restart=always
RestartSec=10
StandardOutput=append:/var/log/cococat/server.log
StandardError=append:/var/log/cococat/server.log

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable cococat
sudo systemctl start cococat

服务启动顺序

v2 中仅需单个服务：

1. CocoCat 主进程 — FastAPI 后端 + Agent 运行时（包含 AgentPool、EventBus、Heartbeat 等所有子系统）

安全性检查清单

• [ ] JWT_SECRET 使用随机生成，非默认值
• [ ] WEB_PASSWORD 强度足够
• [ ] 生产环境禁用 --reload
• [ ] 使用 HTTPS（Nginx + Let's Encrypt）
• [ ] 限制 API 访问来源 IP
• [ ] Linux namespace 隔离开启（如需）
• [ ] 日志轮转配置
• [ ] 定期备份 agents/ 和 chat/ 目录