huihuiSquare/DEPLOYMENT.md

# 会会虚拟用户 AI 互动系统 - 部署与使用指南

## 一、项目概述

本项目是一个基于 AI 大模型的虚拟用户自动化互动系统，主要功能包括：

### 核心功能
1. **虚拟用户管理** - 批量生成、Excel 导入、人格配置
2. **AI 内容生成** - 支持 OpenAI、智谱等主流大模型
3. **自动化互动** - 评论、回复、点赞、收藏、转发
4. **定时任务调度** - 随机时间、活跃度控制、限额管理
5. **数据可视化** - 控制台仪表盘、Token 消耗统计

## 二、快速部署

### 方法一：一键启动脚本（推荐）

```bash
# 进入项目目录
cd /Users/yqq/Works/Projects/会会广场机器人

# 执行启动脚本
./start.sh
```

脚本会自动完成：
- 检查 Docker 环境
- 创建必要目录
- 配置文件初始化
- 启动所有服务

### 方法二：手动 Docker Compose 部署

```bash
# 1. 配置环境变量
cd backend
cp .env.example .env
# 编辑 .env 文件，配置 AI 模型 API Key

# 2. 启动服务
cd ..
docker-compose up -d

# 3. 查看日志
docker-compose logs -f backend

# 4. 访问服务
# 前端：http://localhost
# 后端 API: http://localhost:8000
# API 文档：http://localhost:8000/docs
```

## 三、配置说明

### 1. 环境变量配置（backend/.env）

```bash
# 必选：AI 模型配置（至少配置一个）
OPENAI_API_KEY=sk-your-api-key-here
# 或
ZHIPU_API_KEY=your-zhipu-api-key-here

# 可选：调整系统限制
MAX_TOKENS_PER_DAY=10000          # 每日 Token 上限
MAX_COMMENTS_PER_USER_PER_DAY=20  # 单用户日评论上限
TASK_START_HOUR=9                 # 活动开始时间
TASK_END_HOUR=22                  # 活动结束时间
```

### 2. 数据库配置

默认配置即可，Docker Compose 会自动创建 MySQL 容器：
- 主机：mysql
- 端口：3306
- 用户：huihui_user
- 密码：huihui_password
- 数据库：huihui_ai_bot

### 3. 会会接口配置

默认已配置为：`http://192.168.1.200:63120`

如需修改，在 `.env` 文件中调整：
```bash
HUIHUI_API_BASE=http://your-huihui-api-address
```

## 四、使用流程

### 第一步：AI 模型配置

1. 访问前端界面：http://localhost
2. 进入"AI 模型配置"页面
3. 点击"添加模型"
4. 选择提供商（OpenAI / 智谱等）
5. 填写 API Key 和其他参数
6. 点击"测试"验证配置
7. 设为默认模型

**支持的 AI 模型：**
- OpenAI: gpt-3.5-turbo, gpt-4
- 智谱 AI: glm-4
- 百度文心：ERNIE-Bot（待实现）
- 阿里通义：Qwen（待实现）

### 第二步：虚拟用户管理

#### 方式一：批量生成

1. 进入"虚拟用户管理"页面
2. 点击"批量生成"
3. 设置生成数量（1-100）
4. 选择写作风格（可不选，随机分配）
5. 选择活跃度级别
6. 勾选"AI 人格描述"（推荐）
7. 点击"生成"

#### 方式二：Excel 导入

准备 Excel 文件，包含以下列：
- `username`（必填）- 用户名/账号
- `password`（必填）- 密码
- `nickname`（可选）- 昵称
- `writing_style`（可选）- 写作风格
- `activity_level`（可选）- 活跃度（low/medium/high）

导入步骤：
1. 点击"Excel 导入"
2. 选择 Excel 文件
3. 勾选"生成 AI 人格描述"
4. 确认导入

### 第三步：系统设置

1. 进入"系统设置"页面
2. 配置活动时间段（如 9:00-22:00）
3. 配置互动频率（如 10-30 分钟）
4. 配置限额（Token 上限、评论上限等）
5. 保存配置

### 第四步：启动定时任务

1. 在"系统设置"页面
2. 点击"启动任务"按钮
3. 系统开始自动执行互动任务

### 第五步：监控与调整

1. **控制台** - 查看实时统计数据
   - 虚拟用户总数
   - 今日互动次数
   - Token 消耗情况
   - 最近互动记录

2. **互动记录** - 查看详细执行日志
   - 成功/失败状态
   - Token 消耗
   - 错误信息

3. **调整策略**
   - 根据 Token 消耗调整互动频率
   - 根据效果调整写作风格
   - 根据需求调整限额配置

## 五、高级配置

### 1. 自定义写作风格

在生成虚拟用户时，可以指定写作风格：
- 幽默风趣
- 严肃理性
- 文艺清新
- 吐槽犀利
- 感性温暖
- 客观中立
- 激情澎湃
- 冷静分析
- 活泼可爱
- 深沉内敛

也可在 `.env` 中添加自定义风格。

### 2. 活跃度分级

- **高活跃度**：每日互动 5-10 次（80% 概率执行）
- **中活跃度**：每日互动 2-5 次（50% 概率执行）
- **低活跃度**：每日互动 1-2 次（30% 概率执行）

### 3. 互动概率配置

默认概率：
- 点赞：80%
- 收藏：50%
- 转发：30%
- 评论：剩余概率

可在"系统设置"页面调整。

### 4. Token 限额策略

建议配置：
- 开发测试：1000-5000 tokens/天
- 小规模使用：5000-20000 tokens/天
- 大规模使用：20000+ tokens/天

根据实际 AI 模型价格计算成本。

## 六、运维管理

### 查看日志

```bash
# 查看所有服务日志
docker-compose logs -f

# 查看后端日志
docker-compose logs -f backend

# 查看数据库日志
docker-compose logs -f mysql

# 查看最近 100 行
docker-compose logs --tail=100 backend
```

### 备份数据

```bash
# 备份 MySQL 数据库
docker exec huihui_mysql mysqldump -uhuihui_user -phuihui_password huihui_ai_bot > backup_$(date +%Y%m%d).sql

# 恢复数据库
docker exec -i huihui_mysql mysql -uhuihui_user -phuihui_password huihui_ai_bot < backup_20260323.sql
```

### 服务重启

```bash
# 重启所有服务
docker-compose restart

# 重启单个服务
docker-compose restart backend

# 停止所有服务
docker-compose down

# 停止并删除容器（保留数据）
docker-compose down

# 完全清理（删除数据和容器）
docker-compose down -v
```

### 更新升级

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

# 重新构建并启动
docker-compose build
docker-compose up -d
```

## 七、故障排查

### 1. 后端服务无法启动

```bash
# 查看日志
docker-compose logs backend

# 常见问题：
# - 数据库连接失败：检查 MySQL 是否启动
# - 端口冲突：修改 docker-compose.yml 中的端口映射
# - 环境变量错误：检查 .env 文件格式
```

### 2. 数据库连接失败

```bash
# 检查 MySQL 容器状态
docker-compose ps mysql

# 查看 MySQL 日志
docker-compose logs mysql

# 手动连接测试
docker exec -it huihui_mysql mysql -uroot -proot123456
```

### 3. AI 模型调用失败

- 检查 API Key 是否正确
- 检查网络连接
- 查看 Token 余额
- 检查 API 地址是否正确
- 查看后端日志中的详细错误信息

### 4. 定时任务未执行

- 检查调度器状态（系统设置页面）
- 查看后端日志中的调度信息
- 确认活动时间段配置
- 检查虚拟用户状态（需为启用且已登录）

## 八、性能优化

### 1. 数据库优化

```sql
-- 添加索引（已自动创建）
CREATE INDEX idx_user_status ON virtual_users(status);
CREATE INDEX idx_interaction_time ON interaction_records(execution_time);
```

### 2. 并发控制

修改 `.env` 配置：
```bash
# 增加数据库连接池大小
DATABASE_POOL_SIZE=30
DATABASE_MAX_OVERFLOW=60
```

### 3. 缓存策略

- 新闻数据缓存到数据库
- 避免重复调用会会接口
- 定期清理过期缓存

## 九、安全建议

1. **修改默认密码**
   - 数据库 root 密码
   - 应用 JWT_SECRET_KEY

2. **API Key 保护**
   - 不要将 .env 文件提交到 Git
   - 使用环境变量或密钥管理服务

3. **网络隔离**
   - 生产环境配置防火墙规则
   - 限制数据库访问

4. **定期备份**
   - 每日备份数据库
   - 备份重要配置文件

## 十、技术支持

### 常见问题

**Q: 如何重置系统配置？**
A: 删除 system_configs 表数据，重启服务后会自动创建默认配置。

**Q: 如何批量删除虚拟用户？**
A: 暂时需要通过 API 或数据库操作，后续版本会添加批量删除功能。

**Q: Token 消耗过快怎么办？**
A: 降低 MAX_TOKENS_PER_DAY，减少虚拟用户数量，或调低互动频率。

**Q: 如何查看会会接口的详细文档？**
A: 访问 http://192.168.1.200:63120/doc.html 查看完整接口文档。

### 版本更新

关注项目更新日志，及时升级到最新版本获取新功能和安全修复。

---

**祝您使用愉快！**

如有问题，请联系开发团队或提交 Issue。