wa-app 与 byte-v-forge：WA 应用链路协议实现深度解析

前言

最近在 GitHub 上发现了一个非常有意思的开源项目——wa-app，它是一个 WA（WhatsApp）应用链路服务，提供账号管理、号码探测、注册、登录态检查、长连接会话和消息处理能力，还内置了管理 Dashboard。

更令人兴奋的是，它背后有一个完整的微服务生态系统 byte-v-forge，涵盖了 GPT 账号管理、支付集成、邮箱服务、浏览器自动化、代理网关等基础设施。

本文将从项目概览、架构设计、部署实战、协议解析四个维度，为你详细拆解这两个项目。

⚠️ 声明：本文仅用于协议建模、教学演示和授权安全研究。请勿将相关技术用于商业用途或未授权目标。

一、项目概览

1.1 wa-app 核心能力

wa-app 是整个 WA 链路的核心服务，Go 语言编写，主要能力包括：

仓库地址：github.com/pood1e/wa-app

技术栈：

• 后端：Go 1.26 + gRPC + Protobuf
• 前端：React + TypeScript + Vite + shadcn/ui
• 数据库：SQLite（默认）/ PostgreSQL（可选）
• 缓存：内置运行态 / Redis（可选）
• 部署：Docker Compose，单容器包含所有服务

1.2 byte-v-forge 生态系统

byte-v-forge 是 wa-app 所属的组织，维护着一套完整的微服务基础设施：

组织地址：github.com/orgs/byte-v-forge

二、架构设计深度解析

2.1 wa-app 内部架构

wa-app 采用经典的 分层架构，核心分为三层：

┌─────────────────────────────────────────────────────┐
│                   Dashboard (WebUI)                   │
│           React + shadcn/ui + TypeScript              │
├─────────────────────────────────────────────────────┤
│                    HTTP Gateway                       │
│              dashboard_http.go (REST)                 │
├─────────────────────────────────────────────────────┤
│                   gRPC Server                         │
│         8 个 Service 全部注册在一个进程                  │
├──────────┬──────────┬──────────┬────────────────────┤
│ Discovery│Registrat │ Messagin │ Extraction│ Profile │
│ Service  │ionSvc    │ gSvc     │ Service   │ Service │
├──────────┴──────────┴──────────┴────────────────────┤
│              Protocol Engine (Native)                  │
│   原生协议实现：加密、长连接、设备指纹、状态管理           │
├─────────────────────────────────────────────────────┤
│              Storage Layer (Ports)                     │
│       Store / RuntimeState / Clock / IDGenerator       │
│         SQLite (默认) ←→ PostgreSQL / Redis            │
└─────────────────────────────────────────────────────┘

关键设计决策：

1. 单进程多服务：8 个 gRPC Service 全部注册在同一个进程内，通过 Server 结构体统一管理
2. 端口抽象：Store、RuntimeState、Clock、IDGenerator 全部通过接口注入，方便测试和替换
3. 原生协议引擎：不依赖第三方 WA 库，自行实现了加密、设备指纹、长连接等核心协议逻辑

2.2 gRPC 服务拆分

wa-app 的 Proto 定义在 proto/byte/v/forge/waapp/v1/ 目录下，共 9 个 .proto 文件：

2.3 注册流程状态机

注册是 wa-app 最核心的功能之一，registration_orchestrator.go 实现了完整的注册编排：

StartRegistration
  │
  ├─ 1. normalizePhone()          → 标准化手机号 (E.164)
  ├─ 2. registrationAttemptState() → 获取/复用注册状态
  ├─ 3. registrationRunner()       → 创建协议引擎 runner
  ├─ 4. probeAccountWithState()    → 号码探测
  │     ├─ REACHABLE   → 继续
  │     └─ REJECTED    → 终止，返回错误
  ├─ 5. requestVerificationCode()  → 请求验证码（支持 fallback）
  │     ├─ SMS / Voice / InApp / Flash / Email OTP / Passkey...
  │     └─ 方法降级：SMS → Voice → Flash
  ├─ 6. commitNativeState()        → 提交账号/Profile/Protocol 状态
  └─ 7. 返回结果
        ├─ verification_request_id
        ├─ delivery_method
        ├─ registration_phase
        └─ proxy_route (如有)

支持的验证码投递方式（18 种）：

• SMS、语音通话、应用内消息、Flash
• Email OTP、Passkey、Silent Auth
• reCAPTCHA、OAuth Email
• Account Transfer、Standalone App
• Send SMS、Autoconf、Deep Link OTP...

2.4 消息处理架构

消息系统通过 LongConnectionManager 管理长连接会话：

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Dashboard    │────▶│  gRPC Server    │────▶│  LongConnMgr │
│  (WebSocket)  │     │  WaMessagingSvc │     │              │
└──────────────┘     └─────────────────┘     └──────┬───────┘
                                                     │
                                            ┌────────▼────────┐
                                            │  Protocol Engine │
                                            │  (Native Crypto) │
                                            └────────┬────────┘
                                                     │
                                            ┌────────▼────────┐
                                            │   WA Servers     │
                                            │  (End-to-End)    │
                                            └─────────────────┘

关键 RPC：

• OpenMessageSession：开启消息会话
• ReceiveMessageBatch：批量接收消息
• SendTextMessage：发送 1:1 文本消息
• AcknowledgeMessage：消息 ACK 确认
• GetLongConnectionStatus：查询长连接状态

三、部署实战

3.1 快速启动（Docker Compose）

最简单的方式是使用预构建的 Docker 镜像：

# 克隆仓库
git clone https://github.com/pood1e/wa-app.git
cd wa-app

# 复制环境变量模板
cp .env.example .env

# 编辑 .env（可选）
# WA_APP_AUTH_PASSWORD=your-password   # Dashboard 登录密码
# WA_COMMON_PROXY=socks5://...         # 出站代理

# 启动
docker compose pull
docker compose up -d

启动后访问：

• Dashboard：http://127.0.0.1:8080
• gRPC：127.0.0.1:50091

3.2 环境变量详解

.env 文件中的关键配置项：

# 镜像标签（生产建议用固定版本号）
WA_APP_IMAGE_TAG=latest

# Dashboard 登录密码（留空则关闭鉴权）
WA_APP_AUTH_PASSWORD=

# 持久化目录（容器内路径）
WA_APP_DATA_DIR=/var/lib/wa-app

# PostgreSQL（可选，留空使用 SQLite）
WA_APP_PG_DSN=

# Redis（可选，留空使用内置运行态存储）
WA_APP_REDIS_URL=

# 系统默认出站代理
WA_COMMON_PROXY=

# 注册链路代理租约模式
# optional  → 失败回退直连
# disabled  → 关闭租约
# required  → 强制租约成功
WA_REGISTRATION_PROXY_LEASE_MODE=optional

# 代理租约 API（可选）
WA_REGISTRATION_PROXY_LEASE_API_BASE_URL=
WA_REGISTRATION_PROXY_LEASE_AUTH_TOKEN=

3.3 启用 PostgreSQL + Redis

默认情况下 wa-app 使用 SQLite 和内置运行态存储。如果需要更高性能：

1. 取消 docker-compose.yml 中的注释：

# 取消 postgres 和 redis 服务的注释
postgres:
  image: postgres:17-alpine
  container_name: wa-app-postgres
  environment:
    - POSTGRES_USER=wa-app
    - POSTGRES_PASSWORD=your-password
    - POSTGRES_DB=wa-app
  volumes:
    - postgres-data:/var/lib/postgresql/data
  ports:
    - "5432:5432"

redis:
  image: redis:7-alpine
  container_name: wa-app-redis
  volumes:
    - redis-data:/data
  ports:
    - "6379:6379"

2. 设置环境变量：

WA_APP_PG_DSN=postgres://wa-app:your-password@postgres:5432/wa-app
WA_APP_REDIS_URL=redis://redis:6379

3. 添加依赖关系：

wa-app:
  depends_on:
    postgres:
      condition: service_started
    redis:
      condition: service_started

3.4 源码构建

如果你想从源码构建镜像：

# 在 wa-app 仓库内构建
docker build -t wa-app-service:local .

# 或在 byte-v-forge 聚合目录构建
docker build -f wa-app/Dockerfile -t wa-app-service:local .

Dockerfile 采用 三阶段构建：

1. dashboard_remote_builder：Node.js 22 构建前端（使用 npmmirror 加速）
2. builder：Go 1.26 编译后端 + 生成 Proto
3. 最终镜像：Alpine 最小镜像，只包含二进制和静态文件

四、协议层深度解析

4.1 设备指纹生成

wa-app 内置了设备指纹模拟能力，tooling.proto 中定义了：

message PhoneFingerprintProfile {
  string schema = 1;
  PhoneTarget phone = 2;
  string phone_sha256 = 3;
  map<string, string> base_params = 5;
  map<string, string> raw_params = 6;
  map<string, string> device_map_params = 7;
  string profile_sha256 = 8;
  string device_vendor = 9;
  string device_model = 10;
  string android_version = 11;
}

device_profiles.json 中预置了多种设备配置，支持随机化设备指纹以降低被检测的风险。

4.2 加密与安全

native_crypto.go 实现了原生加密逻辑，关键依赖：

// go.mod 中的加密相关依赖
filippo.io/edwards25519 v1.2.0    // Ed25519 签名
go.mozilla.org/pkcs7 v0.9.0       // PKCS#7 加密
go.step.sm/crypto v0.81.1         // 通用密码学工具
golang.org/x/crypto v0.52.0       // Go 标准加密库

敏感数据（OTP、Token、AuthKey、Identity/PreKey、Session、Cookie）在日志和文档中一律脱敏处理。

4.3 注册请求构建

BuildRegistrationRequest RPC 支持三种类型：

enum RegistrationRequestKind {
  REGISTRATION_REQUEST_KIND_EXIST = 1;     // 存在性检查
  REGISTRATION_REQUEST_KIND_CODE = 2;      // 请求验证码
  REGISTRATION_REQUEST_KIND_REGISTER = 3;  // 完成注册
}

对应的 Python 探测脚本在 scripts/ 目录下：

• wa_exist_probe.py：号码存在性探测
• wa_code_param_probe.py：验证码参数探测
• wa_code_param_experiment.py：参数实验
• wa_code_factor_suite.py：因子套件
• wa_code_random_device_experiment.py：随机设备实验

4.4 Proto 契约设计哲学

从 AGENTS.md 和 common-lib 的设计可以看出，byte-v-forge 遵循严格的契约优先原则：

1. Proto 是唯一真源：所有服务间通信的模型、RPC、状态、错误码都由 Proto 定义
2. 不暴露实现细节：代理地址、数据库表名、Redis Key 等不出现在契约中
3. 敏感数据分级：SensitiveText 包含 value、redacted_value、secret_ref 三层
4. 统一错误码：WaErrorCode 枚举覆盖 16 种错误场景

message SensitiveText {
  string value = 1;           // 仅授权调用者可见
  string redacted_value = 2;  // 脱敏后的值
  string secret_ref = 3;      // 秘密存储引用
}

五、byte-v-forge 生态详解

5.1 服务间协作

byte-v-forge 的各个服务通过 gRPC 和 Temporal 工作流引擎协作：

                    ┌─────────────────┐
                    │  workflow-runtime│
                    │  (Temporal)      │
                    └────────┬────────┘
                             │ 编排
        ┌────────────────────┼────────────────────┐
        │                    │                    │
   ┌────▼────┐         ┌────▼────┐         ┌────▼────┐
   │  gpt    │         │ wa-app  │         │  sms    │
   │ Service │         │ Service │         │ Service │
   └────┬────┘         └────┬────┘         └─────────┘
        │                    │
   ┌────▼────────┐    ┌─────▼──────────┐
   │browser-auto │    │proxy-gateway   │
   │mation       │    │(GOST v3)       │
   └─────────────┘    └────────────────┘
        │
   ┌────▼────┐
   │ mailbox │
   │ Service │
   └─────────┘

5.2 proxy-gateway 代理网关

代理网关是整个基础设施的关键组件，基于 GOST v3 实现：

• 统一出口网关：对业务服务暴露本地 HTTP/SOCKS5 代理
• 动态 IP Sticky Session：支持主动切换出口身份
• 多 Hop 路由：支持复杂代理链组合
• 1024Proxy 集成：动态住宅代理支持

5.3 common-lib 公共能力

common-lib 沉淀了跨仓的稳定能力：

• 公共 Proto 契约：跨服务共享的模型和 gRPC 定义
• 基础库：HTTP/gRPC client、Redis、事件总线、分页、脱敏等
• 前端组件：React/shadcn Dashboard UI Kit
• 契约检查：边界检查脚本，防止跨仓违规依赖

六、注意事项与最佳实践

6.1 安全注意事项

1. 仅限授权研究：本项目仅限协议建模、教学演示和授权安全研究
2. 禁止商业用途：不得用于收费 API、SaaS、代运营等商业场景
3. 敏感数据保护：OTP、Token、AuthKey 等在日志中必须脱敏
4. 代理安全：生产环境务必配置代理，避免直连被封

6.2 性能建议

• 默认 SQLite 足够小规模使用，大规模部署建议切换 PostgreSQL + Redis
• 长连接管理：LongConnectionManager 需要合理配置超时和重连策略
• 消息批量处理：使用 ReceiveMessageBatch 而非逐条接收

6.3 常见问题

Q: 为什么不直接用第三方 WA 库？

A: wa-app 选择自研协议引擎（native_*.go），可以精确控制协议行为、设备指纹、加密参数，避免第三方库的兼容性问题。

Q: Dashboard 鉴权如何工作？

A: 设置 WA_APP_AUTH_PASSWORD 环境变量即可启用单密码登录。留空则关闭鉴权（仅限内网使用）。

Q: 如何添加新的验证码投递方式？

A: 在 registration.proto 中添加新的 VerificationDeliveryMethod 枚举值，然后在 registration_orchestrator.go 中实现对应的逻辑。

总结

wa-app 和 byte-v-forge 展示了一个契约优先、分层清晰的微服务架构实践：

• wa-app 提供了完整的 WA 应用链路实现，从设备指纹到消息收发
• byte-v-forge 提供了从支付、邮箱到代理网关的全套基础设施
• 严格的 Proto 契约设计保证了服务间的清晰边界

虽然基础设施还在早期阶段（workflow-runtime 2 星、contracts 1 星），但整体架构设计非常成熟。如果你对应用层协议建模感兴趣，建议重点研究 wa-app 的协议实现部分，它是一个非常好的学习案例。

相关链接：

• wa-app：github.com/pood1e/wa-app
• byte-v-forge：github.com/orgs/byte-v-forge
• 逆向工程记录（私有）：github.com/byte-v-forge/wa-reverse