Custom Domain
CloudBase HTTP Gateway provides automatically generated domains by default. You can also bind custom domains to the CloudBase HTTP Gateway.
For production environments, it is recommended to bind a custom domain to obtain full service capabilities and stability. For limitations and applicable scope of the default domain, see HTTP Gateway Overview - Default Domain.
ICP filing is not required to connect a custom domain on the international site. Domain ownership verification, DNS configuration, and an SSL certificate for HTTPS are still required when connecting a domain independently.
About the Client Source IP
If your business needs to use rate limiting (such as environment rate limiting or resource rate limiting), or needs to make decisions based on the request origin (such as IP allow/deny lists), you first need to understand how the client source IP recognized by the CloudBase gateway is determined.
The rules below apply to all scenarios, including custom domains configured through the HTTP Gateway, and custom domains connected directly through the SDK, HTTP API, or CLI.
CloudBase Access (HTTP Gateway direct connection, Edge Acceleration, existing CDN)
The gateway uses the IP of the directly connected client. It is not accepted as specified by the requester via X-Forwarded-For, and the client cannot control this value.
Custom Access (with a self-built Layer 7 proxy in front)
When a self-built Layer 7 proxy (such as a reverse proxy, WAF, CDN, or Edge Acceleration) exists before traffic reaches the CloudBase gateway, that proxy must pass the client source IP to the gateway via X-Forwarded-For. The gateway uses the last segment of X-Forwarded-For as the client source IP (it only trusts the XFF set by the immediately preceding proxy); if the proxy fails to forward it correctly, related policies may not take effect as expected.
Only a Layer 7 proxy (which can parse and rewrite HTTP headers) can pass the client source IP via X-Forwarded-For. A Layer 4 proxy (such as a TCP/L4 load balancer) does not parse the HTTP protocol and cannot set or forward X-Forwarded-For; the gateway will still see the proxy's outbound IP.
Prerequisites
Before starting to configure custom domains, please ensure the following preparations are complete:
Edge acceleration requires the Standard plan or above. It is billed by resource points. If your current environment is not in Resource Point mode, first switch the billing mode to Resource Point mode in the CloudBase Console → Plan Usage before enabling edge acceleration.
-
Custom Domain Prepare a domain you own and ensure you can manage its DNS records.
-
SSL Certificate When connecting a domain independently, prepare an SSL certificate, which can be uploaded or applied for in the SSL Certificate Console. If you choose "Inherit Wildcard Domain", you reuse the connected wildcard domain's certificate without configuring it again.
Domain Ownership Verification
When a domain connects to the CloudBase gateway independently, domain ownership verification confirms that you own it. This prevents misuse and protects your business. If you choose "Inherit Wildcard Domain", the result from the connected wildcard domain is reused, so you do not need to verify ownership again.
The verification is done by adding a TXT resolution record at your DNS provider. The specific record value will be provided during the domain access operation - simply follow the on-page instructions.
When connecting a wildcard domain, subdomains it covers do not need to be verified one by one: *.example.com exempts subdomains at any level (e.g., a.example.com, a.b.c.example.com), while *.xxx.example.com exempts first-level subdomains only (e.g., a.xxx.example.com). See Wildcard Domain Access - Domain Ownership Verification Rules.
When adding a domain, the page will guide you through TXT record verification, for example:
When connecting a domain independently and enabling Edge Acceleration for the first time, edge acceleration domain ownership verification is also required. This is a requirement of the edge acceleration platform and is not shared with CloudBase's first-time domain ownership verification. Follow the platform instructions to add the corresponding DNS TXT record. If you choose "Inherit Wildcard Domain", the connected wildcard domain's verification result is reused.
Start Connecting
- Go to CloudBase Console/HTTP Gateway
- Click "Add Domain"
- Enter your custom domain
- Select an access method: configure an SSL certificate for independent access, or reuse existing settings when inheriting a wildcard domain
In addition to managing domains centrally in the HTTP Gateway, you can also add a custom domain directly from the detail page of a specific cloud function / cloud run / static hosting application. The two entry points are equivalent — all added domains are listed and managed in the HTTP Gateway.
Access Method
Custom domains support the following three access methods:
- CloudBase Access: Domain access is managed centrally by the CloudBase platform, and you can choose to enable or disable edge acceleration
- Inherit Wildcard Domain: Reuse a wildcard domain already connected at the platform level or in the current environment, including its certificate, DNS configuration, and domain ownership verification result, without configuring them again
- Custom Access: Access using your own CDN or WAF service
This CDN is used for HTTP associated resource calls. If you want to add CDN for cloud storage, please refer to Cloud Storage Custom CDN
CloudBase Access
CloudBase Access supports two modes: "Enable Edge Acceleration" and "Disable Edge Acceleration".
Enable Edge Acceleration
With edge acceleration enabled, requests enter through nearby edge nodes. Cacheable resources are served directly from an edge node on a cache hit; on a cache miss, they are fetched from the origin. This reduces access latency and origin load.
Edge acceleration is backed by a global edge network covering 70+ countries and regions, so users anywhere can be served from a nearby node. Once enabled, it incurs two fee items: acceleration traffic and acceleration requests, billed by the user's access region. For pricing details, see the CloudBase Billing Documentation.
Acceleration Features
Enabled by default, with no additional configuration
| Feature | Benefit |
|---|---|
| Smart compression | Brotli and Gzip are enabled by default. Compressed content is served according to client support, reducing transfer sizes, load times, and traffic |
| IPv6 access | Accepts IPv6 clients for compatibility with more network environments |
| WebSocket | Supports real-time connections. The edge-side connection timeout is set to 300 seconds; timeouts at the origin and other parts of the request path must be checked separately |
| TLS 1.2 / 1.3 | HTTPS access supports TLS 1.2 and TLS 1.3; TLS 1.0 / 1.1 are not supported |
| OCSP Stapling | Supplies certificate status information during the TLS handshake, reducing separate certificate status queries by clients |
| Cache isolation | Separates cached responses by Origin and Accept-Encoding to prevent incorrect reuse across origins or compression formats |
The client must declare support for br or gzip through Accept-Encoding. The resource must have a supported Content-Type (such as HTML, CSS, JavaScript, or JSON) and a size of 256 B–30 MB. Brotli is preferred when both algorithms are available, but the response also depends on existing cached versions.
Content already returned by the origin with Content-Encoding is not compressed again. When the origin uses Transfer-Encoding: chunked, content is not compressed in real time during the first origin fetch; subsequent requests can use cached content for compression. Compression does not apply to every resource or every request.
Configure according to your business needs
| Feature | Capability |
|---|---|
| Edge and browser caching | Caching follows the origin by default. Configure no caching, a custom duration, or origin-following behavior by request characteristics, with separate control over edge and browser caching. See Cache Configuration |
| Custom cache keys | Choose how the URL and query parameters contribute to the cache key to control which requests share a cache entry. For signed URLs, sign and t are retained for cache isolation; actual signature verification is handled by the CloudBase gateway |
| Referer hotlink protection | Supports Referer allowlists or denylists. Requests that fail the rules receive a 403 at the edge, including on cache hits |
| Protocol control | Supports both HTTP and HTTPS, either protocol alone, or a 301 redirect from HTTP / HTTPS to the other protocol |
| Custom error pages | Platform edition users can configure custom responses for supported 4XX errors to provide a consistent error experience. See Custom Error Page |
Cache isolation does not grant cross-origin access. Configure CORS Validation and origin response headers correctly. Enabling edge acceleration does not remove origin authentication, request size limits, or timeouts.
Next Steps
- Complete edge acceleration domain ownership verification: When edge acceleration is enabled for the first time, edge acceleration domain ownership verification is required. Add the corresponding DNS TXT record as guided.
- Configure CNAME resolution: After the domain access status returns to normal, go to the DNS Console to configure CNAME resolution. The CNAME value will be provided on the page.
Because it takes some time for the edge acceleration platform to distribute configuration during actual access, the processing status after edge acceleration domain ownership verification takes about 10-20 minutes. Please wait patiently.
Disable Edge Acceleration
When edge acceleration is disabled, requests go directly through the CloudBase gateway.
Step 1: Add Custom Domain in CloudBase Console
Add custom domain in CloudBase Console/HTTP Gateway and select CloudBase Access (disable edge acceleration)
Step 2: Wait for Domain Association to Complete
After adding custom domain in CloudBase console, you need to wait for domain association to complete. It usually takes 3-5 minutes. After successful domain association, copy the CNAME value.
Step 3: Go to DNS Console and Add CNAME Resolution
Using the CNAME value copied in step 2, go to your domain DNS service provider to add CNAME record. Request will be routed to CDN only after adding CNAME record and the domain will take effect. Go to DNS Console to add domain resolution record.
Step 4: Complete CloudBase Access
Return to CloudBase console and check custom domain access status
If custom domain access status is not updated, you can refresh the page and check again.
Migrate Existing CloudBase CDN to Enable Edge Acceleration
The previous "CloudBase CDN" access method is no longer supported. If your domain was previously configured with the CloudBase CDN access method, it is recommended to migrate to CloudBase Access (enable Edge Acceleration) to leverage edge acceleration capabilities for a better access experience.
- On the Domain Management page, find the original domain, click "Edit", change the access method to CloudBase Access, and enable Edge Acceleration, then save.
- The first time Edge Acceleration is enabled, edge acceleration domain ownership verification is required. During the process, add the corresponding DNS TXT record as guided.
- After the access method is changed and the status returns to normal, go to the DNS resolution console and point the domain CNAME to the newly created CNAME value.
Inherit Wildcard Domain
If your domain is an exact subdomain under a connected wildcard domain (for example, api.example.com under *.example.com), you can choose "Inherit Wildcard Domain". This reuses the certificate, DNS configuration, and domain ownership verification result of a wildcard domain already connected at the platform level or in the current environment. You do not need to configure them again for the exact subdomain.
See Wildcard Domain Access for how to connect a wildcard domain, and CloudBase Platform Edition Overview for the platform edition.
Custom Access
CDN Access
Step 1: Add Custom Domain in CloudBase Console
Add custom domain in CloudBase Console/HTTP Gateway, select Custom CDN, and copy the origin domain
Step 2: Add CDN Domain
Go to CDN Console and click "Add Domain".
Step 3: CDN Domain Configuration
1. Configure Origin Domain: Add domain configuration, paste the origin domain copied in step 1 into the origin domain address.
Please independently select acceleration region and acceleration type based on business type.
2. Fill in Recommended Configuration: Improve acceleration performance.
If no additional configuration is needed, this step can be skipped.
3. Add CNAME Resolution: Copy the CNAME value in CDN console, go to DNS console to add CNAME type resolution.
DNS resolution needs to be added in the corresponding domain service provider console as CNAME resolution record.
4. Complete Configuration: Complete custom CDN configuration
Step 4: Verify CDN Domain Access
After adding CNAME record, it usually takes 5-30 minutes for DNS resolution to take effect. Return to CloudBase console to check custom CDN access status. You can check whether domain resolution has taken effect using the following command:
nslookup Your Custom Domain
If the result shows the CNAME domain provided by CloudBase, then the resolution has taken effect.
WAF Access
The WAF (Web Application Firewall) access flow is similar to custom CDN access. The key difference is: after configuring the origin server in the WAF console, you need to fill the WAF-assigned CNAME back to the CloudBase console, and then add a CNAME record at your DNS service provider.
Step 1: Add Custom Domain in CloudBase Console
Add custom domain in HTTP Gateway, select Custom CDN, and copy the origin domain.
Step 2: Add WAF Domain
Go to the Web Application Firewall console and click "Add Domain" in the "Access Management" section.
Step 3: Configure WAF Origin Server
Click "Edit" in the newly added domain row, set the "Origin Address" type to "Domain", and paste the CloudBase origin domain copied in Step 1 into the origin address field.
Origin domain example: xxxxxx-1234567890.ap-shanghai.service.tcloudbase.com, please refer to the value shown in the console.
Step 4: Get WAF CNAME and Fill Back to CloudBase
- In the WAF domain list, copy the CNAME value from the "CNAME" column.
- Return to HTTP Gateway, paste the WAF-assigned CNAME value into the "CNAME" field of the corresponding domain and save.
Step 5: Add CNAME Resolution in DNS Console
Point your domain's CNAME to the WAF-assigned CNAME value. Go to DNS Console to add a CNAME record.
DNS resolution needs to be added in your domain's actual DNS service provider console as a CNAME record. For Tencent Cloud DNS, refer to the "Tencent Cloud DNS Setup Method" section at the end of this document.
Step 6: Verify WAF Domain Access
After adding the CNAME record, it usually takes 5-30 minutes for DNS resolution to take effect. Return to the CloudBase console to check the WAF domain access status. You can check whether domain resolution has taken effect using the following command:
nslookup Your Custom Domain
If the result shows the WAF-assigned CNAME domain, then the resolution has taken effect.
Tencent Cloud DNS Setup Method
If your DNS service provider is Tencent Cloud, you can add CNAME records following these steps:
1. Enter Domain ResolutionLog in to Domain Service Console, find the target domain in the domain list, and click "Resolution" in the operation column.
2. Add Resolution Record
On the resolution page, click "Add Record".
3. Configure Resolution Record
Configure resolution record parameters:
- Host Record: Fill in domain prefix (e.g.:
@) - Record Type: Select
CNAME - Record Value: Fill in CNAME value
- Click "Save" to complete configuration
There are priority differences between different record types for domain resolution. When the host record is the same, different record types on the same line cannot coexist, otherwise conflicts will be prompted. CNAME records conflict with any record type except CNAME records, and other records need to be deleted before configuration. For details, please refer to Why does it prompt "record conflict" when adding resolution records.
Usage Restrictions
- The maximum number of custom domains a CloudBase environment can bind varies by plan. For details, refer to the Plan Quotas and Capabilities
- Domain resolution takes time to take effect, please be patient