云引擎 C++ 运行环境

info

这篇文档是针对 C++ 运行环境的深入介绍，如希望快速地开始使用云引擎，请查看 快速开始部署云引擎应用。

云引擎目前支持构建使用 Bazel 或 Makefile（CMake）的项目。

C++ 运行环境提供的编译器是 GCC 9.4。

Bazel 项目

如果项目根目录存在 WORKSPACE，云引擎会默认使用 bazel build -c opt //:all 构建，bazel run -c opt //:all 来运行。

Makefile（CMake）项目

如果项目根目录存在 Makefile，云引擎会使用 make 构建。

如果项目根目录存在 CMakeLists.txt，云引擎会先使用 cmake . 来生成 Makefile。

Makefile 项目没有默认的运行命令，需要在 leanengine.yaml 中自行设置运行命令：

leanengine.yaml

run: ./myapp

上传预编译的程序

你也可以选择预先编译好 binary 再上传到云引擎，我们建议在 Ubuntu 20.04 的环境下编译静态链接。

然后在 leanengine.yaml 中自行设置运行命令：

leanengine.yaml

runtime: cpp
run: ./myapp

info

云引擎的构建环境（如发行版版本）可能会发生变化，届时可能需要调整编译参数，但已在云引擎构建好的版本会将所有运行环境固化下来，可供持续运行或随时回滚。

自定义构建过程

Cloud Engine uses the default commands of each language to complete the build process. You can override these commands by editing leanengine.yaml.

Overriding Command for Execution With run

leanengine.yaml

run: $(npm bin)/serve -c static.json -l ${LEANCLOUD_APP_PORT}

You can use shell syntax here for purposes like accessing environment variables.

Overriding Command for Installing Dependencies With install

You can override the default command for installing dependencies (like npm install) or run additional commands before or after installing dependencies.

leanengine.yaml

install: npm

Most runtimes have their default commands for installing dependencies. You can refer to the default command with {use: 'default'}:

leanengine.yaml

install:
  - { use: "default" }
  - npm run install-additional

When installing dependencies, only the dependency lists (like package.json) will be loaded into the build directory. To load additional files, use require:

leanengine.yaml

install:
  - require:
      - frontend/package.json
      - frontend/package-lock.json
  - cd frontend && npm ci

Overriding Command for Building With build

leanengine.yaml

build: npm run build

When building your project, all the files in your project will be loaded into the build directory.

You can specify multiple pieces of commands with an array. You can use shell syntax here as well:

leanengine.yaml

build:
  - echo 'building'
  - NODE_ENV=production $(npm bin)/webpack

Certain runtimes have their default build commands. You can refer to these commands with {use: 'default'}.

构建日志

By default, the logs generated during the build process won’t be printed to the console. If the build process fails, the logs from the last completed step will be printed to the console.

To print the complete build log for debugging, check Print build logs if you are deploying from the dashboard or add --options 'printBuildLogs=true' if you are deploying with the CLI.

系统级依赖

You can specify the system dependencies provided by the server-side environment by setting systemDependencies in leanengine.yaml:

leanengine.yaml

systemDependencies:
  - imagemagick

The following libraries are available for you to add:

• ffmpeg A library for processing audio and videos.
• imagemagick A library for processing images.
• fonts-wqy 文泉驿点阵宋体 and 文泉驿微米黑. Often used with phantomjs or chrome-headless to display Chinese.
• fonts-noto Source Han Sans (comes with a large size).
• phantomjs A headless browser based on WebKit (discontinued).
• chrome-headless Headless Chrome. It comes with a large size and will significantly increase the time needed for deployment. It also consumes a lot of CPU and RAM resources. If you need to use puppeteer, please provide {executablePath: '/usr/bin/google-chrome', args: ['--no-sandbox', '--disable-setuid-sandbox']} to puppeteer.launch. This library doesn’t support Java yet.
• node-canvas The system dependency required for installing node-canvas (you still need to install node-canvas yourself).
• python-talib A library for performing technical analysis of financial market data.

caution

Adding system dependencies will significantly increase the time needed for deployment. Please avoid adding dependencies that your project doesn’t need.

健康检查

Cloud Engine is primarily optimized for web applications. Your app is expected to provide HTTP services through the port specified by the environment variable named LEANCLOUD_APP_PORT. Keep in mind that the app should listen on 0.0.0.0 (all interfaces) instead of 127.0.0.1 which is the default host of many frameworks.

While your app is being deployed, Cloud Engine will check your app every second to see if it has been successfully started. If your app has not been started within the time limit (30 seconds by default), the deployment will be canceled. After your app has been deployed, Cloud Engine will run health checks for your app regularly and automatically restart it if the check fails.

The way the health check works is that Cloud Engine will send an HTTP request to the homepage (/) of your app. If it gets an HTTP 2xx response, your app will pass the health check.

Health check and the Cloud Engine SDK

Cloud Engine will also check /__engine/1/ping which is handled by the SDK. If the SDK is integrated correctly, Cloud Engine will not check the homepage (/) anymore.

If Developer Center > Your game > Game Services > Cloud Services > Cloud Engine > Your group > Settings > Cloud functions mode is set to Enable, or if functionsMode in leanengine.yaml is set to strict, Cloud Engine will check if the SDK is integrated correctly. If not, it will consider your app to have failed to start.

Customizing startup timeout (startupTimeout)

The default timeout for your app to start is 30 seconds. You can change it to any value between 15 and 120 seconds with leanengine.yaml:

leanengine.yaml

startupTimeout: 60

云端环境

绑定自定义域名

Projects deployed to Cloud Engine can only be accessed with domains configured. You can bind domains by going to Developer Center > Your game > Game Services > Cloud Services > Cloud Engine > Your group > Settings > Domains.

If you bind a domain that starts with stg- (e.g., stg-api.example.com), it will be assigned to the staging environment automatically.

We provide shared domains for apps that are still under testing. You can assign your app a shared domain with a prefix of your choice.

负载均衡和加速节点

All HTTP and HTTPS requests sent to Cloud Engine will go through a load balancer that deals with chores including HTTPS encryption, HTTPS redirection, and response compression. You won’t have to implement features for handling these tasks yourself for the programs hosted on Cloud Engine. Meanwhile, the load balancer brings the following restrictions that your program cannot bypass:

• Paths starting with /.well-known/acme-challenge/ are used by Cloud Engine to automatically renew certificates. Requests sent to these paths won’t be forwarded to your program.
• The size of a request header (URL and headers) should be within 64K and each line of the request header should be within 8K.
• The size of a request (for uploading files) should be within 100M.
• The timeout for connecting or waiting for a response is 60 seconds.

Getting the Client IP Address

Cloud Engine’s load balancer includes the following information depicting the original request in the HTTP header:

• X-Real-IP: The original IP address.
• X-Forwarded-Proto: The original protocol (http or https).
• Forwarded: Information about the proxy, defined by RFC 7239. It contains the IP address and the protocol.

caution

If CDN is enabled, the information included in the HTTP headers above will be those of the CDN rather than the original request.

With CDN enabled, the following HTTP headers will also be present:

• X-Forwarded-For: IP addresses separated by a comma. The first one would be the IP address of the original request.

caution

It’s possible that the information included in the HTTP headers above gets counterfeited. Cloud Engine won’t be able to guarantee its authenticity.

info

For Cloud Engine applications deployed within Mainland China, CDN will be enabled by default. To ensure that your application always gets the accurate IP addresses of original requests, consider enabling dedicated IP. You can learn more about the differences between CDN and dedicated IP on Binding Your Domains § Cloud Engine Domains.

HTTPS Redirect

When you bind a custom Cloud Engine domain, you can enable Force HTTPS to have the load balancer redirect HTTP requests to HTTPS while keeping the paths.

caution

Force HTTPS won’t work properly if CDN is enabled. You’ll still need to implement redirect in your project’s code.

CDN Caching

If you resolve your custom domain to the CDN (including the shared domain provided by Cloud Engine), the CDN will cache the responses for the requests it has received. There are some default rules for caching followed by the CDN.

The CDN will cache the response if:

• The response header contains Last-Modified (this indicates that the resource requested is static; for HTML files, they will be cached for at most 60 seconds).

The CDN will not cache the response if:

• There is an error with the response (not 2xx).
• The request is not idempotent (like a POST request).
• The response header doesn’t contain Last-Modified (this often indicates that the resource requested is dynamic).

The age of the cache for a given file will depend on the file type and the value of the Last-Modified header. The less frequently the file gets modified, the longer the file gets cached. You can override the default behavior by configuring Cache-Control and the CDN will try its best to follow your configurations. For example:

• You can use Cache-Control: no-cache to prevent the response from being cached.
• You can use Cache-Control: max-age=3600 to specify the age of the cache (here we set it to be 1 hour).

info

To prevent your application from being affected by the caching mechanism, consider enabling dedicated IP. You can learn more about the differences between CDN and dedicated IP on Binding Your Domains § Cloud Engine Domains.

环境变量

The following environment variables are available for your application to use:

Variable name	Description
LEANCLOUD_APP_ID	The App ID of the current application.
LEANCLOUD_APP_KEY	The App Key of the current application.
LEANCLOUD_APP_MASTER_KEY	The Master Key of the current application.
LEANCLOUD_APP_ENV	The environment your application is running in. If you are running your application on your local computer, the value will be non-existent or development (if you are starting your application with the CLI). It will be stage for the staging environment and production for the production environment.
LEANCLOUD_APP_PORT	The port opened up for your application. Your application has to listen on this port in order for users to access your service.
LEANCLOUD_API_SERVER	The address used to access the Data Storage service. Please use this value if your application needs to access the Data Storage service or other cloud services with the REST API.
LEANCLOUD_APP_GROUP	The group the instance is located at.
LEANCLOUD_REGION	The region the application is running in. It will be CN for Mainland China and US for the United States.
LEANCLOUD_VERSION_TAG	The version number of the deployment.

日志

note

See Cloud Engine Platform Features § Viewing Logs for more information on how to view logs and access logs on the dashboard.

Cloud Engine will collect the logs your application has printed to standard output (stdout) and standard error (stderr):

note

Each line of the logs can contain a maximum of 4096 characters. A maximum of 600 lines of logs can be collected every minute. The logs generated by your application that exceed these limits will be discarded.

时区

The server side uses Beijing Time (UTC+8).

文件系统

Your application can create temporary files under /home/leanengine and /tmp. The size limit for all the files created by your application is 1 GB.

caution

Each time you trigger a new deployment for your application, Cloud Engine will create a new container for it. Even though you don’t trigger deployments, Cloud Engine will still perform occasional maintenance operations. This means that your application should not treat the file system provided by Cloud Engine as permanent storage.

If the files created by your application bear relatively larger sizes, we recommend that your application always cleans them up once it finishes using them. Creating more files when there are already more than 1 GB files existing might lead to the Disk quota exceeded error. You can trigger a deployment to quickly clean up all the temporary files.

出入口 IP 地址

Some third-party platforms (like Weixin Open Platform) may require that you provide an IP address whitelist. You can obtain the inbound and outbound IP addresses used by Cloud Engine on Developer Center > Your game > Game Services > Cloud Services > Cloud Engine > Your group > Settings > Inbound IP and outbound IP.

info

For Cloud Engine applications deployed within Mainland China, CDN will be enabled by default. Depending on the provider we use, the inbound IP addresses might be changed frequently. To get a fixed inbound IP address for your application, consider enabling dedicated IP.

We will do our best to minimize the frequency of changing the inbound and outbound IP addresses, but there remains the possibility for them to get changed. If you encounter any problems with IP addresses, the first thing you can do is look at the IP addresses displayed on the dashboard and see if they have been changed.

To get a fixed inbound IP address for your application, consider enabling dedicated IP.