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
Direct Public IP Access	Development testing, temporary access	Flexible, supports any protocol and port

Recommended Approach

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: 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: 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 })
})

Q3: 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
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: Direct Public IP Access​

Applicable Scenarios​

Access Methods​

Characteristics​

View Public IP​

FAQ​