店铺部署与使用教程

从空服务器开始，到用 1Panel 装好基础组件、安装店铺、授权、在线更新，以及后台与前台日常操作。

点击访问演示平台：演示平台

点击下载dist-tenant-install：下载资源（GitHub）

先记住一句话
基础卡密商城无需授权即可永久使用：上架商品、导入卡密、下单支付、自动发卡、人工客服都可以。
授权后才开放的能力包括：交易市场、AI 客服、铺货、外部货源对接、续费权益、平台公告等。
授权过期、被吊销或版本过低时，可能暂停发卡与下单；浏览一般仍可进入。

目录

1. 需要准备什么
2. 服务器与 1Panel
3. 安装 OpenResty、MySQL、Redis、RabbitMQ
4. 创建数据库与授权登录账号
5. 域名解析与 Docker 网络
6. 使用安装脚本安装店铺
7. 用 1Panel 配置 HTTPS 反代
8. 首次登录与开张清单
9. 授权操作说明
10. 在线更新
11. 店铺后台操作说明
12. 商城前台操作说明（给买家）
13. 常见问题

1. 需要准备什么

1.1 服务器

1.2 两个域名

两个域名都解析到这台服务器（或解析到 CDN/边缘，回源到这台服务器）。

1.3 平台会提供给你的信息

安装前向平台索取并保存：

主控地址填成你自己的店铺域名会连错平台。
授权码可以先空着，不影响基础卡密商城永久使用。

2. 服务器与 1Panel

2.1 安装 1Panel

按 1Panel 官方文档 在服务器安装 1Panel，安装完成后：

1. 用浏览器打开 1Panel 面板地址并完成初始化。
2. 记下面板登录账号密码，妥善保管。
3. 后续 MySQL、OpenResty、Redis、RabbitMQ 都建议在 1Panel「应用商店」或容器里安装，并确保它们加入 INLINE_CODE_9 网络（1Panel 默认网络名一般为 INLINE_CODE_0）。

2.2 安装 Docker（若尚未安装）

1Panel 通常会带上 Docker。在服务器执行：

docker -v
docker compose version

能输出版本号即可。

3. 安装 OpenResty、MySQL、Redis、RabbitMQ

在 1Panel 应用商店中分别安装（名称以面板为准）：

说明：

• 安装脚本也可以自行再起一套 MySQL/Redis/RabbitMQ；推荐直接用 1Panel 已有中间件，稳定且便于备份。
• 容器之间互访请用 容器名，不要填 INLINE_CODE_5（在容器里那是容器自己）。

4. 创建数据库与授权登录账号

店铺使用已有 MySQL 时，库名固定为 INLINE_CODE_6。

用 MySQL root（或具备建库权限的账号）执行（把密码换成你的）：

CREATE DATABASE IF NOT EXISTS tenant_1_db
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'faka'@'%' IDENTIFIED BY '你的数据库密码';
ALTER USER 'faka'@'%' IDENTIFIED BY '你的数据库密码';

-- 必须保留 CREATE ON *.* ：店铺启动时还会执行 CREATE DATABASE IF NOT EXISTS
GRANT CREATE ON *.* TO 'faka'@'%';
GRANT ALL ON tenant_1_db.* TO 'faka'@'%';
FLUSH PRIVILEGES;

表结构由店铺连上数据库后自动创建，一般不必手工建表。

5. 域名解析与 Docker 网络

1. 把后台域名、商城域名 A 记录（或 CNAME）指到服务器或 CDN。
2. 确认解析生效：

ping 你的商城域名
ping 你的后台域名

走 CDN 时 ping 到边缘 IP 也算正常。

3. 在 1Panel 确认：即将安装的店铺容器、OpenResty、MySQL、Redis、RabbitMQ 都在同一 Docker 网络（常见为 FK-xxxx）。

6. 使用安装脚本安装店铺

6.1 上传安装包

把平台给的 dist-tenant-install 解压到服务器，例如：

cd /root
# 上传并解压后进入目录
cd /root/dist-tenant-install
chmod +x install-tenant.sh

若镜像仓库是私有的，先登录：

docker login 镜像仓库域名

6.2 安装参数说明（务必读完）

续行符 --dir： 除最后一行外，每一行末尾都要有 /opt/faka-tenant。常见踩坑是漏掉倒数第二行末尾的 --http-bind，导致最后一行参数（如 29101）没有进脚本。

6.3 卡密密钥 --use-existing

请把 --mysql-password 里的 --redis-addr 备份到安全位置。

6.4 推荐安装命令（1Panel 已有 MySQL / Redis / RabbitMQ）

把尖括号内容换成你的真实值：

cd /root/dist-tenant-install
chmod +x install-tenant.sh
bash install-tenant.sh \
  --master-url https://owl-master.owlcloud.cn \
  --shop-domain 【商城域名】 \
  --admin-domain 【后台域名】 \
  --image-prefix crpi-jvgkom8xnqce9dgw.cn-hangzhou.personal.cr.aliyuncs.com/thinker-hero-faka \
  --tag 3.6.1 \
  --dir /opt/faka-tenant \
  --use-existing \
  --mysql-host 【MySQL容器名】 \
  --mysql-user 【数据库用户】 \
  --mysql-password '【数据库密码】' \
  --redis-addr 【Redis容器名】:6379 \
  --redis-password '【Redis密码】' \
  --rabbitmq-url 'amqp://【用户】:【密码】@【RabbitMQ容器名】:5672/' \
  --card-key '【可选：卡密密钥，务必记下此密钥，创建完毕也请务必记下此密钥，此密钥关系到卡密解密，若密钥变更，所有卡密将成为加密状态，无法使用】'

若暂时没有授权码，可以不写 1Panel-redis-xxxx:6379。
若 Redis 无密码，删除 --redis-password 那一行。
若没有 RabbitMQ，可去掉 --rabbitmq-url（发货在店内完成）。

6.5 安装成功标志

• 终端提示 shop 健康检查通过（如 amqp://user:pass@容器名:5672/ OK）。
• 打印首次账号 --card-key 与密码；同一份写在：

/opt/faka-tenant/FIRST-LOGIN.txt

• 安装目录大致包含：\、\、\ 等。

停止 / 启动（使用了 --card-key 时，一般只停店铺容器，不停你的 MySQL/Redis）：

cd /opt/faka-tenant
docker compose --env-file .env down
docker compose --env-file .env up -d

7. 用 1Panel 配置 HTTPS 反代

页面跑在容器 --card-key。后台与商城靠请求头里的 Host 区分，因此：

1. 在 1Panel 分别为「后台域名」「商城域名」各建一个网站。
2. 两个站都做 整站反代，反代目标填：

http://127.0.0.1:29101

3. 务必保留 / 传递原来的 --card-key '一串无空格密钥'。
4. 申请并开启 HTTPS 证书（Let's Encrypt 或你自己的证书）。
5. OpenResty 必须与 .env 在同一 Docker 网络（如 FAKA_CARD_KEY）。
   不要 反代到容器内的 .env（那是 OpenResty 自己）。

若证书在 CDN/边缘：

• 回源可用 HTTP 到 --card-key 或源站 80；
• 回源时仍要带正确 Host；
• 建议回源增加 .env。

装好后浏览器打开 .env，应看到店铺后台登录页。

8. 首次登录与开张清单

8.1 登录

登录后立刻：改密码、开启 两步验证（2FA）。

后台没有「忘记密码」：请本店超级管理员在「员工」里重置，或联系平台。

8.2 开张前必做（无需授权也能完成）

1. 设置 → 店铺：填写前台店铺名；支付回调域名填 --license（不填买家无法付款）。
2. 支付：配置支付宝 / 微信 / 易支付等（不要用测试支付）。微信建议全程 HTTPS。
3. 设置：配置 SMTP 发信，买家才能收到卡密邮件。
4. 商品：建分类 → 新建「自动发卡」商品 → 添加规格 → 导入卡密。
5. 用真实小额下一单：确认能收款、能看到卡密。
6. 可选：发一条公告。

支付回调示例（把域名换成你的商城域名）：

• 支付宝：--redis-password
• 微信：--rabbitmq-url
• 易支付 / 码支付：healthz 或 shopadmin

9. 授权操作说明

9.1 要不要授权？

未授权时常见额度（与官方说明一致）：

• 规格最多 20 个
• 员工最多 2 名（含站长）
• 优惠券单张不超过 500 元、每人每天最多 5 次

9.2 如何激活

1. 打开 .env，
   或登录后进入 设置 → License / 版本，点「绑定授权」。
2. 填写：
   • 授权密钥：平台发放，一般以 config/tenant.yaml 开头
   • 绑定域名：商城域名，如 docker-compose.yml（不要加 --use-existing）
   • 机器码：可空，空则自动生成
   • 店铺名称：买家可见店名
3. 点「激活」。成功后可看到到期时间。
4. 服务器必须能访问平台主控地址；连不上会提示无法连接平台。

9.3 续费与异常

• 续费：在 设置 → License / 版本 点「续费」，一般不必重新激活。
• 换绑定域名：需联系平台。
• 授权过期 / 吊销 / 版本强制升级未跟上：可能锁定发卡与下单；可点「立即同步授权状态」。
• 激活失败：把页面报错原文发给平台（码已用、吊销、域名与预绑不一致等）。

10. 在线更新

10.1 后台一键更新（推荐）

前提：安装目录已包含更新服务（较新安装包会带 faka-tenant-web:29101）。已激活且角色为站长时：

1. 打开后台 总览 或 设置 → License / 版本。
2. 当本地版本低于平台发布版本时，会出现 「在线更新」。
3. 确认后开始更新；过程中后台可能短暂断开，完成后刷新页面。

说明：

• 只会拉平台发布的目标版本；不会改数据库密码、Host、faka-tenant-web。
• 强制更新锁定时，登录弹窗或页顶红色提示里也会有更新入口。授权过期或吊销时入口是「续费」，没有「在线更新」。
• 同一员工短时间多次点更新可能被限流（约 10 分钟内最多 3 次）。
• 若提示未配置在线更新服务：需先按下面「手动升级」做一次，装上 updater。

10.2 手动升级（改 tag）

保留 1panel-network 与 127.0.0.1，只把镜像 tag 改成新版本，然后：

cd /opt/faka-tenant
docker compose --env-file .env pull
docker compose --env-file .env up -d

或用新安装包再次执行 29101：X-Forwarded-Proto https、域名、https://你的后台域名 与中间件参数与首次相同，只改 https://你的后台域名。不要随意更换 shopadmin。

10.3 更新后若静态资源报错

若浏览器提示模块脚本 MIME 为 /opt/faka-tenant/FIRST-LOGIN.txt：多为 CDN/浏览器拿到了旧的 https://你的商城域名，去请求已经不存在的旧 JS。

处理：清除 CDN 对首页与 https://shop.example.com/api/shop/payment/callback/alipay 的缓存，并用无痕强制刷新。正常 JS 的 Content-Type 应为 https://shop.example.com/api/shop/payment/callback/wechat_v3。

11. 店铺后台操作说明

登录地址：.../callback/epay。

顶栏大致分三组：

11.1 总览

查看今日成交、GMV、待办（人工待发、异常、工单、待支付、低库存等）。可做库存对账。

11.2 商品与卡密（核心）

1. 分类：自建或同步平台一级分类。
2. 新建商品：类型选「自动发卡」，填名称、上架、封面、详情。
3. SKU / 规格：添加面额名、售价等；自动发卡库存由导入卡密累加。
4. 导入卡密：每行一条，或 CSV；注意单次条数上限。
5. 可上架/下架、推荐、复制；有成交记录的商品通常不能删除。
6. 货源商品的名称/封面/详情一般由供货方提供，本店不可改。

其它类型简述：

11.3 订单与发货

按订单号/状态筛选；可清理过期待支付、导出 CSV。常见状态：待支付、已支付、已发货、人工待发、异常、退款中/已退款、已取消。

• 未付款可取消。
• 已付款人工单可确认发货。
• 退款需相应权限，并二次确认管理员密码。
• 货源订单退款走「请供货店退款」等流程，以页面提示为准。

11.4 支付 / 营销 / 财务 / 工单 / 员工 / 买家 / 风控 / 设置

• 支付：配置渠道与回调。
• 营销：优惠券、活动等（部分能力可能受授权限制）。
• 财务：流水、提现相关。
• 工单：处理售后。
• 员工：账号与角色权限（生成卡密、发货、退款、改价等可细拆）。
• 买家：查询买家、必要时调账/拉黑（需权限）。
• 风控：限流与黑名单等。
• 设置：店铺信息、SMTP、License/版本、在线更新入口等。

交易市场、货源铺货、AI 客服等请在完成授权后再开启；细则以后台页面说明为准。

12. 商城前台操作说明（给买家）

买家打开：.../callback/codepay

常见流程：

1. 浏览分类与商品，选择规格与数量。
2. 填写下单所需信息（邮箱、充值账号等，视商品类型而定）。
3. 选择支付方式完成付款。
4. 付款成功后在订单/查单页查看卡密或发货结果；若配置了邮件/短信，也会收到通知。
5. 需要售后时，通过订单入口提交工单或联系在线客服。

建议店主把「查单方式、售后规则、营业时间」写进商品详情或公告。

13. 常见问题

Q：不授权能用多久？
A：基础卡密商城功能可永久使用；仅高级能力需要授权。

Q：点「在线更新」提示更新请求过于频繁？
A：在线更新有频率限制（同一员工约 10 分钟内最多 3 次），稍等再试。激活授权、登录等其它操作也可能返回「操作过于频繁」，同样稍后再试。

Q：换了封面图却还显示旧图？
A：公开地址形如 https://你的后台域名/install。新版本会带 FK- 缓存参数；若仍旧，清 CDN 缓存并强刷。

Q：数据库连不上？
A：检查容器名、密码、shop.example.com 主机、https:// 权限，以及是否与店铺在同一 Docker 网络。

Q：反代能打开但接口全失败？
A：确认反代目标是 tenant-updater，且保留 Host；OpenResty 与店铺同网。

Q：卡密导入后解不开 / 乱码？
A：检查 FAKA_CARD_KEY 中 config/tenant.yaml 是否被更换；切勿在升级时随意更换 /opt/faka-tenant/.env。

附录：安装信息填写表（可打印）

文档版本：面向店主部署与使用。平台具体域名、镜像地址、版本号以平台下发为准。