访问云服务器

云开发提供了多种方式访问轻量应用服务器上部署的服务，满足不同场景的需求：

访问方式	适用场景	特点
小程序 SDK 访问	微信小程序调用后端服务	内网访问、自动携带用户身份、无需暴露公网 IP
HTTP 网关（待上线支持）	Web 应用、H5 页面、第三方系统调用	支持自定义域名、HTTPS 加密、便于管理
公网 IP 直连	开发测试、临时访问	灵活、支持任意协议和端口

推荐方式

生产环境：建议使用 HTTP 网关 绑定自定义域名，获得更好的稳定性和安全性
小程序场景：使用 小程序 SDK 访问，享受内网加速和身份认证能力
开发调试：可以临时使用 公网 IP 直连 进行快速验证

方式一：小程序 SDK 访问

小程序可以通过微信云开发 SDK 直接调用云服务器接口，无需暴露公网 IP，享受内网加速和自动身份认证。当前小程序 SDK 访问时，仅可以请求到云服务器上的 80 端口，请确保在 80 端口上启动服务并进行监听。

前置准备

确保云服务器上的服务已启动并监听 80 端口。可以通过以下方式实现：

使用 Nginx 反向代理：将 80 端口转发到应用端口
应用直接监听 80 端口：配置 Web 框架（如 Express、Flask 等）监听 80 端口

代码示例

// 1. 在小程序 app.js 的 onLaunch 中初始化云开发环境
wx.cloud.init({
    env: 'your-env-id',  // 替换为你的环境 ID
    traceUser: true,
})

// 2. 在需要调用的地方使用 callContainer 方法
const result = await wx.cloud.callContainer({
    config: {
        env: "your-env-id"  // 可以在调用时指定环境
    },
    header: {
        "X-WX-SERVICE": "tcbanyservice",        // 【必填】固定值，指定云开发服务
        "X-Vm-Service": "lhins-xxxxxxxxx",      // 【必填】替换为你的实例 ID
        // 可以添加其他自定义 Header
    },
    path: "/api/user/info",     // API 路径
    method: "POST",             // HTTP 方法
    data: {                     // 请求参数
        userId: 123
    }
})

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

核心参数说明

Header 字段	是否必填	说明	示例值
`X-WX-SERVICE`	✅ 必填	固定为 `tcbanyservice`，用于路由到云开发服务	`tcbanyservice`
`X-Vm-Service`	✅ 必填	轻量服务器的实例 ID，在控制台可查看	`lhins-abc123`

如何获取实例 ID

在云开发控制台 - 云服务器页面，点击服务器名称可查看实例 ID（格式如 lhins-xxxxxxxxx）

调试步骤

本地验证：使用公网 IP + 80 端口测试服务是否正常
```
curl http://<服务器公网IP>/api/user/info
```
小程序端验证：确认本地验证通过后，在小程序开发者工具中测试 SDK 调用

自动注入的信息

云开发会在请求 Header 中自动携带小程序用户和环境信息，后端服务可直接读取这些 Header 实现身份验证和业务逻辑：

用户身份信息

Header 字段	说明	示例
`X-WX-OPENID`	用户 OpenID（用户唯一标识）	`oABCD1234567890`
`X-WX-APPID`	小程序 AppID	`wx1234567890abcdef`
`X-WX-UNIONID`	用户 UnionID（跨应用标识，需满足条件）	`oUNIONabcd123456`

环境与调用信息

Header 字段	说明	示例
`X-WX-ENV`	云开发环境 ID	`test-1a2b3c`
`X-WX-SOURCE`	调用来源	`wx_devtools`（开发者工具） `wx_client`（真机）
`X-WX-PLATFORM`	调用平台	`devtools` / `android` / `ios`
`X-Forwarded-For`	客户端真实 IP（支持 IPv4/IPv6）	`192.168.1.100`

资源复用场景（当使用其他小程序的云资源时）

Header 字段	说明
`X-WX-FROM-OPENID`	资源所属小程序的用户 OpenID
`X-WX-FROM-APPID`	资源所属小程序的 AppID
`X-WX-FROM-UNIONID`	资源所属小程序的用户 UnionID

后端获取示例（Node.js Express）

app.post('/api/user/info', (req, res) => {
    // 获取用户 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)
    
    // 业务逻辑...
    res.json({ code: 0, message: 'success' })
})

响应信息

云开发会在响应中添加调试和监控相关的 Header：

Header 字段	说明
`X-Cloudbase-Request-Id`	请求唯一标识，用于问题追踪和日志查询
`X-Cloudbase-Upstream-Status-Code`	后端服务实际返回的 HTTP 状态码
`X-Cloudbase-Upstream-Timecost`	后端服务处理耗时（毫秒）
`X-Cloudbase-Upstream-Type`	后端服务类型标识

故障排查

遇到问题时，请记录 X-Cloudbase-Request-Id，提供给技术支持以便快速定位问题。

方式二：HTTP 网关（推荐）

CloudBase 提供统一的 HTTP 网关，通过域名绑定的方式访问云服务器，支持 HTTPS 加密、自定义域名，适合生产环境使用。

待上线支持

HTTP 网关支持云服务器即将提供，敬请期待。

核心优势

✅ HTTPS 加密传输：支持配置 SSL 证书，保障数据安全
✅ 自定义域名支持：可绑定已备案域名，提升品牌形象
✅ 统一访问管理：在控制台统一管理所有访问路径
✅ 适用多种场景：Web 应用、H5 页面、API 服务、第三方系统调用

配置步骤

步骤 1：创建路由配置

登录云开发控制台，进入目标环境
点击左侧菜单「HTTP 网关」
在「路由配置」模块点击「新建」按钮
填写配置信息：

配置项	说明	示例
关联资源类型	选择「云服务器」	-
选择实例	选择目标轻量应用服务器实例	`lhins-abc123`
域名	可选择默认域名、自定义域名或 `*`（所有域名）	`默认域名` 或 `api.example.com`
触发路径	设置访问路径，支持 `/` 或自定义路径	`/` 或 `/api`

关于域名选择

默认域名：云开发提供的 xxx.service.tcloudbase.com，开通即用
自定义域名：需已完成 ICP 备案，并配置 DNS 解析，详见自定义域名配置
* 通配符：匹配所有访问域名，适合多域名场景

步骤 2：配置服务器端口

确保云服务器上的服务已启动并监听 80 端口（HTTP 网关会将请求转发到 80 端口）。

步骤 3：测试访问

配置完成后，通过以下方式访问：

# 使用默认域名
curl https://your-env-id.service.tcloudbase.com/api/hello

# 使用自定义域名
curl https://api.example.com/api/hello

浏览器访问示例：

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

高级配置

路径映射示例

配置	访问 URL	转发到服务器
触发路径：`/`	`https://domain.com/api/user`	`http://server-ip:80/api/user`
触发路径：`/api`	`https://domain.com/api/user`	`http://server-ip:80/user`

注意

如果设置触发路径为 /api，则访问 https://domain.com/api/user 时，实际转发到服务器的路径是 /user（会移除 /api 前缀）

方式三：公网 IP 直连

轻量应用服务器默认分配公网 IP 地址，可以直接通过 IP 访问服务器上运行的服务。

适用场景

🔧 开发调试：快速验证服务是否正常运行
🧪 临时测试：无需配置域名即可测试功能
🌐 非 HTTP 协议：访问 SSH、数据库、自定义协议服务

访问方式

HTTP/HTTPS 服务

# HTTP 访问（默认 80 端口）
curl http://<公网IP>/api/hello

# HTTPS 访问（需要服务器配置 SSL 证书）
curl https://<公网IP>:443/api/hello

# 自定义端口
curl http://<公网IP>:8080/api/hello

SSH 连接

ssh root@<公网IP>

数据库连接

# MySQL 示例
mysql -h <公网IP> -P 3306 -u root -p

特点

特性	说明
协议支持	支持任意协议（HTTP、HTTPS、TCP、UDP 等）
端口限制	无限制，由服务器上运行的服务决定
安全性	需要注意配置防火墙规则，避免暴露不必要的端口
稳定性	IP 地址可能会变化（重启服务器等操作）

安全提示

生产环境不建议使用：公网 IP 直连缺少 HTTPS 加密和访问控制，存在安全风险
配置防火墙：在控制台的防火墙设置中，仅开放必要的端口（如 80、443、22）
使用强密码：如果开放 SSH 等管理端口，务必使用强密码或密钥认证

查看公网 IP

在云开发控制台 - 云服务器页面，点击服务器实例可查看公网 IP 地址。

常见问题

Q1：小程序 SDK 访问云服务器报错 "找不到服务"？

可能原因：

X-Vm-Service 填写的实例 ID 不正确
服务器上的服务未监听 80 端口
服务器防火墙未开放 80 端口

解决方法：

在控制台确认实例 ID（格式如 lhins-xxxxxxxxx）
在服务器上执行 netstat -tlnp | grep 80 确认服务已监听
先用公网 IP + 80 端口测试服务是否正常

Q2：HTTP 访问服务配置后无法访问？

检查清单：

✅ 服务器上的服务是否已启动并监听 80 端口
✅ 路由配置中的实例 ID 是否正确
✅ 触发路径配置是否与实际请求路径匹配
✅ 如使用自定义域名，DNS 解析是否已生效

调试方法：

# 1. 在服务器上测试本地服务
curl http://localhost:80/

# 2. 使用公网 IP 测试
curl http://<公网IP>/

# 3. 使用域名测试
curl https://your-domain.com/

Q3：如何在后端获取小程序用户的 OpenID？

通过小程序 SDK 调用时，云开发会自动在请求 Header 中注入用户信息：

// Node.js 示例
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: '未授权' })
    }
    
    // 使用 openid 进行业务逻辑
    res.json({ openid, appid })
})

Q4：生产环境应该选择哪种访问方式？

推荐方案：

小程序场景：使用「小程序 SDK 访问」，享受内网加速和自动身份认证
Web/API 场景：使用「HTTP 访问服务」+ 自定义域名，提供稳定的 HTTPS 服务
避免使用：公网 IP 直连（仅适合开发测试）

原因：

公网 IP 可能会变化，不适合长期使用
缺少 HTTPS 加密，存在数据泄露风险
无法进行统一的访问控制和流量管理

方式一：小程序 SDK 访问​

前置准备​

代码示例​

核心参数说明​

调试步骤​

自动注入的信息​

响应信息​

方式二：HTTP 网关（推荐）​

核心优势​

配置步骤​

步骤 1：创建路由配置​

步骤 2：配置服务器端口​

步骤 3：测试访问​

高级配置​

方式三：公网 IP 直连​

适用场景​

访问方式​

特点​

查看公网 IP​

常见问题​