All Products
Search

This Product

    Microservices Engine:Debug XXL-JOB jobs in on-premises environments by using the on-premises and cloud interconnection feature

    Document Center

    Microservices Engine:Debug XXL-JOB jobs in on-premises environments by using the on-premises and cloud interconnection feature

    Last Updated:Mar 11, 2026

    The on-premises and cloud interconnection feature in Alibaba Cloud Toolkit connects a locally running XXL-JOB executor to a cloud-hosted Microservices Engine (MSE) XXL-JOB admin console. With this feature, you can set breakpoints, inspect variables, and iterate on job logic in your IDE without deploying to the cloud after every change.

    How it works

    On-premises and cloud interconnection creates a secure tunnel between your local development environment and an MSE XXL-JOB instance through three components:

    1. Local IDE (IntelliJ IDEA) -- Alibaba Cloud Toolkit runs as a plug-in in your IDE. It registers your local executor with the cloud-hosted XXL-JOB admin and routes traffic through the tunnel.

    2. ECS proxy instance -- An Elastic Compute Service (ECS) instance in the same virtual private cloud (VPC) as your MSE instance acts as an SSH relay. The plug-in opens an SSH tunnel to this instance, bridging your local network to the cloud VPC.

    3. MSE XXL-JOB instance -- The cloud-hosted XXL-JOB admin dispatches jobs to your local executor through the tunnel, the same way it dispatches to any cloud-deployed executor.

    +-----------------+     SSH tunnel      +---------------+     VPC      +------------------+
|  Local machine  | ------------------- |  ECS instance | ----------- |  MSE XXL-JOB     |
|  (IntelliJ IDEA |   Port 22           |  (SSH proxy)  |  Internal   |  admin console   |
|  + Cloud Toolkit)|  (password auth)   |               |  network    |                  |
+-----------------+                     +---------------+             +------------------+

    After the tunnel is established, your local executor registers with the MSE XXL-JOB admin. The admin dispatches jobs to the local executor the same way it dispatches to cloud-deployed executors. Standard IDE debugging tools -- breakpoints, step-through, and variable inspection -- all work as expected.

    Prerequisites

    Before you begin, make sure you have:

    • An MSE XXL-JOB instance

    • IntelliJ IDEA 2018.3 or later

    • An ECS instance that meets all of the following requirements:

      Important

      • Located in the same VPC as your MSE XXL-JOB instance

      • Has a public IP address

      • Allows SSH logon with password authentication (key pair-based logon is not supported)

      For instructions, see Create an ECS instance

    Step 1: Install Alibaba Cloud Toolkit

    Note

    You can install the plug-in from the IntelliJ IDEA marketplace or from a downloaded package.

    Option A: Install from the marketplace (recommended)

    1. Open IntelliJ IDEA.

    2. Open the plug-in settings:

      • macOS: Choose IntelliJ IDEA > Preference... > Plugins.

      • Windows: Choose File > Settings > Plugins.

    3. Search for Alibaba Cloud Toolkit and click Install.

    Option B: Install from a downloaded package

    1. Download toolkit-intellij-2025.3.1-232-243.zip.

    2. In IntelliJ IDEA, open the plug-in settings and click Install Plugin from Disk. Select the downloaded .zip file.

    After installation, restart IntelliJ IDEA. The Alibaba Cloud Toolkit icon appears in the toolbar.

    Note

    If the icon does not appear after restarting, choose View > Toolbar to make sure the toolbar is visible.

    Step 2: Configure your Alibaba Cloud account

    1. In the main menu bar, choose Tools > Alibaba Cloud > Preferences....

    2. In the left-side navigation pane, choose Alibaba Cloud Toolkit > Accounts.

    3. Enter your Access Key ID and Access Key Secret, then click OK.

    Note

    A RAM user's AccessKey pair requires at least the permission to deploy applications. For details, see Grant permissions to a RAM user. To retrieve your AccessKey pair, click Get existing AK/SK in the Accounts dialog box. If you do not have an Alibaba Cloud account, click Sign up in the Accounts dialog box to go to the registration page and create an account.

    Step 3: Configure an SSH proxy

    The SSH proxy defines how Alibaba Cloud Toolkit connects to the ECS instance that bridges your local machine to the cloud VPC.

    1. In the Settings dialog box, choose Alibaba Cloud Toolkit > Microservice > Proxy.

    2. Click AddProfile and enter a Profile Name (for example, mse-debug-proxy).

    3. Click Add on the right side and configure the proxy:

      • Proxy type: Select SSH.

      • Endpoint: Enter the public IP address of your ECS instance. The default port is 22.

      • Account: Select root.

      • Authentication: Select password logon and enter the password for the ECS instance.

    4. Click OK.

    Verify the proxy: After saving, confirm that the SSH tunnel can be established. If the connection fails, check that:

    • The ECS security group allows inbound traffic on port 22 from your local IP.

    • The ECS instance is running and reachable from your network.

    • The root password is correct.

    Step 4: Enable on-premises and cloud interconnection

    1. In the Settings dialog box, choose Alibaba Cloud Toolkit > Microservice > Microservice.

    2. Configure the following parameters:

      Parameter

      Description

      Configuration Granularity

      Scope for the interconnection settings. Project (recommended) applies a single configuration across the project. Module lets you configure different settings per module for multi-module projects where only some modules need interconnection.

      On-premises and Cloud Interconnection

      Select this checkbox to enable the feature. To only receive job dispatches from the cloud admin without registering local services in the cloud registry, also select Only Subscribe To Cloud Services, Do Not Register On-premises Services.

      Product

      Select Microservices Engine (MSE).

      Region

      Select the region where your MSE XXL-JOB instance is deployed.

      Instance

      Select your MSE XXL-JOB instance.

      Local Spring Cloud Service Port

      Required only for Spring Cloud applications. Enter the service port of the application.

      Proxy

      Select the SSH proxy profile you created in Step 3.

      Initialize Proxy...

      Click this to configure SSH rules that enable the tunnel. If the SSH proxy profile does not use a root account, you are prompted to grant root permissions. If you do not want to configure a proxy by using the plug-in, you can manually configure a proxy.

      Advanced Configuration

      Select Automatically Disable Startup Prompt to set the duration (in milliseconds) for the application startup prompt.

    3. Click Apply, then click OK.

    Note

    If initialization fails, click One-click Diagnostics to troubleshoot. This tool checks for common issues such as etrans channel startup failures and service connection errors.

    Step 5: Debug a job locally

    With the tunnel configured, run your local executor and dispatch jobs to it from the MSE console.

    Set up the XXL-JOB application in the MSE console

    1. Download the alibabacloud-edas-demo project as a starting point, or use your own XXL-JOB executor project.

    2. Log on to the MSE console and select the region of your XXL-JOB instance.

    3. Click the ID of your XXL-JOB instance. In the left-side navigation pane, click Application Management, then click CreateApplication.

    4. After the application is created, click Access Configuration in the Operation column.

    5. Copy the configuration parameters to your project:

      • Access Method 1 (recommended): Click One-click Copy under Access Method 1: Modify the Spring Boot Configuration File and paste the parameters into your application.properties file.

      • Access Method 2: Restart the application with the -D parameter. This method does not require changes to code or configuration files.

    Important

    Make sure the application parameters in the MSE console match those in your application.properties file. With the current version of Alibaba Cloud Toolkit, the xxl.job.admin.addresses parameter is automatically set when you select the instance in Step 4. You do not need to configure it manually. If you use an older version of Alibaba Cloud Toolkit where the instance is not specified, you need to set xxl.job.admin.addresses to the server address.

    Start the executor and run a job

    1. Start the project in IntelliJ IDEA. To set breakpoints, use debug mode.

    2. In the MSE console, go to Application Management and confirm that the number of executors for your application is 1. This confirms that your local executor registered through the tunnel.

    3. Create an XXL-JOB job of type JobHandler.

    4. Click Run once in the Operation column to dispatch the job to your local executor.

    5. In the left-side navigation pane, click Execution List and verify that the task status is success.

    If the executor count does not show 1, the tunnel may not be working. Click One-click Diagnostics in the interconnection settings (Step 4) to identify the issue.

    FAQ

    How do I enable on-premises and cloud interconnection with an older version of Alibaba Cloud Toolkit?

    In older versions of Alibaba Cloud Toolkit, MSE XXL-JOB is not listed as a product option. Instead:

    1. In the interconnection settings, select Serverless App Engine (SAE) as the product.

    2. Click Advanced Configuration in the upper-right corner.

    3. In the dialog box, select Enable XXL-JOB Interconnection.

    The current version of Alibaba Cloud Toolkit includes MSE as a direct product option. Upgrade to the latest version for a streamlined setup.

    What to do next