Appsmith 2.5.1 Docker Compose 部署指南

目标：在一台干净的 Ubuntu 22.04 服务器上，用官方 CE 版发行包从零部署一套可长期运行的 Appsmith 2.5.1 低代码平台实例，覆盖版本选型、编排文件编写、启动验证、首启管理员初始化、数据持久化与日常运维命令。本文全部命令与回显均在「Ubuntu 22.04.4 LTS（x86_64）/ 8 vCPU / 32GB 内存 / Docker Engine 29.8.1 / Docker Compose v5.5.1」环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（Jammy Jellyfish，x86_64）
• 基础组件：Docker Engine 29.8.1、Docker Compose v5.5.1（docker compose version 实测）
• 部署对象：Appsmith 社区版（appsmith-ce）v2.5.1，官方最新稳定版（GitHub Releases 2026-10-21 实查）
• 发行包构成：一体化应用栈（编辑器前端 + 后端服务 + 实时通道 + 内置 MongoDB 7.x + Redis + PostgreSQL），单编排文件拉起，数据统一落 stacks/ 目录
• 端口规划：宿主 8128 → 应用 HTTP 80；宿主 8130 → 应用 HTTPS 443（避免与既有 80/443 冲突；未启用 TLS 前 8130 不会被监听，见第十章常见问题）
• 数据目录：编排文件所在目录下的 stacks/（对应应用内路径 /appsmith-stacks）
• 独立网段：10.89.65.0/24（显式指定，避免与同机其他应用网段冲突）

二、版本与形态选型说明

2.1 版本选择

版本号获取方法（不硬编码、随官方更新）：

# 浏览器访问 GitHub Releases 页取页首最新 tag
# https://github.com/appsmithorg/appsmith/releases/latest

⚠️ 注意：v2.5.1 起官方对 docker.env 配置文件启用「字面值」强校验：文件内容必须是解析后的明文键值，禁止 shell 表达式（如 $()、变量拼接），否则启动会被阻断；JVM 参数等需改由编排文件环境注入（详见《Appsmith 2.5.1 配置参数详解》）。

2.2 部署形态选择

💡 技术拓展：Appsmith 官方提供三种自托管形态，如何选——

形态	原理/特点	适用场景
Docker Compose（本文）	单编排文件声明应用与数据卷，一条命令拉起/升级	单机生产、小中型团队，运维成本最低
Kubernetes/Helm	声明式编排，天然滚动升级与弹性	已有 K8s 平台、需多副本与高可用治理
安装脚本（install.appsmith.com）	脚本内生成 Compose 文件并拉起	想跳过手写编排文件的快速试用

本文采用 Compose 形态并显式编写编排文件：既保留官方最小形态的可读性，又能显式锁定版本号、端口、网段与数据目录，便于长期维护。

2.3 社区版与商业版

自托管镜像有 appsmith-ce（社区版）与 appsmith-ee（商业版）两条线。CE 版覆盖编辑器、数据源、权限、发布等全部核心能力；EE 版增强企业级 RBAC、审计日志、SAML/LDAP 登录与白标。本文部署 CE 版；EE 版编排写法一致，仅 image 标签不同，未订阅授权时按 CE 行为运行。

三、前置条件

1. 服务器已安装 Docker Engine 与 Compose 插件，且当前用户具备 Docker 操作权限：

docker version --format 'Engine={{.Server.Version}}'

实测回显：

Engine=29.8.1

docker compose version

实测回显：

Docker Compose version v5.5.1

2. 资源建议：最低 2 vCPU / 4GB 内存 / 20GB 磁盘；本文实测环境为 8 vCPU / 32GB 内存。应用栈内置数据库与后端服务，空闲态常驻内存约 1.5–2GB。
3. 端口确认：宿主侧 8128、8130 未被占用（按需替换为自己的端口）：

ss -ltn | grep -E ':(8128|8130)\b' || echo '端口空闲'

实测回显：

端口空闲

4. 可访问镜像仓库（内网环境可为 Docker 守护进程配置代理后再拉取）。
5. 一个常规域名邮箱（如 admin@example.com），用于首启创建实例管理员；⚠️ 不要使用 .local、.internal 等保留伪域名，实测会被校验拒绝（见第十章常见问题 1）。

四、部署步骤

4.1 创建部署目录与编排文件

选定编排目录（本文约定 /opt/appsmith），创建官方 CE 版编排文件。相比官方文档最小形态，本文做了三处生产化调整：显式项目名（避免多套栈同名项目互相误删）、显式独立网段（避免网段冲突）、端口映射到非冲突的 8128/8130：

mkdir -p /opt/appsmith

编写 /opt/appsmith/docker-compose.yml：

name: appsmith-2.5.1-stack
services:
  appsmith:
    image: index.docker.io/appsmith/appsmith-ce:v2.5.1
    container_name: appsmith-2-5-1-web
    ports:
      - "8128:80"
      - "8130:443"
    volumes:
      - ./stacks:/appsmith-stacks
    restart: unless-stopped
    networks:
      - appsmithnet
networks:
  appsmithnet:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.65.0/24

逐项说明：

• name: appsmith-2.5.1-stack：Compose 项目名。多套应用共存于一台服务器时必须显式命名，否则默认项目名取目录名（各目录都叫 appsmith 时会互相干扰，执行 down 会误删其他同名项目）。
• image：锁定 CE 版 v2.5.1 小版本号，升级时只改这一行（见第九章 9.4）。
• container_name: appsmith-2-5-1-web：固定实例运行名，便于日志检索与命名一致性（版本点号以连字符书写）。
• ports：宿主 8128 → 应用 HTTP 80；8130 → 应用 HTTPS 443。应用内 443 仅在配置自定义域名后才会启用 TLS 监听（见第十章常见问题 3）。
• volumes：./stacks 挂载为应用数据根 /appsmith-stacks，全部状态（配置、数据库数据、日志、Git 存储、证书）都落在宿主该目录，删除/升级实例不丢数据。
• restart: unless-stopped：开机自启与异常自动拉起（手动停止后不自动启动）。
• networks：独立 bridge 网段 10.89.65.0/24，显式声明避免与同机其他应用既有网段冲突。

4.2 拉起应用栈

cd /opt/appsmith
docker compose up -d

实测回显（输出节选，首次启动包含发行包下载过程）：

 d64d29b11960 Extracting 1B
 d64d29b11960 Pull complete 0B
 f6098365a7ee Pull complete 0B
 8df58ed19feb Pull complete 0B
 bd9ddc54bea9 Pull complete 0B
 f6c006d28630 Pull complete 0B
 Image index.docker.io/appsmith/appsmith-ce:v2.5.1 Pulled
 Network appsmith-251-stack_appsmithnet Creating
 Network appsmith-251-stack_appsmithnet Created
 Container appsmith-2-5-1-web Creating
 Container appsmith-2-5-1-web Created
 Container appsmith-2-5-1-web Starting
 Container appsmith-2-5-1-web Started

4.3 等待就绪并确认状态

首次启动需完成内置数据库初始化、迁移与各内部服务拉起，实测约 1–2 分钟进入健康态。观察编排状态：

docker compose ps

实测回显（就绪后）：

NAME                 IMAGE                                         COMMAND                   SERVICE    CREATED          STATUS                    PORTS
appsmith-2-5-1-web   index.docker.io/appsmith/appsmith-ce:v2.5.1   "/opt/appsmith/entry…"   appsmith   13 minutes ago   Up 13 minutes (healthy)   0.0.0.0:8128->80/tcp, [::]:8128->80/tcp, 0.0.0.0:8130->443/tcp, [::]:8130->443/tcp

关键确认点：STATUS 列出现 Up (healthy) 即内置健康检查通过。就绪过程可跟踪日志：

docker compose logs appsmith --tail=20

实测回显（输出节选，出现以下两行即后端就绪）：

backend stdout | [2026-10-21 08:09:20,624] [main] requestId= userEmail= orgId= traceId= spanId= - Netty started on port 8080 (http)
backend stdout | [2026-10-21 08:09:20,626] [main] requestId= userEmail= orgId= traceId= spanId= - Started ServerApplication in 19.125 seconds (process running for 19.545)

同段日志可确认内置数据组件版本与实时通道健康：

backend stdout | [2026-10-21 08:09:20,663] [nioEventLoopGroup-3-11] requestId= userEmail= orgId= traceId= spanId= - Fetched and set conenncted mongo db version as: 7.0.43
backend stdout | [2026-10-21 08:09:21,888] [reactor-http-epoll-5] requestId= userEmail= orgId= traceId= spanId= - RTS health check succeeded

4.4 健康检查验证

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

实测回显：

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

首页可访问性：

curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:8128/

实测回显：

200 text/html; charset=utf-8

4.5 首启初始化：创建实例管理员

浏览器访问 http://<服务器地址>:8128/，进入实例初始化向导：

1. 页面表单填写管理员信息——姓名 admin、邮箱 admin@example.com、密码 q1w2e3r4（生产环境请替换为强密码；本篇为演示约定值）；
2. 提交后以该账号登录，进入应用工作台（Applications 列表页）；
3. 实例数据目录会自动把管理员邮箱回写进配置文件 stacks/configuration/docker.env 的 APPSMITH_ADMIN_EMAILS 键，后续可用于找回与实例级管理。

创建完成后可用健康接口 + 登录接口做一轮命令行验证（两步，先取 CSRF 令牌再登录）：

# 第一步：请求健康接口，取得 XSRF-TOKEN 令牌 cookie
curl -s -c /tmp/appsmith-cookies.txt http://localhost:8128/api/v1/health -o /dev/null
TOKEN=$(awk '$6=="XSRF-TOKEN"{print $NF}' /tmp/appsmith-cookies.txt)
echo "TOKEN=$TOKEN"

实测回显：

TOKEN=727015fb-4cbb-4771-be6d-10100258695b

# 第二步：带令牌与 Origin 头提交登录表单
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' \
  -b /tmp/appsmith-cookies.txt -c /tmp/appsmith-cookies.txt \
  -X POST http://localhost:8128/api/v1/login \
  -H "X-XSRF-TOKEN: $TOKEN" -H 'Origin: http://localhost:8128' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'username=admin@example.com' \
  --data-urlencode 'password=q1w2e3r4'

实测回显（302 且跳转 /applications 即登录成功；若跳转 ?error=true 则账号或密码不正确）：

302 -> http://localhost:8128/applications

⚠️ 注意：若不用浏览器向导而走接口直创管理员，v2.5.1 的接口是 POST /api/v1/users/super（不是旧文档的 /api/v1/users/super-user），且只接受表单编码并必须携带 Origin 头与 CSRF 令牌——逐项排障实录见第十章常见问题 2。

至此部署完成。数据全部持久化在 /opt/appsmith/stacks/，重启服务器后应用栈会由 restart: unless-stopped 自动拉起。

五、数据持久化说明

Appsmith 一体化栈把全部状态收敛在挂载目录 /appsmith-stacks（宿主 /opt/appsmith/stacks）。首启后实测目录结构：

ls /opt/appsmith/stacks/

实测回显：

configuration
data
git-storage
git-storage-appsmith-backup-2026-10-21T08-17-54.063Z
logs
ssl

ls /opt/appsmith/stacks/data/

实测回显：

backup
caddy
mongodb
postgres
redis
restore

⚠️ 注意：stacks/data/backup/ 是实例备份工具的默认归档目录（appsmithctl backup/restore 与数据库导出产物都在这里），请纳入服务器备份计划；加密密钥 APPSMITH_ENCRYPTION_PASSWORD/SALT 不包含在备份包内，必须从 docker.env 单独妥善保存（备份命令结束后会显式提醒）。

六、环境变量表

首启后自动生成 /opt/appsmith/stacks/configuration/docker.env（实测 77 行），常用键如下（完整逐项解析见《Appsmith 2.5.1 配置参数详解》）：

修改方式：编辑 docker.env 后执行 docker compose restart appsmith 生效；也可以直接在编排文件 environment: 段注入（两类方式实测验证过程见《Appsmith 2.5.1 配置参数详解》第三章）。

七、配置参数说明

编排文件层面可调的生产参数与建议：

1. 项目名与实例名：name 与 container_name 按「产品-版本-用途」可读规则命名（本文 appsmith-2.5.1-stack / appsmith-2-5-1-web），多实例共存时一眼可辨。
2. 端口规划：宿主侧避开 80/443 与既有业务端口；只暴露 8128（HTTP）即可满足内网使用，8130（HTTPS）仅在配置自定义域名启用 TLS 后才有意义。
3. 重启策略：restart: unless-stopped 兼顾开机自启与人工停止后的可控性；若希望人工停止后也不受影响可保持默认。
4. 网段规划：同机部署多套应用时为每套栈显式分配独立 /24 网段（本文 10.89.65.0/24），并在分配前用 docker network ls + docker network inspect 核对已占网段。
5. 资源限制：如需约束应用栈内存，可在编排文件 deploy.resources.limits.memory 或 mem_limit 上设置；后端 JVM 堆用环境变量显式控制（APPSMITH_JAVA_ARGS，实测验证见《Appsmith 2.5.1 配置参数详解》第六章）。
6. 日志增长：stacks/logs/ 与访问日志会持续增长，建议在编排文件为服务加 logging: {driver: json-file, options: {max-size: "50m", max-file: "3"}} 限制日志体量。

八、配置文件挂载

应用读取配置的唯一宿主路径是挂载目录中的 stacks/configuration/docker.env。查看与确认：

wc -l /opt/appsmith/stacks/configuration/docker.env

实测回显：

77 /opt/appsmith/stacks/configuration/docker.env

grep -E 'ADMIN_EMAILS|DISABLE_TELEMETRY' /opt/appsmith/stacks/configuration/docker.env

实测回显（管理员邮箱为首启创建后自动回写）：

APPSMITH_DISABLE_TELEMETRY=true
APPSMITH_ADMIN_EMAILS=admin@example.com

⚠️ 注意：该文件由首启过程生成并写入了内置数据库与 Redis 的随机口令、加密密钥对，权限与备份等级应等同数据库凭据：不要提交到代码仓库、不要在公共频道粘贴；升级或迁移实例时按备份工具的提示单独保存 APPSMITH_ENCRYPTION_PASSWORD/SALT 两行。

九、常用运维命令

以下命令均在编排目录 /opt/appsmith 下执行。

9.1 状态与日志

docker compose ps

实测回显：

NAME                 IMAGE                                         COMMAND                   SERVICE    CREATED          STATUS                    PORTS
appsmith-2-5-1-web   index.docker.io/appsmith/appsmith-ce:v2.5.1   "/opt/appsmith/entry…"   appsmith   13 minutes ago   Up 13 minutes (healthy)   0.0.0.0:8128->80/tcp, [::]:8128->80/tcp, 0.0.0.0:8130->443/tcp, [::]:8130->443/tcp

docker compose logs appsmith --tail=3

实测回显（输出节选，各内部服务日志前缀区分：backend / editor / mcp 等）：

appsmith-2-5-1-web  | backend stdout | [2026-10-21 08:22:12,653] [scheduling-1] requestId= userEmail= orgId= traceId= spanId= - Lock already acquired for: lock:
appsmith-2-5-1-web  | editor stdout | {"level":"info","ts":1792570934.1143432,"logger":"http.log.access.log0","msg":"handled request","request":{"remote_ip":"::
appsmith-2-5-1-web  | mcp stderr | {"event":"appsmith_mcp_request","timestamp":"2026-10-21T08:22:14.120Z","requestId":"b622466d-b893-4ce0-876e-82a61c95bb03","pa

9.2 重启与停止

docker compose restart appsmith

实测回显（约 30–60 秒后恢复健康）：

 Container appsmith-2-5-1-web Restarting
 Container appsmith-2-5-1-web Started

docker compose stop appsmith && docker compose start appsmith

实测回显：

 Container appsmith-2-5-1-web Stopped
 Container appsmith-2-5-1-web Started

重启/启停后统一用健康接口确认恢复：

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

实测回显：

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

9.3 配置变更后生效

修改 stacks/configuration/docker.env 或编排文件后，按变更类型执行：

# 仅改 docker.env：重启应用栈即可
docker compose restart appsmith

# 改了编排文件（端口/卷/环境注入）：重建式生效
docker compose up -d

9.4 升级小版本

数据在 ./stacks，升级即替换版本号重建：

1. 先备份：docker compose exec appsmith appsmithctl backup（实测流程见《Appsmith 2.5.1 常用 CLI 命令与工具详解》）；
2. 修改 docker-compose.yml 中 image 的版本号；
3. docker compose up -d 应用变更；
4. docker compose ps 等待 (healthy)，再执行 curl -s http://localhost:8128/api/v1/health 验证；
5. 出现不兼容问题时：把版本号改回旧值执行 docker compose up -d 回滚，再用备份包按《Appsmith 2.5.1 常用 CLI 命令与工具详解》的恢复流程回灌数据。

9.5 彻底卸载

cd /opt/appsmith
docker compose down        # 移除运行实例与内部网络（数据卷 ./stacks 保留）
rm -rf /opt/appsmith/stacks   # 确认不再需要数据后删除全部状态

十、常见问题

Q1：首启创建管理员提交后无反应/报「无效邮箱」，怎么排查？ 应用对管理员邮箱做常规域名校验，.local、.internal 等伪域名会被拒绝。实测过程：使用 admin@appsmith.local 创建失败，实例日志中出现明确拒绝原因：

backend stdout | [2026-10-21 08:15:05,574] [nioEventLoopGroup-3-3] requestId=5ae15912-478f-4fbf-844d-30716d2bd6c4 ... - Super user creation failed after claiming slot. Releasing sentinel.
backend stdout | com.appsmith.server.exceptions.AppsmithException: Please enter a valid parameter email.

解决：改用常规域名邮箱（如 admin@example.com）重新提交即可，实测随即创建成功。

Q2：想用接口直创管理员，为什么 POST /api/v1/users/super-user 返回 401、application/json 返回 415？ 这是版本演进与接口形态两个问题叠加，实测排障链如下：

1. v2.5.1 已不存在 /api/v1/users/super-user 路径，直接请求返回 HTTP/1.1 401 Unauthorized（空响应体）；新路径为 POST /api/v1/users/super；
2. 新接口只接受表单编码，用 Content-Type: application/json 提交会被拒绝：{"responseMeta":{"status":415,"message":"415 UNSUPPORTED_MEDIA_TYPE \"Content type 'application/json' not supported\"","success":false},"errorDisplay":""}；
3. 正确形态：先 GET 任意接口取 XSRF-TOKEN cookie，再以 X-XSRF-TOKEN 头回传、带 Origin 头、表单字段 email/password/name 提交，成功返回 302。

Q3：映射了 443（宿主 8130）却打不开 HTTPS？ 应用内 443 不会凭空启用：未配置 APPSMITH_CUSTOM_DOMAIN 时，证书目录为空且 443 不提供 TLS 监听。实测证据：首启后 stacks/ssl/ 为空目录，curl -sk https://localhost:8130/ 返回 000（连接失败）。解决：在 docker.env 配置 APPSMITH_CUSTOM_DOMAIN 并解析好域名后重启应用栈，由内置网关自动签发证书；仅内网使用可直接走 8128（HTTP）。

Q4：up -d 后立即访问 8128 返回连接被拒或 502？ 首启要完成内置数据库初始化、迁移与后端启动，实测约 1–2 分钟。判定标准是编排状态出现 Up (healthy)、日志出现 Started ServerApplication，再进行健康检查与页面访问。

Q5：健康检查一直不通过怎么办？ 按顺序排查：docker compose logs appsmith --tail=100 看首个报错服务前缀（backend/editor/mongodb 等）；确认 stacks/configuration/docker.env 未使用 shell 表达式（v2.5.1 强校验，违规会阻断启动并给出诊断信息）；确认宿主内存 ≥4GB；确认网段/端口未与同机其他应用冲突。

十一、参考链接

1. 官方安装文档（Docker）：https://docs.appsmith.com/getting-started/setup/installation-guides/docker
2. 环境变量配置官方说明：https://docs.appsmith.com/getting-started/setup/instance-configuration/configure-using-environment-variables
3. GitHub Releases（版本与升级注记）：https://github.com/appsmithorg/appsmith/releases
4. 本系列认知篇：《Appsmith 介绍与选型指南》
5. 本系列配套篇目：《Appsmith 2.5.1 配置参数详解》《Appsmith 2.5.1 常用 CLI 命令与工具详解》（专栏内检索标题即可）