DouYin SparkFlow：抖音多账号续火花自动维护系统 · 最全部署与使用指南

一句话定位：GitHub 开源项目 halfwaystudent/douyin-sparkflow 是一个自托管的抖音续火花工具——每天在你设置的发送窗口内，自动给选定的好友和群聊发一条消息，支持多账号、发送前巡查、结果推送和 Web 控制台。

仓库地址：https://github.com/halfwaystudent/douyin-sparkflow · 许可证：PolyForm Noncommercial License 1.0.0（仅限非商业用途）

目录

• 一、官方跳转与下载链接
• 二、项目简介与核心能力
• 三、主界面预览（官方图片）
• 四、快速开始与部署
• 五、部署方式详解
• 六、使用流程与方法
• 七、功能模块详解
• 八、配置说明
• 九、服务器部署最佳实践
• 十、高级配置
• 十一、技术栈与项目结构
• 十二、免责声明与商业使用限制
• 十三、更新日志与项目状态
• 十四、常见问题排查
• 十五、参考链接汇总

一、官方跳转与下载链接

⚠️ 重要提示：本项目是非官方第三方开源项目，与抖音及其关联方不存在隶属、授权、赞助、代理或合作关系。使用者只能操作本人拥有或已获明确授权的账号，自动化操作可能导致验证、限流、功能限制、账号封禁等后果。

二、项目简介与核心能力

2.1 这是什么

DouYin SparkFlow（续火花 SparkFlow）是一个自托管的抖音火花（聊天互动标识）自动维护系统：在发送窗口内分批给选定的好友和群聊每天发一条消息，把"续火花"这件事完全自动化，还带完整的 Web 管理后台。

2.2 核心能力一览

三、主界面预览（官方图片）

3.1 暗色模式

▲ 图 1：Web 管理控制台 - 今日概览（暗色主题，演示数据）——左侧功能导航（今日/发送明细/账号/登录/管理/设置/运行日志），右侧今日火花进度（今天还差 2 个火花、已发送 75% 6/8 个），下方各账号发送明细。

3.2 亮色模式

▲ 图 2：Web 管理控制台 - 今日概览（亮色主题，演示数据）

两张截图均来自项目官方 README，路径 DouYinSparkFlow/docs/images/screenshot-*.png。

四、快速开始与部署

4.1 前置要求

4.2 快速开始（Docker 一键，官方推荐）

# 1. 克隆仓库
git clone https://github.com/halfwaystudent/douyin-sparkflow.git
cd douyin-sparkflow

# 2. 创建本地环境变量
cp .env.example .env
nano .env        # 按需修改配置；可填 PROXY_SUB_URL（订阅地址，勿提交）

# 3. 初始化运行时文件并启动服务（自动创建 proxy/config.yaml）
bash ./deploy/install-local.sh

# Windows PowerShell 用：
# powershell -ExecutionPolicy Bypass -File .\deploy\install-local.ps1

# 4. 浏览器打开 Web 界面
# http://localhost:8787

服务端口说明：

服务器远程访问 noVNC（先建 SSH 隧道）：

ssh -L 8788:127.0.0.1:8788 <user>@<server-ip>

然后浏览器打开：http://127.0.0.1:8788/vnc.html?autoconnect=1&resize=scale&view_only=0

Apple Silicon（M 系列）：默认 Playwright 基础镜像同时支持 amd64 和 arm64，无需指定 platform。

五、部署方式详解

方式一：Docker Compose 一键部署（推荐，生产环境）

项目提供完整 Compose 编排，共 5 个服务：

# 1. 准备环境变量
cp .env.example .env

# 2. 初始化 proxy/config.yaml 并启动所有服务
bash ./deploy/install-local.sh

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

# 4. 停止服务
docker compose down

仅部署 Web 服务：

docker compose up -d web

定时任务由 scheduler 容器直接运行 /app/main.py --doTask，不再通过 docker exec 控制 web 容器，因此 scheduler 不需要挂载宿主机 Docker socket。旧部署的共享定时文件会在启动时自动迁移；更新脚本会备份并清理宿主机 root crontab 中旧的 Docker 发送任务，避免两套定时器同时运行。

方式二：本地开发运行

# 1. 克隆仓库
git clone https://github.com/halfwaystudent/douyin-sparkflow.git
cd douyin-sparkflow/DouYinSparkFlow

# 2. 安装依赖
pip install -r requirements.txt
pip install -r requirements-web.txt

# 3. 安装 Playwright 浏览器
playwright install chromium

# 4. 启动 Windows 本地登录浏览器（另开一个 PowerShell）
.\scripts\start_login_desktop.ps1

# 5. 启动 Web 服务（再开一个终端）
python main.py --web

# 6. 访问 http://localhost:8787

六、使用流程与方法

6.1 五步上手

6.2 好友与群聊目标

好友： - 在「账号」页点「刷新好友列表」后勾选，或每行手动填写一个昵称； - 勾选的好友按 UID 绑定，改昵称后自动跟随。

群聊： - 点「刷新群列表」后勾选，列表显示为 群名（会话编号）； - 程序按编号找群并在发送前核对——群改名照常发送，有同名群也不会发错； - 也可以不绑定编号直接填群名，此时要求群名在列表第一屏唯一，否则跳过； - ⚠️ 群聊目标只支持浏览器发送通道，协议发送通道仅用于好友。

6.3 巡查与推送

• 巡查时机：每天发送窗口开始前半小时自动只读检查：登录是否有效、登录的是不是这个账号、目标好友和群是否还在、有没有改名；
• 巡查原则：不打开聊天、不发消息，纯只读；
• 手动巡查：在「账号」页点「立即巡查」，结果显示每个目标「找到 / 缺失 / 已改名」；
• 推送渠道：Telegram、钉钉、企业微信或通用 Webhook；同一问题每天只推一次，另有每日汇总。

七、功能模块详解

7.1 续火花（核心）

7.2 发送确认分级（证据分级）

7.3 消息模板

• 一言（Hitokoto）：随机诗词、名言警句；
• 节日祝福：自动识别节假日，发送对应祝福语；
• 自定义消息：纯文本自定义。

发送策略：时间窗口（如 09:00–22:00）、可配置发送间隔与限速（降低操作频率和对接收方的打扰）；发送失败按类别处理，可重试的在窗口内重试，结果不确定的标待核验。

八、配置说明

8.1 .env 环境变量（节选）

WEB_BIND_ADDRESS=0.0.0.0
WEB_PORT=8787

# noVNC 默认仅允许本机或 SSH 隧道访问
LOGIN_DESKTOP_BIND_ADDRESS=127.0.0.1
LOGIN_DESKTOP_WEB_PORT=8788
LOGIN_DESKTOP_PUBLIC_URL=/login-desktop/proxy/vnc.html?autoconnect=1&resize=scale&view_only=0&path=login-desktop/proxy/websockify

# 登录浏览器默认先直连抖音，直连失败时再尝试 Mihomo
LOGIN_DESKTOP_PROXY_MODE=auto
LOGIN_DESKTOP_PROXY=http://proxy:7890

# Mihomo 代理和控制端口默认仅绑定本机
PROXY_BIND_ADDRESS=127.0.0.1
PROXY_HTTP_PORT=7890
PROXY_CONTROLLER_PORT=9090
PROXY_SUB_URL=            # 可选：Mihomo/Clash 订阅地址（含敏感 token，只写本地 .env）

网络策略：登录、好友刷新和发送任务默认"直连优先，Mihomo 回退"。LOGIN_DESKTOP_PROXY_MODE=auto 时登录浏览器先直连 creator.douyin.com，直连预检失败才走代理；没有配置有效订阅时，Mihomo 仅提供 DIRECT-only 配置。

8.2 config.json 应用配置（节选）

{
  "messageTemplate": "✨今日火花+1\n",
  "useProtocolSender": false,
  "browserSenderAccounts": [],
  "dailySendWindow": {
    "enabled": true,
    "startHour": 10,
    "endHour": 18,
    "scheduleIntervalMinutes": 20
  },
  "friendListScan": {
    "maxScanSeconds": 300,
    "idleScanSeconds": 120,
    "scrollStepPx": 400,
    "scrollDelaySeconds": 0.8
  },
  "persistentBrowserProfiles": {
    "enabled": true,
    "root": "/opt/douyin-sparkflow/state/browser-profiles",
    "seedCookiesWhenEmpty": true,
    "syncStoredCookiesBeforeRun": true,
    "refreshStoredCookiesAfterLogin": true
  }
}

usersData.json、webui_settings.json、浏览器 Profile、Cookie 和日志均为运行时敏感数据，不应提交到 Git。

九、服务器部署最佳实践

9.1 系统要求

9.2 持久化数据卷

volumes:
  - ./state:/app/state          # 运行状态数据
  - ./logs:/app/logs            # 日志文件
  - ./DouYinSparkFlow:/app      # 应用代码（开发环境）

9.3 Nginx 反向代理示例

server {
    listen 80;
    server_name sparkflow.example.com;

    location / {
        proxy_pass http://localhost:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

9.4 安全建议

• ✅ 首次访问面板时创建管理员账号，使用足够强的密码（系统不提供默认密码）；
• ✅ 启用 HTTPS（Let's Encrypt）；
• ✅ 配置防火墙规则；
• ✅ 定期备份 state/ 和 usersData.json；
• ✅ 使用环境变量管理敏感配置。

十、高级配置

10.1 代理配置

仓库提供 proxy/config.example.yaml 安全模板；部署脚本启动前生成本地 proxy/config.yaml：

mixed-port: 7890
allow-lan: true
mode: rule
# ... 更多见 proxy/config.example.yaml

• PROXY_SUB_URL 非空时，refresh_proxy.sh 下载订阅并更新本地配置；为空则生成 DIRECT-only 配置；
• ⚠️ 首次部署不要跳过初始化步骤直接 docker compose up -d，否则 Docker 可能把缺失的配置文件创建成目录；
• Mihomo 控制接口（9090）需要密码：首次运行 refresh_proxy.sh（或 Windows 的 install-local.ps1）生成随机密码，保存在 state/proxy/controller-secret；想自己指定就在 .env 设置 PROXY_CONTROLLER_SECRET（只能含字母数字和 . _ ~ -）。

10.2 默认网络安全

• noVNC、Mihomo 代理端口和控制端口默认仅绑定 127.0.0.1；
• 远程服务器请优先 SSH 隧道 / VPN / 带认证的 HTTPS 反向代理访问，不建议直接把 8788、7890、9090 暴露公网；
• Web 走 HTTPS 反向代理时可设 SPARKFLOW_SESSION_COOKIE_SECURE=1；
• 宿主机 Docker Engine 较旧时可能需要显式指定 DOCKER_API_VERSION（如 1.43）。

10.3 持续集成（GitHub Actions）

工作流 .github/workflows/tests.yml 在 push / PR / 手动触发时运行：Python 单元测试、字节码编译检查、Node 协议发送器测试。不使用 Secret、不启动浏览器、不发送任何消息——fork 和外部 PR 也能跑同一套检查。

早期曾有一个会在 GitHub 上执行真实发送的定时工作流（schedule.yml），已在 2026-09 移除（云端机房 IP 发消息既不必要也易触发风控）。需要定时发送请用项目自带的调度（面板自动发送窗口 + 容器内 cron），运行在你自己的服务器上。

十一、技术栈与项目结构

11.1 技术栈

11.2 项目结构

douyin-sparkflow/
├── DouYinSparkFlow/              # 核心应用源码
│   ├── core/                     # 核心功能模块
│   │   ├── tasks.py              # 发送任务与调度（核心）
│   │   ├── streak_state.py       # 每个目标的发送状态与失败分类
│   │   ├── friends.py            # 好友列表读取
│   │   ├── friend_identity.py    # 好友 UID 绑定与改名跟随
│   │   ├── groups.py             # 群列表读取（只读）
│   │   ├── patrol.py             # 发送前巡查（只读）
│   │   ├── notifications.py      # 推送事件的去重与汇总
│   │   ├── identity.py           # 抖音账号身份核对
│   │   ├── browser.py            # 浏览器、持久化配置与账号锁
│   │   ├── login.py / cookies.py # 登录与 Cookie 校验
│   │   ├── msg_builder.py        # 消息内容构建
│   │   └── protocol_*.{py,mjs}   # 协议发送通道（可选，仅好友）
│   ├── webui/                    # Web 控制台
│   │   ├── app.py                # FastAPI 主应用
│   │   ├── auth.py / users.py    # 登录认证与子用户
│   │   ├── ops.py                # 运维与概览数据
│   │   ├── static/               # 静态资源（CSS/JS）
│   │   └── templates/            # HTML 模板
│   ├── utils/                    # 配置、日志、推送渠道、一言等
│   ├── scripts/                  # 定时任务与辅助脚本
│   ├── tests/                    # 单元测试
│   ├── main.py                   # 主入口（--web / --doTask / --patrol）
│   └── login_desktop_server.py   # 登录桌面服务
├── .github/workflows/            # GitHub Actions 测试（只跑测试，不发送）
├── deploy/                       # 一键部署脚本
├── docs/                         # 使用文档
├── proxy/                        # 代理配置模板
├── docker-compose.yml            # 容器编排配置
├── .env.example                  # 环境变量模板
└── README.md

十二、免责声明与商业使用限制

12.1 非官方项目声明

本项目为第三方个人项目，与抖音及其关联方不存在隶属、授权、代理、赞助、技术支持或合作关系。项目名称中的"抖音"仅用于说明兼容目标或使用场景。

12.2 使用授权与账号责任

• 使用者只能操作本人拥有或已获明确授权的账号；
• 不得使用他人未经授权的账号、Cookies、登录态、身份凭据或个人信息；
• 使用者应自行判断是否符合法律法规、抖音用户协议及平台规则。

12.3 平台风险

抖音可能随时调整服务、接口、页面、风控策略和用户协议。自动化操作可能导致验证码、限流、功能限制、账号异常、账号封禁、登录态失效或其他平台处理。本项目不保证平台兼容性、持续可用性或账号安全，也不提供规避平台风控的保证。

12.4 商业使用限制（PolyForm 非商用 1.0.0）

未经版权持有人事先书面授权，禁止将本项目用于： - 收费软件、收费脚本、收费镜像或收费部署服务； - SaaS、托管服务、代运营或客户账号管理； - 企业、品牌、店铺、主播或其他商业账号运营； - 广告投放、商业推广、营销获客或客户维护； - 将本项目集成到商业产品、商业平台或付费课程； - 以部署、维护、代发、运营等方式向第三方收取费用； - 其他直接或间接服务于营利性活动的场景。

如需商业使用，请事先联系版权持有人取得书面商业授权。

十三、更新日志与项目状态

最近更新（2026-10）： - 💬 支持群聊目标：刷新群列表、勾选后按会话编号绑定，发送前核对，巡查也会检查群； - 🚓 新增发送前巡查：检查登录状态、账号身份和目标是否还在； - 🪪 好友按 UID 绑定，改昵称后自动跟随； - 🔔 新增推送通知：Telegram、钉钉、企业微信、通用 Webhook； - 🧑‍🤝‍🧑 支持子用户，各自管理分配给自己的抖音账号； - 📱 登录支持 Cookie，扫码登录保存后在后台验证； - 🐳 默认镜像同时支持 x86 和 ARM（Apple Silicon）。

项目状态：作为个人项目维护，暂不接受外部 Pull Request；发现问题或建议可提交 Issue。

十四、常见问题排查

十五、参考链接汇总

免责声明：本文所有命令、规则、数据均整理自官方 GitHub 仓库 halfwaystudent/douyin-sparkflow 的 README 与官方文档原文，如仓库更新请以最新版本为准。本项目非抖音官方项目，使用请遵守 PolyForm 非商用许可、抖音用户协议及相关法律法规。