SSH 一键部署：从上传到跑起来（含踩坑清单）

这是最省事的一条路：把发版包丢到服务器上，跑一条 install.sh，剩下的 （环境自检 → 生成密钥 → 建库 → 起容器 → 健康检查）都由脚本完成。整套流程无外网依赖之外的手工步骤， 断点也都能重跑。

先看清楚这套东西由什么组成：PostgreSQL 15 + 原生网关服务 + 扩展层 + Nginx 网关， 四个容器组成一套实例。不是单容器，所以下面的命令都用 docker compose，不要用 docker run 拼。

一、前置条件

• 系统：Ubuntu 22.04+ / Debian 12+ / Rocky 9 / AlmaLinux 9（x86_64）
• 配置：**1 核 2G 起**，建议 2 核 4G；磁盘 20G 起（数据库与日志都在本地）
• Docker Engine 24+ 与 Compose v2；install.sh 会自检，缺了会明确告诉你缺什么
• 一个域名（可选，但上线收款建议配）；已备案的域名请先把 A 记录指向服务器

二、把包拉下来并解压

发版包放在分发桶里，是公共读的 —— 服务器上一条 curl 直接拉，不需要先下载到本地再 scp。下面这个地址是固定别名，始终指向最新版：

sudo mkdir -p /opt/yaka && cd /opt/yaka
sudo curl -fsSLO https://yaka-dist.tos-cn-beijing.volces.com/releases/latest/yaka-instance.tar.gz

建议顺手校验一次（同目录还有个 .sha256，里面写的文件名与下载下来的完全一致， sha256sum -c 可以直接用）：

sudo curl -fsSLO https://yaka-dist.tos-cn-beijing.volces.com/releases/latest/yaka-instance.tar.gz.sha256
sha256sum -c yaka-instance.tar.gz.sha256      # 必须看到 OK 再往下

要钉住某个版本（审计 / 复现 / 灰度）时，把地址里的 releases/latest/yaka-instance.tar.gz 换成 releases/<版本号>/yaka-instance-<版本号>.tar.gz —— 归档对象永不被覆盖。 服务器上没有 curl 的极简系统，换成 wget 等价替换即可。

然后解压（不要解压到 /root、/tmp 这类可能带 noexec 的分区， 原因见文末踩坑第 1 条）：

sudo tar -xzf yaka-instance.tar.gz
cd yaka-instance-*
ls        # 应看到 install.sh / docker-compose.yml / .env.example / build/ / docs/

三、跑一键安装

sudo bash install.sh

向导会依次问你几件事，都有默认值，直接回车也能过：

向导项	说明
部署版本	标准版（免费、免登录、离线可用）或 高级版（需母版授权）
对外访问地址	填 https://你的域名；先不配域名就填 http://服务器IP:端口
监听端口	默认 80 / 443。若 80 已被占用（宝塔、Nginx、其他站点），改成 8088 之类
数据库口令	脚本自动生成强随机口令并写进 .env 与 secrets/
管理员账号	平台管理员初始账号，装完立刻改密码

脚本化/演示场景可以全默认值跑：sudo bash install.sh --yes； 只更新产品文件（不重新问参数）用 sudo bash install.sh --upgrade。

四、验收：三件事都过了才算装好

# ① 容器状态：postgres 与 yaka-ext 必须是 healthy
docker compose ps

# ② 网关健康检查：返回 ok
curl -fsS http://127.0.0.1:8088/healthz

# ③ 浏览器打开你的地址，能进首页 / 控制台

首次启动数据库要初始化，postgres 从 starting 变 healthy 通常需要 10–30 秒。这期间打开页面报 502 是正常的，等 docker compose ps 里的状态稳住了再刷。

五、配域名与 HTTPS

两种做法，二选一：

• 让实例自己扛 443：把证书放到包内的证书目录，解开 nginx.conf 里的 443 server 块， 然后 docker compose up -d --no-deps --force-recreate nginx。
• 前面挂宝塔 / 1Panel / NPM 反代：实例只监听 127.0.0.1:8088，面板站点反代到它并申请 SSL。 反代时务必带上 Host、X-Real-IP、X-Forwarded-For、X-Forwarded-Proto 四个头， 否则后台看到的访客 IP 全是 127.0.0.1，风控与审计全部失真。

六、备份与升级

./backup.sh                      # 数据库全量 dump + secrets + 上传的品牌资源
ls backups/                      # backup-YYYYmmdd-HHMMSS.tar.gz

备份文件里含密钥，属于敏感文件：不要传公共网盘，建议加密后离线保存。 升级时替换 build/ 下的二进制 / 前端 / 迁移脚本，再 docker compose up -d --no-deps --force-recreate yaka-ext；后台「版本更新」也支持在线更新。

七、踩坑清单（都是真机上踩过的）

现象	原因与处置
容器起来就 exec: "/app/yaka-ext": permission denied	解压目录所在分区带 noexec：二进制是 bind mount 进容器后直接执行的。 用 findmnt -no OPTIONS -T /opt/yaka 确认，换到普通目录（如 /opt/yaka）重新解压。 install.sh 已内置这条守卫，会在安装前直接拦下。
更新时脚本/容器直接崩，或服务停在旧版本	装的是 Compose v1（docker-compose）。必须用 v2 插件 docker compose。
改了 .env 但完全不生效	restart 不会重新读取环境变量。必须 docker compose up -d --no-deps --force-recreate yaka-ext。
打开页面 502 / 一直转圈	数据库还没 healthy 就来了请求；或 443/80 被别的服务占用。先看 docker compose ps，再看 docker compose logs -n 50 yaka-ext。
后台「访客统计」里 IP 全是 127.0.0.1	反代没传 X-Forwarded-For。补上反代头，并把面板/宿主机网段加进 .env 的 TRUSTED_PROXIES。
时间比本地慢 8 小时	数据库统一存 UTC，展示按北京时间换算。如果某处显示错位，是那里没做换算，不是装错了。 别用「把服务器时区改成 +8」来凑，会造成库内时间错乱。
高级版装完起不来，日志里直接退出	高级版是门控启动：拿不到母版授权就拒绝启动。检查 .env 里 MASTER_URL 是否可达、INSTANCE_ID 是否已在母版登记。
以为删容器就把数据删了 / 以为 down 很安全	数据库在命名卷里，删容器不删数据；但 docker compose down -v 会连卷一起删。 永远不要加 -v，需要清理先 ./backup.sh。