Stooland Docs

Appearance

Social Publisher - 抖音自动化发布工具 & API ​

基于 Playwright 的抖音视频自动化发布工具，支持 CLI 命令行调用和 RESTful API 服务化调用。

✨ 核心特性 ​

  • 自动登录与持久化：首次扫码后自动保存 Session，后续无需重复登录。
  • 多账号支持：支持管理多个抖音账号，发布时可指定账号。
  • 智能防检测：集成 playwright-stealth，模拟真实用户指纹，避开风控。
  • 全功能发布：支持视频上传、标题、描述、话题标签、自定义封面。
  • 微服务架构：提供 FastAPI 接口，支持异步任务队列、状态查询、失败回溯。
  • 高级选项：
    • 定时发布：支持指定未来时间发布。
    • 自主声明：支持勾选“内容由AI生成”、“取材网络”等声明。
    • 人工审查模式：独创的 --manual_review 模式（仅 CLI）。

🚀 快速开始 ​

1. 安装依赖 ​

bash
cd social-publisher
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium

2. 命令行使用 (CLI) ​

使用 start.sh 执行一次性发布任务。

bash
# 方式 1：直接传参（推荐）
./start.sh --video "/path/to/video.mp4" --title "我的视频"

# 方式 2：显式 CLI 模式
./start.sh cli --video "/path/to/video.mp4" --title "我的视频"

3. 服务端使用 (API) ​

启动常驻 API 服务：

bash
./start.sh server

服务默认运行在 8989 端口。

🌐 API 配置与文档 ​

1. 数据库配置 ​

本项目使用 MySQL 数据库，并依赖 Phinx 进行数据表迁移。

  1. 配置环境变量：在 social-publisher 目录下创建 .env 文件（参考根目录配置）：

    env
    DB_HOST=127.0.0.1
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DATABASE=your_database
DB_PREFIX=sets_

  2. 执行迁移：在项目根目录运行 Phinx 迁移命令（确保已安装 PHP 环境）：

    bash
    php think migrate:run

    这将创建 publish_tasks 表（例如 sets_publish_tasks）。

2. 接口文档 ​

启动服务后，访问 http://localhost:8989/docs 查看 Swagger 文档。

3. 调用示例 ​

发布视频 ​

Endpoint: POST /api/v1/publish

json
{
  "video_url": "https://example.com/video.mp4",
  "title": "API Test",
  "description": "Published via API",
  "tags": ["api", "test"],
  "cover_path": "https://example.com/cover.png",
  "claim_type": "内容由AI生成",
  "schedule_time": "2026-02-07 18:00",
  "account_name": "my_douyin_account" // 可选，默认 default_user
}

4. 账号管理 ​

  1. 获取账号列表: GET /api/v1/accounts
    • 返回账号的基本信息、状态、待发布队列数、排期情况等。
  2. 请求登录新账号: POST /api/v1/accounts/login
    • Body: {"account_name": "new_user"}
    • Response: {"login_id": "...", "qr_code_base64": "..."}
    • 前端展示 Base64 二维码供用户扫码。
  3. 轮询登录状态: GET /api/v1/accounts/login/{login_id}
    • Response: {"status": "pending" | "success" | "failed" | "expired"}
  4. 删除账号: DELETE /api/v1/accounts/{account_name}
  5. 测试连接: POST /api/v1/accounts/{account_name}/verify
    • 测试账号连通性，更新头像/昵称，并抓取最新的作品队列信息（待发布数、最晚排期时间）。
  6. 配置排期: PUT /api/v1/accounts/{account_name}
    • Body: {"schedule_config": ["18:00", "22:00"]}
    • 设置该账号每天固定的发布时间点，系统将在智能排期时优先使用。

⚠️ 服务器部署与登录指南 (Ubuntu/Linux) ​

由于 Playwright 需要浏览器环境，而服务器通常是无头环境（无 GUI），请遵循以下 最佳实践流程 进行部署和登录：

1. 本地登录（获取凭证） ​

在本地电脑（Mac/Windows）上运行程序（默认有头模式），完成扫码登录。

bash
# 启动 API 服务
./start.sh server
# 或者运行一次性发布
./start.sh --video "test.mp4" --title "Login Check"

登录成功后，你的登录凭证会保存在 social-publisher/data/ 目录下（例如 data/default_user/）。

2. 迁移凭证 ​

将本地生成的 social-publisher/data/ 目录完整上传到服务器的对应位置：

bash
# 示例：上传到服务器
scp -r social-publisher/data user@your-server:/path/to/stooland/social-publisher/

3. 服务器运行（静默模式） ​

在服务器上，设置 HEADLESS=true 环境变量来强制开启静默模式。

bash
# 方式 1：临时运行
export HEADLESS=true
./start.sh server

# 方式 2：写入 .env 文件 (推荐)
echo "HEADLESS=true" >> .env

此时程序会检测到 data/ 目录下的凭证，跳过扫码环节，直接在后台执行发布任务。

注意：如果凭证过期（通常数周），你需要重复上述步骤重新获取最新的 data 目录。 进阶：在服务器上可以配合 xvfb 运行，模拟有头模式以降低风控概率： xvfb-run --auto-servernum python app.py

📝 目录结构 ​

social-publisher/
├── start.sh            # 总控脚本 (Entry Point)
├── cli.sh              # CLI 逻辑脚本
├── server.sh           # API 服务启动脚本
├── app.py              # API 入口 (FastAPI)
├── worker.py           # 后台任务消费者
├── database.py         # 数据库模型 (SQLModel + MySQL)
├── service/            # 业务逻辑层
│   ├── account_service.py # 账号管理服务
│   └── publisher_service.py # 发布服务封装
├── core/               # 核心逻辑
├── platforms/          # 平台适配
└── requirements.txt    # 依赖列表