支持地域：上海

LeanCloud 云引擎迁移至 CloudBase 云托管/云函数指南

概述

LeanCloud 云引擎使用固定框架模式开发，支持 Node.js、Python、Java、PHP、.NET、Go 等多种语言。迁移到腾讯云 CloudBase 时，可根据业务场景选择云托管或云函数两种方案。

核心优势

云托管：支持Dockerfile 部署，同时也支持无 Dockerfile 自动识别框架，保留原有项目结构，迁移更平滑
云函数：无服务器架构，适合轻量级 API 和事件驱动场景

迁移方案选择

场景	推荐方案	说明
完整 Web 应用	云托管	保留原有框架结构，支持无 Dockerfile 部署
复杂业务逻辑	云托管	支持长连接、WebSocket、多进程
简单 API	云函数	按调用计费，成本更低
轻量逻辑	云函数	无需管理服务器
定时任务	云函数 + 定时触发器	配置简单
Hook 钩子	云函数 + 数据库触发器	功能对等

云托管迁移详解

核心特性：无 Dockerfile 部署

云托管支持无 Dockerfile 模式，会自动识别项目的语言和框架，完成构建部署。这与 LeanCloud 云引擎的固定框架模式非常相似，迁移成本极低。

支持的语言和框架

语言	支持的框架
Node.js	Express、Koa、NestJS、Egg.js、Next.js、Nuxt.js 等
Python	Flask、Django、FastAPI 等
Java	Spring Boot、Spring MVC 等
Go	Gin、Echo、Beego 等
PHP	Laravel、ThinkPHP 等

步骤 1：理解 leanengine.yaml 配置映射

LeanCloud 云引擎使用 leanengine.yaml 配置启动脚本和端口。迁移到云托管时，需要将这些配置映射到云托管的部署配置中。

LeanCloud leanengine.yaml 示例

# leanengine.yaml（LeanCloud 配置）
runtime: nodejs # 运行时语言
run: npm start # 启动脚本
build: npm run build # 构建脚本（可选）
install: npm install # 安装依赖脚本
port: 3000 # 监听端口

云托管无 Dockerfile 配置映射

在云托管控制台部署时，需要配置以下对应项：

leanengine.yaml 配置	云托管配置项	说明
`runtime`	语言版本选择	在控制台选择对应语言和版本
`run`	启动命令	配置启动脚本，如 `npm start`
`build`	构建命令	配置构建脚本，如 `npm run build`
`install`	安装命令	配置依赖安装，如 `npm install`
`port`	监听端口	配置服务监听端口

配置示例对照

LeanCloud 原配置（leanengine.yaml）：

runtime: nodejs
run: node server.js
build: npm run build
install: npm ci --production
port: 3000

云托管部署配置：

语言版本：Node.js 18
安装命令：npm ci --production
构建命令：npm run build
启动命令：node server.js
监听端口：3000

步骤 2：代码改造

2.1 移除 LeanCloud 特有代码

旧代码（LeanCloud 云引擎入口）：

const AV = require("leancloud-storage");
const { Cloud } = require("leancloud-storage");

// LeanCloud 初始化
AV.init({
  appId: process.env.LEANCLOUD_APP_ID,
  appKey: process.env.LEANCLOUD_APP_KEY,
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY,
});

// 云引擎特有中间件
app.use(AV.express());

新代码（标准应用）：

const express = require("express");
const app = express();

// 使用标准中间件
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

2.2 替换数据库操作

旧代码（LeanCloud SDK）：

const AV = require("leancloud-storage");

// 查询数据
const query = new AV.Query("Todo");
query.equalTo("status", "active");
const todos = await query.find();

// 创建数据
const Todo = AV.Object.extend("Todo");
const todo = new Todo();
todo.set("title", "新任务");
await todo.save();

新代码（CloudBase SDK）：

const cloudbase = require("@cloudbase/node-sdk");

const app = cloudbase.init({ env: process.env.ENV_ID });
const db = app.database();

// 查询数据
const { data: todos } = await db
  .collection("Todo")
  .where({ status: "active" })
  .get();

// 创建数据
await db.collection("Todo").add({
  title: "新任务",
  _createTime: Date.now(),
});

2.3 配置监听端口

确保应用读取环境变量中的端口配置：

// 从环境变量读取端口，与 leanengine.yaml 中的 port 配置保持一致
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

步骤 3：准备部署配置

3.1 创建 cloudbaserc.json（可选）

如果使用 CLI 部署，可以创建配置文件：

{
  "envId": "your-env-id",
  "framework": {
    "name": "my-app",
    "plugins": {
      "node": {
        "use": "@cloudbase/framework-plugin-node",
        "inputs": {
          "entry": "server.js",
          "installCommand": "npm ci --production",
          "buildCommand": "npm run build"
        }
      }
    }
  }
}

3.2 不同语言的配置示例

Node.js 项目：

启动命令：npm start 或 node server.js
安装命令：npm install 或 npm ci
构建命令：npm run build（如有）
监听端口：3000（或自定义）

Python 项目：

启动命令：python app.py 或 gunicorn app:app
安装命令：pip install -r requirements.txt
构建命令：（通常不需要）
监听端口：5000（或自定义）

Java 项目（Spring Boot）：

启动命令：java -jar target/app.jar
安装命令：（通常不需要）
构建命令：mvn package -DskipTests
监听端口：8080（或自定义）

Go 项目：

启动命令：./main
安装命令：go mod download
构建命令：go build -o main
监听端口：8080（或自定义）

步骤 4：通过控制台部署（无 Dockerfile）

登录 CloudBase 控制台：https://tcb.cloud.tencent.com/dev
进入「云托管」服务
点击「新建服务」
选择「代码库导入」或「本地代码上传」
部署配置选择「无 Dockerfile」
选择对应的语言版本
配置启动命令（对应 leanengine.yaml 的 run）
配置构建命令（对应 leanengine.yaml 的 build）
配置安装命令（对应 leanengine.yaml 的 install）
配置监听端口（对应 leanengine.yaml 的 port）
点击「部署」，云托管会自动完成构建和部署

步骤 5：配置环境变量

在云托管控制台配置环境变量，替换原有的 LeanCloud 环境变量：

LeanCloud 环境变量	CloudBase 替代	说明
`LEANCLOUD_APP_ID`	`ENV_ID`	CloudBase 环境 ID
`LEANCLOUD_APP_KEY`	不需要	云托管内部自动鉴权
`LEANCLOUD_APP_MASTER_KEY`	不需要	云托管内部自动鉴权
`LEANCLOUD_APP_PORT`	`PORT`	服务监听端口
`LEANCLOUD_APP_ENV`	`TCB_ENV`	环境标识（可自定义）

自定义环境变量迁移：

原有在 LeanCloud 控制台配置的自定义环境变量，需要在云托管控制台重新配置。

步骤 6：配置域名和路由

在云托管控制台进入服务详情
点击「访问配置」
添加自定义域名
上传 HTTPS 证书（或使用免费证书）
配置路由规则（如需）

云函数迁移详解

适用场景

简单的 API 接口
事件驱动的处理逻辑
定时任务
数据库 Hook（触发器）

步骤 1：云函数迁移

LeanCloud 云函数 → CloudBase 云函数

旧代码（LeanCloud）：

AV.Cloud.define("hello", async (request) => {
  const name = request.params.name;
  const user = request.currentUser;
  return `Hello, ${name}!`;
});

新代码（CloudBase）：

// functions/hello/index.js
const cloudbase = require("@cloudbase/node-sdk");

exports.main = async (event, context) => {
  const { name } = event;
  // context.userInfo 包含用户信息（如已登录）
  return {
    message: `Hello, ${name}!`,
    code: 0,
  };
};

云函数目录结构

functions/
├── hello/
│   ├── index.js      # 入口文件
│   └── package.json  # 依赖配置
├── getUserInfo/
│   ├── index.js
│   └── package.json
└── ...

步骤 2：Hook 迁移（数据库触发器）

beforeSave → insert 触发器

旧代码（LeanCloud）：

AV.Cloud.beforeSave("Todo", async (request) => {
  const todo = request.object;
  if (!todo.get("title")) {
    throw new AV.Cloud.Error("Title is required");
  }
  // 自动设置默认值
  if (!todo.get("status")) {
    todo.set("status", "pending");
  }
});

新代码（CloudBase 触发器）：

// functions/todo-before-insert/index.js
exports.main = async (event, context) => {
  const { data, docId, dataType } = event;

  // dataType: insert / update / delete
  if (dataType === "insert") {
    // 验证数据
    if (!data.title) {
      console.error("Title is required");
      // 注意：触发器无法阻止写入，需在客户端或安全规则中处理
    }
  }

  return { success: true };
};

配置触发器（控制台）：

进入 CloudBase 控制台 > 数据库
选择集合 > 触发器
添加触发器，选择触发事件（写入/更新/删除）
关联云函数

afterSave / afterUpdate / afterDelete

// functions/todo-after-save/index.js
exports.main = async (event, context) => {
  const { data, docId, dataType } = event;

  if (dataType === "insert") {
    // afterSave 逻辑
    console.log(`Todo ${docId} created`);
  } else if (dataType === "update") {
    // afterUpdate 逻辑
    console.log(`Todo ${docId} updated`);
  } else if (dataType === "delete") {
    // afterDelete 逻辑
    console.log(`Todo ${docId} deleted`);
  }

  return { success: true };
};

步骤 3：定时任务迁移

旧代码（LeanCloud）：

AV.Cloud.define("dailyReport", async () => {
  // 每日报告生成逻辑
  const report = await generateDailyReport();
  await sendEmail(report);
});
// 在控制台配置 Cron: 0 8 * * *

新代码（CloudBase）：

// functions/dailyReport/index.js
exports.main = async (event, context) => {
  // event.TriggerTime 包含触发时间
  const report = await generateDailyReport();
  await sendEmail(report);

  return {
    success: true,
    triggerTime: event.TriggerTime,
  };
};

配置定时触发器：

// functions/dailyReport/config.json
{
  "triggers": [
    {
      "name": "dailyTrigger",
      "type": "timer",
      "config": "0 0 8 * * * *"
    }
  ]
}

或在控制台配置：

进入云函数详情
点击「触发器」
添加定时触发器
配置 Cron 表达式：0 0 8 * * * *（每天 8:00）

步骤 4：部署云函数

# 安装 CloudBase CLI
npm install -g @cloudbase/cli

# 登录
tcb login

# 初始化项目（如未初始化）
tcb config init

# 部署所有云函数
tcb fn deploy

# 部署单个云函数
tcb fn deploy hello

# 查看云函数日志
tcb fn log hello

# 调用云函数（测试）
tcb fn invoke hello --params '{"name": "World"}'

功能迁移对照表

云引擎功能映射

LeanCloud 云引擎功能	CloudBase 对应方案	备注
`leanengine.yaml` 配置	云托管部署配置	启动命令、端口等
`AV.Cloud.define()`	云函数 `exports.main`	API 接口
`AV.Cloud.beforeSave()`	数据库触发器（insert）	前置处理
`AV.Cloud.afterSave()`	数据库触发器（insert）	后置处理
`AV.Cloud.beforeUpdate()`	数据库触发器（update）	更新前
`AV.Cloud.afterUpdate()`	数据库触发器（update）	更新后
`AV.Cloud.beforeDelete()`	数据库触发器（delete）	删除前
`AV.Cloud.afterDelete()`	数据库触发器（delete）	删除后
`AV.Cloud.onLogin()`	登录鉴权回调	用户登录
`AV.Cloud.onVerified()`	自定义云函数	验证回调
定时任务（Cron）	定时触发器	配置相同
LeanDB Redis	腾讯云 Redis	单独购买
LeanDB MySQL	腾讯云 MySQL	单独购买
环境变量	云托管/云函数环境变量	控制台配置
分组管理	云托管服务 + 版本管理	多版本部署

API 迁移对照

LeanCloud API	CloudBase API	说明
`request.params`	`event`	函数参数
`request.currentUser`	`context.userInfo`	当前用户
`request.object`	`event.data`	触发器数据
`AV.Cloud.Error()`	`throw new Error()`	错误处理
`AV.Cloud.run()`	`cloudbase.callFunction()`	调用云函数

常见问题

1. 如何处理 LeanCloud 的 before 钩子验证逻辑？

CloudBase 的数据库触发器是异步的，无法阻止数据写入。建议：

使用安全规则进行数据验证
在客户端 SDK 调用前进行验证
使用云函数作为数据写入的唯一入口

2. 端口配置不同怎么办？

云托管支持自定义端口，在部署时配置即可。确保代码中读取 PORT 环境变量：

const PORT = process.env.PORT || 3000;

3. 如何保持 API 路径不变？

云托管支持自定义域名和路由配置，可以保持原有 API 路径：

原地址：https://xxx.leancloud.cn/1.1/functions/hello
新地址：https://your-domain.com/1.1/functions/hello

通过云托管的路由规则配置即可实现。

4. LeanDB 如何迁移？

Redis：购买腾讯云 Redis 实例，导出 RDB 后导入
MySQL：购买腾讯云 MySQL，使用 mysqldump 导出后导入

5. 环境变量如何迁移？

在云托管或云函数控制台的「环境变量」配置中添加：

ENV_ID=your-cloudbase-env-id
DATABASE_URL=mysql://...
REDIS_URL=redis://...
# 其他自定义环境变量

目录​

概述​

核心优势​

迁移方案选择​

云托管迁移详解​

核心特性：无 Dockerfile 部署​

支持的语言和框架​

步骤 1：理解 leanengine.yaml 配置映射​

LeanCloud leanengine.yaml 示例​

云托管无 Dockerfile 配置映射​

配置示例对照​

步骤 2：代码改造​

2.1 移除 LeanCloud 特有代码​

2.2 替换数据库操作​

2.3 配置监听端口​

步骤 3：准备部署配置​

3.1 创建 cloudbaserc.json（可选）​

3.2 不同语言的配置示例​

步骤 4：通过控制台部署（无 Dockerfile）​

步骤 5：配置环境变量​

步骤 6：配置域名和路由​

云函数迁移详解​

适用场景​

步骤 1：云函数迁移​

LeanCloud 云函数 → CloudBase 云函数​

云函数目录结构​

步骤 2：Hook 迁移（数据库触发器）​

beforeSave → insert 触发器​

afterSave / afterUpdate / afterDelete​

步骤 3：定时任务迁移​

步骤 4：部署云函数​

功能迁移对照表​

云引擎功能映射​

API 迁移对照​

常见问题​

1. 如何处理 LeanCloud 的 before 钩子验证逻辑？​

2. 端口配置不同怎么办？​

3. 如何保持 API 路径不变？​

4. LeanDB 如何迁移？​

5. 环境变量如何迁移？​

迁移检查清单​

目录

概述

核心优势

迁移方案选择

云托管迁移详解

核心特性：无 Dockerfile 部署

支持的语言和框架

步骤 1：理解 leanengine.yaml 配置映射

LeanCloud leanengine.yaml 示例

云托管无 Dockerfile 配置映射

配置示例对照

步骤 2：代码改造

2.1 移除 LeanCloud 特有代码

2.2 替换数据库操作

2.3 配置监听端口

步骤 3：准备部署配置

3.1 创建 cloudbaserc.json（可选）

3.2 不同语言的配置示例

步骤 4：通过控制台部署（无 Dockerfile）

步骤 5：配置环境变量

步骤 6：配置域名和路由

云函数迁移详解

适用场景

步骤 1：云函数迁移

LeanCloud 云函数 → CloudBase 云函数

云函数目录结构

步骤 2：Hook 迁移（数据库触发器）

beforeSave → insert 触发器

afterSave / afterUpdate / afterDelete

步骤 3：定时任务迁移

步骤 4：部署云函数

功能迁移对照表

云引擎功能映射

API 迁移对照

常见问题

1. 如何处理 LeanCloud 的 before 钩子验证逻辑？

2. 端口配置不同怎么办？

3. 如何保持 API 路径不变？

4. LeanDB 如何迁移？

5. 环境变量如何迁移？

迁移检查清单