# cool-red-ai-server

**Repository Path**: Dzreal_admin/cool-red-ai-server

## Basic Information

- **Project Name**: cool-red-ai-server
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-26
- **Last Updated**: 2025-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小红书AI运营工具

一个基于FastAPI的智能小红书运营自动化工具，集成AI内容生成、任务调度和浏览器自动化技术。

## 🚀 功能特性

- **AI内容生成**: 基于LangChain集成大语言模型，自动生成小红书风格的图文内容
- **内容管理**: 完整的图文内容CRUD操作，支持草稿、待发布、已发布等状态管理
- **自动化发布**: 基于Playwright的浏览器自动化，支持即时发布和定时发布
- **任务调度**: 集成XXL-Job分布式任务调度平台，支持动态创建、管理和监控发布任务
- **对象存储**: 通用S3兼容接口，支持MinIO、AWS S3、阿里云OSS等多种存储方案
- **RESTful API**: 完整的API接口，支持前端集成和第三方调用

## 🏗️ 技术架构

### 核心技术栈

- **后端框架**: FastAPI + Uvicorn
- **数据库**: MySQL + SQLAlchemy ORM
- **任务调度**: XXL-Job
- **对象存储**: MinIO (S3兼容)
- **浏览器自动化**: Playwright
- **AI集成**: LangChain + OpenAI
- **数据验证**: Pydantic

### 项目结构

```
xiaohongshu-helper/
├── app/                    # 应用核心代码
│   ├── api/               # API路由层
│   │   └── v1/           # API v1版本
│   │       ├── posts.py  # 帖子相关API
│   │       └── jobs.py   # 任务调度API
│   ├── core/             # 核心配置
│   │   └── config.py     # 全局配置
│   ├── crud/             # 数据库操作
│   │   └── crud_post.py  # 帖子CRUD
│   ├── db/               # 数据库会话
│   │   └── session.py    # 数据库连接
│   ├── models/           # 数据模型
│   │   └── post.py       # 帖子模型
│   ├── schemas/          # 数据校验
│   │   └── post.py       # 帖子Schema
│   ├── services/         # 业务服务层
│   │   ├── ai_service.py      # AI生成服务
│   │   ├── storage_service.py # 对象存储服务
│   │   └── playwright_service.py # 自动化服务
│   ├── xxl_job/          # XXL-Job集成
│   │   ├── executor.py   # 执行器
│   │   ├── handler.py    # 任务处理器
│   │   └── xxl_api.py    # API客户端
│   └── main.py           # 应用入口
├── scripts/              # 自动化脚本
│   └── publish_post.py   # 发布脚本
├── .env                  # 环境变量
├── requirements.txt      # 依赖包
├── init_db.sql          # 数据库初始化
└── README.md            # 项目文档
```

## 🛠️ 快速开始

### 环境要求

- Python 3.8+
- MySQL 5.7+
- Node.js (用于Playwright)

### 1. 克隆项目

```bash
git clone <repository-url>
cd xiaohongshu-helper
```

### 2. 安装依赖

```bash
# 安装Python依赖
pip install -r requirements.txt

# 安装Playwright浏览器
playwright install
```

### 3. 配置环境变量

复制 `.env` 文件并根据实际情况修改配置：

```bash
cp .env.example .env
```

主要配置项：

```env
# 数据库配置
DATABASE_URL=mysql+pymysql://root:password@localhost:3306/xiaohongshu_helper

# MinIO配置
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin

# XXL-Job配置
XXL_JOB_ADMIN_URL=http://localhost:8080/xxl-job-admin
XXL_JOB_USERNAME=admin
XXL_JOB_PASSWORD=123456

# OpenAI配置 (可选 - 不配置将使用模拟数据)
# OPENAI_API_KEY=your-api-key-here  # 可选：用于AI内容生成
```

### 4. 初始化数据库

```bash
# 创建数据库和表
mysql -u root -p < init_db.sql
```

### 5. 启动服务

```bash
# 开发模式
python -m app.main

# 或使用uvicorn
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 6. 访问API文档

启动后访问：
- API文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

## 📋 基础设施部署

### MySQL

```bash
# Docker方式
docker run -d \
  --name mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=xiaohongshu_helper \
  -p 3306:3306 \
  mysql:8.0
```

### MinIO

```bash
# Docker方式
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"
```

### XXL-Job

1. 下载XXL-Job: https://github.com/xuxueli/xxl-job
2. 配置数据库连接
3. 启动调度中心: `java -jar xxl-job-admin-2.4.0.jar`
4. 访问管理界面: http://localhost:8080/xxl-job-admin

## 🔧 API使用示例

### 1. 生成AI内容

```bash
curl -X POST "http://localhost:8000/api/v1/posts/generate-content" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "秋季护肤",
    "style": "小红书爆款"
  }'
```

### 2. 创建帖子

```bash
curl -X POST "http://localhost:8000/api/v1/posts/" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "秋季护肤必备清单",
    "content": "分享我的秋季护肤心得...",
    "tags": "护肤,秋季,美妆"
  }'
```

### 3. 创建定时发布任务

```bash
curl -X POST "http://localhost:8000/api/v1/jobs/" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": 1,
    "job_cron": "0 0 10 * * ?",
    "job_desc": "每天上午10点发布"
  }'
```

### 4. 启动任务

```bash
curl -X POST "http://localhost:8000/api/v1/jobs/1/start"
```

## 🎯 核心功能详解

### AI内容生成

系统集成LangChain框架，支持多种LLM提供商：

- **OpenAI GPT**: 可选配置，不配置时使用模拟内容生成
- **本地模型**: 支持Ollama等本地部署方案
- **其他云服务**: 可扩展支持Claude、文心一言等

生成的内容包括：
- 吸引人的标题
- 符合小红书风格的正文
- 相关话题标签建议

### 自动化发布

Playwright脚本特性：

- **智能选择器**: 多重备用选择器，应对页面变化
- **异常处理**: 完整的错误捕获和重试机制
- **截图调试**: 失败时自动截图便于问题排查
- **无头模式**: 支持有头/无头模式切换

### 任务调度

XXL-Job集成功能：

- **动态任务管理**: API方式创建、启动、停止任务
- **执行器集成**: 内置执行器，无需单独部署
- **任务监控**: 实时查看任务执行状态和日志
- **失败重试**: 支持任务失败自动重试

### 对象存储

通用存储适配器：

- **多厂商支持**: MinIO、AWS S3、阿里云OSS、腾讯云COS
- **统一接口**: 屏蔽底层差异，便于切换
- **自动管理**: 自动创建bucket，处理权限配置

## 🔍 监控和日志

### 应用监控

- **健康检查**: `/health` 端点监控服务状态
- **服务状态**: 实时检查数据库、存储、AI服务可用性
- **性能指标**: 响应时间、错误率等关键指标

### 日志管理

- **结构化日志**: 统一的日志格式和级别
- **错误追踪**: 详细的错误堆栈和上下文信息
- **操作审计**: 关键操作的完整记录

## 🚨 注意事项

### 安全考虑

1. **API密钥管理**: 妥善保管各种服务的API密钥（OpenAI为可选配置）
2. **数据库安全**: 使用强密码，限制网络访问
3. **文件上传**: 验证文件类型和大小，防止恶意上传
4. **CORS配置**: 生产环境限制跨域访问来源

### 合规使用

1. **平台规则**: 遵守小红书平台的使用条款和社区规范
2. **内容审核**: 确保生成和发布的内容符合平台要求
3. **频率控制**: 合理设置发布频率，避免被平台限制
4. **账号安全**: 使用专门的运营账号，避免影响个人账号

### 性能优化

1. **数据库优化**: 合理设计索引，定期清理历史数据
2. **缓存策略**: 对频繁访问的数据进行缓存
3. **异步处理**: 耗时操作使用异步处理，提升响应速度
4. **资源限制**: 合理配置并发数和超时时间

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支: `git checkout -b feature/new-feature`
3. 提交更改: `git commit -am 'Add new feature'`
4. 推送分支: `git push origin feature/new-feature`
5. 提交Pull Request

## 📄 许可证

MIT License

## 📞 支持

如有问题或建议，请提交Issue或联系维护者。

---

**免责声明**: 本工具仅供学习和研究使用，使用者需自行承担使用风险，并遵守相关平台的使用条款。