Cloudflare Worker Integration
Relevant source files
The following files were used as context for generating this wiki page:
Cloudflare Worker Integration enables the project to utilize Cloudflare's edge infrastructure for proxy egress and residential IP rotation. The system manages the lifecycle of Cloudflare Workers, including deployment, script obfuscation, and subscription parsing. It primarily leverages the BPB-Worker-Panel template to facilitate VLESS and Trojan protocols over WebSocket, providing rotated egress addresses for proxy traffic.
This integration allows the control plane to automate account management tasks such as checking account status, ensuring workers.dev subdomains, and handling KV namespace storage for worker configurations.
Sources: internal/cfworker/client.go:1-10, ref/README.md:9-15, internal/cfworker/deploy.go:94-105
Architecture and Components
The integration consists of a Go-based client that interacts with the Cloudflare API v4 and a deployment engine that handles script preparation and verification.
Core Components
| Component | Description |
|---|---|
| Cloudflare API Client | Manages HTTP communication with https://api.cloudflare.com/client/v4 using Bearer token authentication. |
| Deployment Engine | Orchestrates the upload, configuration, and verification of worker scripts. |
| Template Manager | Fetches and caches the BPB-Worker-Panel worker.js script and injects runtime settings. |
| Obfuscator | Applies randomized obfuscation to worker scripts before deployment to avoid detection. |
| Subscription Parser | Decodes Base64 payloads from deployed workers into VLESS/Trojan proxy nodes. |
Sources: internal/cfworker/client.go:19-35, internal/cfworker/template.go:14-25, internal/residential/cfworker_test.go:13-20, internal/cfworker/deploy.go:94-110
Deployment Workflow
The following diagram illustrates the sequence of actions taken when deploying a new Cloudflare Worker.
Cloudflare API Client
The Client struct encapsulates the API token and an optional HTTP proxy for communication with Cloudflare. It implements methods for account validation, worker management, and KV storage operations.
Key Client Methods
- AccountOK: Verifies if the provided API token and Account ID are valid. HTTP 401 or 403 responses indicate the account is banned or the token is revoked.
- EnsureSubdomain: Retrieves the account's
workers.devsubdomain. If none exists, it creates one using a sanitized version of the account ID. - UploadWorker: Performs a multipart upload. The body must contain an
application/jsonmetadata part (definingmain_moduleandbindings) and anapplication/javascript+modulescript part. - FindKVNamespace / CreateKVNamespace: Manages Key-Value namespaces used for persistent worker configuration.
Sources: internal/cfworker/client.go:76-88, internal/cfworker/client.go:91-115, internal/cfworker/client.go:140-188, internal/cfworker/client.go:210-230
Worker Script Management
The system uses specific templates and obfuscation strategies to ensure the longevity and effectiveness of the edge egress.
Template Injection and Caching
The control plane fetches the BPB-Worker-Panel (v5.1.1) worker.js from GitHub. It caches this script locally in cfworker/worker.js. Before deployment, the InjectSettings function prepends const EMBEDED_SETTINGS = {...}; to the script bytes, allowing the control plane to bake configurations directly into the worker.
Sources: internal/cfworker/template.go:14-30, internal/cfworker/template.go:54-58
Naming and Obfuscation
Workers are assigned "neutral" names to avoid risk keywords. A list of 28 business-sounding words (e.g., aurora, nimbus, zenith) is combined with random digits to form names like ember42.
If a deployment attempt fails, the system clears cached obfuscation artifacts and retries with a fresh name and a new randomized obfuscation recipe. It allows up to 4 attempts before falling back to a raw template deployment.
Sources: internal/cfworker/deploy.go:12-25, internal/cfworker/deploy.go:107-130, internal/cfworker/deploy.go:167-175
Proxy Node Integration
The integration translates Cloudflare Worker outputs into proxy node configurations compatible with the mihomo dataplane.
Subscription Parsing
Deployed workers serve a Base64-encoded list of VLESS and Trojan share URIs via the /sub/raw?app=xray path. The system parses these URIs, extracting parameters such as host, path, sni, and ed (early data).
Sources: internal/residential/cfworker_test.go:13-25, internal/dataplane/mihomo/nodes.go:114-125
Mihomo Compatibility Handling
The mihomo compiler specifically handles Cloudflare Worker conventions:
- WebSocket Early Data: It splits the
edparameter from the WebSocket path. The size is mapped tows-opts.max-early-data, and the header name is set toSec-WebSocket-Protocol. - ALPN Normalization: Ensures ALPN values (like
h2,http/1.1) are converted into the slice format required by Mihomo YAML. - TLS Configuration: Maps
security=tlsorsecurity=realityfrom the share URI to the booleantlsfield in the node config.
Sources: internal/dataplane/mihomo/nodes.go:114-148, internal/dataplane/mihomo/nodes.go:207-230, internal/dataplane/mihomo/nodes.go:265-275
The diagram shows the transformation of worker-provided data into a format usable by the proxy engine.
Sources: internal/dataplane/mihomo/nodes.go:114-150, internal/residential/cfworker_test.go:28-40
Conclusion
The Cloudflare Worker Integration provides a robust mechanism for edge-based proxying by automating the lifecycle of Workers. By combining automated deployment, randomized obfuscation, and specialized parsing for the BPB-Worker-Panel template, the system ensures a high degree of availability for residential-style egress nodes while maintaining compatibility with the Mihomo dataplane.