Appsmith 2.5.1 常用 CLI 命令与工具详解

Appsmith 2.5.1 实例管理命令实测全集：appsmithctl 备份/恢复/导库（含 v2.5.1 交互缺陷排障实录与 mongorestore --gzip 兜底）、supervisorctl 组件管理、mongosh/redis-cli/jps 巡检与恢复后验证闭环。

Appsmith低代码Appsmith2026/10/21

Appsmith 2.5.1 常用 CLI 命令与工具详解

目标：把 Appsmith 2.5.1 自托管实例的日常管理命令一次讲透——appsmithctl 全量备份与恢复（含 v2.5.1 交互缺陷的三次排障实录与可行形态）、supervisorctl 组件进程管理、mongosh/redis-cli/jps 数据层巡检，以及恢复后的验证闭环。本文全部命令与回显在「Ubuntu 22.04.4 LTS / Docker Engine 29.8.1 / Docker Compose v5.5.1 / Appsmith CE v2.5.1」环境实测通过；部署基线来自 《Appsmith 2.5.1 Docker Compose 部署指南》，配置参数背景见 《Appsmith 2.5.1 配置参数详解》。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（x86_64）
  • 基础组件：Docker Engine 29.8.1、Docker Compose v5.5.1
  • 实例版本：Appsmith CE v2.5.1（官方最新稳定版，GitHub Releases 查询日期 2026-10-21）
  • 实例形态：官方 CE 版一体化栈，配置根目录 /opt/appsmith/stacks/（应用内路径 /appsmith-stacks）
  • 服务组成：backend（Java/Spring WebFlux，监听应用内 8080）、editor（前端与网关）、rts（实时通道）、mcp（治理接口）、mongodb（7.0.43，元数据）、postgres（辅助存储）、redis（缓存）
  • 实例管理员：admin@example.com（密码 q1w2e3r4，演示约定值）
  • 访问端口：宿主 8128 → 应用 HTTP 80

二、工具概览

工具所在位置用途
appsmithctl/opt/bin/appsmithctl（实例内 PATH 可直接调用）实例级管理：全量备份/恢复、元数据库导出/导入、副本集检查、表单登录开关
supervisorctl/usr/bin/supervisorctl实例内组件进程管理：backend/editor/rts/mcp/mongodb/postgres/redis/stdout 的状态与启停
mongosh/usr/bin/mongosh元数据库（MongoDB）带认证查询巡检
mongorestore实例内随数据库工具附带归档导入（import_db 失效时的手工兜底，见 4.4）
redis-cli/usr/local/bin/redis-cli缓存连通性检查
jps/opt/java/bin/jps后端 JVM 进程与启动参数查看
docker compose宿主编排层运维入口（exec 进入实例执行上述工具）
curl宿主 /usr/bin/curl（实例内亦有）健康检查与接口验证

命令形态约定：本篇统一采用 docker compose exec -T appsmith <命令> 从宿主执行实例内命令，均在部署目录 /opt/appsmith 下执行。-T 关闭伪终端分配，在脚本、定时任务等无终端场景必需；交互式会话中省略 -T 效果相同。

三、前置条件

  1. 已按部署篇完成实例部署并通过健康检查：
curl -s http://localhost:8128/api/v1/health

实测回显：

{"responseMeta":{"status":200,"success":true},"data":"All systems are up","errorDisplay":""}
  1. 确认实例版本（info.json 同时给出构建溯源信息）：
cd /opt/appsmith
docker compose exec -T appsmith cat /opt/appsmith/info.json

实测回显：

{
  "commitSha": "8e430d61e606bc20eccab19fbf411a644030f9db",
  "commitUrl": "https://github.com/appsmithorg/appsmith/commit/8e430d61e606bc20eccab19fbf411a644030f9db",
  "githubRef": "refs/tags/v2.5.1",
  "githubRunUrl": "https://github.com/appsmithorg/appsmith/actions/runs/39533329812/attempts/1",
  "version": "v2.5.1",
  "imageBuiltAt": "2026-10-21T02:36:46+00:00",
  "isCI": true
}
  1. 知晓密钥文件位置：/opt/appsmith/stacks/configuration/docker.env。本篇多条命令需要从中提取内置数据库口令与加密密钥（APPSMITH_MONGODB_PASSWORD、APPSMITH_REDIS_PASSWORD、APPSMITH_ENCRYPTION_PASSWORD、APPSMITH_ENCRYPTION_SALT），该文件包含敏感口令，注意权限与保密。

四、appsmithctl 命令详解

4.1 命令清单

docker compose exec -T appsmith appsmithctl --help

实测回显（全文）：


Usage: appsmith <command> to interact with appsmith utils tool

Options:
        ex, export_db           Export internal database.
        im, import_db           Import internal database.
        crs, check_replica_set  Check replica set mongoDB.
        backup                  Take a backup of Appsmith instance.
        restore                 Restore Appsmith instance from a backup.
        efl, enable-form-login          Enable form login.
        --help                  Show help.

子命令速查：

子命令缩写作用v2.5.1 可用性（本文实测）
backup—全量备份（元数据库 + Git 存储 + 环境文件打成归档）✅ 直接可用
restore—从备份归档恢复实例⚠️ 仅非交互形态可用（见 4.3）
export_dbex仅导出元数据库为归档✅ 直接可用
import_dbim导入元数据库归档❌ 已知缺陷（见 4.4，有兜底）
check_replica_setcrs检查 MongoDB 副本集状态✅ 直接可用
enable-form-loginefl开启租户表单登录✅ 直接可用

⚠️ v2.5.1 重要背景：该工具的交互式输入依赖实例内脚本 /opt/appsmith/rts/bundle/ctl/read.sh，该文件在 v2.5.1 发布包中缺失。因此凡是走到「交互式提问」的路径（restore 选择备份、restore 询问加密密钥、加密备份口令等）都会以同样的报错失败。下文所有命令均给出绕开交互的实测可用形态。

4.2 backup：全量备份实例

cd /opt/appsmith
docker compose exec -T appsmith appsmithctl backup

实测回显（全文，mongodump 逐集合明细保留）：

Exporting database
2026-10-21T09:03:45.365+0000    writing `appsmith.mongockChangeLog` to "archive `/tmp/appsmith/appsmithctl-backup-tYGWf4/mongodb-data.gz`"
2026-10-21T09:03:45.365+0000    writing `appsmith.theme` to "archive `/tmp/appsmith/appsmithctl-backup-tYGWf4/mongodb-data.gz`"
2026-10-21T09:03:45.366+0000    writing `appsmith.permissionGroup` to "archive `/tmp/appsmith/appsmithctl-backup-tYGWf4/mongodb-data.gz`"
2026-10-21T09:03:45.366+0000    writing `appsmith.plugin` to "archive `/tmp/appsmith/appsmithctl-backup-tYGWf4/mongodb-data.gz`"
2026-10-21T09:03:45.368+0000    done dumping `appsmith.permissionGroup` (7 documents)
2026-10-21T09:03:45.368+0000    done dumping `appsmith.theme` (9 documents)
2026-10-21T09:03:45.371+0000    done dumping `appsmith.plugin` (27 documents)
2026-10-21T09:03:45.371+0000    done dumping `appsmith.mongockChangeLog` (151 documents)
2026-10-21T09:03:45.371+0000    done dumping `appsmith.config` (5 documents)
2026-10-21T09:03:45.378+0000    done dumping `appsmith.user` (2 documents)
2026-10-21T09:03:45.378+0000    done dumping `appsmith.tenant` (1 document)
2026-10-21T09:03:45.385+0000    done dumping `appsmith.customJSLib` (1 document)
2026-10-21T09:03:45.387+0000    done dumping `appsmith.userData` (1 document)
2026-10-21T09:03:45.388+0000    done dumping `appsmith.superUserSetupLock` (1 document)
2026-10-21T09:03:45.389+0000    done dumping `appsmith.workspace` (1 document)
2026-10-21T09:03:45.389+0000    done dumping `appsmith.sequence` (1 document)
2026-10-21T09:03:45.394+0000    done dumping `appsmith.newPage` (1 document)
2026-10-21T09:03:45.394+0000    done dumping `appsmith.application` (1 document)
2026-10-21T09:03:45.395+0000    done dumping `appsmith.organization` (1 document)
2026-10-21T09:03:45.397+0000    done dumping `appsmith.datasourceStorageStructure` (0 documents)
2026-10-21T09:03:45.398+0000    done dumping `appsmith.mcp_changes` (0 documents)
2026-10-21T09:03:45.398+0000    done dumping `appsmith.mongockLock` (0 documents)
2026-10-21T09:03:45.398+0000    done dumping `appsmith.collection` (0 documents)
2026-10-21T09:03:45.399+0000    done dumping `appsmith.mcpKey` (0 documents)
2026-10-21T09:03:45.399+0000    done dumping `appsmith.mcpToken` (0 documents)
2026-10-21T09:03:45.400+0000    done dumping `appsmith.actionCollection` (0 documents)
2026-10-21T09:03:45.402+0000    done dumping `appsmith.newAction` (0 documents)
2026-10-21T09:03:45.403+0000    done dumping `appsmith.passwordResetToken` (0 documents)
2026-10-21T09:03:45.405+0000    done dumping `appsmith.datasource` (0 documents)
2026-10-21T09:03:45.405+0000    done dumping `appsmith.applicationSnapshot` (0 documents)
2026-10-21T09:03:45.407+0000    done dumping `appsmith.datasourceStorage` (0 documents)
2026-10-21T09:03:45.407+0000    done dumping `appsmith.mcpKey` (0 documents)
Exporting database done.
Creating git-storage archive
Created git-storage archive
Exporting docker environment file
Exporting docker environment file done.
Creating final archive
Created final archive

***************************** IMPORTANT!!! *****************************
*** Please ensure you have saved the APPSMITH_ENCRYPTION_SALT and    ***
*** APPSMITH_ENCRYPTION_PASSWORD variables from the docker.env file. ***
*** These values are not included in the backup export.              ***
************************************************************************

Post-backup done. Final archive at /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
Finished taking a backup at /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
Starting cleanup.
Cleanup completed.

要点解读：

  1. 备份内容三件套：元数据库归档（gzip 压缩的 mongodump 流）、Git 存储归档（应用代码）、环境文件导出。最终归档落在 /appsmith-stacks/data/backup/，对应宿主 /opt/appsmith/stacks/data/backup/。
  2. 加密密钥不进备份包：结尾 IMPORTANT 提示原文明确 APPSMITH_ENCRYPTION_SALT 与 APPSMITH_ENCRYPTION_PASSWORD 不包含在备份导出中，必须随归档另行抄录保管（本实例取值为 qJMYTj9XSd2lq / FyHg5JqPDUYK1）。恢复到另一台实例时没有这对值，数据源凭据将无法解密。
  3. 备份过程不停服务：整个备份期间健康检查保持 200，适合生产时段执行。
  4. 保留策略：备份目录默认最多保留 4 份归档，超过后工具自动清理最旧（收尾日志中的 Starting cleanup. / Cleanup completed. 即为该动作）。

查看备份产物：

docker compose exec -T appsmith ls -lh /appsmith-stacks/data/backup

实测回显（本实例含此前一次备份与 export_db 产物）：

total 132K
-rw-r--r-- 1 root root 41K Oct 21 08:17 appsmith-backup-2026-10-21T08-17-54.063Z.tar.gz
-rw-r--r-- 1 root root 41K Oct 21 09:03 appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
-rw-r--r-- 1 root root 41K Oct 21 08:59 appsmith-data.archive

4.3 restore：从备份恢复实例

restore 是本篇排障密度最高的命令——v2.5.1 直接按「直觉」调用必失败。以下按实测顺序给出三种形态：两种失败、一种可用。

失败形态一：位置参数传完整路径（被忽略，转入交互选单）

docker compose exec -T appsmith appsmithctl restore /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz

实测回显（全文）：


2 Appsmith backup file(s) found: [Sorted in ascending/chronological order]
----------------------------------------------------------------
Index   |       Appsmith Backup Archive File
----------------------------------------------------------------
0       |       appsmith-backup-2026-10-21T08-17-54.063Z.tar.gz
1       |       appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz <--Most recent backup
----------------------------------------------------------------
/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file
Error: The current environment doesn't support interactive reading from TTY.
/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file
    at readlineExt (/node_modules/readline-sync/lib/readline-sync.js:221:19)
    at tryExt (/node_modules/readline-sync/lib/readline-sync.js:258:15)
    at <anonymous> (/node_modules/readline-sync/lib/readline-sync.js:363:15)
    at _readlineSync (/node_modules/readline-sync/lib/readline-sync.js:433:3)
    at getValidLine (/node_modules/readline-sync/lib/readline-sync.js:775:11)
    at Object.$.question (/node_modules/readline-sync/lib/readline-sync.js:857:10)
    at getBackupFileName (/opt/appsmith/src/ctl/restore.ts:81:18)
    at async run (/opt/appsmith/src/ctl/restore.ts:430:26) {
  method: 'execFileSync',
  program: '/bin/sh',
  args: [
    '/opt/appsmith/rts/bundle/ctl/read.sh',
    '--display',
    'Please#32;enter#32;the#32;backup#32;file#32;index#58;#32;',
    '--mask',
    '#42;'
  ],
  extMessage: '/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file',
  exitCode: 2,
  code: undefined,
  signal: null
}
Starting [ 'backend', 'rts' ]
backend: ERROR (already started)
rts: ERROR (already started)
Started [ 'backend', 'rts' ]

结论：位置参数不参与备份文件解析（restore.ts 的 getBackupFileName 只认 --backup-file），传入路径被忽略后进入交互选单，提问「Please enter the backup file index: 」（栈回显 args 中的 #32; 为空格转义），随后因 read.sh 缺失报错。退出码 1，服务未被改动。

失败形态二：--backup-file 但缺 --non-interactive（卡在加密密钥问询）

docker compose exec -T appsmith appsmithctl restore --backup-file=appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz

实测回显（全文）：

Extracting the Appsmith backup archive at /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
Extracting the backup archive completed
Current Appsmith Version: v2.5.1
Restore Appsmith Version: v2.5.1
The restore instance is compatible with the current appsmith version
Validating docker environment file
/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file
Error: The current environment doesn't support interactive reading from TTY.
/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file
    at readlineExt (/node_modules/readline-sync/lib/readline-sync.js:221:19)
    at tryExt (/node_modules/readline-sync/lib/readline-sync.js:258:15)
    at <anonymous> (/node_modules/readline-sync/lib/readline-sync.js:363:15)
    at _readlineSync (/node_modules/readline-sync/lib/readline-sync.js:433:3)
    at getValidLine (/node_modules/readline-sync/lib/readline-sync.js:775:11)
    at Object.$.question (/node_modules/readline-sync/lib/readline-sync.js:857:10)
    at prepareDockerEnvFile (/opt/appsmith/src/ctl/restore.ts:261:34)
    at async run (/opt/appsmith/src/ctl/restore.ts:479:32) {
  method: 'execFileSync',
  program: '/bin/sh',
  args: [
    '/opt/appsmith/rts/bundle/ctl/read.sh',
    '--display',
    'If#32;you#32;are#32;restoring#32;to#32;the#32;same#32;Appsmith#32;deployment#32;which#32;generated#32;the#32;backup#32;archive#44;#32;you#32;can#32;use#32;the#32;existing#32;encryption#32;keys#32;on#32;the#32;instance#46;#10;#32;#32;#32;#32;#32;#32;Press#32;Enter#32;to#32;continue#32;with#32;existing#32;encryption#32;keys#10;#32;#32;#32;#32;#32;#32;Or#32;Type#32;#34;n#34;#47;#34;No#34;#32;to#32;provide#32;encryption#32;key#32;#38;#32;password#32;corresponding#32;to#32;the#32;original#32;Appsmith#32;instance#32;that#32;is#32;being#32;restored#46;#10;',
    '--mask',
    '#42;'
  ],
  extMessage: '/bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file',
  exitCode: 2,
  code: undefined,
  signal: null
}
Starting [ 'backend', 'rts' ]
backend: ERROR (already started)
rts: ERROR (already started)
Started [ 'backend', 'rts' ]

结论：解包与版本兼容校验都通过了（Current/Restore Version 比对），卡在 prepareDockerEnvFile（restore.ts:261）的交互问询——提示词解码为：「If you are restoring to the same Appsmith deployment which generated the backup archive, you can use the existing encryption keys on the instance. Press Enter to continue with existing encryption keys. Or Type "n"/"No" to provide encryption key & password corresponding to the original Appsmith instance that is being restored.」同样因 read.sh 缺失失败。

可用形态：-e 注入加密密钥 + --backup-file 文件名 + --non-interactive

两个先决条件：

条件说明
--backup-file 只接受文件名不能是路径；归档文件必须已位于实例内 /appsmith-stacks/data/backup/ 目录
密钥经 -e 注入执行环境APPSMITH_ENCRYPTION_PASSWORD / APPSMITH_ENCRYPTION_SALT 取自备份时保存的 docker.env 值
cd /opt/appsmith
ENCRYPTION_PWD=$(grep '^APPSMITH_ENCRYPTION_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
ENCRYPTION_SALT=$(grep '^APPSMITH_ENCRYPTION_SALT=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T -e APPSMITH_ENCRYPTION_PASSWORD="$ENCRYPTION_PWD" -e APPSMITH_ENCRYPTION_SALT="$ENCRYPTION_SALT" appsmith appsmithctl restore --backup-file=appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz --non-interactive

实测回显（首段）：

Extracting the Appsmith backup archive at /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
Extracting the backup archive completed
Current Appsmith Version: v2.5.1
Restore Appsmith Version: v2.5.1
The restore instance is compatible with the current appsmith version
Validating docker environment file
Restoring docker environment file with the encryption password & salt from the current environment
****************************************************************
Restoring Appsmith instance from the backup at /appsmith-stacks/data/backup/appsmith-backup-2026-10-21T09-03-45.343Z.tar.gz
Stopping [ 'backend', 'rts' ]
backend: stopped
rts: stopped
Stopped [ 'backend', 'rts' ]
Restoring database...
Backup Database Name: appsmith
Restoring database from appsmith to appsmith
2026-10-21T09:04:36.427+0000	The --db and --collection flags are deprecated for this use-case; please use --nsInclude instead, i.e. with --nsInclude=${DATABASE}.${COLLECTION}
2026-10-21T09:04:36.434+0000	preparing collections to restore from
2026-10-21T09:04:36.441+0000	reading metadata for `appsmith.passwordResetToken` from "archive `/tmp/appsmithHajO6V/mongodb-data.gz`"

（中略：mongorestore 逐集合读取、逐文档写入与逐索引重建明细约 200 行，格式同上，最终统计如下）

实测回显（尾段）：

2026-10-21T09:04:37.121+0000    210 document(s) restored successfully. 0 document(s) failed to restore.
Restoring database completed
Restoring git-storage archive
Restoring git-storage archive completed
Appsmith instance successfully restored.
Starting [ 'backend', 'rts' ]
backend: started
rts: started
Started [ 'backend', 'rts' ]

恢复后验证闭环：

curl -s http://localhost:8128/api/v1/health

实测回显：

{"responseMeta":{"status":200,"success":true},"data":"All systems are up","errorDisplay":""}

MONGO_PWD=$(grep '^APPSMITH_MONGODB_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T appsmith mongosh --quiet "mongodb://appsmith:${MONGO_PWD}@localhost:27017/appsmith" --eval 'JSON.stringify(db.user.find({email:{$ne:"anonymousUser"}},{email:1,name:1}).toArray())'

实测回显（管理员与用户数据随备份恢复）：

[{"_id":"6ad874fe69247a69152af277","name":"admin","email":"admin@example.com"}]

restore 行为要点：

  1. 覆盖式恢复：目标实例元数据整体替换为备份内容（210 document(s) restored successfully. 0 document(s) failed to restore.），Git 存储归档同样被还原。
  2. docker.env 会被工具重建：实测恢复前 35 行 → 恢复后 34 行，键序与注释归一化；本次实测中手工追加的 APPSMITH_FORM_LOGIN_DISABLED 行仍被保留，APPSMITH_ADMIN_EMAILS、APPSMITH_ENCRYPTION_PASSWORD/SALT 等关键键亦正确回写。恢复完成后应 grep 核对一遍关键键再投入使用。
  3. 服务中断窗口：工具自动停启 backend 与 rts，恢复期间健康检查返回 502，结束后约 10 秒内回到 200。
  4. 跨实例恢复：-e 注入的密钥必须是备份来源实例的值（见 4.2 的 IMPORTANT 提示）；版本兼容性由工具自动比对（Current/Restore Version 行）。

4.4 export_db / import_db：元数据库导出与导入

export_db：导出元数据库归档（可用）

docker compose exec -T appsmith appsmithctl export_db

实测回显（首段）：

Exporting database
Export database done
stop backend & rts application before export database
Stopping [ 'backend', 'rts' ]
backend: stopped
rts: stopped
Stopped [ 'backend', 'rts' ]
export_database  ....
2026-10-21T08:59:19.327+0000    writing `appsmith.mongockChangeLog` to "archive `/appsmith-stacks/data/backup/appsmith-data.archive`"
2026-10-21T08:59:19.328+0000    writing `appsmith.theme` to "archive `/appsmith-stacks/data/backup/appsmith-data.archive`"
2026-10-21T08:59:19.328+0000    writing `appsmith.permissionGroup` to "archive `/appsmith-stacks/data/backup/appsmith-data.archive`"
2026-10-21T08:59:19.329+0000    done dumping `appsmith.permissionGroup` (7 documents)

（中略：其余集合的 writing/done dumping 明细与 4.2 backup 同格式，略）

实测回显（尾段）：

2026-10-21T08:59:19.371+0000    done dumping `appsmith.passwordResetToken` (0 documents)
export_database done
start backend & rts application after export database

++++++++++++++++++++ NOTE ++++++++++++++++++++

Please remember to also copy APPSMITH_ENCRYPTION_SALT and APPSMITH_ENCRYPTION_PASSWORD variables from the docker.env file to the target instance where you intend to import this database dump.

++++++++++++++++++++++++++++++++++++++++++++++

Starting [ 'backend', 'rts' ]
backend: started
rts: started
Started [ 'backend', 'rts' ]

要点：产物为 /appsmith-stacks/data/backup/appsmith-data.archive（gzip 压缩的 mongodump 归档，宿主路径 /opt/appsmith/stacks/data/backup/）；工具自动完成「停服务 → 导出 → 起服务」，NOTE 提示目标实例需要原实例的加密密钥对（与 backup 的 IMPORTANT 一致）。

import_db：导入归档（v2.5.1 存在已知缺陷）

docker compose exec -T appsmith appsmithctl import_db

实测回显（全文，含崩溃栈）：

Importing database
Importing database done
stop backend & rts application before import database
Stopping [ 'backend', 'rts' ]
backend: stopped
rts: stopped
Stopped [ 'backend', 'rts' ]
node:events:505
    throw er; // Unhandled 'error' event
    ^

Error: spawn mongo ENOENT
    at ChildProcess._handle.onexit (node:internal/child_process:287:19)
    at onErrorNT (node:internal/child_process:525:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
Emitted 'error' event on ChildProcess instance at:
    at ChildProcess._handle.onexit (node:internal/child_process:293:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'spawn mongo',
  path: 'mongo',
  spawnargs: [
    'mongodb://appsmith:zvS15PrfonOo2@localhost:27017/appsmith',
    '--quiet',
    '--eval',
    'db.getCollectionNames().length'
  ]
}

Node.js v24.21.0

根因：v2.5.1 一体化包内只有 mongosh，已不含旧版 mongo 命令行客户端，而 import_db 在导入完成后的验证步骤仍硬编码调用 mongo（见栈内 spawnargs），进程崩溃退出（退出码 1）。此时 backend 与 rts 处于停止状态，数据库导入动作本身已执行。该缺陷使 import_db 在 v2.5.1 不可作为可靠流程，推荐下面的手工兜底。

手工兜底：mongorestore 导入归档（注意 --gzip）

先看一个必然踩的坑——归档是 gzip 压缩格式，不加 --gzip 会报错：

docker compose exec -T appsmith od -An -tx1 -N4 /appsmith-stacks/data/backup/appsmith-data.archive

实测回显（头 4 字节 1f 8b 08 00，即 gzip 魔数）：

 1f 8b 08 00

MONGO_PWD=$(grep '^APPSMITH_MONGODB_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T appsmith mongorestore --archive=/appsmith-stacks/data/backup/appsmith-data.archive --drop --uri="mongodb://appsmith:${MONGO_PWD}@localhost:27017/appsmith?authSource=appsmith"

实测回显（未加 --gzip 时的报错）：

2026-10-21T09:00:59.214+0000    The --db and --collection flags are deprecated for this use-case; please use --nsInclude instead, i.e. with --nsInclude=${DATABASE}.${COLLECTION}
2026-10-21T09:00:59.214+0000    Failed: stream or file does not appear to be a mongodump archive
2026-10-21T09:00:59.214+0000    0 document(s) restored successfully. 0 document(s) failed to restore.

完整的可用兜底流程（四步，均为实测）：

# 1) 停止应用服务（若刚执行过 import_db 已自动停止，可跳过）
docker compose exec -T appsmith supervisorctl stop backend rts

实测回显：

backend: stopped
rts: stopped

# 2) 带 --gzip 导入归档（口令从 docker.env 提取）
cd /opt/appsmith
MONGO_PWD=$(grep '^APPSMITH_MONGODB_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T appsmith mongorestore --quiet --gzip --archive=/appsmith-stacks/data/backup/appsmith-data.archive --drop --uri="mongodb://appsmith:${MONGO_PWD}@localhost:27017/appsmith?authSource=appsmith"
echo "mongorestore exit=$?"

实测回显（--quiet 下无过程输出，退出码 0 即成功）：

mongorestore exit=0

# 3) 重新启动应用服务
docker compose exec -T appsmith supervisorctl start backend rts

实测回显：

backend: started
rts: started

# 4) 等待健康恢复（backend 启动约 20 秒）
curl -s http://localhost:8128/api/v1/health

实测回显：

{"responseMeta":{"status":200,"success":true},"data":"All systems are up","errorDisplay":""}

4.5 check_replica_set：副本集状态检查

docker compose exec -T appsmith appsmithctl check_replica_set; echo "exit=$?"

实测回显（单机模式，无输出且退出码 0 即为通过）：

check_replica_set exit=0

该命令用于确认内置 MongoDB 是否满足副本集要求。一体化栈默认单机部署、未启用副本集，返回 0 属正常；仅在将 APPSMITH_DB_URL 指向外部副本集做变更前预检时使用。

4.6 enable-form-login：开启租户表单登录

docker compose exec -T appsmith appsmithctl enable-form-login

实测回显（全文）：

Enabling form login
Found organization: default
{
  "acknowledged": true,
  "insertedId": null,
  "matchedCount": {
    "$numberInt": "1"
  },
  "modifiedCount": {
    "$numberInt": "0"
  },
  "upsertedCount": {
    "$numberInt": "0"
  }
}
Organization ID: 6ad8732569247a69152af25b
Successfully updated organization configuration
1
Successfully cleared organization cache from Redis

该命令直接改写租户配置并清除 Redis 中的租户缓存，即时生效，无需重启。适用场景：实例曾以 APPSMITH_FORM_LOGIN_DISABLED=true 初始化（该开关仅首启落库有效，事后改环境变量不回改库，详见《Appsmith 2.5.1 配置参数详解》3.5 节），需要重新放开表单登录时，用此命令一键恢复。

五、supervisorctl：实例内组件管理

5.1 查看组件状态

docker compose exec -T appsmith supervisorctl status

实测回显（8 个组件全部 RUNNING）：

backend                          RUNNING   pid 1447, uptime 0:10:41
editor                           RUNNING   pid 1448, uptime 0:10:41
mcp                              RUNNING   pid 1446, uptime 0:10:41
mongodb                          RUNNING   pid 1444, uptime 0:10:41
postgres                         RUNNING   pid 1450, uptime 0:10:41
redis                            RUNNING   pid 1443, uptime 0:10:41
rts                              RUNNING   pid 1445, uptime 0:10:41
stdout                           RUNNING   pid 1442, uptime 0:10:41

组件职责：backend（Java 后端服务）、editor（前端与网关）、rts（实时通道）、mcp（治理接口）、mongodb（元数据库 7.0.43）、postgres（辅助存储）、redis（缓存）、stdout（日志输出通道）。任何组件非 RUNNING 都会直接影响健康检查。

5.2 停止与启动组件

以最常用的 backend/rts 为例（export/restore 流程会自动执行同样动作）：

docker compose exec -T appsmith supervisorctl stop backend rts

实测回显：

backend: stopped
rts: stopped

docker compose exec -T appsmith supervisorctl status

实测回显（目标组件转为 STOPPED 并标注时间）：

backend                          STOPPED   Oct 21 08:58 AM
editor                           RUNNING   pid 1448, uptime 0:11:18
mcp                              RUNNING   pid 1446, uptime 0:11:18
mongodb                          RUNNING   pid 1444, uptime 0:11:18
postgres                         RUNNING   pid 1450, uptime 0:11:18
redis                            RUNNING   pid 1443, uptime 0:11:18
rts                              STOPPED   Oct 21 08:58 AM
stdout                           RUNNING   pid 1442, uptime 0:11:18

backend 停止期间健康检查返回 502（网关在、后端不在）。重新启动：

docker compose exec -T appsmith supervisorctl start backend rts

实测回显：

backend: started
rts: started

启动后 Spring Boot 就绪需要约 20 秒（配置篇实测 Started ServerApplication in 19.125 seconds），期间健康检查短暂 502，随后回到 200；若超过 1 分钟未恢复，按部署篇排障章节查服务日志。

六、数据层巡检工具

6.1 mongosh：元数据库带认证查询

内置 MongoDB 开启了认证，连接串口令从 docker.env 的 APPSMITH_MONGODB_PASSWORD 提取：

cd /opt/appsmith
MONGO_PWD=$(grep '^APPSMITH_MONGODB_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T appsmith mongosh --quiet "mongodb://appsmith:${MONGO_PWD}@localhost:27017/appsmith" --eval 'JSON.stringify(db.user.find({email:{$ne:"anonymousUser"}},{email:1,name:1}).toArray())'

实测回显（匿名内置账号外的全部用户）：

[{"_id":"6ad874fe69247a69152af277","name":"admin","email":"admin@example.com"}]

巡检参考：元数据库名为 appsmith，核心集合包括 user（用户）、organization（工作空间/组织）、application（应用）、config/plugin（实例配置与插件清单，实测 27 个插件）、tenant（租户配置）。统计类巡检示例：

docker compose exec -T appsmith mongosh --quiet "mongodb://appsmith:${MONGO_PWD}@localhost:27017/appsmith" --eval 'JSON.stringify({users: db.user.countDocuments({}), orgs: db.organization.countDocuments({}), plugins: db.plugin.countDocuments({})})'

实测回显：

{"users":2,"orgs":1,"plugins":27}

6.2 redis-cli：缓存连通性检查

cd /opt/appsmith
REDIS_PWD=$(grep '^APPSMITH_REDIS_PASSWORD=' stacks/configuration/docker.env | cut -d= -f2)
docker compose exec -T appsmith redis-cli -a "$REDIS_PWD" ping

实测回显：

Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.
PONG

首行 Warning 是 redis-cli 对「命令行传口令」的安全提示，不影响结果；PONG 即缓存服务正常。

6.3 jps：后端 JVM 进程与参数查看

docker compose exec -T appsmith jps -l

实测回显（进程号每次启动不同）：

1447 server.jar
2461 jdk.jcmd/sun.tools.jps.Jps

docker compose exec -T appsmith jps -v | grep -- '-Xm'

实测回显（本实例通过编排 environment: 注入了 APPSMITH_JAVA_ARGS="-Xms256m -Xmx512m"，堆参数在进程参数中原样可见）：

1447 server.jar -Xms256m -Xmx512m --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.time=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED -Dserver.port=8080 -XX:+ShowCodeDetailsInExceptionMessages -Djava.security.egd=file:/dev/./urandom -Dlog4j2.formatMsgNoLookups=true

堆参数的注入方式与默认行为分析见《Appsmith 2.5.1 配置参数详解》第六章。

七、注意事项

  1. v2.5.1 的交互式管理路径全部不可用：read.sh 随包缺失，restore 交互选单、restore 加密密钥问询、备份加密口令输入等一律失败。一切 restore/备份加密操作都应使用本文给出的非交互形态。
  2. 加密密钥不进备份包：APPSMITH_ENCRYPTION_PASSWORD / APPSMITH_ENCRYPTION_SALT 必须随备份归档单独抄录保管（backup 与 export_db 结尾都有显式提醒），跨实例恢复时缺失这对值将无法解密数据源凭据。
  3. restore 是覆盖式操作：元数据与 Git 存储整体被备份内容替换，docker.env 会被工具重建（实测 35 行 → 34 行、键序归一化）。恢复前若对 docker.env 有手工定制，先另存一份；恢复后 grep 核对关键键再投入使用。
  4. --backup-file 只认文件名：传绝对路径会被忽略并转入交互选单（4.3 失败形态一）。归档须先放到实例内 /appsmith-stacks/data/backup/（宿主 /opt/appsmith/stacks/data/backup/）。
  5. import_db 在 v2.5.1 不可靠：spawn mongo ENOENT 为已知缺陷，用 export_db + mongorestore --gzip 兜底（4.4）；归档是 gzip 压缩格式，漏掉 --gzip 会报 Failed: stream or file does not appear to be a mongodump archive。
  6. 导库与恢复都有服务中断窗口：export_db/import_db/restore 均会自动停启 backend 与 rts，窗口内健康检查 502，完成后 10–40 秒内恢复，安排在业务低峰执行。
  7. supervisorctl 与 docker compose 的分工：supervisorctl 管实例内部组件进程（backend/mongodb/redis 等）；实例整体的生命周期（重建、升级、端口变更）走编排层 docker compose 命令，二者不要混用层级。
  8. 备份保留份数：默认保留 4 份归档，超出自动清理最旧；如需更长保留周期，定期将 /opt/appsmith/stacks/data/backup/ 下的归档复制到外部存储。

八、常见问题

Q1：执行 appsmithctl 报 /bin/sh: 0: cannot open /opt/appsmith/rts/bundle/ctl/read.sh: No such file？ 这是 v2.5.1 发布包缺失交互输入脚本的已知问题（4.3 两次失败形态的根因）。凡走到该报错，说明当前命令触发了交互式提问——改用非交互形态：restore 加 --backup-file=<文件名> --non-interactive 并以 -e 注入 APPSMITH_ENCRYPTION_PASSWORD/SALT；备份加密功能在修复前暂不可用，普通 backup 不受影响。

Q2：restore 传了备份路径，为什么弹出了备份清单而不是直接恢复？ --backup-file 参数必须用 键=值 形式且只接受文件名；位置参数形式的路径不会被解析为备份文件（4.3 实测），随后进入交互选单并因 read.sh 缺失失败。把归档放进实例内 backup 目录后改用文件名即可。

Q3：import_db 报 Error: spawn mongo ENOENT 怎么办？ v2.5.1 已知缺陷（包内无旧版 mongo 客户端），命令本身不可用。按 4.4 的四步兜底：supervisorctl stop backend rts → mongorestore --quiet --gzip --archive=... --drop --uri=... → supervisorctl start backend rts → 健康验证。注意 --gzip 必不可少。

Q4：mongorestore 报 Failed: stream or file does not appear to be a mongodump archive？ export_db 产出的归档是 gzip 压缩流（文件头 1f 8b 08 00，4.4 实测），命令行漏了 --gzip 时 mongorestore 按裸归档解析即报此错。补上 --gzip 重新导入即可。

Q5：supervisorctl start 提示 ERROR (already started)？ 组件本就在运行（export/restore 的收尾会自动拉起 backend/rts），不是故障。用 supervisorctl status 确认状态即可，无需处理。

Q6：恢复完成后登录不上或数据「回到过去」？ 先核对三点：恢复的归档确实是预期那份（--backup-file 的文件名含时间戳）；版本兼容行 Current/Restore Version 是否一致；-e 注入的加密密钥是否来自备份来源实例（密钥不一致时加密数据无法解密）。恢复是覆盖式操作，实例数据就是所选备份时点的状态，并非异常。

九、参考链接

  1. 官方实例备份：https://docs.appsmith.com/getting-started/setup/instance-management/backup-and-restore/backup-instance
  2. 官方实例恢复：https://docs.appsmith.com/getting-started/setup/instance-management/backup-and-restore/restore-instance
  3. Appsmith GitHub Releases（v2.5.1 与升级注记）：https://github.com/appsmithorg/appsmith/releases
  4. 本系列选型篇：《Appsmith 介绍与选型指南》
  5. 本系列部署篇：《Appsmith 2.5.1 Docker Compose 部署指南》
  6. 本系列配置篇：《Appsmith 2.5.1 配置参数详解》