应用商城上架教程

1. 发布前准备

先完成签名与打包，在模拟器和目标真机验证安装、启动、退出、权限拒绝和升级。准备应用名称、简介、详细说明、分类、图标、实际截图与更新说明。

正式版本使用自己长期维护的 P-256 密钥。App ID、publisher lineage root 和 release sequence 决定更新身份；不能用商城表单修正签名包里错误的身份。

2. 注册与登录

进入 PXA 应用商城，注册或登录开发者账号，再进入开发者后台。按当前页面完成邮箱或 GitHub 登录流程；登录方式由商城配置决定。

3. 登记发布者身份

商城要求发布者公钥完成持有证明，否则上传会返回“签名公钥尚未登记或已撤销”。目前使用已登录会话和 CSRF token 调用两个接口，下面给出完整操作步骤。流程只上传公钥和签名证明，私钥始终留在本机。

获取挑战

在已登录的商城后台页面打开浏览器开发者工具的 Console，执行下面代码。它会从当前页面读取 CSRF 字段，用当前登录会话申请挑战：

var csrf = document.querySelector('input[name="csrf"]').value;
var response = await fetch('/api/v2/publisher-keys/challenge', {
  method: 'POST',
  headers: { 'X-CSRF-Token': csrf }
});
if (!response.ok) throw new Error(await response.text());
var challenge = await response.json();
console.log(challenge);

返回 challenge 和 domain。复制 challenge 字符串，在 10 分钟内完成登记；挑战使用一次后失效。此代码要在 app.doit.am 的已登录后台运行，不是在本官网页面运行。

本地生成签名证明

下载本站的公钥证明脚本，保存为 local/publisher-proof.py。可先查看脚本，它只在本地读密钥、签名并打印证明，不会发起网络请求。

python -m pip install cryptography
python local/publisher-proof.py local/keys/publisher-private.pem

粘贴刚取得的 challenge。脚本输出 JSON，包含 challenge、Base64 DER SPKI 公钥 publisher_spki 和 Base64 P1363 签名 signature。

实现细节：待签名字节为 PXA-STORE-PUBLISHER-KEY、一个 NUL 字节和 challenge 的 UTF-8 字节，使用 ECDSA P-256 / SHA-256。签名是 32 字节 r 加 32 字节 s，不能直接提交 OpenSSL 的 DER 签名字节。

提交证明

回到同一个后台 Console，将下面空对象替换为脚本输出的完整 JSON，然后执行：

var proof = {}; // 替换为本地脚本输出的 JSON
var result = await fetch('/api/v2/publisher-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': document.querySelector('input[name="csrf"]').value
  },
  body: JSON.stringify(proof)
});
if (!result.ok) throw new Error(await result.text());
console.log(await result.json());

预期返回 key_id 和 status: "verified"。若挑战过期，重新获取并重新签名；若提示公钥属于其他开发者，应使用正确账号或自己的密钥。401/403 时检查登录状态和 CSRF，刷新后台页面后重新开始。接口参考见商城 API 文档。

4. 创建应用并上传图片

在后台创建应用，填写标识、名称、简介、详细介绍、应用 / 游戏类型和对应分类。保持应用标识与签名包身份一致。

上传 PNG、JPEG 或 WebP 图标和截图。图标会裁剪为 512×512，截图保留比例且最长边缩放至 1920 像素；文件大小和数量上限以页面显示为准。图片需要直接上传到商城，不能只填外部 URL。

截图可用 pxadb screenshot screenshot.png --port /dev/ttyACM0 获取，选择能够真实说明功能的页面。

5. 上传 .pxa 并提交审核

打开应用详情中的“上传新版本”，选择 .pxa 容器并填写更新说明，然后点击“提交审核”。选择 PXA 后，版本、平台和兼容性由服务端从已签名 manifest 读取。

服务器核对容器与清单双签名、发布者和 lineage、release sequence、组件、制品、服务与权限。上传成功后检查“PXA 已验证兼容性”和版本记录，确认目标架构、运行时 ABI 与权限符合预期。

6. 多平台版本

设备按目标选择下载包时，分别构建单目标包，并保持 App ID、version、sequence、lineage root 和当前发布者密钥一致：

tools/app.sh build hello --source-root local/my-apps --target esp32s3 --output local/app-output/s3
tools/app.sh build hello --source-root local/my-apps --target esp32s31 --output local/app-output/s31

在同一应用中依次上传 s3/pxa-hello.pxa 与 s31/pxa-hello.pxa。同 sequence 的不同目标包会合并到同一个待审版本，同目标重传替换该目标包。已完成审核的 sequence 不能复用；后续版本提高 sequence 后重新构建。

7. 审核与公开验证

应用资料审核与版本审核分别进行，且应用不能处于下架状态。已上架后修改名称、介绍或图片，会暂停公开入口并进入资料审核，审核通过后恢复。

上架后再用目标设备确认目录可见、包可安装与更新可用。签名有效不等于目标设备具备应用所需服务，仍需核对设备 Profile 与产品策略。

8. 后续更新

保留相同应用身份，修改 version 并提高 release_sequence，用相同密钥或有效 lineage 签名，重复构建、测试和审核。保存原始源码、构建环境、制品摘要和 provenance，方便追溯问题。

不要把短时下载票据写死进文档或 App。商城在实际下载时提供带有效期的地址；需要设备集成时使用 /api/v2 的签名目录与下载票据流程。