项目日志1：系统环境部署总结

目录

• 一、环境配置工具选择
  • uv 包管理工具介绍
  • uv 安装步骤
• 二、项目结构与依赖安装
  • 项目整体结构
  • 各模块依赖安装
• 三、环境变量配置
  • 服务器配置
  • API密钥配置
• 四、目录结构规划
  • 包结构设计
  • 模块划分
• 五、常见问题与解决方案
  • 依赖安装问题
  • 会话管理问题
  • 其他常见问题
• 六、部署验证
  • 服务启动验证
  • 功能测试验证

团队信息
组号：73组

项目：AI社交媒体运营方案

负责人：程岩

小组成员：程岩，阚荣至，尚弘毅

一、环境配置工具选择

uv 包管理工具介绍

uv 是一款基于 Rust 开发的高性能 Python 包管理与环境管理工具，具备以下特点：

• 高性能：执行速度远超传统 pip、venv、poetry 等工具
• 自动环境管理：虚拟环境自动管理，无需手动创建和激活
• 依赖安装与版本锁定：确保项目依赖的一致性
• 全平台支持：可在 Windows、macOS、Linux 等平台使用
• 极快极简零配置：操作简单，便于在容量较小的计算机上运行

选择 uv 作为环境配置工具，主要看重其高性能和易用性，能够快速搭建开发环境，保障团队环境一致性，实现项目依赖的高效管理。

uv 安装步骤

在 Windows 系统上安装 uv 的步骤如下：

# 使用 PowerShell 安装 uv
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装是否成功
uv --version

安装完成后，uv 会自动添加到系统 PATH 中，可在任何命令行窗口中直接使用。

二、项目结构与依赖安装

项目整体结构

小红书 MCP 系统采用分层模块化架构，整体结构如下：

┌─────────────────────────────────────────────────────────┐
│   AI Social Scheduler (智能调度层)                       │
│   - AI决策引擎                                         │
│   - 事件监听器                                         │
│   - 任务调度器                                         │
│   - 策略管理器                                         │
└───┬──────────┬──────────┬──────────┬──────────┬────────┘
    │ MCP协议  │ MCP协议  │ MCP协议  │ MCP协议  │ MCP协议
    ↓         ↓         ↓         ↓         ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│xhs-content   │ │xhs-image-mcp │ │xhs-video-mcp  │ │xhs-browser-   │ │xhs-data-     │
│generator     │ │(图像生成)     │ │(视频生成)     │ │automation-mcp │ │collector-mcp │
│              │ │              │ │              │ │(平台操作)     │ │(数据收集)     │
│- 内容生成    │ │- 图像生成     │ │- 视频脚本生成 │ │- 内容发布     │ │- 数据收集     │
│- 文案创作    │ │- Prompt模板   │ │- TTS语音合成 │ │- 内容搜索     │ │- 数据分析     │
│              │ │- Resource    │ │- 视频合成     │ │- 用户互动     │ │- 趋势识别     │
└──────────────┘ └──────────────┘ └──────────────┘ │- 账户管理     │ └──────────────┘
                                                  └────────┬────────┘
                                                         │ 浏览器自动化
                                                         ↓
                                                  ┌──────────┐
                                                  │  小红书平台 │
                                                  └──────────┘    

各模块依赖安装

使用 uv 为各个模块安装依赖的步骤如下：

# 进入图像生成模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-image-mcp"
uv sync

# 进入视频生成模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-video-mcp"
uv sync

# 进入内容生成模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-content-generator-mcp"
uv sync

# 进入浏览器自动化模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-browser-automation-mcp"
uv sync
# 安装 Playwright 浏览器
uv run playwright install chromium

# 进入数据收集模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-data-collector-mcp"
uv sync

# 进入智能调度模块目录并安装依赖
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\ai_social_scheduler"
uv sync

每个模块的依赖安装过程会自动处理依赖关系，确保所有必需的包都被正确安装。

三、环境变量配置

服务器配置

在各模块目录下创建 .env 文件，配置服务器相关参数：

# 服务器配置
MCP_HOST=127.0.0.1
MCP_PORT=8003

使用 127.0.0.1 作为主机地址，确保服务仅在本机上访问，提高安全性。

API密钥配置

以图像生成模块为例，配置 API 密钥：

# 通义万相配置（图像生成）
WANT2I_API_KEY=your_api_key
WANT2I_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

不同模块需要配置相应的 API 密钥，例如：

• 内容生成模块：可能需要配置 OpenAI、阿里云百炼或 Gemini 的 API 密钥
• 视频生成模块：可能需要配置视频合成服务的 API 密钥
• 浏览器自动化模块：可能需要配置小红书登录相关的参数

四、目录结构规划

包结构设计

采用分层架构的目录结构设计，符合工业界标准：

xiaohongshu_mcp_python/  # 包根目录
├── __init__.py           # 包入口，统一接口暴露与兼容性处理
├── main.py               # 程序入口（命令行+主函数）
├── server/               # Web服务模块
│   ├── __init__.py
│   ├── app.py            # Flask服务实例初始化
│   ├── mcp.py            # MCP核心实例封装
│   ├── mcp_tools.py      # MCP工具函数（登录、发布、搜索等）
│   └── server_run.py     # Web服务启动逻辑
├── services/             # 核心业务服务层
│   ├── __init__.py
│   └── XiaohongshuService.py # 封装MCP底层接口，统一业务逻辑
├── managers/             # 资源管理层
│   ├── __init__.py
│   └── user_session_manager.py # 登录会话管理（创建、校验、清理）
├── tests/                # 测试目录
│   ├── __init__.py
│   ├── test_login.py     # 登录功能测试
│   ├── test_publish.py   # 内容发布测试
│   └── test_search.py    # 内容检索测试
├── requirements.txt      # 依赖管理
└── pyproject.toml        # 包构建配置

模块划分

1. server 模块：负责 Web 服务的启动和管理，提供 HTTP 接口
2. services 模块：封装核心业务逻辑，处理 MCP 底层接口调用
3. managers 模块：管理资源，如用户会话、配置等
4. tests 模块：包含单元测试，确保功能的正确性

每个子目录都必须添加空的 __init__.py 文件，确保 Python 识别为可导入模块。

五、常见问题与解决方案

依赖安装问题

问题：使用 pip 安装依赖时速度慢，容易出现超时

解决方案：使用 uv 包管理工具，其执行速度远快于 pip，能够快速完成依赖安装

问题：依赖版本冲突

解决方案：

• 使用 uv 的版本锁定功能，确保依赖版本的一致性
• 在 pyproject.toml 中明确指定依赖版本
• 定期更新依赖，确保兼容性

会话管理问题

问题：多线程调用时，会话信息被覆盖

解决方案：在会话增删改查方法中添加 threading.Lock()，确保同一时间仅一个线程操作会话字典

# managers/user_session_manager.py
import threading
_session_lock = threading.Lock()
_user_sessions = {}

def create_session(user_id):
    with _session_lock:
        session_id = str(uuid.uuid4())
        _user_sessions[session_id] = {
            "user_id": user_id,
            "token": "",
            "create_time": time.time(),
            "expire_seconds": 7200
        }
    return session_id

问题：会话过期判断逻辑错误，未过期会话被误判为过期

解决方案：修正时间对比逻辑，确保正确判断会话是否过期

其他常见问题

问题：Playwright 浏览器安装失败

解决方案：使用 uv run playwright install chromium 命令安装，确保网络连接稳定

问题：环境变量未生效

解决方案：确保 .env 文件放置在正确的目录下，重启服务后环境变量会自动加载

问题：端口被占用

解决方案：修改 .env 文件中的 MCP_PORT 配置，使用未被占用的端口

六、部署验证

服务启动验证

启动各模块服务，验证服务是否正常运行：

# 启动图像生成服务
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-image-mcp"
uv run python -m server.server_run

# 启动内容生成服务
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-content-generator-mcp"
uv run python -m server.server_run

# 启动浏览器自动化服务
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\xhs-browser-automation-mcp"
uv run python -m server.server_run

# 启动智能调度服务
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master\ai_social_scheduler"
uv run python -m api.app

服务启动后，可通过访问 http://localhost:端口 查看服务状态。

功能测试验证

运行测试脚本，验证核心功能是否正常：

# 运行测试
cd "e:\实验\项目实习\xiaohongshu-mcp-python-master"
uv run pytest

测试通过后，说明环境部署成功，系统可以正常运行。

总结

通过使用 uv 包管理工具，我们成功搭建了小红书 MCP 系统的开发环境，实现了各模块的依赖安装和配置。采用分层架构的目录结构设计，确保了代码的高内聚低耦合，便于团队协作和后续维护。

环境部署过程中，我们解决了依赖安装、会话管理等常见问题，确保了系统的稳定性和可靠性。通过服务启动验证和功能测试，确认了环境部署的成功。

这套环境配置方案为后续的系统开发和功能扩展奠定了坚实的基础，能够支持小红书 MCP 系统的全流程自动化运营需求。