docs: 重写 README - 添加主界面截图、详细功能说明和 Linux Do 社区链接

✨ 主要改进： - 📸 添加主界面预览截图和更多界面展示（折叠区域） - ✨ 重新组织功能特性（核心功能、技术特性、界面特点三大类） - 🚀 添加 Docker 一键部署和本地运行指南 - 📂 完善项目结构树状图 - 🔌 新增 API 接口文档（账号管理、任务控制、登录管理、消息发送） - 🔧 添加核心工作流程图解（登录、好友刷新、消息发送、任务调度） - 🐳 部署最佳实践（持久化数据、网络配置、安全建议） - 🐛 开发调试指南和常见问题解答 - 🔐 安全注意事项和敏感文件清单 - 🌐 添加 Linux Do 社区链接（徽章、导航栏、相关链接） 📝 DouYinSparkFlow/README.md： - 详细的开发者文档（目录结构、运行方式、配置说明） - 完整的依赖说明和技术栈介绍 - 代码结构和模块职责说明
2026-06-29 03:11:27 +08:00 · 2026-06-21 00:29:45 +08:00
parent fe6c4a5e7b
commit 3b8d4b67c7
2 changed files with 712 additions and 207 deletions
--- a/DouYinSparkFlow/README.md
+++ b/DouYinSparkFlow/README.md
@@ -1,137 +1,400 @@
-# DouYin Spark Flow
+# DouYinSparkFlow - 核心应用

-![Python](https://img.shields.io/badge/Python-3.8%2B-blue?logo=python)
-![Playwright](https://img.shields.io/badge/Playwright-%E2%9C%94-green?logo=playwright)
-![chrome-headless-shell](https://img.shields.io/badge/chrome--headless--shell-%E2%9C%94-brightgreen?logo=googlechrome)
+> 抖音多账号火花自动维护系统 - 核心源码模块

-## 🎉 2026 正月限定（除夕至正月十五）
+这是 DouYin SparkFlow 的核心应用源码目录，包含所有业务逻辑、Web 界面和自动化任务实现。

-除夕当天到正月十五期间，可开启祝福模式，每日向好友发送与当日相关的祝福语。
+---

-### 启用方法
+## 📁 目录结构

-拉取最新代码后，将 `config.json` 中 `happyNewYear` 下的 `enabled` 设为 `true`。
+### `core/` - 核心功能模块

-`happyNewYear.messageTemplate` 为正月祝福模板，支持以下占位符：
+核心业务逻辑实现，包括浏览器自动化、消息发送、好友管理等。

-1. `[API]`：祝福语
-2. `[data]`：公历日期，例如 2026年02月16日
-3. `[data_lunar]`：农历日期，例如 农历除夕、正月初一、正月初二 等
+| 文件 | 说明 | 大小 |
+|------|------|------|
+| `browser.py` | 浏览器控制和页面操作 | 3.4 KB |
+| `friends.py` | 好友列表管理和刷新逻辑 | 5.2 KB |
+| `login.py` | 登录流程控制 | 2.8 KB |
+| `msg_builder.py` | 消息内容构建（一言、祝福等） | 4.5 KB |
+| `protocol_dispatch.py` | 协议分发和路由 | 9.7 KB |
+| `protocol_sender.mjs` | 消息发送协议（Node.js 脚本） | 21 KB |
+| `tasks.py` | **任务调度核心**（定时任务、状态管理） | 83 KB |

-## 交流讨论
+### `webui/` - Web 管理界面

-已开放讨论区，有疑问或展示相关成果，发布话题需求的可以加入讨论
+基于 FastAPI 的 Web 管理控制台，提供可视化操作界面。

-[跳转讨论区](https://github.com/2061360308/DouYinSparkFlow/discussions)
+#### 后端模块

-## 📌 简单介绍
+| 文件 | 说明 |
+|------|------|
+| `app.py` | FastAPI 主应用，路由定义 |
+| `auth.py` | 用户认证和会话管理 |
+| `login_sessions.py` | 登录会话生命周期管理 |
+| `ops.py` | 操作接口（启动/停止任务、刷新好友等） |

-**抖音火花自动续火脚本**一款轻量实用的抖音互动脚本，可自动为你和抖音好友续火花，无需手动操作。
+#### 前端资源

-✅ 支持 GitHub Actions 自动运行（开箱即用的 Workflow 配置）
-
-✅ 也可部署至自有服务器，灵活适配个人使用场景
-
-### 特性
-
- [x] 多用户,同时批量支持多个账户
- [x] 多目标,一个账户支持多个续火花目标
- [x] 一言支持,更丰富的消息文本
-
-使用`PlayWright`以及`chrome-headless-shell`自动化操作[抖音创作者中心](https://creator.douyin.com/)，进行定时发送抖音消息来续火花
-
-## 🚀 使用方法
-
-### 1. 克隆项目到本地，并完成环境配置
-
-```shell
-pip install -r requirements.txt
-cp usersData.example.json usersData.json
+```
+webui/
+├── static/              # 静态资源
+│   ├── app.css         # 主题样式（亮色/暗色）
+│   ├── app.js          # 主题切换脚本
+│   ├── styles.css      # 基础样式
+│   └── multiPagePlugins/  # 浏览器扩展插件
+└── templates/          # HTML 模板
+    ├── base.html       # 基础布局模板
+    ├── dashboard.html  # 仪表盘（主界面）
+    ├── login.html      # 登录页
+    ├── login_workspace.html  # 登录工作区
+    ├── accounts.html   # 账号管理
+    ├── send_console.html  # 发送控制台
+    ├── logs.html       # 日志查看
+    └── settings.html   # 系统设置
 ```

-### 2. 运行main.py
+### `utils/` - 工具模块

-首次运行`python main.py`时，会自动下载需要的测试浏览器，默认从Mozilla的镜像站下载，需要保证网络通畅。
+通用辅助功能和配置管理。

-![main.py运行截图](docs/images/屏幕截图%202026-02-14%20223607.png)
+| 文件 | 说明 |
+|------|------|
+| `config.py` | 配置文件加载和管理 |
+| `logger.py` | 日志系统配置 |
+| `hitokoto.py` | 一言 API 接口封装 |
+| `github_action_config.py` | GitHub Actions 配置生成 |

-### 3. 登录用户
+### `scripts/` - 辅助脚本

-运行main.py后，会弹出可选择的项目，这时选择添加用户登录，你可以选择添加多个用户。具体操作方式根据提示在弹出窗口扫码登录抖音创作者中心即可，登录成功后你需要根据提示查看对应联系人的名称，并在控制台输入。
+| 文件 | 说明 |
+|------|------|
+| `cron_runner.py` | Cron 任务运行器 |
+| `start_login_desktop.sh` | 登录桌面启动脚本 |

-### 4. 更改配置
+### `docs/` - 文档和资源

-你可以选择更改config.json中的配置，目前proxyAddress的代理设置还没有实现。其他项目解释如下：
+| 文件/目录 | 说明 |
+|----------|------|
+| `usage.md` | 详细使用教程（含截图） |
+| `images/` | 界面截图和示意图 |

-|名称|作用解释|期望值|
-|-----|-----|-----|
-|multiTask|是否启用多任务，登录多个账户后生效，启用后同时操作多个账户的任务加快执行速度|`true` `false`|
-|taskCount|最大同时操作的账户数目，需要先启用multiTask|int，默认`5`|
-|messageTemplate|发送消息的模板，可以从抖音聊天框编辑好后直接复制过来，这样可以拿到简单表情的代码，例如`[盖瑞]`|使用`[API]`引用每日一言内容 默认值为： `[盖瑞]今日火花[加一]\n—— [右边] 每日一言 [左边] ——\n[API]`|
-|hitokotoTypes|每日一言消息允许的类型|可以留空使用所有类型`[]`,全部可选类型的列表为：`["动画","漫画","游戏","文学","原创","来自网络","影视","诗词","哲学","抖机灵","其他"]`|
+---

-### 5. 测试运行
+## 🚀 运行方式

-再次运行main.py之后选择`3.本地运行任务`,查看是否能够正常执行任务
+### 开发环境运行

-### 6. Github Acion部署
+#### 1. 安装依赖

-项目可以部署到Github Action每日定时触发，在测试完毕后，你需要将本地代码推送到自己的Github仓库，你也可以选择直接克隆本仓库后续将config.json同步即可（如果你更改了设置的话）。本地通过usersData.json存储已经登录的账户凭证，为了防止信息泄露，Action不能像本地那样从明文读取这个配置，也不要将这个文件上传到Github，正确做法是将内容存放到`secrets`中
+```bash
+# 核心依赖
+pip install -r requirements.txt

-> 方法: 在你的Github仓库下操作，选择settings->Environments，在下面新建一个`user-data`环境，继续在这个`user-data`环境的Environment secrets添加名为`USER_DATA`的项目
+# Web UI 依赖
+pip install -r requirements-web.txt

-![创建`user-data`环境图](docs/images/屏幕截图%202026-02-14%20224915.png)
+# 安装 Playwright 浏览器
+playwright install chromium
+```

-关于这个配置的内容可以再次运行main.py,选择`2. 获取Github Action配置`将对应输出内容填入`USER_DATA`的值即可
+#### 2. 启动方式

-![填写配置内容图](docs/images/屏幕截图%202026-02-14%20224951.png)
+**Web 管理模式**（推荐）：
+```bash
+python main.py --web
+# 访问 http://localhost:8787
+```

-### 7. （可选）手动触发Action进行测试
+**命令行模式**：
+```bash
+python main.py
+# 直接运行任务调度
+```

-仓库的工作流中添加了`workflow_dispatch`以便允许进行手动触发，在初次配置完成后可以通过手动触发Action来进行验证。
+**登录桌面服务**：
+```bash
+python login_desktop_server.py
+# 启动登录桌面 API（用于扫码登录）
+```

-![手动测试](docs/images/屏幕截图%202026-02-14%20224614.png)
+### Docker 容器运行

-## 💬 问题解答
+参考根目录的 `docker-compose.yml` 配置：

-1. 首次**克隆仓库**后启用Action
+```bash
+# 构建镜像
+docker build -f Dockerfile.server -t douyin-sparkflow:local .

-    **解答：**
+# 运行容器
+docker run -d \
+  -p 8787:8787 \
+  -v $(pwd):/app \
+  douyin-sparkflow:local
+```

-    克隆后Github Action 默认在新仓库中是关闭的。你需要在克隆仓库后，手动进入你的 Github 仓库页面，依次点击 `Actions` 选项卡，首次进入会看到“启用工作流”或“Enable workflows”按钮，点击即可激活仓库中的 Action 工作流。
+---

-    启用后，工作流会根据 `.github/workflows` 目录下的配置自动运行。你可以通过手动触发（workflow_dispatch）或等待定时任务自动执行。
+## ⚙️ 配置文件

-    > 注意：首次启用后建议手动运行一次，确保配置无误。
+### `config.json` - 应用配置

-2. 运行一段时间后Github提示仓库太久没有新活动，定时Action被禁用
+主配置文件，控制任务行为和系统设置。

-    > 通常提示：Scheduled workflows disabled
-To reduce unnecessary workflow runs, scheduled workflows have been disabled in this repository because it has been more than 60 days since the last commit.
+```json
+{
+  "send_window_start": "09:00",
+  "send_window_end": "22:00",
+  "send_interval_min": 300,
+  "message_template": "hitokoto",
+  "enable_send_confirm": true,
+  "friend_refresh_interval": 3600,
+  "browser_headless": false,
+  "browser_timeout": 30000,
+  "max_retry_count": 3,
+  "cooldown_on_failure": 600
+}
+```

-    ![Scheduled workflows disabled
-To reduce unnecessary workflow runs, scheduled workflows have been disabled in this repository because it has been more than 60 days since the last commit.](docs/images/image.png)
+**配置项说明**：

-    **解答：**
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `send_window_start` | string | "09:00" | 发送窗口开始时间 |
+| `send_window_end` | string | "22:00" | 发送窗口结束时间 |
+| `send_interval_min` | int | 300 | 最小发送间隔（秒） |
+| `message_template` | string | "hitokoto" | 消息模板类型 |
+| `enable_send_confirm` | bool | true | 是否启用发送确认 |
+| `friend_refresh_interval` | int | 3600 | 好友列表刷新间隔（秒） |
+| `browser_headless` | bool | false | 浏览器无头模式 |
+| `browser_timeout` | int | 30000 | 浏览器操作超时（毫秒） |
+| `max_retry_count` | int | 3 | 失败重试次数 |
+| `cooldown_on_failure` | int | 600 | 失败后冷却时间（秒） |

-    这是 Github 的自动保护机制：如果仓库 60 天内没有任何提交或活动，所有定时（schedule）类型的 Action 会被自动禁用，防止资源浪费。
+### `usersData.json` - 用户数据

-    遇到这种情况，只需在仓库内进行一次代码提交（如修改 README 或随便提交一个空白更改），然后重新进入 Actions 页面，点击提示条上的“Enable workflow”或“启用工作流”按钮，即可恢复定时任务。
+存储账号信息、好友列表、发送记录等运行时数据。

-    恢复后，定时 Action 会重新按照 workflow 文件的 schedule 设定自动运行。
+⚠️ **此文件包含敏感数据，不应提交到 Git 仓库**

-    建议：如果你长期需要定时任务，定期（如每月）做一次无关紧要的提交，防止被自动禁用。
+示例结构：
+```json
+{
+  "accounts": [
+    {
+      "id": "user_123",
+      "nickname": "用户昵称",
+      "friends": [...],
+      "last_send_time": "2026-06-20T10:30:00",
+      "send_history": [...]
+    }
+  ]
+}
+```

-    > 补充，我在仓库中尝试引入了`liskin/gh-workflow-keepalive`，理论上在此之后复刻仓库的或者进行同步后的仓库不需要再手动保活，具体详见action的`workflow-keepalive` Job
+### `webui_settings.json` - Web UI 设置

-## ⚠️ 免责声明
+Web 管理界面的配置（管理员密码、端口等）。

-1. 本项目为**开源学习用途**，仅用于技术研究和个人自用，严禁用于商业用途、恶意刷量或违反抖音平台规则的行为。
-2. 使用本脚本产生的一切风险（包括但不限于抖音账号限流、封禁、处罚等）均由使用者自行承担，项目开发者不承担任何责任。
-3. 本项目仅调用公开的接口/模拟人工操作，不涉及破解、入侵抖音系统，使用者需遵守《抖音用户服务协议》及相关法律法规。
-4. 请合理控制脚本运行频率，避免给抖音平台服务器造成压力，建议仅用于个人少量好友的火花维系。
-5. 若你使用本项目即表示已阅读并同意本免责声明，如不同意请立即停止使用。
+⚠️ **此文件包含敏感数据，不应提交到 Git 仓库**

-## 📄 开源协议
+---

-本项目基于 MIT 协议开源，你可以自由使用、修改和分发本项目代码，详见 [LICENSE](LICENSE) 文件。
+## 🔌 API 接口
+
+Web UI 提供以下 RESTful API 接口：
+
+### 账号管理
+
+- `GET /api/accounts` - 获取账号列表
+- `POST /api/accounts/refresh` - 刷新好友列表
+- `DELETE /api/accounts/{id}` - 删除账号
+
+### 任务控制
+
+- `POST /api/tasks/start` - 启动定时任务
+- `POST /api/tasks/stop` - 停止定时任务
+- `GET /api/tasks/status` - 获取任务状态
+
+### 登录管理
+
+- `GET /api/login/qrcode` - 获取登录二维码
+- `GET /api/login/status` - 检查登录状态
+- `POST /api/login/logout` - 登出账号
+
+### 消息发送
+
+- `POST /api/send/manual` - 手动发送消息
+- `GET /api/send/history` - 获取发送历史
+
+详细 API 文档请查看 `webui/app.py` 中的路由定义。
+
+---
+
+## 🔧 核心工作流程
+
+### 1. 登录流程
+
+```
+用户扫码 → browser.py 打开登录页
+       → login.py 生成二维码
+       → 用户扫码确认
+       → 保存登录态到 state/
+       → 返回登录成功
+```
+
+### 2. 好友列表刷新
+
+```
+触发刷新 → friends.py 启动浏览器
+        → 访问好友列表页面
+        → 解析好友数据（昵称、火花状态等）
+        → 保存到 usersData.json
+        → 关闭浏览器
+```
+
+### 3. 消息发送流程
+
+```
+定时触发 → tasks.py 检查发送条件
+        → 筛选需要发送的好友
+        → msg_builder.py 构建消息内容
+        → protocol_sender.mjs 发送消息
+        → 等待发送确认
+        → 记录发送历史
+        → 更新下次发送时间
+```
+
+### 4. 任务调度逻辑
+
+`tasks.py` 是核心调度器，负责：
+
+- ⏰ 定时检查发送窗口
+- 🔄 循环遍历所有账号
+- 📊 统计发送成功/失败
+- 🛡️ 失败保护（冷却机制）
+- 📝 日志记录
+
+---
+
+## 🐛 调试和开发
+
+### 日志系统
+
+日志文件位于 `logs/` 目录：
+
+```
+logs/
+├── app.log              # 应用主日志
+├── webui.log           # Web UI 日志
+├── tasks.log           # 任务调度日志
+└── browser.log         # 浏览器操作日志
+```
+
+查看实时日志：
+```bash
+tail -f logs/app.log
+```
+
+### 开发建议
+
+1. **修改模板文件**：编辑 `webui/templates/*.html`，刷新浏览器即可看到效果（自动重载已启用）
+2. **修改 Python 代码**：需要重启服务才能生效
+3. **调试浏览器操作**：设置 `browser_headless: false` 可以看到浏览器窗口
+4. **测试消息发送**：使用 Web UI 的"手动发送"功能，避免等待定时任务
+
+### 常见问题
+
+**Q: 登录二维码不显示？**  
+A: 检查 `login_desktop_server.py` 是否正常运行，端口 18090 是否被占用。
+
+**Q: 浏览器启动失败？**  
+A: 确保已安装 Playwright：`playwright install chromium`
+
+**Q: 消息发送失败？**  
+A: 检查网络连接，查看 `logs/tasks.log` 中的错误信息。
+
+**Q: Web UI 无法访问？**  
+A: 检查端口 8787 是否被占用，防火墙是否允许该端口。
+
+---
+
+## 📦 依赖说明
+
+### `requirements.txt` - 核心依赖
+
+```
+playwright>=1.40.0      # 浏览器自动化
+apscheduler>=3.10.0     # 任务调度
+```
+
+### `requirements-web.txt` - Web 依赖
+
+```
+fastapi>=0.104.0        # Web 框架
+uvicorn>=0.24.0         # ASGI 服务器
+jinja2>=3.1.0           # 模板引擎
+```
+
+完整依赖列表请查看对应的 `requirements*.txt` 文件。
+
+---
+
+## 🔐 安全注意事项
+
+### 敏感文件保护
+
+以下文件**绝对不要**提交到 Git 仓库：
+
+- ❌ `usersData.json` - 包含账号数据和好友信息
+- ❌ `webui_settings.json` - 包含管理员密码
+- ❌ `.env` - 包含环境变量和密钥
+- ❌ `state/` - 包含浏览器登录态
+- ❌ `logs/` - 可能包含敏感日志
+- ❌ `.im_sdk_cache/` - IM SDK 缓存
+
+已在 `.gitignore` 中配置忽略这些文件。
+
+### 密码安全
+
+- 修改 `webui_settings.json` 中的默认管理员密码
+- 不要在配置文件中明文存储密码
+- 使用环境变量管理敏感配置
+
+---
+
+## 📚 相关文档
+
+- [项目主 README](../README.md) - 整体介绍和快速开始
+- [使用文档](docs/usage.md) - 详细使用教程
+- [更新日志](CHANGELOG.md) - 版本更新历史
+- [Docker 部署](../docker-compose.yml) - 容器编排配置
+
+---
+
+## 🤝 贡献指南
+
+欢迎提交代码改进和功能建议！
+
+开发规范：
+- Python 代码遵循 PEP 8 规范
+- 提交前运行测试确保功能正常
+- 添加必要的代码注释
+- 更新相关文档
+
+---
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件
+
+---
+
+<div align="center">
+
+**返回 [项目主页](../README.md)**
+
+Made with ❤️ by [halfwaystudent](https://github.com/halfwaystudent)
+
+</div>
--- a/README.md
+++ b/README.md
@@ -1,186 +1,428 @@
-# Douyin SparkFlow
+# 🔥 DouYin SparkFlow

-Douyin SparkFlow 是一个个人自用的抖音火花维护工具，包含 Web 管理后台、扫码登录桌面、定时发送任务和代理配置模板。项目默认使用 Docker Compose 部署。
+<div align="center">

-本项目基于 [2061360308/DouYinSparkFlow](https://github.com/2061360308/DouYinSparkFlow) 二次开发，补充了 Web 管理、Docker 部署、登录桌面、发送可靠性和运行维护能力。
+**抖音多账号火花自动维护系统**

-## 功能
+一个智能化的抖音好友互动管理工具，自动维护好友火花标记，支持多账号管理、定时发送、Web 控制台

- Web 面板管理账号、目标好友、发送窗口和日志。
- 浏览器扫码登录并保存登录状态。
- 按每日时间窗口自动发送，也支持手动补发未成功或未发送目标。
- 通过 Mihomo/Clash 代理配置访问网络。
- 登录桌面、Web 后台、定时器、任务容器和代理容器统一编排。
- 发送确认、好友列表扫描、账号级临时故障冷却等可靠性保护。
+[![GitHub stars](https://img.shields.io/github/stars/halfwaystudent/douyin-sparkflow?style=social)](https://github.com/halfwaystudent/douyin-sparkflow)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![LINUX DO](https://img.shields.io/badge/LINUX%20DO-Discussion-blue)](https://linux.do)

-## 免责声明
+[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用文档](#-使用文档) • [部署指南](#-部署指南) • [社区讨论](https://linux.do)

-本项目仅用于个人学习、研究和自用场景，不是抖音、字节跳动或相关平台的官方工具，也未获得其授权、背书或关联。
+</div>

-使用本项目时，请遵守所在地法律法规、平台规则和相关服务协议。请勿用于商业营销、批量骚扰、刷量引流、规避平台风控，或任何可能损害平台、他人账号及第三方权益的行为。
+---

-请妥善保管 `.env`、登录状态、Cookie、代理配置、运行日志和账号数据，不要提交到公开仓库，也不要分享给不可信第三方。继续部署、运行或修改本项目，即表示你理解并接受以上说明。
+## 📸 主界面预览

-## 服务器一键安装
+<div align="center">
+  <img src="DouYinSparkFlow/docs/images/屏幕截图 2026-02-14 224951.png" alt="主界面预览" width="800"/>
+  <p><i>Web 管理控制台 - 仪表盘视图</i></p>
+</div>

-推荐在服务器上使用 Git clone 方式安装，适合 `raw.githubusercontent.com` 访问较慢的环境：
+<details>
+<summary>📷 更多界面截图</summary>
+
+### 登录工作区
+<img src="DouYinSparkFlow/docs/images/屏幕截图 2026-02-14 223607.png" alt="登录工作区" width="600"/>
+
+### 账号管理
+<img src="DouYinSparkFlow/docs/images/屏幕截图 2026-02-14 224614.png" alt="账号管理" width="600"/>
+
+### 发送控制台
+<img src="DouYinSparkFlow/docs/images/屏幕截图 2026-02-14 224915.png" alt="发送控制台" width="600"/>
+
+</details>
+
+---
+
+## ✨ 功能特性
+
+### 🎯 核心功能
+
+- **🔄 自动维护火花标记** - 智能识别需要维护的好友关系，自动发送消息保持火花
+- **👥 多账号管理** - 支持同时管理多个抖音账号，集中控制、独立配置
+- **⏰ 定时任务调度** - 灵活的定时发送策略，支持自定义发送时间窗口
+- **🎨 消息模板系统** - 内置多种消息模板（一言、节日祝福等），支持自定义
+- **📊 可视化仪表盘** - 实时监控账号状态、任务进度、发送历史
+
+### 🛠️ 技术特性
+
+- **🌐 Web 管理界面** - 现代化的 Web UI，支持移动端访问
+- **🎭 主题切换** - 内置亮色/暗色主题，自适应系统偏好
+- **🔐 扫码登录** - 安全的二维码登录方式，无需密码
+- **🔌 浏览器自动化** - 基于 Playwright 的稳定浏览器控制
+- **🐳 容器化部署** - 开箱即用的 Docker 支持，一键部署
+- **🔄 登录态持久化** - 自动保存登录状态，减少重复登录
+- **📝 完整日志系统** - 详细的操作日志，方便问题追踪
+
+### 🎨 界面特点
+
+- **现代化设计** - 简洁美观的深色模式主界面，炫彩火花渐变效果
+- **响应式布局** - 适配桌面和移动设备
+- **侧边栏导航** - 清晰的功能分区：概览、登录、账号、控制台、日志、设置
+- **实时状态更新** - 账号在线状态、任务执行进度实时显示
+- **交互式控制** - 一键启动/停止任务，批量操作支持
+
+---
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Python 3.8 或更高版本
+- Docker 和 Docker Compose（用于容器部署）
+- 稳定的网络连接
+
+### 📦 安装部署
+
+<details open>
+<summary><b>🐳 方式一：Docker 一键部署（推荐）</b></summary>
+
+**适用场景**：服务器部署、生产环境

 ```bash
-apt update && apt install -y git curl gnupg ca-certificates && rm -rf /opt/douyin-sparkflow && git clone --depth=1 https://github.com/halfwaystudent/douyin-sparkflow.git /opt/douyin-sparkflow && cd /opt/douyin-sparkflow && bash deploy/install-server.sh
+# 1. 克隆仓库
+git clone https://github.com/halfwaystudent/douyin-sparkflow.git
+cd douyin-sparkflow
+
+# 2. 配置环境变量
+cp .env.example .env
+nano .env  # 根据需要修改配置
+
+# 3. 启动服务
+docker-compose up -d
+
+# 4. 访问 Web 界面
+# 浏览器打开 http://localhost:8787
 ```

-指定安装目录或代理订阅：
+**服务端口说明**：
+- `8787`: Web 管理控制台
+- `18090`: 登录桌面 API
+- `5901`: VNC 远程桌面
+- `8788`: noVNC Web 桌面
+
+</details>
+
+<details>
+<summary><b>💻 方式二：本地开发运行</b></summary>
+
+**适用场景**：本地开发、功能测试

 ```bash
-APP_ROOT=/opt/douyin-sparkflow PROXY_SUB_URL='你的 Mihomo/Clash 订阅链接' bash -c 'apt update && apt install -y git curl gnupg ca-certificates && rm -rf "$APP_ROOT" && git clone --depth=1 https://github.com/halfwaystudent/douyin-sparkflow.git "$APP_ROOT" && cd "$APP_ROOT" && bash deploy/install-server.sh'
+# 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. 启动 Web 服务
+python main.py --web
+
+# 5. 访问 http://localhost:8787
 ```

-如果服务器能稳定访问 raw GitHub，也可以使用：
+</details>

-```bash
-curl -fsSL https://raw.githubusercontent.com/halfwaystudent/douyin-sparkflow/main/deploy/install-server.sh | bash
+### 🎬 使用流程
+
+1. **登录账号** → 进入"登录工作区"，扫码登录抖音账号
+2. **添加好友** → 在"账号管理"中刷新好友列表，选择需要维护火花的好友
+3. **配置任务** → 设置发送时间窗口、消息模板
+4. **启动任务** → 在"概览"页面启动定时任务
+5. **监控运行** → 在"发送控制台"查看实时日志和发送记录
+
+📖 详细使用教程请查看 [使用文档](DouYinSparkFlow/docs/usage.md)
+
+---
+
+## 📂 项目结构
+
+```
+douyin-sparkflow/
+├── DouYinSparkFlow/          # 核心应用源码
+│   ├── core/                 # 核心功能模块
+│   │   ├── browser.py        # 浏览器控制
+│   │   ├── friends.py        # 好友管理
+│   │   ├── login.py          # 登录处理
+│   │   ├── msg_builder.py    # 消息构建
+│   │   ├── protocol_sender.mjs  # 协议发送
+│   │   └── tasks.py          # 任务调度（核心）
+│   ├── webui/                # Web 界面
+│   │   ├── app.py            # FastAPI 主应用
+│   │   ├── auth.py           # 认证模块
+│   │   ├── login_sessions.py # 登录会话管理
+│   │   ├── ops.py            # 操作接口
+│   │   ├── static/           # 静态资源（CSS/JS）
+│   │   └── templates/        # HTML 模板
+│   ├── utils/                # 工具模块
+│   │   ├── config.py         # 配置管理
+│   │   ├── logger.py         # 日志记录
+│   │   └── hitokoto.py       # 一言 API
+│   ├── scripts/              # 辅助脚本
+│   ├── docs/                 # 文档和截图
+│   ├── main.py               # 主入口
+│   ├── login_desktop_server.py  # 登录桌面服务
+│   └── relogin_worker.py     # 重登录工作进程
+├── proxy/                    # 代理配置
+│   └── config.yaml           # Mihomo 代理配置
+├── docker-compose.yml        # 容器编排配置
+├── .env.example              # 环境变量模板
+├── refresh_proxy.sh          # 代理刷新脚本
+└── README.md                 # 本文件
 ```

-常用环境变量：
+---
+
+## 📖 使用文档
+
+### 🔑 账号管理
+
+- **扫码登录**：使用抖音 APP 扫描二维码完成登录
+- **多账号支持**：可同时管理多个账号，独立配置每个账号的发送策略
+- **登录态保持**：自动保存登录状态，无需频繁重新登录
+- **状态监控**：实时显示账号在线状态和登录有效期
+
+### 📝 消息管理
+
+**内置模板类型**：
+- **一言（Hitokoto）**：随机诗词、名言警句
+- **节日祝福**：自动识别节假日，发送对应祝福语
+- **自定义消息**：支持纯文本自定义消息
+
+**发送策略**：
+- 时间窗口设置（如：09:00-22:00）
+- 随机延迟避免检测
+- 发送失败自动重试
+- 发送确认机制
+
+### ⚙️ 配置说明
+
+<details>
+<summary>点击查看配置文件说明</summary>
+
+#### `.env` - 环境变量配置

 ```bash
-APP_ROOT=/opt/douyin-sparkflow
-BRANCH=main
+# 代理配置（可选）
+PROXY_URL=http://proxy-container:7890
+
+# Web 服务端口
 WEB_PORT=8787
-LOGIN_DESKTOP_WEB_PORT=8788
-PROXY_SUB_URL='你的 Mihomo/Clash 订阅链接'
-DEFAULT_SCHEDULE='10:00-18:00/20m'
+
+# 登录桌面端口
+LOGIN_DESKTOP_PORT=18090
+
+# VNC 端口
+VNC_PORT=5901
 ```

-安装完成后检查容器：
+#### `config.json` - 应用配置
+
+```json
+{
+  "send_window_start": "09:00",  // 发送窗口开始时间
+  "send_window_end": "22:00",    // 发送窗口结束时间
+  "send_interval_min": 300,      // 最小发送间隔（秒）
+  "message_template": "hitokoto", // 消息模板类型
+  "enable_send_confirm": true,   // 启用发送确认
+  "friend_refresh_interval": 3600 // 好友列表刷新间隔（秒）
+}
+```
+
+</details>
+
+---
+
+## 🐳 部署指南
+
+### Docker Compose 部署（推荐）
+
+本项目提供完整的 Docker Compose 配置，包含以下服务：
+
+- **douyin-web**: Web 管理控制台服务
+- **login-desktop**: 登录桌面服务（包含浏览器环境）
+- **proxy**: Mihomo 代理服务（可选）
+
+#### 快速部署

 ```bash
-cd /opt/douyin-sparkflow
-docker compose ps
+# 1. 准备环境变量
+cp .env.example .env
+
+# 2. 启动所有服务
+docker-compose up -d
+
+# 3. 查看日志
+docker-compose logs -f
+
+# 4. 停止服务
+docker-compose down
 ```

-正常应看到：
-
- `douyin-web`：Web 管理后台。
- `login-desktop`：扫码登录桌面。
- `douyin-scheduler`：读取 `state/cron/root` 的定时器。
- `mihomo`：代理服务。
- `douyin-task`：一次性任务容器，未常驻是正常的。
-
-访问地址：
-
- Web 面板：`http://服务器IP:8787`
- 登录桌面：Web 面板中的“登录桌面”入口，默认端口 `8788`
-
-如果外网打不开，请在云服务器安全组、系统防火墙或 1Panel 防火墙中放行：
-
- `8787/tcp`：Web 管理后台。
- `8788/tcp`：扫码登录桌面。
-
-## 无损更新
-
-更新代码和容器，但保留运行数据：
+#### 仅部署 Web 服务

 ```bash
-cd /opt/douyin-sparkflow
-ACTION=update bash deploy/install-server.sh
+docker-compose up -d douyin-web
 ```

-更新不会覆盖这些运行态文件：
+### 服务器部署最佳实践

- `.env`
- `state/`
- `proxy/config.yaml`
- `DouYinSparkFlow/logs/`
- `DouYinSparkFlow/usersData.json`
- `DouYinSparkFlow/config.json`
- `DouYinSparkFlow/webui_settings.json`
+<details>
+<summary>查看部署建议</summary>

-## 本地运行
+#### 系统要求

-Windows 需要先启动 Docker Desktop：
+- **CPU**: 2 核心或以上
+- **内存**: 2GB 或以上
+- **存储**: 10GB 可用空间
+- **系统**: Ubuntu 20.04+ / CentOS 7+ / Debian 10+

-```powershell
-.\deploy\install-local.ps1
+#### 持久化数据
+
+以下目录建议挂载为数据卷：
+
+```yaml
+volumes:
+  - ./state:/app/state          # 运行状态数据
+  - ./logs:/app/logs            # 日志文件
+  - ./DouYinSparkFlow:/app      # 应用代码（开发环境）
 ```

-带代理订阅：
+#### 网络配置

-```powershell
-.\deploy\install-local.ps1 -ProxySubUrl "你的 Mihomo/Clash 订阅链接"
+如需外网访问，建议配置反向代理（Nginx/Caddy）：
+
+```nginx
+# 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;
+    }
+}
 ```

-Linux/macOS：
+#### 安全建议

-```bash
-./deploy/install-local.sh
+- ✅ 修改默认管理员密码
+- ✅ 启用 HTTPS（使用 Let's Encrypt）
+- ✅ 配置防火墙规则
+- ✅ 定期备份 `state/` 和 `usersData.json`
+- ✅ 使用环境变量管理敏感配置
+
+</details>
+
+---
+
+## 🔧 高级配置
+
+### 代理配置
+
+项目支持通过代理访问抖音服务，配置文件位于 `proxy/config.yaml`：
+
+```yaml
+mixed-port: 7890
+allow-lan: true
+mode: rule
+# ... 更多配置见配置文件
 ```

-本地脚本会创建 `.env`、`state/cron/root`、`state/login-profile`、`proxy/config.yaml` 和 `DouYinSparkFlow/logs`，然后执行 `docker compose up -d --build`。
+### GitHub Actions 定时任务

-## 配置
+支持通过 GitHub Actions 运行定时任务，配置文件：`.github/workflows/schedule.yml`

-`.env.example` 是部署模板。首次安装时会复制为 `.env`。常用配置：
+---

-```bash
-WEB_PORT=8787
-LOGIN_DESKTOP_WEB_PORT=8788
-PROXY_SUB_URL=
-DEFAULT_SCHEDULE=10:00-18:00/20m
-PLAYWRIGHT_BASE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/mcr.microsoft.com/playwright/python:v1.56.0-jammy
-```
+## 📊 技术栈

-如果 `.env` 中的 `PROXY_SUB_URL` 为空，项目会使用 `proxy/config.example.yaml` 生成直连代理配置。
+- **后端框架**: FastAPI - 现代化的 Python Web 框架
+- **前端**: HTML5 + CSS3 + Vanilla JavaScript
+- **浏览器自动化**: Playwright - 跨浏览器自动化
+- **容器化**: Docker + Docker Compose
+- **代理**: Mihomo (Clash Meta)
+- **任务调度**: APScheduler
+- **模板引擎**: Jinja2

-默认定时任务写入 `state/cron/root`：
+---

-```cron
-*/20 10-17 * * * cd /app && python main.py --doTask >> /app/logs/app.log 2>&1
-0 18 * * * cd /app && python main.py --doTask >> /app/logs/app.log 2>&1
-20 18 * * * cd /app && env SPARKFLOW_MANUAL_RUN=1 SPARKFLOW_MANUAL_UNSENT_ONLY=1 PYTHONUNBUFFERED=1 python main.py --doTask >> /app/logs/app.log 2>&1
-```
+## ⚠️ 免责声明

-你也可以在 Web 面板里修改发送窗口，Web 会更新同一个 cron 文件。
+> **本项目仅供学习研究使用**

-## 常用命令
+- 本工具仅用于技术学习和个人使用，不得用于任何商业用途
+- 使用本工具产生的一切后果由使用者自行承担
+- 请遵守平台规则，合理使用，避免频繁操作
+- 作者不对使用本工具导致的账号异常、封禁等问题负责
+- 请评估使用风险，建议使用小号测试

-```bash
-docker compose ps
-docker compose logs -f web
-docker compose logs -f scheduler
-docker compose up -d --build
-docker compose down
-./refresh_proxy.sh
-```
+---

-手动跑一次发送任务：
+## 📝 更新日志

-```bash
-docker compose run --rm task
-```
+查看 [CHANGELOG.md](DouYinSparkFlow/CHANGELOG.md) 了解版本更新历史。

-## 项目结构
+**最新更新** (2026-05-30):
+- ✨ 重新设计 Web UI，全新视觉风格
+- 🎨 新增亮色/暗色主题切换
+- 📱 优化移动端响应式布局
+- 🔄 改进好友列表刷新可靠性
+- 🚀 优化一键部署流程
+- 📖 新增截图使用指南

- `DouYinSparkFlow/`：核心应用、Web UI、登录桌面和发送任务。
- `docker-compose.yml`：容器编排入口。
- `deploy/`：服务器和本地部署脚本。
- `proxy/config.example.yaml`：直连代理配置模板。
- `.env.example`：部署环境变量模板。
+---

-## 运行时文件
+## 🤝 贡献

-以下文件由部署或运行生成，通常不纳入版本控制：
+欢迎提交 Issue 和 Pull Request！

- `.env`
- `state/`
- `logs/`
- `proxy/config.yaml`
- `DouYinSparkFlow/logs/`
- `DouYinSparkFlow/usersData.json`
- `DouYinSparkFlow/config.json`
- `DouYinSparkFlow/webui_settings.json`
- `DouYinSparkFlow/.im_sdk_cache/`
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request

-## 许可
+---

-核心应用采用 MIT 协议，详见 [DouYinSparkFlow/LICENSE](DouYinSparkFlow/LICENSE)。
+## 📄 许可证
+
+本项目采用 [MIT License](DouYinSparkFlow/LICENSE) 开源协议。
+
+---
+
+## 🌟 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=halfwaystudent/douyin-sparkflow&type=Date)](https://star-history.com/#halfwaystudent/douyin-sparkflow&Date)
+
+---
+
+## 🔗 相关链接
+
+- **项目主页**: [GitHub Repository](https://github.com/halfwaystudent/douyin-sparkflow)
+- **社区讨论**: [Linux Do 社区](https://linux.do)
+- **使用文档**: [docs/usage.md](DouYinSparkFlow/docs/usage.md)
+- **问题反馈**: [Issues](https://github.com/halfwaystudent/douyin-sparkflow/issues)
+
+---
+
+<div align="center">
+
+**如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！**
+
+Made with ❤️ by [halfwaystudent](https://github.com/halfwaystudent)
+
+</div>