docs/DOCKER_DEPLOYMENT.md

# Docker 部署指南

## 📋 概述

本项目支持通过Docker容器化部署4个独立的Telegram Bot实例：
- **Tomato** (西红柿)
- **Cyrene**
- **Gold Ship** (黄金船)
- **LunaTalk Private**

每个bot都是独立的Docker容器，拥有自己的配置、日志和持久化数据。

## 🏗️ 架构设计

```
aichatbot/
├── Dockerfile                    # 共享的镜像定义
├── docker-bot.sh                # 统一管理脚本
├── run/
│   ├── tomato/
│   │   ├── docker-compose.yml   # Tomato bot配置
│   │   ├── .env.example         # 环境变量模板
│   │   ├── .env                 # 实际配置（需创建）
│   │   ├── CLAUDE.md            # 个性提示词
│   │   ├── bot.log              # Bot日志
│   │   └── debug.log            # 调试日志
│   ├── cyrene/                  # 同上结构
│   ├── gold-ship/               # 同上结构
│   └── lunatalk_private/        # 同上结构
```

## 🚀 快速开始

### 1. 配置环境变量

每个bot目录都需要创建 `.env` 文件：

```bash
# 以Tomato为例
cd run/tomato
cp .env.example .env
nano .env  # 编辑配置
```

必需的配置项：
- `ANTHROPIC_API_KEY` - Claude API密钥
- `TELEGRAM_BOT_TOKEN` - Telegram Bot Token
- `TELEGRAM_ALLOWED_USERS` - 允许的用户ID列表（JSON格式）
- `TELEGRAM_ALLOWED_GROUPS` - 允许的群组ID列表（JSON格式）

可选配置：
- `ANTHROPIC_BASE_URL` - 自定义API端点（留空使用官方API）
- `WEBHOOK_PORT` - Webhook回调端口

### 2. 使用管理脚本

项目提供了便捷的管理脚本 `docker-bot.sh`：

```bash
# 查看帮助
./docker-bot.sh help

# 启动单个bot
./docker-bot.sh start tomato

# 启动所有bot
./docker-bot.sh start all

# 停止bot
./docker-bot.sh stop tomato

# 重启bot
./docker-bot.sh restart cyrene

# 查看日志
./docker-bot.sh logs tomato

# 查看所有bot状态
./docker-bot.sh status

# 重新构建镜像
./docker-bot.sh build

# 清理Docker资源
./docker-bot.sh clean
```

### 3. 手动操作（不使用脚本）

如果你更喜欢手动操作：

```bash
# 启动单个bot
cd run/tomato
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止bot
docker-compose down

# 重启bot
docker-compose restart

# 查看容器状态
docker-compose ps
```

## 🔧 配置说明

### 环境变量详解

#### ANTHROPIC_API_KEY
Claude API密钥，从 [Anthropic Console](https://console.anthropic.com/) 获取。

**必需**

#### ANTHROPIC_BASE_URL
自定义API端点，用于：
- 使用代理服务器
- 第三方API提供商
- 自建Claude API端点

**可选**，留空使用官方API

#### TELEGRAM_BOT_TOKEN
Telegram Bot Token，从 [@BotFather](https://t.me/BotFather) 创建bot时获取。

**必需**

#### TELEGRAM_ALLOWED_USERS
允许使用bot的用户ID列表，JSON数组格式。

获取用户ID：发送消息给 [@userinfobot](https://t.me/userinfobot)

**示例**:
```bash
TELEGRAM_ALLOWED_USERS=[156318176, 123456789]
```

**必需**

#### TELEGRAM_ALLOWED_GROUPS
允许bot加入的群组ID列表，JSON数组格式。

获取群组ID：添加 [@raw_data_bot](https://t.me/raw_data_bot) 到群组

**注意**: 群组ID通常是负数

**示例**:
```bash
TELEGRAM_ALLOWED_GROUPS=[-1001074286857, -1002454076747]
```

**必需**

#### WEBHOOK_PORT
Webhook回调端口，默认值：
- Tomato: 30541
- Cyrene: 30542
- Gold Ship: 30543
- LunaTalk: 30544

**可选**

## 📊 数据持久化

每个bot使用Docker Volume持久化数据：

- **{bot}_data** - 对话历史和Agent状态
- **{bot}_sessions** - Claude SDK Sessions（V2.2必需）
- **{bot}_temp** - 临时文件

查看Volumes：
```bash
docker volume ls | grep claude-bot
```

清理特定bot的数据（⚠️ 会删除所有历史记录）：
```bash
docker volume rm claude-bot-tomato_data
docker volume rm claude-bot-tomato_sessions
```

## 🔍 故障排除

### 1. Bot无法启动

**检查 .env 文件**:
```bash
cd run/tomato
cat .env
```

确保：
- 所有必需字段已填写
- JSON格式正确（no trailing commas）
- 没有多余的空格

**查看日志**:
```bash
./docker-bot.sh logs tomato
```

### 2. API错误

**错误**: `401 Unauthorized`
- 检查 `ANTHROPIC_API_KEY` 是否正确
- 确认API密钥没有过期

**错误**: `403 Forbidden`
- 检查API额度是否充足
- 确认API密钥有正确的权限

### 3. Telegram连接失败

**检查Token**:
```bash
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
```

**检查网络**:
```bash
docker exec -it claude-bot-tomato ping -c 3 api.telegram.org
```

### 4. 端口冲突

**错误**: `address already in use`

修改 `.env` 文件中的 `WEBHOOK_PORT`：
```bash
WEBHOOK_PORT=40541  # 使用不同的端口
```

### 5. 日志文件权限错误

如果日志文件无法写入：
```bash
cd run/tomato
touch bot.log debug.log
chmod 666 bot.log debug.log
```

## 🔄 更新部署

### 更新代码

```bash
# 1. 拉取最新代码
git pull

# 2. 停止所有bot
./docker-bot.sh stop all

# 3. 重新构建镜像
./docker-bot.sh build

# 4. 启动所有bot
./docker-bot.sh start all
```

### 更新配置

修改 `.env` 文件后重启bot：
```bash
./docker-bot.sh restart tomato
```

### 更新CLAUDE.md

修改 `run/{bot}/CLAUDE.md` 后重启bot：
```bash
./docker-bot.sh restart tomato
```

## 📝 日志管理

### 查看实时日志

```bash
# 使用管理脚本
./docker-bot.sh logs tomato

# 或直接使用docker-compose
cd run/tomato
docker-compose logs -f
```

### 日志文件位置

每个bot的日志文件：
- `run/{bot}/bot.log` - Bot运行日志
- `run/{bot}/debug.log` - 详细调试日志

### 清理日志

```bash
# 清空日志文件
cd run/tomato
> bot.log
> debug.log
```

## 🔒 安全建议

1. **保护 .env 文件**
   ```bash
   chmod 600 run/*/. env
   ```

2. **不要提交敏感信息到Git**
   - `.env` 文件已在 `.gitignore` 中
   - 只提交 `.env.example`

3. **定期更新依赖**
   ```bash
   # 更新基础镜像
   docker pull python:3.12-slim

   # 重新构建
   ./docker-bot.sh build
   ```

4. **使用最小权限**
   - 只授权必要的用户ID
   - 只授权必要的群组ID

5. **监控API使用**
   - 定期检查 [Anthropic Console](https://console.anthropic.com/)
   - 设置使用限额

## 🌐 网络配置

每个bot使用独立的Docker网络：
- `claude-bot-tomato`
- `claude-bot-cyrene`
- `claude-bot-goldship`
- `claude-bot-lunatalk`

这确保了bot之间的隔离。

## 💡 最佳实践

1. **分阶段部署**
   ```bash
   # 先测试单个bot
   ./docker-bot.sh start tomato

   # 确认正常后再启动其他
   ./docker-bot.sh start all
   ```

2. **监控资源使用**
   ```bash
   docker stats claude-bot-tomato
   ```

3. **定期备份数据**
   ```bash
   # 备份Volume
   docker run --rm -v claude-bot-tomato_data:/data \
     -v $(pwd):/backup alpine \
     tar czf /backup/tomato-backup.tar.gz -C /data .
   ```

4. **使用健康检查**
   - 每个bot都配置了健康检查
   - 不健康时Docker会自动重启

5. **日志轮转**
   ```bash
   # 配置logrotate
   sudo nano /etc/logrotate.d/claude-bot
   ```

## 🔗 相关文档

- [项目主文档](../../README.md)
- [V2.2 技术设计](../../docs/technical-design/)
- [Telegram Bot配置](../../docs/telegram-bot-setup.md)

## ❓ 常见问题

**Q: 可以在同一台机器上运行多个bot吗？**
A: 可以，每个bot是独立容器，使用不同的端口和网络。

**Q: 数据存储在哪里？**
A: 使用Docker Volume持久化存储，位置由Docker管理。

**Q: 如何迁移bot到另一台服务器？**
A: 导出Volume数据，传输到新服务器，导入Volume即可。

**Q: Bot重启后会丢失对话历史吗？**
A: 不会，对话历史持久化在Docker Volume中。

**Q: 可以使用自己的API代理吗？**
A: 可以，设置 `ANTHROPIC_BASE_URL` 环境变量。

---

**维护者**: Rivoreo AutoPilot
**最后更新**: 2025-12-11