抖音多账号火花自动维护系统 · 自托管续火花工具 · 中文部署与使用全指南

项目仓库： https://github.com/halfwaystudent/douyin-sparkflow

开源协议：PolyForm Noncommercial License 1.0.0（仅授权非商业用途） · 后端语言：Python 3.10+ · 容器化：Docker + Docker Compose · 浏览器自动化：Playwright · 仓库分支：main（截至 2026-10-25，Star 588 / Fork 134，数据以仓库页面实时徽章为准）

1 项目简介

DouYin SparkFlow（仓库名 douyin-sparkflow，控制台内名称“续火花 SparkFlow”）是一个自托管的抖音多账号火花自动维护系统：在你设定的每日发送窗口内，给选定的好友和群聊自动发送一条问候消息，支持多账号集中管理、发送前只读巡查、结果分级记录与异常推送提醒，并内置一个响应式 Web 管理控制台，手机和电脑都能操作。

项目由第三方开发者个人维护，不是抖音官方产品。代码全部运行在你自己的服务器或本机上，不附带任何账号、Cookie、好友或群聊数据，首次使用需要在面板里自行扫码登录自己的账号。

非官方声明（务必先读）：本项目与抖音及其关联方不存在隶属、授权、赞助、代理、技术支持或合作关系；项目名称中的“抖音”仅用于说明兼容目标或使用场景，不代表任何官方认可。只能操作本人拥有或已获得明确授权的账号，自动化操作可能触发验证码、限流、功能限制、账号封禁、登录态失效或数据丢失，项目不保证规避平台风控。完整风险与责任边界见本文第 18 章。

1.1 核心信息一览

1.2 适用场景

• 需要同时维护多个抖音账号与若干好友、群聊的每日火花，希望在固定时间窗口内自动分批发送，而不是手动逐个点开聊天。
• 希望发送前先只读巡查一遍：登录是否有效、登录的是不是这个账号、好友和群是否还在、有没有改名，避免发错对象。
• 需要把发送失败、巡查异常、登录失效等情况推送到 Telegram、钉钉、企业微信或通用 Webhook，并拿到每日汇总。
• 要求登录态、Cookie、好友信息和发送记录保存在自己可控的服务器上，不经过第三方云端后台。

1.3 能力边界（官方口径）

• 每个目标一天只发一次；发送前会核对聊天对象，对象对不上就跳过并记录原因，宁可不发也不重发；结果不确定时标为“待核验”，当天不会自动重发。
• 群聊目标只支持浏览器发送通道；协议发送通道仅用于好友。
• 项目不提供账号、Cookie、好友或群数据；不保证平台兼容性、持续可用性、账号安全或特定发送结果，也不保证规避平台风控。

2 功能特性

2.1 续火花

• 每日自动发送：在设置的发送窗口内分批发送，每个目标一天只发一次。
• 好友目标：在账号页刷新好友列表后勾选；按好友 UID 绑定，好友改昵称后自动跟随，不会因为改名丢失目标。
• 群聊目标：刷新群列表后勾选，按群会话编号绑定；群改名或存在同名群都不会发错。
• 宁可不发、也不重发：发送前核对聊天对象，对不上就跳过并记录原因；发送结果不确定时标为“待核验”，当天不会自动重发。
• 消息模板：支持自定义模板、一言（Hitokoto）、节日祝福，可设置多条变体随机使用。

2.2 巡查与提醒

• 发送前巡查：发送窗口开始前半小时只读检查一遍——登录是否有效、登录的是不是这个账号、目标好友和群是否还在、有没有改名；巡查不打开聊天，也不发消息。
• 结果推送：发送失败、巡查发现问题、登录失效时推送到 Telegram、钉钉、企业微信或通用 Webhook，并每天发送一份汇总；同一问题每天只推一次。
• 发送明细：每个目标的结果按证据分级（服务端确认 / 页面回显 / 仅回执），可单独重试。

2.3 账号与登录

• 多账号：集中管理多个抖音账号，每个账号单独配置目标。
• 扫码或 Cookie 登录：在网页登录工作区扫码，或粘贴 Cookie；保存前会在真实浏览器里验证。
• 身份绑定：重新登录时核对抖音账号身份，防止把登录态存到别的账号下。
• 子用户：管理员可以添加面板用户，每个用户只能看到分配给自己的抖音账号。

2.4 技术特性

• Web 控制台：FastAPI + 原生 JavaScript，手机也能用，支持亮色 / 暗色主题；电脑端导航在左侧，手机端在底部标签栏。
• 浏览器自动化：基于 Playwright，每个账号使用独立的持久化浏览器配置。
• Docker 部署：一条命令起全部服务，默认镜像同时支持 amd64 和 arm64（含 Apple Silicon）。
• 网络回退：默认直连抖音，直连不通时再走 Mihomo 代理。
• 账号互斥：发送、刷新好友 / 群列表、巡查和登录共用账号锁，不会同时打开同一个账号。

3 官方界面预览

3.1 亮色主题

开头封面即为亮色主题的今日概览：今日页直接显示“今天还差几个火花”，包含进度环、今日已续上数量、强确认 / 弱证据 / 待发送统计、下一轮发送时间、发送窗口、最近强确认时间，以及每个账号的进度卡片。

3.2 暗色主题

同一页面的暗色主题演示数据；点击月亮 / 太阳图标切换，主题选择会保存在当前浏览器中。

4 官方跳转链接汇总

下表列出项目相关的全部官方入口，均可直接点击访问。

5 前置要求与服务器配置

5.1 软件前提

• Python 3.10 或更高版本：代码使用了 X | None 等 PEP 604 语法，Python 3.9 会在导入时报错（本地开发方式需要）。
• Node.js 18+：仅在使用协议发送通道（core/protocol_sender.mjs）时需要。
• Docker 和 Docker Compose：容器部署方式需要，推荐使用 Docker Engine 自带的 Compose 插件。
• 稳定的网络连接。
• 你自己的抖音账号：项目不附带任何账号、Cookie 或好友数据，首次使用需在面板里扫码登录。

5.2 服务器硬件与系统建议（官方推荐）

5.3 端口分配

安全提示：noVNC、代理端口和控制端口默认只绑定本机回环地址。远程服务器请优先通过 SSH 隧道、VPN 或带认证的 HTTPS 反向代理访问，不要直接把 8788、7890、9090 暴露到公网。

6 方式一：Docker 一键部署（推荐）

适用于服务器部署、生产环境。仓库提供完整的 docker-compose.yml 与初始化脚本，克隆后一条命令完成目录初始化、代理配置生成与容器构建启动。

Apple Silicon（M 系列）：默认 Playwright 基础镜像同时提供 amd64 和 arm64，无需指定 platform。如果需要通过 PLAYWRIGHT_BASE_IMAGE 使用镜像站，请确认所选镜像也提供 arm64；这只解决容器镜像架构兼容性，不保证抖音登录流程一定可用。

6.1 分步命令（Linux / macOS）

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

# 2. 创建本地环境变量
cp .env.example .env
nano .env   # 根据需要修改配置
# 可选：在本地 .env 中填写 PROXY_SUB_URL，不要提交真实订阅地址

# 3. 初始化运行时文件并启动服务
# 会创建 proxy/config.yaml；没有订阅时使用 DIRECT-only 配置
bash ./deploy/install-local.sh

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

Windows PowerShell 使用对应的脚本：

powershell -ExecutionPolicy Bypass -File .\deploy\install-local.ps1

6.2 初始化脚本做了什么

deploy/install-local.sh 按顺序执行以下动作（供排障对照）：

1. 检查 docker 命令与 docker compose version 是否可用，缺少则报错退出。
2. 若当前目录不存在 .env，从 .env.example 复制一份。
3. 把传入的代理订阅地址（若有）写入 .env 的 PROXY_SUB_URL。
4. 创建 proxy、state/cron、state/login-api、state/login-profile、state/browser-profiles、DouYinSparkFlow/logs 目录。
5. 若 proxy/config.yaml 不存在，从 proxy/config.example.yaml 复制；若 state/cron/root 为空，写入默认定时任务（10:00–17:59 每 20 分钟一轮、18:00 最后一轮、18:20 未发送兜底）。
6. 运行 refresh_proxy.sh 生成 / 刷新代理配置。
7. 执行 docker compose up -d --build 构建并启动全部服务。
8. 读取 .env 中的 WEB_PORT，输出控制台访问地址并尝试自动打开浏览器。

6.3 常用运维命令

# 查看全部服务实时日志
docker compose logs -f

# 停止全部服务
docker compose down

# 仅启动 Web 服务（调试用）
docker compose up -d web

# 查看当前运行容器
docker compose ps

# 查看某个服务最近 80 行日志
docker compose logs --tail 80 login-desktop

6.4 远程服务器访问 noVNC 登录桌面

8788 端口默认只绑定服务器 127.0.0.1，远端浏览器不能直接访问。先建立 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

多数情况下无需单独连 noVNC：管理后台会通过当前登录会话提供同源代理，在面板“登录”页直接扫码即可；SSH 隧道仅作为直接访问登录桌面的备选方式。

7 方式二：服务器一键安装脚本（install-server.sh）

仓库 deploy/ 目录还提供 install-server.sh，面向全新 Linux 服务器做全自动安装：检测并安装基础工具与 Docker / Compose 插件、把仓库克隆到 APP_ROOT、生成 .env 与运行时目录、写入默认定时任务、清理宿主机旧版 Docker 定时任务，然后先启动 proxy 容器、再构建并启动 web、login-desktop、scheduler，最后输出 Web 与登录桌面访问地址。

7.1 首次安装

# 在仓库根目录执行（需要 root 或可 sudo）
sudo bash deploy/install-server.sh

脚本默认取值可通过环境变量覆盖：

7.2 后续更新

ACTION=update sudo bash /opt/douyin-sparkflow/deploy/install-server.sh

update 模式会 git fetch 后 checkout / reset --hard 到对应分支，并自动备份、恢复 DouYinSparkFlow/config.json 运行时配置；同时清理宿主机 root crontab 中旧的 Docker 发送任务，避免两套定时器同时运行。脚本末尾提示：运行时数据保留在 Git 仓库之外，包括 .env、state/、proxy/config.yaml、DouYinSparkFlow/logs/、usersData.json、webui_settings.json。

8 方式三：本地开发运行

适用于本地开发与功能测试，需要本机具备 Python 3.10+ 与 Playwright 浏览器环境。

# 1. 克隆仓库并进入应用源码目录
git clone https://github.com/halfwaystudent/douyin-sparkflow.git
cd douyin-sparkflow/DouYinSparkFlow

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

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

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

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

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

本地开发方式下，登录桌面服务脚本面向 Windows PowerShell；Linux 本地调试可参照 docker-compose.yml 中 login-desktop 的启动命令 bash /app/scripts/start_login_desktop.sh 理解其行为。协议发送通道需要 Node.js 18+ 运行 core/protocol_sender.mjs，仅使用浏览器发送通道时可不装 Node。

9 Docker Compose 服务构成

docker-compose.yml 共定义五个服务，首次 docker compose up -d --build 后由 scheduler 按窗口调度发送。

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

10 环境变量配置（.env）

仓库跟踪 .env.example，部署时复制为本地 .env。下表字段与默认值均来自官方模板，可按实际环境调整。

10.1 Web 控制台与通用

10.2 登录桌面（noVNC 与内部 API）

10.3 代理（Mihomo）

10.4 调度、镜像与构建网络

登录、好友刷新和发送任务默认都采用“直连优先，Mihomo 回退”。LOGIN_DESKTOP_PROXY_MODE=auto 时登录浏览器先直连，直连预检失败后才走代理；好友刷新和续火花任务也会在任务开始前选择可用出口，发送动作开始后不会因响应不明确而盲目切换代理重发。没有配置有效订阅时，Mihomo 仅提供 DIRECT-only 配置，回退不会凭空产生代理节点。

11 应用配置文件（config.json）

仓库跟踪 DouYinSparkFlow/config.example.json；首次运行会生成被 Git 忽略的 DouYinSparkFlow/config.json，运行时修改不会被覆盖。下表字段与默认值来自官方模板。

11.1 全局开关与发送通道

11.2 发送策略 sendStrategy

默认变体列表：

• 🤩今日火花+1
• 今天来补个火花
• 给你续一下今天的火花
• 路过给你加个小火花

11.3 每日发送窗口 dailySendWindow

Web 设置里的窗口写法为 10:00-18:00/20m：表示每天 10:00 到 18:00 之间执行，调度间隔 20 分钟。

11.4 消息类型与好友列表扫描

11.5 持久化浏览器配置 persistentBrowserProfiles

11.6 通知推送 notifications

顶层 enabled 控制总开关；channels 下分四个渠道，每个渠道独立 enabled 与 useProxy。

推送策略：同一账号 / 目标 / 类别问题每天只推一次，另有一份每日汇总；失败通知在单次运行内合并；密钥在面板中掩码显示，不会写入日志。

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

12 代理配置（proxy/config.yaml）

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

mixed-port: 7890
allow-lan: true
bind-address: '*'
mode: rule
log-level: info
external-controller: '0.0.0.0:9090'

rules:
  - MATCH,DIRECT

• PROXY_SUB_URL 不为空时，refresh_proxy.sh 会下载订阅并更新本地配置；为空则生成上述 DIRECT-only 配置。
• 不要在 Git 中提交包含订阅 token 的 proxy/config.yaml。
• 首次部署不要跳过初始化步骤直接执行 docker compose up -d，否则 Docker 可能把缺失的配置文件创建成目录。
• Mihomo 控制接口（9090）需要密码：refresh_proxy.sh（以及 Windows 的 deploy/install-local.ps1）首次运行生成随机密码，保存在 state/proxy/controller-secret 并写入 proxy/config.yaml 的 secret，之后刷新订阅沿用同一密码；想自定义时在 .env 设置 PROXY_CONTROLLER_SECRET 后再运行一次 refresh_proxy.sh。通过 SSH 隧道用 metacubexd 等面板连接控制接口时，需要填写这个密码：

cat state/proxy/controller-secret

13 部署后的使用流程

本节按官方 docs/usage.md 的第一次操作顺序编写：先完成服务器或本地部署并访问 Web 面板，再依次登录账号、选择目标、配置任务、查看进度、处理异常。

13.1 登录控制台

打开 Web 面板地址：

• 服务器部署：http://服务器IP:8787
• 本地部署：http://127.0.0.1:8787

首次打开时创建管理员账号；后续登录输入管理员用户名和密码。

登录保护与密码规则

• 连续输错同一用户名和网络来源组合 5 次，会锁定这一组合 15 分钟。
• 同一用户名在不同网络来源累计输错 10 次后进入慢速模式：30 秒只能尝试一次。系统不会按整个 IP 地址锁定，避免同一网络中的其他人被一起锁住。
• 被锁时先停止反复尝试：等待 15 分钟，或换一个网络后再登录；慢速模式只需等 30 秒再试。
• 新建或修改面板密码时，密码至少 10 位，且要包含字母、数字、符号中的至少两类；不能包含用户名，也不要使用重复字符组成的简单密码。已有密码不会因为这条规则失效。

13.2 查看今日进度

登录后进入 今日 页。标题直接告诉你今天还差几个火花，下面是进度环、下一轮发送时间、需要处理的目标和每个账号的进度。第一次打开时跟随手机或电脑的深浅色设置；点月亮 / 太阳图标手动切换，选择保存在当前浏览器中。电脑导航在左侧，手机在底部标签栏。

13.3 登录抖音账号

进入 登录 页，点 添加新账号。二维码大图显示在左侧，远端浏览器在右侧，验证码等人工验证步骤直接在远端浏览器里完成。

• noVNC 默认只监听服务器 127.0.0.1:8788，管理后台会通过当前登录会话提供同源代理，电脑或手机直接在 登录 页操作即可。
• 手机端会显示单独的大图二维码，可直接扫码，或长按保存后从抖音扫码页面读取相册图片。
• 需要直接访问 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。登录完成后点击 保存新账号。

13.4 维护账号、好友和群聊目标

进入 账号 页查看已保存的账号：可以启用或停用账号、修改显示名、维护目标；登录态失效时点 重新登录，会带着这个账号跳到登录页。

好友目标

点击 刷新好友列表，再从好友选择器中选择目标好友；保存后定时任务按这些目标执行续火花。通过选择器保存的好友按 UID 绑定，改昵称后也能跟随。也可以每行手动填写一个昵称补充好友。

群聊目标

1. 在同一账号的“群聊目标”区域点击 刷新群列表。
2. 从列表勾选要发送的群；每项显示为 群名（完整会话编号），保存后按该编号绑定，不会因改名或同名群选错。
3. 刷新失败、扫描不完整、绑定的编号找不到，或发送前核对到目标变化时，系统会跳过该群，不发送也不猜测选择。

• 可以手动填写群名，但这类目标没有绑定编号，只支持当前列表第一屏内的群；同名或找不到时同样不会发送。
• 群聊只能使用浏览器发送通道，不能使用协议发送通道。

账号巡查入口

页面下方显示最近一次巡查时间与结果（找到 / 缺失 / 已改名等），也可点击 立即巡查 手动触发一次只读巡查。

13.5 设置运行参数和发送窗口

进入 设置 调整消息模板、随机策略、消息间隔、发送窗口、运维操作和 Web 用户。

发送窗口使用北京时间，格式为 开始:结束/间隔m，例如：

10:00-18:00/20m

表示每天 10:00 到 18:00 之间执行，调度间隔为 20 分钟。消息设置区可配置：固定消息模板、消息变体（每行一条，优先随机挑选）、两条消息最短 / 最长间隔、发送顺序（随机打乱等）。

13.6 账号巡查

系统会在发送窗口开始前约半小时进行只读巡查，也可以在 账号 页点 立即巡查。巡查检查：登录状态、当前登录账号身份、好友目标和群聊目标是否仍能找到；群聊按已绑定的会话编号检查，并提示改名、未绑定、缺失或未检查。巡查不打开聊天、不发送消息；登录失效或目标异常时，先处理提示的问题，再决定是否手动重试。

13.7 处理发送结果和日志

在 发送明细 页查看每个目标今天的发送结果。

• 已确认：收到足够明确的服务端或协议回执，作为当天已发送成功。
• 待核验：发送过程或回执不足以确认结果。协议回执字段不完整、格式未知、包含拒绝信息，或无法确定是否已被服务端接受时，系统宁可保留为待核验。
• 被拒绝及拒绝代码：平台回执明确表示未接受时，明细显示拒绝原因和可识别代码；按原因处理，不要直接反复发送。
• 仅页面回显 / 仅回执：属于较弱证据，页面单独显示，可由你决定是否标记为待核验后重试。

系统不会因为结果未知自动重发，避免实际已经送达时重复打扰对方。需要补发时，在明细中逐个确认后使用 重试，或使用 补发异常；全部重发 会包含今天已经强确认成功的目标，只有确认范围无误时才使用。需要排查问题时，管理员可进入 运行日志 查看最近任务输出，支持过滤和自动刷新。

13.8 使用暗色模式

暗色模式适合夜间运维或长时间盯屏，点击月亮图标即可切换。

14 消息模板与发送策略细化

14.1 内置模板类型

• 一言（Hitokoto）：随机抽取诗词、名言警句等，分类范围由 hitokotoTypes 控制（默认文学、影视、诗词、哲学）。
• 节日祝福：happyNewYear.enabled 开启后，自动识别节假日发送对应祝福语。
• 自定义消息：支持纯文本固定模板；填写消息变体后优先从变体里随机挑选。

14.2 发送策略

• 时间窗口按 dailySendWindow 与 Web 设置中的 10:00-18:00/20m 口径执行。
• 可配置发送间隔与限速（账号启动延迟 15–60 秒、消息间隔 25–70 秒等），用于降低操作频率和对接收方的打扰；不保证规避平台风控，也不保证账号不会受到平台处理。
• 发送失败按类别处理：可重试的失败在窗口内重试；结果不确定的标为“待核验”，不会自动重发。
• 发送确认分级：服务端确认、页面回显、仅回执，在“发送明细”中分别显示。

15 网络、反向代理与 HTTPS 安全

15.1 网络回退策略

登录浏览器、好友 / 群列表刷新和发送浏览器默认直连抖音；未配置 Mihomo 不影响直连。LOGIN_DESKTOP_PROXY_MODE=auto 时先直连 creator.douyin.com，直连预检失败后才使用 LOGIN_DESKTOP_PROXY；任务开始前选择可用出口，发送动作开始后不会因响应不明确而盲目切换代理重发。

15.2 反向代理示例

如需外网访问，建议配置 Nginx / Caddy 反向代理到 8787 端口：

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;
    }
}

15.3 安全建议（官方口径）

• 首次访问面板时创建管理员账号，并使用足够强的密码（系统不提供默认密码）。
• 启用 HTTPS（使用 Let's Encrypt 等证书）；经 HTTPS 反向代理部署时，在 .env 设置 SPARKFLOW_SESSION_COOKIE_SECURE=1。
• 配置防火墙规则，不要把 8788、7890、9090 直接暴露到公网。
• 定期备份 state/ 和 usersData.json。
• 使用环境变量管理敏感配置，订阅 token、Cookie 等不要写入公开仓库或日志。

16 数据持久化与备份

16.1 建议挂载的数据卷

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

实际 docker-compose.yml 中还挂载了 state/cron（定时任务文件）、state/login-api（登录桌面令牌）、state/login-profile（登录浏览器配置）、state/browser-profiles（各账号持久化浏览器配置）等目录。

16.2 运行时敏感数据清单

以下文件 / 目录属于运行时敏感数据，不应提交到 Git，也不应出现在公开日志或不可信服务器上：

• usersData.json：面板用户与账号绑定关系；
• webui_settings.json：面板运行设置；
• 浏览器 Profile 目录与 Cookie；
• state/ 下的登录态、令牌、代理密钥；
• DouYinSparkFlow/logs/ 日志文件。

备份时优先打包 state/、usersData.json、webui_settings.json 与 proxy/config.yaml。

17 升级与回滚

17.1 常规更新

常规部署可直接使用根目录 deploy/install-local.sh 重新初始化并启动；服务器环境使用 install-server.sh 的 ACTION=update（见第 7.2 节）。

17.2 增量发布包（release-files.sh）

需要把两个 Git 提交之间的源码文件发布到现有服务器时，使用 deploy/release-files.sh：先在包含 Git 仓库的本地副本中生成包，再把包传到服务器执行；不要在发送或巡查进行时升级。

# 本地：只查看两个提交之间会更新或删除哪些源码文件
bash deploy/release-files.sh plan <base-commit> <target-commit>

# 本地：生成带清单和校验和的发布包
bash deploy/release-files.sh pack <base-commit> <target-commit> <release-bundle.tgz>

# 服务器：应用发布包；第二个参数可省略，默认是应用源码目录
bash deploy/release-files.sh apply <release-bundle.tgz> [app_dir]

# 服务器：查看当前发布记录
bash deploy/release-files.sh status [app_dir]

# 服务器：回滚最近一次备份；也可指定备份目录和应用目录
bash deploy/release-files.sh rollback [backup_dir] [app_dir]

apply 会先检查发送 / 巡查是否正在运行、服务器文件是否与基线提交一致、发布包校验和是否正确；随后备份触及的文件，安装后校验文件、重启 Web 服务并检查登录页；任一步骤失败会自动回滚。脚本不会自动删除已在新版本中删除的文件，plan 会把这类文件列出来，需确认后手动处理。

18 常见问题排查

18.1 登录工作区打不开 / 二维码一直不出现

先分清是“登录桌面容器坏了”还是“这个会话没拿到工作区”，两者表现和处理方式不同。

1）页面提示“本会话当前未持有登录工作区”，或二维码一直停在“正在读取登录二维码…（已等待 N 秒）”

这是工作区（租约）没有分配给当前会话，不是容器故障。点页面上的“打开登录工作区”重新申请；提示排队时等前面的人释放即可。工作区同一时间只允许一个会话使用，离开或关闭页面会自动释放。

想直接确认租约归谁，在服务器上执行：

cat /opt/douyin-sparkflow/state/login-workspace.lock.json

其中 active.username / active.session_id 是当前持有者；文件不存在说明当前没有人持有。

2）页面提示“登录桌面服务暂时不可用”或“无法访问抖音（网络或代理异常）”

不要只看 /health（它不检查浏览器，也不校验令牌），按下面三条查真实状态：

docker compose ps
docker compose logs --tail 80 login-desktop

# 令牌 + 状态（/health 之外的所有接口都需要这个 Bearer 令牌）
docker compose exec login-desktop sh -lc 'T=$(cat /run/login-api/token); \
  curl -s -H "Authorization: Bearer $T" http://127.0.0.1:18090/status; echo; \
  curl -s -H "Authorization: Bearer $T" http://127.0.0.1:18090/preflight; echo; \
  curl -s -o /dev/null -w "qr=%{http_code}\n" -H "Authorization: Bearer $T" http://127.0.0.1:18090/qr'

# 容器内的显示栈与端口
docker compose exec login-desktop sh -lc 'ls -l /tmp/.X11-unix/; ss -ltn | grep -E "6080|5901|18090"'

• /status 里 running:false 且 /qr 一直是 202：登录浏览器没起来，看日志里有没有 Missing X server 或 Target closed。
• /preflight 不是 200：服务器到抖音的网络不通，检查直连或代理设置。
• /qr 返回 200 但页面不出码：问题在前端或租约，不在容器。

3）确认是网络问题后，再在“系统设置”中选择 Mihomo 并填写代理地址。登录浏览器、好友 / 群列表刷新和发送浏览器默认使用直连，未配置 Mihomo 不影响直连。

18.2 账号保存后没有好友或群列表

进入 账号 页，点击对应的 刷新好友列表 或 刷新群列表。刷新需要当前账号的登录态有效；如果登录态过期，点 重新登录 后在登录页扫码并保存。群列表刷新是只读操作，不会打开群聊或发送消息。

18.3 定时任务没有按预期发送

检查 设置 里的发送窗口，再查看调度容器日志：

docker compose logs -f scheduler

正常情况下可以看到 scheduled send start 和 scheduled send exit rc=0。如果仍看到 docker ps 或 docker exec，说明定时文件还是旧格式；重启 scheduler 后会自动迁移共享定时文件。使用服务器更新脚本时，还会清理宿主机 root crontab 中旧的 Docker 发送任务，防止同一时间运行两遍。

如果只是少量目标失败，先使用 补发异常，不要直接全部重发。

19 技术栈一览

GitHub Actions 工作流位于 .github/workflows/tests.yml，在每次 push、pull_request 或手动触发时运行 Python 单元测试、字节码编译检查（compileall）以及 Node 侧协议发送器测试（node --test）；它不使用任何 Secret、不启动浏览器、不发送任何消息，fork 和外部 PR 也能运行同一套检查。

20 版本更新记录（官方 CHANGELOG 摘要）

• 2026-10-24：新增按会话编号绑定的群聊目标（选择器显示 name（full id），重名、扫描不全、绑定缺失或目标变化时失败关闭而不是发送）；新增 favicon 支持与旧发送控制台锚点重定向；严格的 protobuf message_send 回执解析，只有明确成功才确认，其余不确定响应保持待核验且不自动重发；新增 Web 控制台登录保护（同用户名 + 来源 5 次失败锁 15 分钟，跨来源 10 次失败进入 30 秒慢速模式；新密码至少 10 位、两类字符、不含用户名）；新增 release-files.sh 漂移校验、备份、哈希校验、自动回滚与发布版本记录。
• 2026-10-13：新增运行结果推送通知（Telegram、带签名钉钉、企业微信、通用 JSON Webhook）：单次运行内失败通知合并，按账号 / 目标 / 类别每天去重，另有每日汇总；由管理员在设置页配置，密钥掩码显示且不写入日志。
• 2026-08-27：项目自有代码许可证由 MIT 改为 PolyForm Noncommercial License 1.0.0，后续版本仅源码可见、非商业使用；旧版本仍按其适用许可证条款执行；README 补充非官方、平台风险、账号授权、数据责任、商业使用与知识产权提示。
• 2026-08-25：实验分支默认直连抖音业务流量，Mihomo 改为浏览器流量的显式高级选项；登录浏览器改为直连优先、Mihomo 回退，并给出明确预检错误。
• 2026-07-11：登录桌面资源尖峰优化（Chromium 懒启动、空闲 / 导出后关闭、状态缓存、降低动效、降低 x11vnc 轮询频率、Compose CPU / 内存 / PID 限额）；二维码刷新改为强制抖音登录页生成新的带缓存破坏参数的二维码；修复构建期本地代理变量泄漏到运行时 Chromium 导致的登录桌面空白；新增带认证的同源 noVNC HTTP / WebSocket 代理与同步手机弹窗处理；服务端镜像显式提供 Node.js 22 供协议模式使用；Web 控制台重构为响应式统一运维面板；发送确认状态、可重试未确认目标、失败分类、账号冷却与手动重试模式改进；好友列表发现、持久化浏览器配置、Cookie 同步与浏览器 / 协议失败持久化改进。

21 免责声明与使用限制

以下条款整理自官方 README 与 LICENSE，使用前请完整阅读；如与官方原文不一致，以仓库 LICENSE 与 README 为准。

21.1 非官方项目声明

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

21.2 使用授权与账号责任

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

21.3 平台风险与责任限制

• 抖音可能随时调整服务、接口、页面、风控策略和用户协议。
• 自动化操作可能导致验证码、限流、功能限制、账号异常、账号封禁、登录态失效或其他平台处理。
• 本项目不保证平台兼容性、持续可用性、账号安全或任何特定功能结果，也不提供规避平台风控或绕过平台限制的保证。
• 在法律允许的最大范围内，作者不对因使用、修改、部署或运行本项目产生的账号处置、数据丢失、服务中断、隐私泄露、业务损失或其他损害承担责任；法律不得排除或限制的责任除外。

21.4 消息内容与数据责任

• 使用者对自动发送的消息内容、发送对象、发送频率以及由此产生的骚扰、侵权、违法或其他纠纷承担相应责任。
• 登录态、Cookies、账号信息、好友信息和发送记录可能属于敏感数据。使用者应自行负责其存储、访问控制、备份、传输和删除，不得将相关数据提交到公开仓库、公开日志或不可信服务器。

21.5 商业使用限制（PolyForm Noncommercial 1.0.0）

本项目自有代码采用 PolyForm Noncommercial License 1.0.0。未经版权持有人事先书面授权，禁止将本项目用于以下场景：

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

如需将本项目用于商业场景，请事先联系版权持有人并取得单独的书面商业授权。未经书面授权，不得进行商业使用。

21.6 知识产权与侵权联系

本项目中的自有代码、文档、截图、图标和其他素材分别按照其适用的许可或权利声明使用。抖音名称、商标、页面内容、用户内容及相关数据的权利归相应权利人所有，本项目不主张取得任何相关权利。如认为仓库中的特定文件侵犯了合法权益，请通过 GitHub Issues 提交通知，提供涉嫌侵权的具体文件路径或内容、权利归属或授权证明、侵权理由及可用于回复的联系方式；请勿在公开 Issue 中提交身份证件、账号凭据或其他敏感材料。

22 相关链接汇总

• 项目主页（仓库）：https://github.com/halfwaystudent/douyin-sparkflow
• 问题反馈（Issues）：https://github.com/halfwaystudent/douyin-sparkflow/issues
• 使用文档：docs/usage.md
• 社区讨论：Linux Do 社区
• Star History：star-history.com/#halfwaystudent/douyin-sparkflow&Date
• 许可证：LICENSE（PolyForm Noncommercial 1.0.0）

本文为基于官方公开 README、使用文档、配置模板与部署脚本整理的中文部署指南，仅供学习与非商业用途参考；部署与使用前请自行确认符合目标平台规则与法律法规。