9.6 KiB

Raw Permalink Blame History

Shopify 真实环境部署上线说明

本文档用于测试人员和上线人员把当前代码部署到真实测试环境和生产环境。仓库里的默认 shopify.app.toml 是模板配置，不应保留个人账号测试时生成的 client_id、extension uid、.shopify/ 本地 link 状态或任何 .env 密钥。

1. 环境边界

个人验证环境只用于本地 CLI 校验，验证完成后必须移除个人账号生成的 app 绑定信息。
真实测试环境和生产环境必须分别使用各自 Shopify Partner / Developer Dashboard 中的 app。
不要把 SHOPIFY_API_SECRET、第三方 api_secret、Admin access token、数据库密码提交到 Git。
client_id 和 extension uid 虽不是密钥，但属于环境绑定信息；若项目要求保密，放在私有部署配置或 CI/CD secret 里，不提交到公开仓库。
.shopify/ 是 Shopify CLI 本地状态目录，已在 .gitignore 中忽略；不要复制到其他环境。

2. 前置条件

在部署机器或 CI/CD 环境中准备：

node -v
npm -v
shopify version

要求：

Node.js 20 或更高版本。
Shopify CLI 可用。
真实测试/生产 Shopify 账号已具备创建、配置和部署 app 的权限。
已准备公网 HTTPS 后端域名，例如 https://staging-app.example.com 和 https://app.example.com。
已准备数据库连接、Dreame 第三方接口地址和密钥。

3. 安装和基础校验

cd "/path/to/dreame-action"
npm install
npx prisma generate
npx prisma validate --schema prisma/schema.prisma
npm test
npm run typecheck
npm run build

如果使用 CI/CD，建议把以上命令作为部署前质量门槛。

4. 创建或链接 Shopify app

建议测试和生产使用命名配置，避免互相覆盖：

shopify app config link --config staging --reset
shopify app config link --config production --reset

CLI 会提示输入 app name。建议使用：

测试环境：dreame-action Staging
生产环境：dreame-action

如果真实 app 已经存在，使用对应 app 的 Client ID 链接：

shopify app config link --config staging --client-id <staging-client-id>
shopify app config link --config production --client-id <production-client-id>

链接后检查生成的配置文件：

shopify.app.staging.toml
shopify.app.production.toml
extensions/thank-you-activity/shopify.extension.toml 中的 uid

5. 修改环境配置

在对应 shopify.app.<env>.toml 中确认：

application_url = "https://<public-backend-domain>"

[access_scopes]
scopes = "read_orders,read_metaobjects,write_metaobjects,write_metaobject_definitions"

[auth]
redirect_urls = [
  "https://<public-backend-domain>/auth/callback",
  "https://<public-backend-domain>/auth/shopify/callback",
  "https://<public-backend-domain>/api/auth/callback"
]

extensions/thank-you-activity/shopify.extension.toml 保留 CLI 为真实 app 生成的 uid。不要使用个人账号测试时生成的 uid。

6. 运行官方配置校验

shopify app config use staging
shopify app config validate --config staging --json
shopify app info --config staging --json

生产环境：

shopify app config use production
shopify app config validate --config production --json
shopify app info --config production --json

非交互环境中，如果还没有本地 link 状态，直接带目标 app Client ID：

shopify app config validate --client-id <client-id> --json

验收标准：

shopify app config validate --json 返回 valid: true。
issues 为空。
app info 中的 client_id、application_url、redirect_urls、scopes 与目标环境一致。

7. 准备运行时环境变量

部署后端服务时配置：

SHOPIFY_API_KEY=<client_id>
SHOPIFY_API_SECRET=<app_secret_from_dashboard>
SHOPIFY_APP_URL=https://<public-backend-domain>
SCOPES=read_orders,read_metaobjects,write_metaobjects,write_metaobject_definitions
DATABASE_URL=<database_connection_string>
THIRD_PARTY_MODE=live
THIRD_PARTY_TIMEOUT_MS=5000
LOG_RETENTION_DAYS=7
METAOBJECT_TYPE=$app:dreame_activity
METAOBJECT_HANDLE=dreame-activity-config

Shopify CLI 可拉取 app 相关环境变量：

shopify app env pull --config staging --env-file .env.staging
shopify app env pull --config production --env-file .env.production

不要把 .env.staging、.env.production 提交到 Git。

8. 数据库和 Prisma

当前本地开发默认使用 SQLite：

DATABASE_URL="file:./dev.sqlite"

真实环境必须先确认数据库方案。若使用 Postgres，需要在上线前完成 Prisma datasource 和迁移策略调整，并在目标环境执行迁移。部署前至少确认以下表已经创建：

Session
ActivityPushLog
ActivityPushIdempotency

9. Metaobject 配置

Metaobject definition 已声明在 shopify.app.toml，由 Shopify CLI 在 shopify app dev/deploy 时应用：

TOML key: [metaobjects.app.dreame_activity]
Admin API type: $app:dreame_activity
Handle: dreame-activity-config
Admin access: merchant_read_write
Storefront access: none

如果目标店铺已经存在旧的 merchant-owned type dreame_activity，可以通过 METAOBJECT_TYPE=dreame_activity 兼容，但新环境建议使用 app-owned $app:dreame_activity。

字段：

Key	Type	Required
`activity_id`	`number_integer`	yes
`api_app_id`	`single_line_text_field`	yes
`api_secret`	`single_line_text_field`	yes
`status_api_url`	`url`	yes
`push_api_url`	`url`	yes
`status_success_code`	`number_integer`	no
`status_active_required`	`boolean`	no
`push_success_code`	`number_integer`	no
`redirect_url`	`url`	yes
`button_text`	`json`	yes
`shop`	`single_line_text_field`	no

api_secret 只能由后端读取，不应暴露给 Checkout UI Extension。

可选字段默认值：

status_success_code: 0
status_active_required: true
push_success_code: 0

若第三方确认接口②成功码不是 0，只需修改 Metaobject entry 的 push_success_code，不需要改代码。

写入或更新 entry：

SHOPIFY_SHOP_DOMAIN=<shop>.myshopify.com \
SHOPIFY_ADMIN_ACCESS_TOKEN=shpat_xxx \
npx tsx scripts/setup-metaobject.ts

脚本使用 metaobjectUpsert，重复执行会更新同一个 handle，不会创建重复 entry。

10. 部署后端服务

Shopify CLI 的 app deploy 不会部署 Remix 后端服务。需要先把 web app 部署到自有托管环境，并确认：

curl -i https://<public-backend-domain>/
curl -i -X OPTIONS https://<public-backend-domain>/api/action/activity/check

期望：

首页或健康页返回 200。
OPTIONS 返回 204，并包含 CORS headers。
未带 Shopify checkout session token 的 POST 应返回 HTTP 4xx，且不应触发第三方推送。

11. 部署 Shopify 配置和扩展

测试环境：

shopify app deploy --config staging --allow-updates --message "staging deployment"

生产环境建议先创建未发布版本：

shopify app deploy --config production --no-release --message "production candidate"

确认版本无误后，再发布生产版本：

shopify app deploy --config production --allow-updates --message "production release"

不要在生产环境使用 --allow-deletes，除非已经明确确认要删除远端扩展或配置。

12. Checkout UI Extension 设置

在目标 app 的 Checkout UI Extension 配置中，把 setting app_url 设置为当前环境后端地址：

https://<public-backend-domain>

确认 extension target：

purchase.thank-you.block.render

该 target 是 Thank You Page block target，商家可在 checkout and accounts editor 控制展示位置。若改为 purchase.thank-you.header.render-after 等静态 target，需要修改 shopify.extension.toml 并重新部署 app extension。

当前 TOML 设置：

default_placement = "ORDER_STATUS1"

首次推荐位置为订单状态卡片上方；商家仍可在编辑器移动该 block。

13. 上线验收

测试订单验收：

在目标店铺完成一笔测试订单。
Thank You Page 加载 extension。
Extension 调用 /api/action/activity/check。
后端通过 Shopify checkout session token 校验。
后端读取订单、Metaobject 配置和 Dreame 状态接口。
status=true 时只推送一次 order_end。
页面展示本地化按钮。
点击按钮跳转到 Metaobject 配置的 redirect_url。
重复刷新订单完成页不会重复 push。
ActivityPushLog 和 ActivityPushIdempotency 有对应记录，且不含 api_secret 或签名明文。

14. 回滚

Shopify app 配置或扩展异常：在 Developer Dashboard 回滚到上一个 app version。
后端异常：回滚托管平台的 web app release。
第三方接口异常：临时切回 THIRD_PARTY_MODE=mock 只能用于测试环境，不允许作为生产长期方案。

15. 交付检查清单

代码测试通过：npm test
TypeScript 通过：npm run typecheck
构建通过：npm run build
Shopify config validate 通过
后端公网 URL 与 redirect URLs 一致
数据库迁移完成
Metaobject definition 和 entry 已创建
Checkout UI Extension 已部署并配置 app_url
真实测试订单通过
日志和幂等记录已核验
未提交 .env、.shopify/、个人 client_id 或个人 extension uid

参考：

Shopify CLI: https://shopify.dev/docs/api/shopify-cli
App configuration: https://shopify.dev/docs/apps/tools/cli/configuration

9.6 KiB Raw Permalink Blame History Unescape Escape