生产切换

本页用于将匠铺出图（JumpCLI）从本地或测试环境逐步切换到公开域名。每完成一个阶段都应验证成功，再进入下一阶段；不要把认证、计费或支付与首次静态站发布混在一次变更中。

应用保持单个容器和单个 worker（GRANIAN_WORKERS=1）。每次更新前先备份 data/、images/ 和 maintenance/，再用已审核镜像滚动替换单个应用容器。

8 个 canonical 图片队列与并发设置都是 restart-required，修改后按下方流程替换单个应用容器。MAX_SSE_SUBSCRIBERS_GLOBAL、MAX_SSE_SUBSCRIBERS_PER_IP、SSE_CONNECTION_TTL_SECONDS 与 GENERATE_SOURCE_ATTEMPTS 可通过 Overall Config 热更新；更新值仅作用于后续连接或请求，不要求重启。

公开域名

域名	当前职责	首次动作
`docs.jumpcli.com`	VitePress 静态文档	首先上线
`app.jumpcli.com`	创作工作台与运营控制台	HTTPS 后上线
`auth.jumpcli.com`	Casdoor OIDC 登录认证	应用公开来源确认后上线
`api.jumpcli.com`	将来的开发者 API 网关	仅保留 DNS 解析

第一阶段：DNS 与 TLS

为 docs、app、auth 和 api 创建指向服务器公网 IPv4 的 A 记录。
不要添加尚未配置的 IPv6 AAAA 记录。
在 1Panel 中分别创建网站并为实际开放的 docs、app 和 auth 域名签发证书。
开启 HTTP 到 HTTPS 的跳转。

验收： 浏览器访问每个已开放域名时没有证书警告。
回滚： 停止后续切换；保留原有生产入口，不要通过临时关闭 TLS 绕过证书问题。

第二阶段：文档站

本地执行 npm run docs:check && npm run docs:build。
在 1Panel 创建静态网站 docs.jumpcli.com，不配置应用反向代理。
将 docs/.vitepress/dist/ 中的内容上传到该网站根目录。
访问首页、任意深层页面和搜索功能。

验收： https://docs.jumpcli.com/ 与 /deploy/domains 均返回成功页面。
回滚： 恢复上一个静态构建目录；不影响工作台、认证或支付服务。

第三阶段：工作台

为 app.jumpcli.com 配置应用反向代理，并设置 PUBLIC_ORIGIN=https://app.jumpcli.com、 ALLOWED_HOSTS=app.jumpcli.com、安全 Cookie 与真实的可信代理范围。不要将同一应用同时公开到 api.jumpcli.com。

当前服务器中的 JumpCLI 使用独立 Compose 项目和仅本机监听的 127.0.0.1:19091 -> 9090 端口。其运行路径、图片、数据和维护目录均与旧应用隔离；反向代理应只转发到该回环地址，不能复用旧应用端口或挂载目录。

生产 .env 必须设置非空、独立的 ADMIN_EMAIL、ADMIN_PASSWORD 与 ADMIN_KEY。当 FORCE_HTTPS=true 且 PUBLIC_ORIGIN 为 HTTPS 地址时，JumpCLI 会拒绝以空 ADMIN_PASSWORD 创建首个管理员账户，且不会将随机凭据写入日志。

首次部署或从其他镜像迁移前，确保绑定目录由容器的运行账号拥有：

bash

cd /srv/apps/jumpcli
chown -R 1001:1001 data images maintenance

否则 SQLite 无法创建迁移或 WAL 文件，应用会启动失败。该命令只修正目录权限，不删除业务数据。

应用源码更新后，先从已审核的发布目录构建一次镜像，再把脚本输出的不可变 APP_IMAGE=sha256:... 与同一个 APP_VERSION 写入 .env。生产 Compose 只使用该镜像 ID，不会再次构建或拉取可变标签。不要把端口、卷或密钥写入 1Panel 表单生成的临时 Compose 片段：

bash

cd /srv/apps/jumpcli
APP_VERSION=<verified-commit> sh scripts/production_build_release.sh
docker compose \
  -f docker-compose.yml \
  -f docker-compose.production.yml \
  -f deploy/meteroid/docker-compose.jumpcli-network.yml \
  up -d --no-build --pull never --force-recreate

该覆盖文件只发布 127.0.0.1:19091 -> 9090；1Panel/OpenResty 继续反向代理该回环地址。

更新顺序：

先备份持久化数据卷。
只构建一次已审核的发布版本，把不可变 APP_IMAGE=sha256:... 和匹配的 APP_VERSION 写入 .env，然后用 --no-build --pull never 只重建这个应用容器。
在干净浏览器配置里验证 /ready、真实登录和工作台。
如果健康检查或浏览器回归失败，先恢复上一版已验证的镜像和环境变量，再切换流量。

验收： /ready、访问控制和基础页面均通过 HTTPS 正常工作；无痕访客打开 /workspace 时可看到完整示例项目和 6 张图片，且不会请求受保护的任务、图库、设置、计费、出图、上传、缩略图、SSE 或 WebSocket 接口。登录后必须切换到真实租户工作台，示例数据不得写入租户。scripts/production_preflight.sh 还需验证镜像 revision 与 APP_VERSION 一致。 回滚： 恢复上一组环境变量和应用镜像，清除测试浏览器 Cookie 后重试。

第四阶段：认证

为 auth.jumpcli.com 配置 Casdoor 后，更新 OIDC Application 回调地址为 https://app.jumpcli.com/api/identity/callback，并同步应用的认证公开来源配置。

验收： 无痕窗口可登录、返回工作台、登出并再次登录。
回滚： 恢复上一组 Casdoor 公开来源和回调地址，停止支付切换。

第五阶段：计费与支付

先验证 Meteroid 连接、已发布套餐与测试订单履约。然后以 HTTPS 支付通知地址接入支付宝，并用沙箱或受控测试订单完成“选择套餐、支付、通知验证、开通权益、账单刷新”全流程。

验收： 订单仅在服务端通知验证和 Meteroid 履约成功后开通。
回滚： 关闭支付入口，保留订单和审计线索，不按浏览器回跳或人工判断直接开通权益。

生产切换 ​

公开域名 ​

第一阶段：DNS 与 TLS ​

第二阶段：文档站 ​

第三阶段：工作台 ​

第四阶段：认证 ​

第五阶段：计费与支付 ​