openclaw/.github/GITHUB-DEPLOY.md

🚀 Moltbot GitHub 部署指南

在 GitHub Codespaces 上运行你的私人 AI Assistant，随时随地访问！

📋 目录

• 为什么选择 GitHub 部署？
• 架构概述
• 快速开始
• 详细配置
• 访问方式
• 自动化维护
• 故障排除
• 最佳实践

---

为什么选择 GitHub 部署？

✅ 优势

特性	GitHub Codespaces	自建服务器
成本	每月免费额度（60小时）	需要购买服务器
维护	零维护	需要运维
可访问性	任何有浏览器的地方	需要 VPN/公网 IP
开发环境	完整 VS Code	需要本地配置
协作	即时分享	需要配置
备份	自动集成 Git	需要手动备份

💰 成本

• 免费额度: 60 小时/月
• 超时后: $0.18/小时
• 推荐: 日常开发完全够用

---

架构概述

┌─────────────────────────────────────────────────────────────────────┐
│                    GitHub 部署架构                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐ │
│   │           GitHub Codespaces (云端环境)                        │ │
│   │  ┌──────────────────────────────────────────────────────────┐ │ │
│   │  │  Moltbot Gateway (持续运行)                             │ │ │
│   │  │  ─────────────────────────────────────────────────────   │ │ │
│   │  │  • Node.js v22 + pnpm                                  │ │ │
│   │  │  • Ollama (本地 LLM)                                    │ │ │
│   │  │  │   - llama3.3 (主模型)                               │ │ │
│   │  │  │   - deepseek-coder (代码助手)                       │ │ │
│   │  │  │   - nomic-embed-text (embeddings)                   │ │ │
│   │  │  • Memory Plugin (LanceDB)                             │ │ │
│   │  │  • WebSocket Server (18789)                            │ │ │
│   │  │  • 所有开发插件                                         │ │ │
│   │  └──────────────────────────────────────────────────────────┘ │ │
│   │                                                             │ │
│   │  硬件配置:                                                   │ │
│   │  • 4 核 CPU                                                │ │
│   │  • 8 GB RAM                                                │ │
│   │  • 32 GB 存储                                              │ │
│   │                                                             │ │
│   └─────────────────────────────────────────────────────────────┘ │
│                              ▲                                      │
│                              │                                      │
│                  ┌───────────────┴──────────────────┐              │
│                  │   GitHub Port Forwarding    │              │
│                  │   (Codespaces → Internet)   │              │
│                  └───────────────────────────────┘              │
│                              │                                      │
│         ┌──────────────────────┬──────────────────┐              │
│         ▼                      ▼                  ▼              │
│  ┌─────────────┐      ┌─────────────┐   ┌─────────────┐     │
│  │ VS Code     │      │ 浏览器      │   │ GitHub CLI  │     │
│  │ (本地连接)  │      │ WebChat     │   │ (命令行)    │     │
│  │             │      │             │   │             │     │
│  │ • 编辑代码   │      │ • 对话      │   │ • gh ci run │     │
│  │ • 调试       │      │ • 测试       │   │ • 管理任务   │     │
│  │ • 终端       │      │ • 监控       │   │             │     │
│  └─────────────┘      └─────────────┘   └─────────────┘     │
│                                                                     │
│   ┌─────────────────────────────────────────────────────────────┐ │
│   │        GitHub Actions (自动化)                                │ │
│   │  ────────────────────────────────────────────────────────   │ │
│   │  • 自动部署                                                │ │
│   │  • 每日健康检查                                              │ │
│   │  • Memory 自动备份                                          │ │
│   │  • 定时重启                                                │ │
│   │  • 监控报告                                                │ │
│   └─────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

快速开始

方式 1：通过 GitHub 网页创建（推荐）

步骤 1：创建 Codespace

1. 访问你的仓库：https://github.com/你的用户名/moltbot
2. 点击绿色的 "Code" 按钮
3. 选择 "Codespaces" 标签
4. 点击 "Create codespace on main"
5. 等待环境创建（约 2-3 分钟）

步骤 2：自动初始化

Codespace 创建后会自动运行：

• ✅ 安装 Node.js 和 pnpm
• ✅ 安装 Ollama
• ✅ 拉取 LLM 模型（llama3.3, deepseek-coder, nomic-embed-text）
• ✅ 配置 Moltbot
• ✅ 构建项目
• ✅ 启动 Gateway

步骤 3：访问 Gateway

创建完成后：

1. 查看日志：

   • 在 Codespace 终端运行：tail -f /tmp/moltbot.log

2. 配置端口转发：

   • 点击 Codespace 界面的 "Ports" 标签
   • 添加端口：18789
   • 点击转发地址访问 WebChat

3. 测试连接：

   ./moltbot.mjs status
   ./moltbot.mjs agent "你好，请介绍一下你自己"
   

---

方式 2：通过 GitHub CLI 创建

步骤 1：安装 GitHub CLI

# macOS
brew install gh

# Linux
sudo apt install gh
# 或下载: https://github.com/cli/cli/releases

# Windows
winget install GitHub.cli

步骤 2：认证

gh auth login

步骤 3：创建 Codespace

gh codespace create \
  --repo 你的用户名/moltbot \
  --branch main \
  --machine standard-4cores-linux-x64 \
  --display-name "Moltbot Gateway"

步骤 4：等待初始化完成

# 查看 Codespace 状态
gh codespace list

# 查看 Codespace 日志
gh codespace logs

---

详细配置

Codespaces 配置文件

1. .devcontainer/devcontainer.json

定义开发环境配置：

{
  "name": "Moltbot Gateway",
  "dockerComposeFile": "docker-compose.yml",
  "service": "moltbot",

  // 资源要求
  "hostRequirements": {
    "cpus": 4,        // 4 核 CPU
    "memory": "8gb",   // 8 GB RAM
    "storage": "32gb"  // 32 GB 存储
  },

  // 端口转发
  "forwardPorts": [18789, 18791, 11434],

  // 端口属性
  "portsAttributes": {
    "18789": {
      "label": "Gateway WebSocket",
      "onAutoForward": "openBrowser"  // 自动打开浏览器
    }
  },

  // 自动运行脚本
  "postCreateCommand": "bash .devcontainer/post-create.sh"
}

2. .devcontainer/post-create.sh

初始化脚本会自动执行：

1. 安装 Ollama
2. 拉取 LLM 模型
3. 配置 Moltbot
4. 构建项目
5. 启动 Gateway

3. .devcontainer/docker-compose.yml

Docker 服务定义：

services:
  moltbot:
    volumes:
      # 持久化数据
      - moltbot-data:/root/.clawdbot
      - moltbot-memory:/root/.clawdbot/memory

配置 Gateway

在 Codespace 中的配置文件位置：

/root/.moltbot/moltbot.json

默认配置：

{
  "gateway": {
    "mode": "local",
    "bind": "0.0.0.0",  // 绑定所有接口（可外部访问）
    "auth": {
      "token": "github-codespaces-token"
    }
  },

  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434"
      }
    }
  },

  "plugins": {
    "entries": {
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "ollama",
            "model": "nomic-embed-text"
          }
        }
      }
    }
  }
}

---

访问方式

方式 1：浏览器 WebChat（推荐）

1. 打开你的 Codespace
2. 点击 "Ports" 标签
3. 找到 18789 端口
4. 点击转发地址（通常是一个 github.dev URL）
5. 开始对话！

方式 2：VS Code 连接

1. 在 VS Code 中安装 "Remote - SSH" 扩展
2. 连接到 Codespace
3. 打开集成终端
4. 运行命令：
   ./moltbot.mjs agent "消息"

方式 3：本地 CLI 客户端

在你的本地机器上配置：

// ~/.clawdbot/moltbot.json
{
  "gateway": {
    "mode": "remote",
    "remote": {
      "url": "wss://<codespace-name>-18789.github.dev",
      "token": "github-codespaces-token"
    }
  }
}

方式 4：GitHub Actions CLI

# 触发健康检查
gh workflow run github-deploy.yml -f health-check

# 查看状态
gh run list

# 查看日志
gh run view <run-id>

---

自动化维护

GitHub Actions 工作流

1. 自动健康检查（每天 UTC 2:00）

on:
  schedule:
    - cron: '0 2 * * *'  # 每天执行

功能：

• ✅ 检查 Gateway 配置
• ✅ 验证服务状态
• ✅ 生成状态报告

2. 自动备份 Memory

功能：

• ✅ 导出 LanceDB 数据库
• ✅ 上传到 GitHub Artifacts
• ✅ 保留 30 天

3. 自动重启（可选）

# 手动触发
gh workflow run github-deploy.yml -f restart-gateway

监控和日志

查看 Gateway 日志

# 在 Codespace 终端
tail -f /tmp/moltbot.log

# 查看最近 100 行
tail -n 100 /tmp/moltbot.log

查看 Ollama 日志

tail -f /tmp/ollama.log

检查服务状态

# Gateway 状态
./moltbot.mjs status

# 会话列表
./moltbot.mjs sessions

# Memory 统计
./moltbot.mjs ltm stats

---

故障排除

问题 1：Codespace 创建失败

症状：

Error: Failed to create codespace

解决方案：

1. 检查 GitHub 账号权限
2. 确认没有超过 Codespace 限制
3. 尝试删除旧的 Codespace：

   gh codespace list
   gh codespace delete <codespace-name>
   

问题 2：Ollama 模型下载失败

症状：

Error: Failed to pull ollama model

解决方案：

# 手动下载模型
ollama pull llama3.3

# 或使用小模型
ollama pull phi3

问题 3：Gateway 无法启动

症状：

Error: Gateway failed to start

解决方案：

# 检查端口占用
netstat -tlnp | grep 18789

# 杀死占用进程
pkill -f moltbot.mjs

# 重新启动
/root/start-gateway.sh

问题 4：内存不足

症状：

Error: Cannot allocate memory

解决方案：

1. 使用较小的模型：

   ollama pull phi3  # 4GB
   ollama pull gemma2:2b  # 2GB
   

2. 增加 Codespace 配额：

   • GitHub 设置 → Billing
   • 增加 Codespace 配额

3. 优化配置：

   {
     "agents": {
       "defaults": {
         "maxConcurrent": 2  // 减少并发数
       }
     }
   }
   

问题 5：端口转发不工作

症状：

Cannot access forwarded port

解决方案：

1. 检查 Codespace 是否正在运行
2. 重新配置端口转发
3. 使用 GitHub CLI 连接：

   gh codespace view --web
   

---

最佳实践

1. 成本优化

减少 Codespace 使用时间：

# 不使用时停止 Codespace
gh codespace stop

# 需要时再启动
gh codespace start

2. 数据持久化

重要数据备份：

# 备份配置
cp /root/.moltbot/moltbot.json ~/backup/

# 备份 Memory
tar -czf ~/backup/memory-$(date +%Y%m%d).tar.gz ~/.clawdbot/memory/

# 下载备份到本地
gh codespace download backup.tar.gz

3. 安全配置

保护你的 Gateway：

{
  "gateway": {
    "auth": {
      "token": "生成一个强密码",
      "allowTailscale": false  // 仅 GitHub 登录
    }
  }
}

4. 监控和告警

设置 GitHub Actions 通知：

# .github/workflows/notifications.yml
name: Notifications
on:
  workflow_run:
    workflows: ["github-deploy.yml"]
    types: [completed]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Send notification
        run: |
          echo "Gateway health check completed"          

5. 开发工作流

推荐的工作流：

# 1. 本地开发
git clone <repo>
cd moltbot

# 2. 提交更改
git add .
git commit -m "feat: new feature"
git push

# 3. 自动部署到 Codespace
# GitHub Actions 自动触发

# 4. 在 Codespace 中测试
gh codespace view --web

# 5. 验证后合并到 main
git checkout main
git merge feature-branch
git push

---

高级配置

自定义域名

你可以使用自己的域名访问 Gateway：

1. 设置 CNAME：

   moltbot.yourdomain.com CNAME <codespace-name>.github.dev
   

2. 更新配置：

   {
     "gateway": {
       "bind": "moltbot.yourdomain.com"
     }
   }
   

集成其他服务

1. Telegram Bot

# 在 Codespace 中配置 Telegram Bot Token
# 编辑 ~/.moltbot/moltbot.json

# 重启 Gateway
/root/start-gateway.sh

2. GitHub 集成

# 使用 GitHub 作为 Memory 存储
# 配置 GitHub Actions 自动备份

3. Slack 集成

# 配置 Slack Webhook
# 接收 Gateway 通知

性能优化

1. 模型量化

# 使用量化版本
ollama pull llama3.3:q4_0

2. 批处理

# 批量处理请求
./moltbot.mjs agent --batch <<EOF
{"message": "消息1"}
{"message": "消息2"}
{"message": "消息3"}
EOF

3. 缓存优化

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      }
    }
  }
}

---

与本地开发结合

混合架构

┌─────────────────────────────────────────────────────────────────────┐
│                      混合开发架构                                    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   GitHub Codespaces                  本地开发机                   │
│   ┌─────────────────────┐         ┌─────────────────────┐          │
│   │  Gateway (生产)       │         │  Gateway (测试)       │          │
│   │  - 稳定运行          │         │  - 快速测试           │          │
│   │  - 24/7 可用         │         │  - 离线开发           │          │
│   │  - 远程访问          │         │  - 本地调试           │          │
│   └─────────────────────┘         └─────────────────────┘          │
│             ▲                              ▲                         │
│             │                              │                         │
│             │              同步代码和配置                       │
│             └──────────────────────┬───────────────────────┘         │
│                                │                                 │
│                        Git Push / Pull                               │
│                                                                     │
│   工作流：                                                          │
│   1. 本地开发新功能                                                 │
│   2. 本地测试                                                     │
│   3. 推送到 GitHub                                                │
│   4. 自动部署到 Codespace                                        │
│   5. 远程 Gateway 更新                                            │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

代码同步

# 本地开发
cd /path/to/moltbot
# 开发新功能
git add .
git commit -m "feat: new feature"
git push origin main

# Codespace 自动更新
# 或手动在 Codespace 中
cd /workspace
git pull
pnpm build
/root/start-gateway.sh

---

监控和日志

GitHub Actions 监控

查看 Actions 运行历史：

# 列出运行历史
gh run list --workflow=github-deploy.yml

# 查看特定运行
gh run view <run-id>

# 下载日志
gh run download <run-id>

Codespace 监控

# 查看 Codespace 状态
gh codespace view

# 查看资源使用
gh codespace view --json | jq '.resource'

# 停止 Codespace
gh codespace stop

# 删除 Codespace
gh codespace delete

日志管理

# 日志位置
/tmp/moltbot.log        # Gateway 日志
/tmp/ollama.log         # Ollama 日志
~/.pm2/logs/            # PM2 日志（如果使用）

# 查看实时日志
tail -f /tmp/moltbot.log

# 搜索错误
grep -i error /tmp/moltbot.log

---

成本和限制

免费额度

资源	免费额度	超出后费用
存储	32 GB	$0.08/GB/月
计算	60 小时/月	$0.18/小时
带宽	包含在内	无额外费用

使用估算

日常开发使用：

• 每天 8 小时 × 22 天 = 176 小时
• 超出免费额度：116 小时
• 额外成本：116 × $0.18 = $20.88/月

成本优化技巧：

1. 不使用时停止 Codespace
2. 使用 smaller 机型（2 核）
3. 避免空闲运行

---

总结

GitHub Codespaces 部署的优势

特性	说明
✅ 零配置	创建即用，无需手动配置环境
✅ 随时随地	任何有浏览器的地方都能访问
✅ 自动备份	集成 Git，自动版本控制
✅ 团队协作	即时分享和协作
✅ 免费额度	每月 60 小时免费
✅ 自动化	GitHub Actions 自动维护

适用场景

• ✅ 个人开发者 - 无服务器，快速部署
• ✅ 团队协作 - 共享开发环境
• ✅ 演示展示 - 向客户展示功能
• ✅ 临时项目 - 短期测试和验证
• ✅ 学习研究 - 学习 AI 和 LLM 集成

不适用场景

• ❌ 大规模生产 - 需要更高性能
• ❌ 24/7 运行 - 成本较高
• ❌ 数据敏感 - 需要本地存储

---

相关文档

• QUICKSTART.md - 快速上手指南
• DEVELOPMENT-SETUP.md - 完整架构指南
• TEAM.md - 团队成员参考

---

文档版本: 1.0 最后更新: 2025-01-30 维护者: 开发团队