# 🚀 Moltbot GitHub 部署指南

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

## 📋 目录

- [为什么选择 GitHub 部署？](#为什么选择-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. **测试连接**：
   ```bash
   ./moltbot.mjs status
   ./moltbot.mjs agent "你好，请介绍一下你自己"
   ```

---

### 方式 2：通过 GitHub CLI 创建

#### 步骤 1：安装 GitHub CLI

```bash
# macOS
brew install gh

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

# Windows
winget install GitHub.cli
```

#### 步骤 2：认证

```bash
gh auth login
```

#### 步骤 3：创建 Codespace

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

#### 步骤 4：等待初始化完成

```bash
# 查看 Codespace 状态
gh codespace list

# 查看 Codespace 日志
gh codespace logs
```

---

## 详细配置

### Codespaces 配置文件

#### 1. `.devcontainer/devcontainer.json`

定义开发环境配置：

```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 服务定义：

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

### 配置 Gateway

在 Codespace 中的配置文件位置：

```bash
/root/.moltbot/moltbot.json
```

默认配置：

```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 客户端

在你的本地机器上配置：

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

### 方式 4：GitHub Actions CLI

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

# 查看状态
gh run list

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

---

## 自动化维护

### GitHub Actions 工作流

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

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

**功能：**
- ✅ 检查 Gateway 配置
- ✅ 验证服务状态
- ✅ 生成状态报告

#### 2. 自动备份 Memory

**功能：**
- ✅ 导出 LanceDB 数据库
- ✅ 上传到 GitHub Artifacts
- ✅ 保留 30 天

#### 3. 自动重启（可选）

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

### 监控和日志

#### 查看 Gateway 日志

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

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

#### 查看 Ollama 日志

```bash
tail -f /tmp/ollama.log
```

#### 检查服务状态

```bash
# 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：
   ```bash
   gh codespace list
   gh codespace delete <codespace-name>
   ```

### 问题 2：Ollama 模型下载失败

**症状：**
```
Error: Failed to pull ollama model
```

**解决方案：**

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

# 或使用小模型
ollama pull phi3
```

### 问题 3：Gateway 无法启动

**症状：**
```
Error: Gateway failed to start
```

**解决方案：**

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

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

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

### 问题 4：内存不足

**症状：**
```
Error: Cannot allocate memory
```

**解决方案：**

1. **使用较小的模型**：
   ```bash
   ollama pull phi3  # 4GB
   ollama pull gemma2:2b  # 2GB
   ```

2. **增加 Codespace 配额**：
   - GitHub 设置 → Billing
   - 增加 Codespace 配额

3. **优化配置**：
   ```json
   {
     "agents": {
       "defaults": {
         "maxConcurrent": 2  // 减少并发数
       }
     }
   }
   ```

### 问题 5：端口转发不工作

**症状：**
```
Cannot access forwarded port
```

**解决方案：**

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

---

## 最佳实践

### 1. 成本优化

**减少 Codespace 使用时间：**

```bash
# 不使用时停止 Codespace
gh codespace stop

# 需要时再启动
gh codespace start
```

### 2. 数据持久化

**重要数据备份：**

```bash
# 备份配置
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：**

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

### 4. 监控和告警

**设置 GitHub Actions 通知：**

```yaml
# .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. 开发工作流

**推荐的工作流：**

```bash
# 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. **更新配置**：
   ```json
   {
     "gateway": {
       "bind": "moltbot.yourdomain.com"
     }
   }
   ```

### 集成其他服务

#### 1. Telegram Bot

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

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

#### 2. GitHub 集成

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

#### 3. Slack 集成

```bash
# 配置 Slack Webhook
# 接收 Gateway 通知
```

### 性能优化

#### 1. 模型量化

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

#### 2. 批处理

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

#### 3. 缓存优化

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

---

## 与本地开发结合

### 混合架构

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

### 代码同步

```bash
# 本地开发
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 运行历史：

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

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

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

### Codespace 监控

```bash
# 查看 Codespace 状态
gh codespace view

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

# 停止 Codespace
gh codespace stop

# 删除 Codespace
gh codespace delete
```

### 日志管理

```bash
# 日志位置
/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
**维护者**: 开发团队