Access Cloud Server

CloudBase provides multiple ways to access services deployed on Lighthouse servers, meeting the needs of different scenarios:

Access Method	Applicable Scenarios	Features
Mini Program SDK Access	WeChat Mini Program calling backend services	Private network access, automatic user identity, no need to expose public IP
HTTP Access Service (Coming Soon)	Web apps, H5 pages, third-party system calls	Custom domain support, HTTPS encryption, easy management
Direct Public IP Access	Development testing, temporary access	Flexible, supports any protocol and port

Recommended Approach

Production Environment: It is recommended to use HTTP Access Service with a custom domain for better stability and security
Mini Program Scenarios: Use Mini Program SDK Access to enjoy private network acceleration and identity authentication
Development & Debugging: You can temporarily use Direct Public IP Access for quick verification

Method 1: Mini Program SDK Access

Mini Programs can directly call cloud server APIs through the WeChat Cloud Development SDK without exposing a public IP, enjoying private network acceleration and automatic identity authentication. Currently, when accessing via Mini Program SDK, only port 80 on the cloud server can be reached. Make sure to start your service and listen on port 80.

Prerequisites

Ensure the service on the cloud server is started and listening on port 80. This can be achieved by:

Using Nginx Reverse Proxy: Forward port 80 to the application port
Application Directly Listening on Port 80: Configure the web framework (such as Express, Flask, etc.) to listen on port 80

Code Example

// 1. Initialize Cloud Development environment in app.js onLaunch
wx.cloud.init({
    env: 'your-env-id',  // Replace with your environment ID
    traceUser: true,
})

// 2. Use callContainer method where needed
const result = await wx.cloud.callContainer({
    config: {
        env: "your-env-id"  // You can specify the environment at call time
    },
    header: {
        "X-WX-SERVICE": "tcbanyservice",        // [Required] Fixed value, specifies CloudBase service
        "X-Vm-Service": "lhins-xxxxxxxxx",      // [Required] Replace with your instance ID
        // You can add other custom Headers
    },
    path: "/api/user/info",     // API path
    method: "POST",             // HTTP method
    data: {                     // Request parameters
        userId: 123
    }
})

console.log('Response:', result.data)

Core Parameter Description

Header Field	Required	Description	Example Value
`X-WX-SERVICE`	✅ Required	Fixed as `tcbanyservice`, used to route to CloudBase service	`tcbanyservice`
`X-Vm-Service`	✅ Required	Instance ID of the Lighthouse server, viewable in the console	`lhins-abc123`

How to Get the Instance ID

On the CloudBase Console - Cloud Server page, click the server name to view the instance ID (format: lhins-xxxxxxxxx)

Debugging Steps

Local Verification: Test whether the service is working properly using public IP + port 80
```
curl http://<server-public-ip>/api/user/info
```
Mini Program Verification: After local verification passes, test the SDK call in the WeChat Developer Tools

Auto-Injected Information

CloudBase automatically carries Mini Program user and environment information in the request Headers. The backend service can directly read these Headers for identity verification and business logic:

User Identity Information

Header Field	Description	Example
`X-WX-OPENID`	User OpenID (unique user identifier)	`oABCD1234567890`
`X-WX-APPID`	Mini Program AppID	`wx1234567890abcdef`
`X-WX-UNIONID`	User UnionID (cross-app identifier, requires conditions)	`oUNIONabcd123456`

Environment & Call Information

Header Field	Description	Example
`X-WX-ENV`	CloudBase environment ID	`test-1a2b3c`
`X-WX-SOURCE`	Call source	`wx_devtools` (Developer Tools) `wx_client` (Real device)
`X-WX-PLATFORM`	Call platform	`devtools` / `android` / `ios`
`X-Forwarded-For`	Client real IP (supports IPv4/IPv6)	`192.168.1.100`

Resource Sharing Scenarios (when using cloud resources from another Mini Program)

Header Field	Description
`X-WX-FROM-OPENID`	User OpenID of the resource-owning Mini Program
`X-WX-FROM-APPID`	AppID of the resource-owning Mini Program
`X-WX-FROM-UNIONID`	User UnionID of the resource-owning Mini Program

Backend Example (Node.js Express)

app.post('/api/user/info', (req, res) => {
    // Get user OpenID
    const openid = req.headers['x-wx-openid']
    const appid = req.headers['x-wx-appid']
    
    console.log('User OpenID:', openid)
    console.log('App ID:', appid)
    
    // Business logic...
    res.json({ code: 0, message: 'success' })
})

Response Information

CloudBase adds debugging and monitoring Headers to the response:

Header Field	Description
`X-Cloudbase-Request-Id`	Unique request identifier for issue tracking and log queries
`X-Cloudbase-Upstream-Status-Code`	Actual HTTP status code returned by the backend service
`X-Cloudbase-Upstream-Timecost`	Backend service processing time (milliseconds)
`X-Cloudbase-Upstream-Type`	Backend service type identifier

Troubleshooting

When encountering issues, please record the X-Cloudbase-Request-Id and provide it to technical support for quick problem identification.

Method 2: HTTP Access Service (Recommended)

CloudBase provides a unified HTTP Access Service to access cloud servers through domain binding, supporting HTTPS encryption and custom domains, suitable for production environments.

Coming Soon

HTTP Access Service support for Cloud Server is coming soon. Stay tuned.

Core Advantages

✅ HTTPS Encrypted Transmission: Automatically configures SSL certificates to ensure data security
✅ Custom Domain Support: Bind registered domains to enhance brand presence
✅ Unified Access Management: Manage all access paths centrally in the console
✅ Multiple Scenario Support: Web applications, H5 pages, API services, third-party system calls

Configuration Steps

Step 1: Create Route Configuration

Log in to the CloudBase Console and navigate to the target environment
Click "HTTP Access Service" in the left menu
Click the "Create" button in the "Route Configuration" section
Fill in the configuration details:

Configuration Item	Description	Example
Associated Resource Type	Select "Cloud Server"	-
Select Instance	Choose the target Lighthouse server instance	`lhins-abc123`
Domain	Choose default domain, custom domain, or `*` (all domains)	`Default Domain` or `api.example.com`
Trigger Path	Set the access path, supports `/` or custom paths	`/` or `/api`

About Domain Selection

Default Domain: xxx.service.tcloudbase.com provided by CloudBase, ready to use immediately
Custom Domain: Must have completed ICP filing, and DNS resolution must be configured. See Custom Domain Configuration
* Wildcard: Matches all access domains, suitable for multi-domain scenarios

Step 2: Configure Server Port

Ensure the service on the cloud server is started and listening on port 80 (HTTP Access Service will forward requests to port 80).

Step 3: Test Access

After configuration, access via the following methods:

# Using default domain
curl https://your-env-id.service.tcloudbase.com/api/hello

# Using custom domain
curl https://api.example.com/api/hello

Browser Access Example:

https://your-env-id.service.tcloudbase.com/

Advanced Configuration

Path Mapping Examples

Configuration	Access URL	Forwarded to Server
Trigger Path: `/`	`https://domain.com/api/user`	`http://server-ip:80/api/user`
Trigger Path: `/api`	`https://domain.com/api/user`	`http://server-ip:80/user`

Note

If the trigger path is set to /api, when accessing https://domain.com/api/user, the actual path forwarded to the server is /user (the /api prefix is removed)

Method 3: Direct Public IP Access

Lighthouse servers are assigned a public IP address by default, and you can directly access services running on the server via the IP.

Applicable Scenarios

🔧 Development & Debugging: Quickly verify that the service is running properly
🧪 Temporary Testing: Test functionality without configuring a domain
🌐 Non-HTTP Protocols: Access SSH, databases, custom protocol services

Access Methods

HTTP/HTTPS Services

# HTTP access (default port 80)
curl http://<public-ip>/api/hello

# HTTPS access (requires SSL certificate configured on the server)
curl https://<public-ip>:443/api/hello

# Custom port
curl http://<public-ip>:8080/api/hello

SSH Connection

ssh root@<public-ip>

Database Connection

# MySQL example
mysql -h <public-ip> -P 3306 -u root -p

Characteristics

Feature	Description
Protocol Support	Supports any protocol (HTTP, HTTPS, TCP, UDP, etc.)
Port Restrictions	None, determined by the services running on the server
Security	Firewall rules must be configured carefully to avoid exposing unnecessary ports
Stability	IP address may change (e.g., after server restart)

Security Tips

Not recommended for production: Direct public IP access lacks HTTPS encryption and access control, posing security risks
Configure Firewall: In the console's firewall settings, only open necessary ports (e.g., 80, 443, 22)
Use Strong Passwords: If management ports like SSH are open, always use strong passwords or key-based authentication

View Public IP

On the CloudBase Console - Cloud Server page, click the server instance to view the public IP address.

FAQ

Q1: Mini Program SDK access to cloud server returns "service not found" error?

Possible Causes:

The instance ID in X-Vm-Service is incorrect
The service on the server is not listening on port 80
The server firewall has not opened port 80

Solutions:

Confirm the instance ID in the console (format: lhins-xxxxxxxxx)
Run netstat -tlnp | grep 80 on the server to confirm the service is listening
First test the service using public IP + port 80

Q2: Cannot access after configuring HTTP Access Service?

Checklist:

✅ Is the service on the server started and listening on port 80?
✅ Is the instance ID in the route configuration correct?
✅ Does the trigger path configuration match the actual request path?
✅ If using a custom domain, has DNS resolution taken effect?

Debugging Methods:

# 1. Test local service on the server
curl http://localhost:80/

# 2. Test using public IP
curl http://<public-ip>/

# 3. Test using domain
curl https://your-domain.com/

Q3: How to get the Mini Program user's OpenID in the backend?

When called via the Mini Program SDK, CloudBase automatically injects user information in the request Headers:

// Node.js example
app.post('/api/user/info', (req, res) => {
    const openid = req.headers['x-wx-openid']
    const appid = req.headers['x-wx-appid']
    
    if (!openid) {
        return res.status(401).json({ error: 'Unauthorized' })
    }
    
    // Use openid for business logic
    res.json({ openid, appid })
})

Q4: Which access method should be chosen for production environments?

Recommended:

Mini Program Scenarios: Use "Mini Program SDK Access" for private network acceleration and automatic identity authentication
Web/API Scenarios: Use "HTTP Access Service" + custom domain to provide stable HTTPS services
Avoid: Direct Public IP access (only suitable for development and testing)

Reasons:

Public IP may change, not suitable for long-term use
Lacks HTTPS encryption, posing data leakage risks
Cannot perform unified access control and traffic management

Method 1: Mini Program SDK Access​

Prerequisites​

Code Example​

Core Parameter Description​

Debugging Steps​

Auto-Injected Information​

Response Information​

Method 2: HTTP Access Service (Recommended)​

Core Advantages​

Configuration Steps​

Step 1: Create Route Configuration​

Step 2: Configure Server Port​

Step 3: Test Access​

Advanced Configuration​

Method 3: Direct Public IP Access​

Applicable Scenarios​

Access Methods​

Characteristics​

View Public IP​

FAQ​