运营者指南

本指南带你从一台空服务器走到第一笔销售，然后介绍日常工作：订单、退款、余额、备份、更新。安装请预留一小时， 其中大部分时间是在等待批发账户开通和 DNS 记录生效。

其他文档：概览 · 智能体指南 · 接入指南 · 集成 · SDK

1. 你要搭建什么

            https://esim.example.com
                      │
                   Caddy (80, 443, Let's Encrypt)
      ┌───────────────┼──────────────────────────────┐
      │               │                              │
   store          rails (/agents/*)              node (/.well-known/ai-market.json, /ai-market/*)
  用户购买        智能体通过 x402 购买            枢纽发现你的套餐
      │               │
      └──── 你的 eSIM Access 余额 ────┘        付款进入你自己的钱包

• store 是网站：国家页面、付款、带二维码的订单页面。
• rails 是面向 AI 智能体的卖家节点：免费报价，付费订单走 x402。
• node 是 aimarket node。它告诉 AIMarket 枢纽你在卖什么，让智能体能找到你。等其他部分都正常后再最后启动它。
• Caddy 申请并续期 HTTPS 证书，并把请求分发给三个服务。

store 和 rails 从同一个批发账户购买。两者都不持有资金：买家付款到你的地址，套件只读取链上数据来确认款项到账。

2. 开始之前

3. 批发账户

1. 在 esimaccess.com 注册并验证邮箱。
2. 充值余额（在控制台中：余额，然后充值）。最低 50 美元。你卖出的每张 eSIM 都按批发价从这笔余额中扣除，所以它是你的库存，不是手续费。
3. 打开控制台的开发者（API）部分。那里有两个值：AccessCode 和 SecretKey。像对待密码一样对待 SecretKey。

没有沙盒：每一笔 API 订单都是真实的。两种低成本的测试方法：

• 订购最便宜的套餐（几十美分），然后取消未使用的配置文件。未使用的配置文件会退回余额。
• 首次充值之前，向客服申请少量测试额度：Customer Support，然后 Submit ticket，类型选 “Top Up”。说明你正在对接 API，需要几美元做测试订单。

4. 服务器和域名

1. 为你的域名创建 A 记录，指向服务器的 IPv4 地址。在你的电脑上检查：

dig +short esim.example.com

2. 在服务器上安装 Docker（docs.docker.com/engine/install），并确认 compose 可用：

docker compose version

3. 在服务器防火墙和云服务商面板中开放 80 和 443 端口。Let's Encrypt 在签发证书前会检查 80 端口。

5. 获取套件并配置

git clone https://github.com/alexar76/esim-operator-kit.git
cd esim-operator-kit
cp .env.example .env
nano .env

价格怎么算。 价格 = 批发价 × (1 + MARGIN_PCT/100)，但不低于批发价 + MIN_MARGIN_USD，向上取整到美分。按默认值（100% 和 1.00 美元），法国 1 GB 7 天的批发价是 0.70 美元，售价 1.70 美元。批发价 9.00 美元的 20 GB 套餐售价 18.00 美元。零售 eSIM 商店的小套餐通常要价 4 到 8 美元，所以你有空间。

只要地址。 每个 PAY_TO_* 都是你的收款地址。套件从不需要私钥或助记词。如果某份指南或某个人让你把它们放进 .env，那一定是错的。

6. 放置密钥

密钥存放在 secrets/，每个文件一个值。该目录不进 git，以只读方式挂载到容器中。用下面的方式输入，避免它们进入 shell 历史记录：

cd ~/esim-operator-kit
umask 077
printf 'AccessCode: '; read -rs v; printf %s "$v" > secrets/esimaccess_access_code; echo
printf 'SecretKey: '; read -rs v; printf %s "$v" > secrets/esimaccess_secret_key; echo
unset v

容器以用户 1000 运行，所以要把密钥文件和数据目录交给该用户：

mkdir -p data/store data/rails data/node data/caddy
sudo chown 1000:1000 secrets/*
sudo chown -R 1000:1000 data/store data/rails data/node
ls -l secrets

目录本身仍属于你，之后可以继续添加文件。每个新的密钥文件都需要同样的 sudo chown 1000:1000 和 chmod 600。

secrets/README.md 列出了所有可选文件：CDP 密钥、tonapi 和 TronGrid 密钥、Stripe 密钥。

7. 以演示模式启动

docker compose up -d --build
docker compose ps
docker compose logs --tail 30 store rails

首次构建需要几分钟。然后检查三件事：

curl -s https://esim.example.com/agents/healthz
curl -s -X POST https://esim.example.com/agents/quote -H 'content-type: application/json' \
  -d '{"country":"FR","min_gb":3,"min_days":7,"limit":3}'

• 健康检查返回 "ok":true 和套餐数量，eSIM Access 约有 1,700 个。目前出现 "demo":true 是正常的。
• 报价请求按你的价格列出真实套餐。
• https://esim.example.com/ 显示带演示横幅的店铺。打开一个国家，走一遍付款流程：每个付款步骤都会回答“演示模式：支付已关闭”。

如果健康检查返回 "ok":false，说明批发密钥错误或无法读取。见第 14 节。

检查你的价格。 下面的命令打印余额，以及任意国家按你的加价计算的最佳套餐，旁边附批发价：

docker compose exec -T rails node scripts/catalog.mjs FR ES IT US JP TH

在 .env 中修改 MARGIN_PCT 或 MIN_MARGIN_USD，然后用 docker compose up -d 生效。

8. 付款

每种方式在设置好地址（以及所需的密钥）后开启。开启你的买家常用的方式。Tron 上的 USDT 是最常见的加密货币付款方式，其次是 EVM 链上的 USDT 和 USDC，以及 TON 上的 USDT。

主动转账类付款（除免 gas 的 Base 和银行卡外的所有方式）在订单创建后的 24 小时内都会被查找。

Coinbase Developer Platform 密钥。 它为用户开启 Base 上免 gas 的 USDC，也开启智能体的 x402 订单。没有它，店铺仍可以普通转账的方式接收 Base 上的 USDC，但面向智能体的节点不接受订单。

1. 登录 portal.cdp.coinbase.com 并创建项目。
2. API Keys：创建一个 secret API key，下载它的 JSON 文件。
3. 把文件复制为 secrets/cdp_api_key.json（其中包含 id 和 privateKey），然后运行 sudo chown 1000:1000 secrets/cdp_api_key.json && sudo chmod 600 secrets/cdp_api_key.json 和 docker compose up -d。

Stripe。 在 Stripe 控制台添加 webhook 端点 https://<你的域名>/api/stripe/webhook，事件选 checkout.session.completed 和 checkout.session.async_payment_succeeded。把私钥（sk_live_…）放进 secrets/stripe_secret_key，把端点的签名密钥（whsec_…）放进 secrets/stripe_webhook_secret。

频率限制。 公共的 TronGrid、tonapi 和 RPC 端点足够小店使用。销售稳定后，添加免费的 TronGrid 密钥和 tonapi 密钥，并把 EVM_RPC_<id> 和 SOLANA_RPC 指向你自己的服务商。

9. 智能体与联邦

rails 节点已经在 https://<你的域名>/agents/ 为智能体提供服务。要让智能体在枢纽上搜索时找到你，需要向联邦描述你的节点并发布公告。

1. 根据实时目录生成 node.toml。填入你自己的名称、域名和 PRODUCT_ID：

docker compose exec -T rails node scripts/node-toml.mjs \
  --name "My Travel eSIM" --url https://esim.example.com \
  --product esim-mytravel --upstream http://rails:9490 > node.toml
head -20 node.toml

2. 启动节点：

docker compose --profile federation up -d --build node
curl -s https://esim.example.com/.well-known/ai-market.json | head -c 400; echo

3. 用枢纽的方式检查它，然后发布公告：

docker compose exec node aimarket doctor --url https://esim.example.com
docker compose exec node aimarket node knock --config /node/node.toml --hub https://modelmarket.dev

在收录你之前，枢纽会用一个真实国家调用 esim.quote。收录后，在枢纽上搜索 “eSIM France” 的智能体就会得到你的套餐。付款从不经过枢纽：智能体通过 x402 直接付款到你节点对应的钱包。

data/node/ 存放节点的签名密钥，也就是它在联邦中的身份。请备份。目录新增国家后，重新执行第 1 步。

10. 测试订单，然后正式上线

1. 在 .env 中设置 DEMO_MODE=0，并逐字符再次核对 PAY_TO_* 地址。
2. 生效：

docker compose up -d
curl -s https://esim.example.com/agents/healthz

应显示 "demo":false。设置了 CDP 密钥和 PAY_TO_EVM 后会显示 "paid_orders":true。

3. 在你自己的店铺，用你自己的钱包，在你预计买家最常用的网络上，购买某个国家最便宜的套餐。订单页面应在一分钟内显示二维码。
4. 在钱包中核对付款，在 eSIM Access 控制台中核对订单。
5. 如果你不想保留这张 eSIM，在 eSIM Access 控制台取消未使用的配置文件。批发价会退回余额。你付的钱本来就进了你自己的钱包。

对每个已开启的网络都这样做一遍。然后你就正式上线了。

11. 日常工作

订单。 店铺把订单保存在 data/store/orders.json。列出需要你处理的订单：

sudo jq -r '.[] | select(.status=="refund_due" or .status=="underpaid")
  | [.created_at, .id, .status, .method, (.price_cents/100), .payment.ref, (.payment.payer // "-"), (.error // "")] | @tsv' \
  data/store/orders.json

买家会写信到 STORE_CONTACT。向他们索要页面地址中的订单号（/o/<订单号>）。不要索要完整链接：里面有他们的令牌。

余额。 让批发余额保持在几天销量以上。余额不足以支付订单时，付款页会显示“该套餐暂时不可用”，而不会收款。用下面的命令查看余额：

docker compose exec -T rails node scripts/catalog.mjs | head -1

日志。

docker compose logs -f --tail 100 store rails

日志中从不包含激活码或密钥。

备份。 每天把 data/ 和 secrets/ 备份到服务器以外的地方：

• data/store/：订单。丢失后买家的订单页面将无法使用。
• data/rails/：智能体的订单、其状态令牌的密钥，以及节点的签名密钥。
• data/node/：联邦身份。
• data/caddy/：证书。可以重新签发，但备份能避免触发 Let's Encrypt 的限额。

更新。

git pull
docker compose up -d --build
docker compose --profile federation up -d --build node    # 如果你运行联邦节点

在更新正在销售的店铺之前，先阅读版本说明。

12. 智能体的订单

智能体通过 POST /agents/order 购买（见智能体指南）。节点验证 x402 付款、购买配置文件，并且只在配置文件创建后才结算。如果结算失败，节点会取消配置文件，批发价退回你的余额。智能体的订单记录在 data/rails/orders.json 中，不含激活码。USDC 会到达你在 Base 上的 PAY_TO_EVM。

13. 法律、税务和条款

以下不构成法律或税务建议。开始销售前，请咨询你所在国家的会计师。

• 卖家是你。 买家向你购买，适用你的条款。eSIM Access 是你的供应商。退款、客服和税务都由你负责。
• 条款和隐私。 eSIM Access 要求你的网站公布销售条款和隐私政策。设置 STORE_TERMS_URL 和 STORE_PRIVACY_URL。条款应涵盖退款（已安装的 eSIM 通常不能退款）、设备兼容性（支持 eSIM 且未锁网的手机）以及有效期何时开始。
• 欧盟增值税。 向消费者销售的电信服务在买家所在国征税。一站式申报（OSS）可以用一份申报覆盖所有欧盟国家。欧盟以外规则不同。
• 加密货币。 能否接受加密货币以及如何记账，取决于你所在的国家。请保留订单记录：店铺记录了每笔付款的网络、交易和金额。
• 个人数据。 店铺不向买家索取任何信息：没有姓名，没有邮箱。它保存订单（套餐、价格、付款方式）和付款（交易及付款方地址）。根据 GDPR，区块链地址仍可能属于个人数据，请在隐私政策中说明。

14. 故障排查