Appsmith 保姆级部署教程：开源自托管低代码平台，拖拽搭建内部工具与管理后台

一、项目介绍

Appsmith 是一个开源的低代码应用开发平台（官方 README 原文："Appsmith is an open-source low-code platform that streamlines custom application development, deployment, and maintenance"）。企业通常需要搭建大量内部工具——仪表盘（Dashboard）、管理后台（Admin Panel）、客户 360 视图、IT 自动化、服务管理台等，传统方式需要前后端从头写，Appsmith 把这个过程压缩为"在浏览器里拖组件、连数据源、写少量 JS 查询"。

项目由 Appsmith Inc. 维护，官方同时提供：
- Appsmith Cloud 托管版（app.appsmith.com / login.appsmith.com）；
- 自托管 Docker 镜像 appsmith/appsmith-ce（社区版，Docker Hub 拉取量在 README 徽章上持续增长）；
- Kubernetes Helm Chart、AWS AMI 等企业部署方式。

项目在 GitHub（appsmithorg/appsmith）持续活跃维护，提交活跃度徽章为绿色（官方 README 顶部 commit-activity 徽章）。

二、功能拆解

按官方 README 与文档，Appsmith 核心能力如下：

功能	说明
可视化页面搭建	浏览器画布拖拽组件（Button、Table、Form、Chart、Modal、List 等）
数据源连接	内置支持 PostgreSQL、MySQL、MongoDB、Redis、REST API、GraphQL、S3、Google Sheets 等
查询与 JS 编程	组件事件触发查询；查询里写 SQL/JS/REST；组件可绑定查询结果
权限与团队	多用户、工作区（Workspace）、应用级/页面级权限
应用发布与嵌入	一键发布；可通过 iframe 嵌入到其他系统
自托管一体化镜像	单容器内含后端、前端、MongoDB、Redis、NGINX（官方 Docker 文档原文："built with all the components required for it to run, within a single Docker container"）

三、官方/GitHub 链接

GitHub 仓库：https://github.com/appsmithorg/appsmith
官方网站：https://www.appsmith.com
官方文档：https://docs.appsmith.com
Docker 安装指南：https://docs.appsmith.com/getting-started/setup/installation-guides/docker
Kubernetes 安装指南：https://docs.appsmith.com/getting-started/setup/installation-guides/kubernetes
AWS AMI 安装指南：https://docs.appsmith.com/getting-started/setup/installation-guides/aws-ami
Appsmith Cloud（托管版）：https://app.appsmith.com
社区论坛：https://community.appsmith.com
Discord：https://discord.gg/rBTTVJp

四、环境要求

官方 Docker 部署文档（deploy/docker/README.md）明确前置条件：

已安装 Docker 与 Docker Compose（官方给出安装链接：https://docs.docker.com/engine/install/ 与 https://docs.docker.com/compose/install/ ）。
验证命令（官方原文）：

docker --version
docker-compose --version

官方期望输出参考：

text Docker version 20.10.7, build f0df350 docker-compose version 1.29.2, build 5becea4c

端口：官方 compose 映射 80（HTTP）与 443（HTTPS）。
数据目录：官方示例将宿主 ./stacks 挂载为容器内 /appsmith-stacks（持久化数据库、配置、加密密钥）。
操作系统：Docker 部署方式官方未限定具体 Linux 发行版；macOS/Windows 通过 Docker Desktop 亦可运行（官方文档以 Linux 服务器为主场景）。
硬件：官方文档未给出最低 CPU/内存指标；单容器内含 MongoDB 与 Redis，建议至少 2 GB 内存（社区常见建议，非官方硬性数字）。

五、部署步骤

步骤 1：创建部署目录

官方文档原文："Create a folder called appsmith (or some other name that you like), which will serve as our installation folder."

mkdir appsmith && cd appsmith

逐段解释：mkdir appsmith 创建名为 appsmith 的目录；&& 表示前一条成功后才执行下一条；cd appsmith 进入该目录。后续 docker-compose.yml 与 stacks/ 数据目录都放在这里。

预期输出参考： 命令成功，无输出。

步骤 2：创建官方 docker-compose.yml

在 appsmith/ 目录内新建 docker-compose.yml，内容完全照搬官方文档：

version: "3"

services:
  appsmith:
    image: appsmith/appsmith-ce
    container_name: appsmith-ce
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./stacks:/appsmith-stacks
    restart: unless-stopped
  #   # Uncomment the lines below to enable auto-update
  #   labels:
  #     com.centurylinklabs.watchtower.enable: "true"

  # auto_update:
  #   image: containrrr/watchtower
  #   volumes:
  #     - /var/run/docker.sock:/var/run/docker.sock
  #   # Update check interval in seconds.
  #   command: --schedule "0 0 * ? * *" --label-enable --cleanup
  #   restart: unless-stopped

逐段解释：
- version: "3"：Compose 文件格式版本。
- services.appsmith：唯一业务服务。
- image: appsmith/appsmith-ce：官方社区版镜像（-ce 后缀即 Community Edition）。
- container_name: appsmith-ce：固定容器名，便于后续 docker exec / docker logs。
- ports：把宿主 80 与 443 映射到容器同端口；容器内 NGINX 同时处理 HTTP/HTTPS。
- volumes: ./stacks:/appsmith-stacks：把宿主当前目录下的 stacks/ 挂载到容器内 /appsmith-stacks，这是 Appsmith 的全部持久化数据（MongoDB 数据、加密环境变量、SSL 证书、用户上传）所在位置。
- restart: unless-stopped：容器异常退出或 Docker 重启后自动拉起；手动 docker stop 不会被自动重启。
- 下方被注释的 auto_update 服务：官方可选的 Watchtower 自动更新配置——官方原文注释："To enable auto-update for Appsmith, please uncomment all the commented lines in the docker-compose file." 默认不开。

步骤 3：后台启动

官方文档原文命令：

docker-compose up -d

逐段解释：docker-compose up 依据同目录 docker-compose.yml 创建并启动容器；-d 表示后台（detached）运行。官方文档提示："This command may take a few minutes to download the docker image and initialize the application."

预期输出参考： 首次运行会拉取镜像，出现 Pulling appsmith (appsmith/appsmith-ce:latest)...、Creating appsmith-ce ... done 之类日志；最终回到命令行。Appsmith 官方说明："Appsmith should soon be available at http://localhost."

步骤 4：确认容器运行状态

官方文档原文："You can check if application is running correctly by running docker ps or docker-compose ps."

docker ps

官方期望输出参考：

text CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 3b8f2c9638d0 appsmith/appsmith "/opt/appsmith/entrypoint.sh" 17 minutes ago Up 17 minutes 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp appsmith

六、配置参数详解

1. 持久化目录 /appsmith-stacks： 官方容器把所有运行时数据放在此目录，宿主对应 ./stacks/。该目录下由 Appsmith 首次启动自动生成，包含：
- MongoDB 数据；
- env.sh（容器启动时读取的环境变量文件，含加密密钥）；
- NGINX 配置与 SSL 证书；
- 用户上传的文件。

官方 Docker 文档强调：升级、备份、迁移都以这个目录为单位。

2. 自定义环境变量（官方文档说明）： 如需修改端口、SMTP、Mongo 选项等，编辑 ./stacks/configuration/docker.env（容器启动时由 entrypoint 读取），改完后 docker-compose restart 生效。官方文档列出的常用变量包括（来自官方 docker.env 模板，路径见 deploy/docker/docker.env）：

变量	默认值	说明
APPSMITH_ENCRYPTION_PASSWORD	（首次启动自动生成）	应用数据加密口令，丢失将无法解密旧数据
APPSMITH_ENCRYPTION_SALT	（首次启动自动生成）	加密盐值
APPSMITH_MONGODB_URI	（内置 localhost）	自定义外部 MongoDB 连接串
APPSMITH_REDIS_URL	（内置 localhost）	自定义外部 Redis 地址
PORT	80	容器内 NGINX 监听端口
APPSMITH_CUSTOM_DOMAIN	（空）	绑定自定义域名时填写

官方文档警告：APPSMITH_ENCRYPTION_PASSWORD 与 APPSMITH_ENCRYPTION_SALT 在首次启动时自动随机生成并写入 ./stacks，请勿修改或删除——否则旧数据将无法解密。

3. 开启自动更新（官方可选配置）： 如需要 Watchtower 自动拉取新镜像，取消 docker-compose.yml 中 labels 与 auto_update 两段注释（官方原文注释已给出完整配置，定时表达式 "0 0 * ? * *" 即每天 0 点检查一次）。

七、启动与运维

启动 / 停止 / 重启：
启动：docker-compose up -d（已运行则为幂等）。
停止：docker-compose stop。
重启：docker-compose restart。
停止并删除容器（数据保留在 ./stacks）：docker-compose down。
查看日志：

docker logs -f appsmith-ce

逐段解释：docker logs 输出容器 stdout；-f 持续跟踪。Ctrl+C 退出跟踪不停止容器。

开机自启： 官方 compose 中 restart: unless-stopped 即官方提供的自启方式——Docker 守护进程启动时会自动拉起容器（前提是 Docker 自身已设为开机启动，这属于 Docker 平台通用机制）。
修改对外端口： 改 docker-compose.yml 中 ports 映射左侧（宿主端口），例如 "8080:80"；容器内仍监听 80。改完 docker-compose up -d 重建容器。
数据备份（官方建议）： 停容器后整目录打包 ./stacks/：

docker-compose stop
tar -czf appsmith-stacks-backup.tar.gz ./stacks
docker-compose start

八、实操验证

浏览器访问 http://服务器IP（官方原文："Appsmith should soon be available at http://localhost"）。若服务器有防火墙，放行 80 端口。
首次打开会自动跳转注册/创建管理员账号页面——Appsmith 没有出厂默认账号密码，第一个注册的用户即工作区管理员。
填写邮箱、姓名、密码，完成工作区初始化。
进入后点击「New Application」新建一个应用，从左侧组件面板拖一个 Table 与一个 Button 到画布，点击右上角 Deploy 发布。
验证数据源：左侧「Queries / APIs」→ 新建 PostgreSQL 查询（或先使用内置示例数据源），运行后把结果绑定到 Table。

登录与安全（重要）

官方默认账号密码：无默认账号。 Appsmith 不预置任何账号；首次访问时第一个完成注册的用户自动成为工作区管理员。
登录地址： http://服务器IP（未配置 HTTPS 时）。
首次登录后： 右上角头像 →「Profile」可修改姓名与密码；工作区「Settings」→「Members」可邀请同事。
密码配置存放位置： 用户凭据以哈希形式存于容器内 MongoDB（即宿主 ./stacks/ 数据卷中），不存明文。
加密密钥： ./stacks/configuration/env.sh 中的 APPSMITH_ENCRYPTION_PASSWORD 与 APPSMITH_ENCRYPTION_SALT 是 Appsmith 加密存储数据的密钥，丢失则历史数据无法解密，备份时务必连同 ./stacks/ 一起备份。
安全提醒： ① 部署在公网时务必通过 443/HTTPS 暴露（官方容器自带 SSL 证书管理能力，配合 APPSMITH_CUSTOM_DOMAIN）；② 不要把 80 端口长期暴露在公网而不设置强密码；③ 关注官方安全公告 https://github.com/appsmithorg/appsmith/security/advisories 。

九、故障排查

案例 1：访问 80 端口返回 502 / 空白页

报错原文（常见形式）：浏览器显示 502 Bad Gateway，或 NGINX 默认页而非 Appsmith 工作台。
报错原因：官方容器 entrypoint 需要数十秒初始化 MongoDB、Redis 与后端服务；刚 docker-compose up -d 后立即访问会撞上后端未就绪。
分步解决：① docker logs -f appsmith-ce 观察日志，等待出现类似 started / listening 的就绪日志；② docker ps 确认容器状态为 Up 且未反复 Restarting；③ 若日志报端口冲突，检查宿主 80/443 是否被其他服务占用（sudo ss -ltnp | grep ':80 '）。

案例 2：升级后无法登录，提示解密失败

报错原文（官方 Issues 常见形式，参考 appsmithorg/appsmith Issues）：Error: Failed to decrypt 或登录后页面空白、接口 500。
报错原因：./stacks/configuration/env.sh 中的 APPSMITH_ENCRYPTION_PASSWORD / APPSMITH_ENCRYPTION_SALT 被改动、删除或容器挂载了不同目录，导致后端无法解密 MongoDB 中已有数据。
分步解决：① 确认 docker-compose.yml 中 ./stacks:/appsmith-stacks 路径未变；② 与上次备份对比 ./stacks/configuration/env.sh 中两个加密变量；③ 如变量丢失且无备份，官方未提供解密恢复手段——只能清空 ./stacks/ 重新初始化（数据全部丢失）。

案例 3：docker-compose up 报端口已被占用

报错原文（Docker 常见）：Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use。
报错原因：宿主 80 端口被 Nginx/Apache/其他容器占用。
分步解决：① sudo ss -ltnp | grep ':80 ' 找到占用进程；② 改 docker-compose.yml 端口映射，例如 "8080:80"、"8443:443"；③ docker-compose up -d 重建。

案例 4：自定义域名后访问跳转到 localhost

报错原因：未设置 APPSMITH_CUSTOM_DOMAIN，应用内部按容器默认地址生成回调/资源 URL。
分步解决：编辑 ./stacks/configuration/docker.env，加入 APPSMITH_CUSTOM_DOMAIN=https://your.domain.com，然后 docker-compose restart。

十、升级、回滚与卸载

升级： 官方 Docker 文档未在 README 中给出专门的升级命令段；按官方镜像机制，升级步骤为：

cd appsmith
docker-compose pull
docker-compose up -d

逐段解释：docker-compose pull 拉取 appsmith/appsmith-ce:latest 新镜像；docker-compose up -d 用新镜像重建容器，./stacks 数据卷保留。官方文档强调 ./stacks 是数据持久化位置，升级前建议先按第七节做备份。

回滚： 官方未提供一键回滚命令；可把 docker-compose.yml 中 image 改为指定旧版本 tag（如 appsmith/appsmith-ce:v1.x.x，版本列表见 https://hub.docker.com/r/appsmith/appsmith-ce/tags ），再 docker-compose up -d。注意：跨大版本回滚可能因 MongoDB schema 迁移不兼容而失败，回滚前需恢复 ./stacks 备份。

卸载：

docker-compose down
docker rmi appsmith/appsmith-ce

如需彻底删除数据（此操作永久删除全部应用与用户数据，先备份 ./stacks/）：rm -rf ./stacks。

十一、商用许可合规说明

许可证：Apache License 2.0（官方 README 末尾「License」一节原文："Appsmith is licensed under the terms of Apache License 2.0"；仓库 LICENSE 文件同样为 Apache-2.0 全文）。
Apache-2.0 允许自由使用、修改、分发与商用，包括闭源商业产品；分发时须保留原始版权声明与许可文本，修改过的文件须标注变更，并附带 NOTICE（如有）。
Appsmith 社区版（appsmith/appsmith-ce）自托管无需付费授权；官方另有 Appsmith Business / Enterprise 商业版（含 SSO、审计日志等增值能力）作为可选商业渠道，非强制项。