appsmith本地开发必须用docker启动，官方不提供二进制或系统包，docker compose up -d是唯一受支持方式；跳过docker直接运行前端会因依赖后端、redis等服务而失败，常见错误包括连接拒绝、数据库失败和登录页空白。
Appsmith 本地开发环境必须用 Docker 启动
Appsmith 官方不提供二进制安装包或系统级 deb/rpm 包，docker compose up -d 是唯一受支持的本地启动方式。跳过 Docker 直接 npm run dev 或 yarn start 会失败——前端项目依赖后端服务、Redis、PostgreSQL 等组件协同运行，手动拉起所有服务极易出错。
常见错误现象：Connection refused（连不上 http://localhost:8080）、Database connection failed、登录页空白但控制台报 ERR_CONNECTION_REFUSED。
- 确保已安装
docker和docker-compose（新版 Docker Desktop 已内置，旧版需单独装docker-compose-plugin） - 不要用
sudo docker-compose启动后再用普通用户访问；要么全程 root 权限，要么把当前用户加进docker组：sudo usermod -aG docker $USER，然后重新登录终端 - 官方
docker-compose.yml默认绑定8080端口，若被占用，直接编辑文件改ports: ["8081:8080"]即可，无需改其他配置
外网访问必须绕过端口映射直连内网穿透
Linux 服务器默认无公网 IP，仅靠 docker-compose.yml 中开放端口无法实现外网访问。试图用 iptables 转发或云服务商安全组放行 8080 端口，对家庭/企业内网无效——你面对的是 NAT 网关，不是裸露公网 IP。
真实可行路径只有一条：用内网穿透工具建立反向隧道。知识库中提到的路由侠（luyouxia/lyx 镜像）是当前最简方案，但要注意它不走标准 HTTP 反代，而是以设备身份注册到中心节点。
- 必须在 Windows 主机上运行路由侠客户端（管理界面），Linux 侧只负责运行
docker run --net=host容器，--net=host是关键，否则容器无法获取宿主机网络状态 -
docker run命令中的-e code=xxx必须与 Windows 客户端生成的安装码完全一致，大小写敏感，多一个空格都会认证失败 - 穿透成功后，访问地址不是
http://your-domain:8080，而是路由侠分配的二级域名（如xxx.lyx.fun），且必须带https://，HTTP 会被强制跳转并失败
.env 文件和证书配置决定 HTTPS 能否启用
Appsmith 开发环境默认不启用 HTTPS，但一旦你执行了 ./start-https.sh 或修改了 .env 中的 APPSMITH_ENFORCE_SECURE_COOKIES=true，没配证书就会卡在白屏或无限重定向。
在无 root/sudo 权限的环境（云容器、VPS、隔离主机）中安装并配置 OpenClaw 浏览器工具的 headless Chrome。适用场景：...
核心矛盾在于：浏览器要求 secure cookie 必须走 HTTPS，而自签名证书又不被信任。解决办法是本地信任 + 域名绑定双管齐下。
- 证书生成命令必须在
app/client/docker目录下运行：mkcert -install && mkcert "*.appsmith.com"，生成的_wildcard.appsmith.com.pem和_wildcard.appsmith.com-key.pem不能挪位置 -
/etc/hosts中必须添加127.0.0.1 dev.appsmith.com，且访问时 URL 必须是https://dev.appsmith.com:8080，用localhost或 IP 地址均无效 -
.env文件里要显式设置：APPSMITH_CLIENT_PROXY_TARGET=https://dev.appsmith.com:8080和APPSMITH_SERVER_PROXY_TARGET=https://dev.appsmith.com:8080，否则前后端跨域请求会 403
数据源连接失败多数因网络策略而非配置错误
在 Appsmith UI 里填对了 MySQL 地址、用户名、密码，测试连接仍显示 Connection timeout，大概率不是密码错了，而是容器网络隔离导致的连通性问题。
Docker 默认桥接网络（bridge）下，Appsmith 容器无法直接访问宿主机的 127.0.0.1。比如你本机跑着 PostgreSQL 在 5432，容器里填 host: 127.0.0.1, port: 5432 必然失败。
- 正确做法是用宿主机真实 IP（如
192.168.1.100）代替127.0.0.1，或改用host.docker.internal（仅 Docker Desktop for Mac/Windows 支持，Linux 需手动添加--add-host=host.docker.internal:host-gateway到docker-compose.yml的 service 配置中） - 数据库需允许远程连接：MySQL 要执行
GRANT ALL ON *.* TO 'user'@'%' IDENTIFIED BY 'pwd'; FLUSH PRIVILEGES;，PostgreSQL 要改pg_hba.conf加host all all 0.0.0.0/0 md5 - 防火墙必须放行对应端口：
sudo ufw allow 5432（PostgreSQL）、sudo ufw allow 3306（MySQL），Ubuntu 22.04 默认启用 ufw
证书路径硬编码、容器网络不可见、穿透域名与本地 hosts 不匹配——这三个点卡住的人最多，调试时优先确认它们。
