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 文件：

# 以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：

# 查看帮助
./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. 手动操作（不使用脚本）

如果你更喜欢手动操作：

# 启动单个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 获取。

必需

ANTHROPIC_BASE_URL

自定义API端点，用于：

• 使用代理服务器
• 第三方API提供商
• 自建Claude API端点

可选，留空使用官方API

TELEGRAM_BOT_TOKEN

Telegram Bot Token，从 @BotFather 创建bot时获取。

必需

TELEGRAM_ALLOWED_USERS

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

获取用户ID：发送消息给 @userinfobot

示例:

TELEGRAM_ALLOWED_USERS=[156318176, 123456789]

必需

TELEGRAM_ALLOWED_GROUPS

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

获取群组ID：添加 @raw_data_bot 到群组

注意: 群组ID通常是负数

示例:

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：

docker volume ls | grep claude-bot

清理特定bot的数据（⚠️ 会删除所有历史记录）：

docker volume rm claude-bot-tomato_data
docker volume rm claude-bot-tomato_sessions

🔍 故障排除

1. Bot无法启动

检查 .env 文件:

cd run/tomato
cat .env

确保：

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

查看日志:

./docker-bot.sh logs tomato

2. API错误

错误: 401 Unauthorized

• 检查 ANTHROPIC_API_KEY 是否正确
• 确认API密钥没有过期

错误: 403 Forbidden

• 检查API额度是否充足
• 确认API密钥有正确的权限

3. Telegram连接失败

检查Token:

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

检查网络:

docker exec -it claude-bot-tomato ping -c 3 api.telegram.org

4. 端口冲突

错误: address already in use

修改 .env 文件中的 WEBHOOK_PORT：

WEBHOOK_PORT=40541  # 使用不同的端口

5. 日志文件权限错误

如果日志文件无法写入：

cd run/tomato
touch bot.log debug.log
chmod 666 bot.log debug.log

🔄 更新部署

更新代码

# 1. 拉取最新代码
git pull

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

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

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

更新配置

修改 .env 文件后重启bot：

./docker-bot.sh restart tomato

更新CLAUDE.md

修改 run/{bot}/CLAUDE.md 后重启bot：

./docker-bot.sh restart tomato

📝 日志管理

查看实时日志

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

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

日志文件位置

每个bot的日志文件：

• run/{bot}/bot.log - Bot运行日志
• run/{bot}/debug.log - 详细调试日志

清理日志

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

🔒 安全建议

1. 保护 .env 文件

   chmod 600 run/*/. env
   

2. 不要提交敏感信息到Git

   • .env 文件已在 .gitignore 中
   • 只提交 .env.example

3. 定期更新依赖

   # 更新基础镜像
   docker pull python:3.12-slim
   
   # 重新构建
   ./docker-bot.sh build
   

4. 使用最小权限

   • 只授权必要的用户ID
   • 只授权必要的群组ID

5. 监控API使用

   • 定期检查 Anthropic Console
   • 设置使用限额

🌐 网络配置

每个bot使用独立的Docker网络：

• claude-bot-tomato
• claude-bot-cyrene
• claude-bot-goldship
• claude-bot-lunatalk

这确保了bot之间的隔离。

💡 最佳实践

1. 分阶段部署

   # 先测试单个bot
   ./docker-bot.sh start tomato
   
   # 确认正常后再启动其他
   ./docker-bot.sh start all
   

2. 监控资源使用

   docker stats claude-bot-tomato
   

3. 定期备份数据

   # 备份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. 日志轮转

   # 配置logrotate
   sudo nano /etc/logrotate.d/claude-bot
   

🔗 相关文档

• 项目主文档
• V2.2 技术设计
• Telegram Bot配置

❓ 常见问题

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