292 lines
15 KiB
Plaintext
292 lines
15 KiB
Plaintext
好的，这是一份为专业 Coding AI 模型或开发者编写的详细开发文档 (Development Document)。文档遵循常见的软件工程规范，旨在将一个概念转化为可实施的技术蓝图。
|
||
|
||
---
|
||
|
||
## **项目名称: Weibo-HotSign**
|
||
|
||
### **1. 项目概述 (Project Overview)**
|
||
|
||
#### 1.1. 项目简介
|
||
Weibo-HotSign 是一个分布式的、面向多用户的微博超话智能签到系统。它旨在通过自动化的方式，帮助用户定时、稳定地完成微博超话的签到任务，以获取积分和经验值。项目的核心挑战在于应对微博复杂的反爬虫机制，确保长期运行的稳定性和成功率。
|
||
|
||
#### 1.2. 核心价值主张
|
||
* **多账户管理**: 为用户提供一个集中的平台来管理多个微博账号的签到任务。
|
||
* **高稳定性与反爬虫**: 采用动态IP代理池、浏览器指纹模拟、智能Cookie管理及高级JS逆向（必要时）等技术，最大限度规避微博的风控策略，保障签到任务的成功率。
|
||
* **用户友好**: 提供Web UI进行可视化管理，避免用户直接操作代码或配置文件。
|
||
* **可观测性**: 实时日志、任务历史和状态监控，让用户清晰掌握每个账号的运作情况。
|
||
* **通知系统**: 提供多种渠道的实时通知，让用户第一时间了解任务结果。
|
||
|
||
#### 1.3. 目标用户
|
||
* 拥有多个微博账号，希望自动化完成日常签到的普通用户。
|
||
* 希望通过技术手段研究反爬虫方案的开发者。
|
||
* 需要将此类自动化功能集成到自己系统中的第三方服务（通过API）。
|
||
|
||
---
|
||
|
||
### **2. 系统架构 (System Architecture)**
|
||
|
||
本项目采用基于微服务的架构，以实现模块间的解耦、独立部署和水平扩展。
|
||
|
||
#### 2.1. 架构图
|
||
```mermaid
|
||
graph TD
|
||
subgraph User Interaction Layer
|
||
A[Web Frontend (React/Vue)]
|
||
end
|
||
|
||
subgraph Backend Services Layer
|
||
B[API Gateway / Main API Service (FastAPI)]
|
||
C[Authentication Service (FastAPI)]
|
||
D[Task Scheduler Service (Celery Beat)]
|
||
E[Sign-in Executor Worker (Celery Worker)]
|
||
F[Notification Hub Service (FastAPI)]
|
||
G[Browser Automation Service (Node.js/Python)]
|
||
end
|
||
|
||
subgraph Core Infrastructure Layer
|
||
H[(Message Queue: Redis/RabbitMQ)]
|
||
I[(Cache & Session Store: Redis)]
|
||
J[(Relational DB: PostgreSQL)]
|
||
K[(Proxy Pool Manager)]
|
||
L[(Browser Fingerprint Generator)]
|
||
end
|
||
|
||
subgraph External Systems
|
||
M[Weibo.com]
|
||
N[User Notification Channels (ServerChan, Email, etc.)]
|
||
O[Payment Gateway (Future)]
|
||
end
|
||
|
||
A -->|HTTPS| B;
|
||
B -->|AuthN/AuthZ| C;
|
||
A -->|API Calls| B;
|
||
|
||
D -->|Publishes Task| H;
|
||
E -->|Consumes Task| H;
|
||
|
||
E -->|Updates Status| J;
|
||
E -->|Reads Config| J;
|
||
E -->|Logs Result| J;
|
||
|
||
E -->|Stores/Retrieves Session| I;
|
||
D -->|Stores Schedule| J;
|
||
|
||
E -->|Requests Proxy| K;
|
||
K -->|Provides Proxy IP| E;
|
||
|
||
E -->|Requests Fingerprint| L;
|
||
L -->|Provides Fingerprint| E;
|
||
|
||
E -->|Performs Action| M;
|
||
G -->|Executes JS & Extracts Data| M;
|
||
E -->|Delegates to| G;
|
||
|
||
F -->|Sends Notification| N;
|
||
|
||
B -->|Authenticated| O;
|
||
|
||
style A fill:#D5F5E3
|
||
style B fill:#EBDEF0
|
||
style C fill:#EBDEF0
|
||
style D fill:#EBDEF0
|
||
style E fill:#EBDEF0
|
||
style F fill:#EBDEF0
|
||
style G fill:#EBDEF0
|
||
style H fill:#FDF2E9
|
||
style I fill:#FDF2E9
|
||
style J fill:#FADBD8
|
||
style K fill:#EAFAF1
|
||
style L fill:#EAFAF1
|
||
style M fill:#FDEBD0
|
||
style N fill:#D6EAF8
|
||
style O fill:#EBDEF0
|
||
```
|
||
|
||
#### 2.2. 组件职责描述
|
||
* **Web Frontend**: 负责所有用户交互，包括登录注册、账号管理、任务配置、日志查看等。
|
||
* **API Gateway / Main API Service**: 作为系统的唯一入口，负责请求路由、API组合、限流和初步的请求验证。
|
||
* **Authentication Service**: 独立的认证授权服务，使用JWT或OAuth2.0标准，为所有服务提供统一的身份验证和权限校验。
|
||
* **Task Scheduler Service**: 基于Celery Beat，负责解析用户配置的Cron表达式，并将签到任务发布到消息队列中。
|
||
* **Sign-in Executor Worker**: 核心工作节点，消费消息队列中的任务，执行具体的登录、签到逻辑。此服务可水平扩展以应对高并发。
|
||
* **Notification Hub Service**: 统一处理所有通知请求，并根据用户偏好分发至不同的渠道（Server酱、邮件等）。
|
||
* **Browser Automation Service**: 独立的、无状态的浏览器服务。当遇到复杂的JS加密时，Executor Worker将通过API调用此服务来获取签名后的参数。此服务可使用Playwright或Puppeteer构建，并可独立集群部署。
|
||
* **Message Queue (Redis/RabbitMQ)**: 实现异步和解耦的核心组件。Scheduler生产任务，Executor消费任务。
|
||
* **Cache & Session Store (Redis)**: 存储短期数据，如用户会话、分布式锁、API速率限制计数器、以及所有微博账号的有效Cookies。
|
||
* **Relational DB (PostgreSQL)**: 存储结构化核心业务数据，如用户信息、账号元数据、任务配置、签到历史记录。
|
||
* **Proxy Pool Manager**: (可以是独立进程或一个服务) 负责维护一个高质量的代理IP池，提供健康检查、分配和回收机制。
|
||
* **Browser Fingerprint Generator**: (可以是独立进程或一个库) 负责生成高仿真的浏览器指纹，供Executor Worker在发起请求时使用。
|
||
|
||
---
|
||
|
||
### **3. 核心技术选型 (Technology Stack)**
|
||
|
||
| 层级 | 技术组件 | 推荐技术 | 备选技术 | 目的 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| **前端** | 框架 | React (Vite) | Vue 3 (Nuxt) | 构建动态、响应式的用户界面 |
|
||
| | 状态管理 | Redux Toolkit / Zustand | Pinia | 管理复杂的应用状态 |
|
||
| | UI库 | Ant Design / Material-UI | Element Plus | 快速搭建美观的界面 |
|
||
| **后端** | Web框架 | Python FastAPI | Node.js Express/NestJS | 高性能、易开发、自动生成API文档 |
|
||
| | ASGI服务器 | Uvicorn | Hypercorn | 运行FastAPI应用 |
|
||
| | 异步任务 | Celery | RQ (Redis Queue) | 分布式任务队列，处理后台任务 |
|
||
| | 消息代理 | Redis | RabbitMQ | Celery的消息中间件 |
|
||
| | ORM | SQLAlchemy (async) | Tortoise-ORM | 与PostgreSQL交互 |
|
||
| | 数据库 | PostgreSQL | MySQL | 存储核心业务数据，保证事务性和数据完整性 |
|
||
| | 缓存 | Redis | Memcached | 高速缓存、会话存储 |
|
||
| **基础设施**| 容器化 | Docker | Podman | 环境标准化、简化部署 |
|
||
| | 编排 | Docker Compose | Kubernetes (K8s) | 本地开发和生产环境部署 |
|
||
| | 反向代理 | Nginx | Traefik/Caddy | SSL终结、负载均衡、静态文件服务 |
|
||
| **浏览器自动化**| 库/工具 | Playwright (Python/Node) | Selenium | 模拟浏览器行为、对抗JS加密 |
|
||
| **运维** | CI/CD | GitHub Actions | GitLab CI/Jenkins | 自动化测试与部署 |
|
||
| | 监控 | Prometheus + Grafana | Zabbix | 系统指标监控 |
|
||
| | 日志 | ELK Stack (Elasticsearch, Logstash, Kibana) | Loki + Grafana | 集中式日志收集与分析 |
|
||
|
||
---
|
||
|
||
### **4. 模块详细设计 (Detailed Module Design)**
|
||
|
||
#### 4.1. 认证与授权模块 (`auth_service`)
|
||
* **API端点**:
|
||
* `POST /auth/register`: 用户注册。
|
||
* `POST /auth/login`: 用户登录，返回JWT。
|
||
* `POST /auth/refresh`: 刷新JWT。
|
||
* `GET /auth/me`: 获取当前用户信息。
|
||
* **数据库模型 (`users`)**: `id`, `username`, `email`, `hashed_password`, `created_at`, `is_active`。
|
||
* **关键逻辑**: 使用 `bcrypt` 或 `argon2` 哈希密码。JWT包含 `user_id` 和权限声明。所有受保护的API都需通过中间件校验JWT的有效性。
|
||
|
||
#### 4.2. 账号与任务管理模块 (`api_service`)
|
||
* **API端点 (示例)**:
|
||
* `POST /accounts`: 添加一个微博账号，需提交从前端获取的微博Cookie或通过二维码登录流程绑定的凭证。
|
||
* `GET /accounts`: 获取当前用户的所有微博账号列表及其状态。
|
||
* `PUT /accounts/{account_id}`: 更新账号信息（如备注、启用/禁用状态）。
|
||
* `DELETE /accounts/{account_id}`: 删除一个账号。
|
||
* `POST /tasks`: 为指定账号创建一个签到任务，接收Cron表达式和配置参数。
|
||
* **数据库模型**:
|
||
* `accounts`: `id`, `user_id` (FK), `weibo_user_id`, `remark`, `encrypted_cookies`, `status` ('active', 'invalid_cookie', 'banned'), `last_check_time`.
|
||
* `tasks`: `id`, `account_id` (FK), `cron_expression`, `is_enabled`, `created_at`.
|
||
* **关键逻辑**: 对用户输入的Cookie进行强加密（如AES-256-GCM）后存储。状态`status`由一个独立的后台校验服务定期更新。
|
||
|
||
#### 4.3. 任务调度模块 (`task_scheduler`)
|
||
* **技术**: Celery Beat + Redis。
|
||
* **配置**: 在启动时，从数据库`tasks`表中加载所有`is_enabled=True`的任务，并将其注册到Celery Beat的调度器中。
|
||
* **工作流程**:
|
||
1. Beat根据Cron表达式触发任务。
|
||
2. 任务内容是向消息队列（Redis）发送一条消息，消息体包含`task_id`和`account_id`。
|
||
3. Worker监听到消息后，调用`Sign-in Executor`的逻辑。
|
||
|
||
#### 4.4. 签到执行模块 (`signin_executor`)
|
||
* **技术**: Celery Worker。
|
||
* **工作流程**:
|
||
1. **接收任务**: 从消息队列获取任务。
|
||
2. **前置检查**: 查询Redis或DB，检查账号`status`是否为`active`。若否，则记录日志并终止。
|
||
3. **获取资源**: 从`Proxy Pool Manager`获取一个健康代理；从`Fingerprint Generator`获取一个指纹；从Redis解密并获取该账号的`cookies`。
|
||
4. **执行签到**:
|
||
* 调用`login_and_verify`模块检查Cookie有效性。
|
||
* 调用`get_super_topics`获取签到列表。
|
||
* 遍历列表，对每个超话调用`sign_topic`。
|
||
* **反爬策略**: 在请求间引入随机延迟；为每个请求构造独特的Headers（含UA、指纹等）；使用代理IP。
|
||
* **JS逆向**: 如果API请求签名失败，向`Browser Automation Service`发起RPC调用，获取签名参数后再重试。
|
||
5. **结果上报**: 将签到结果（成功、失败、原因、获得积分）写入数据库的`signin_logs`表。
|
||
6. **清理**: 归还代理IP，更新Redis中的会话状态。
|
||
|
||
#### 4.5. 浏览器自动化模块 (`browser_automation_service`)
|
||
* **API端点 (gRPC or REST)**:
|
||
* `POST /api/v1/get_signature`: 接收目标URL和必要的上下文，返回一个已签名的请求载荷或Headers。
|
||
* **实现**: 使用Playwright启动一个无头浏览器池。收到请求后，从池中分配一个浏览器上下文，导航至相关页面，注入JS钩子或直接监听网络请求，提取所需数据后关闭上下文并返回结果。
|
||
|
||
---
|
||
|
||
### **5. 数据库设计 (Database Schema)**
|
||
|
||
#### 5.1. `users` Table
|
||
| Column | Type | Constraints | Description |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | UUID | PK | Primary Key |
|
||
| `username` | VARCHAR(50) | UNIQUE, NOT NULL | Unique username |
|
||
| `email` | VARCHAR(255) | UNIQUE, NOT NULL | User's email address |
|
||
| `hashed_password` | VARCHAR(255) | NOT NULL | Hashed password |
|
||
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | Account creation time |
|
||
| `is_active` | BOOLEAN | DEFAULT TRUE | Whether the user account is active |
|
||
|
||
#### 5.2. `accounts` Table
|
||
| Column | Type | Constraints | Description |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | UUID | PK | Primary Key |
|
||
| `user_id` | UUID | FK (`users.id`), ON DELETE CASCADE | Owner of the account |
|
||
| `weibo_user_id` | VARCHAR(20) | NOT NULL | UID on Weibo platform |
|
||
| `remark` | VARCHAR(100) | | User-defined note for the account |
|
||
| `encrypted_cookies` | TEXT | NOT NULL | AES-256 encrypted cookie string |
|
||
| `iv` | VARCHAR(32) | NOT NULL | Initialization vector for AES-GCM |
|
||
| `status` | VARCHAR(20) | DEFAULT 'pending' | 'active', 'invalid_cookie', 'banned' |
|
||
| `last_checked_at` | TIMESTAMPTZ | | Last time the cookie was verified |
|
||
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | When the account was added |
|
||
|
||
#### 5.3. `tasks` Table
|
||
| Column | Type | Constraints | Description |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | UUID | PK | Primary Key |
|
||
| `account_id` | UUID | FK (`accounts.id`), ON DELETE CASCADE | Associated account |
|
||
| `cron_expression` | VARCHAR(50) | NOT NULL | Cron expression for scheduling |
|
||
| `is_enabled` | BOOLEAN | DEFAULT TRUE | Enable or disable the task |
|
||
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | Task creation time |
|
||
|
||
#### 5.4. `signin_logs` Table
|
||
| Column | Type | Constraints | Description |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `id` | BIGSERIAL | PK | Primary Key |
|
||
| `account_id` | UUID | FK (`accounts.id`) | Associated account |
|
||
| `topic_title` | VARCHAR(100) | | Title of the signed super topic |
|
||
| `status` | VARCHAR(20) | NOT NULL | 'success', 'failed_already_signed', 'failed_network', 'failed_banned' |
|
||
| `reward_info` | JSONB | | Details about rewards, e.g., `{"exp": 2, "credit": 1}` |
|
||
| `error_message` | TEXT | | Error details if status is 'failed' |
|
||
| `signed_at` | TIMESTAMPTZ | DEFAULT NOW() | Timestamp of the sign-in attempt |
|
||
|
||
---
|
||
|
||
### **6. API 设计规范 (API Design Specification)**
|
||
|
||
* **协议**: 全站使用 HTTPS。
|
||
* **数据格式**: 请求和响应体均使用 `application/json`。
|
||
* **认证方式**: Bearer Token (JWT)。需要在请求头的 `Authorization` 字段中携带：`Authorization: Bearer <your_jwt_token>`。
|
||
* **版本控制**: URL路径中包含版本号，例如 `/api/v1/auth/login`。
|
||
* **通用响应结构**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... }, // 成功时返回的数据
|
||
"message": "Operation successful.", // 可选的提示信息
|
||
"error": null // 失败时返回的错误对象
|
||
}
|
||
```
|
||
* 失败时 (HTTP状态码 >= 400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"data": null,
|
||
"message": "Validation failed.",
|
||
"error": {
|
||
"code": "VALIDATION_ERROR",
|
||
"details": [
|
||
{"field": "email", "message": "Invalid email format."}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
* **状态码**: 严格遵守 RESTful 规范。200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 500 (Internal Server Error)。
|
||
|
||
---
|
||
|
||
### **7. 部署与运维 (Deployment & Operations)**
|
||
|
||
* **开发环境**: 使用 `docker-compose.yml` 定义所有服务（API, DB, Redis, Frontend Dev Server），实现一键启动。
|
||
* **生产环境**: 使用 `Kubernetes` 进行编排。编写 `Deployment.yaml`, `Service.yaml`, `Ingress.yaml` 等清单文件。
|
||
* **CI/CD Pipeline (GitHub Actions Example)**:
|
||
1. **On Push to `main`**: Trigger workflow.
|
||
2. **Lint & Test**: Run code linters (Black, Flake8) and unit/integration tests.
|
||
3. **Build**: Build Docker images for all services and push them to a container registry (e.g., Docker Hub, AWS ECR).
|
||
4. **Deploy**: Use `kubectl` or ArgoCD to apply the new Kubernetes manifests to the production cluster.
|
||
* **监控与告警**:
|
||
* **Metrics**: Expose metrics via `prometheus_client` in Python services. Monitor queue length, task success/failure rates, API latency.
|
||
* **Alerts**: Configure Alertmanager to trigger alerts on Slack/PagerDuty for critical issues (e.g., high task failure rate > 10%, worker node down).
|
||
* **Logging**: Configure all services to output structured logs (JSON). Use Filebeat or Fluentd to ship logs to Elasticsearch. Use Kibana for visualization and querying.
|
||
|
||
这份文档为专业的 Coding AI 或开发团队提供了从宏观架构到微观实现的全面指导。开发过程应遵循此文档，并可根据实际情况进行迭代和优化。 |