部署指南（文档站与 Web 扫码应用）

本仓库包含两个静态 Web 工程，既可合并发布到同一 Forgejo Pages 站点，也支持将 Web 扫码器独立部署到自定义 HTTPS 服务器：

项目文档站（apps/docs/）：基于 Astro + Starlight 构建的中文产品与集成文档站点，发布于站点根路径 https://iroh-pairing.gjz010.page/。
手机 Web 扫码介绍应用与 PWA（apps/connector-web/）：基于 SolidJS + Vite + connector-core WASM 的静态扫码器，发布于同一 Pages 站点的子路径 https://iroh-pairing.gjz010.page/pair/，同时也支持独立根路径部署。

路径与 --connector-url 规范说明：

站点根路径 https://iroh-pairing.gjz010.page/ 为技术文档，子路径 https://iroh-pairing.gjz010.page/pair/ 为官方 Web 扫码器与 PWA（访问 /pair 或 /pair#<envelope> 会跳转至 /pair/ 并在首屏同步捕获并清除 URL fragment）。

Wire 协议与 CLI 参数规范保持不变：pair-demo invite --connector-url（及 Session::invite_url）的规范值仍必须为无尾斜杠的 https://iroh-pairing.gjz010.page/pair。

1. 同一 Forgejo Pages 站点发布架构（`apps/docs/` + `/pair/`）

1.1 阅读域名、扫码器子路径与 Pages 部署端点区分

在 Forgejo Pages 架构中，读者与手机访问的公开 URL 与 CI 上传静态产物的部署端点职责不同：

用途	URL	说明
公开文档阅读域名（Reader Site）	`https://iroh-pairing.gjz010.page/`	面向读者的文档站点根路径（配置于 `apps/docs/astro.config.mjs` 的 `site` 字段，用于生成 canonical 链接与 sitemap）
官方 Web 扫码器 / PWA 子路径	`https://iroh-pairing.gjz010.page/pair/`	合并到文档构建产物 `apps/docs/dist/pair/` 下的官方 `connector-web` 应用（CLI `--connector-url` 仍传无尾斜杠的 `https://iroh-pairing.gjz010.page/pair`）
Pages 部署上传端点（Deploy Endpoint）	`https://pages.gjz010.com/deploy/gjz010/iroh-pairing/`	仅供 CI 工作流中 `git-pages/action@v2` 推送静态构建目录 `apps/docs/dist` 的上传接口，不是供浏览器直接阅读的页面

1.2 构建产物目录与合并流程

两个前端工作区均复用 apps/connector-web/.yarn/releases/yarn-4.10.3.cjs 固定版本的 Yarn Berry 启动器：

Web 扫码器双构建目标（apps/connector-web/）：
- 常规根路径构建（build）：输出到 apps/connector-web/dist/，适用于独立域名根路径部署。
- Pages 子路径与 PWA 构建（build:pages）：输出到 apps/connector-web/dist-pages/，面向 /pair/ 子路径托管并包含 PWA 静态缓存配置。
文档站构建与 /pair 合并（apps/docs/）：
- build 脚本依次执行 node scripts/sync-assets.mjs（同步 assets/icon.svg 与 docs/media/*）、astro check、astro build 与 node scripts/verify-build.mjs（校验 9 个文档页、5 个媒体文件、Pagefind 索引、零死链，并确保文档站自身未占用保留的 /pair/ 路径），输出至 apps/docs/dist/。
- merge:pair 脚本（node scripts/merge-pair.mjs --source ../connector-web/dist-pages）将构建好的 dist-pages 显式合并到 apps/docs/dist/pair/。

在本地执行文档构建与合并的参考命令（具体脚本参数以各 package.json 最终定稿为准）：

# 1. 构建并校验 Astro + Starlight 文档站（输出至 apps/docs/dist/）
cd apps/docs
node ../connector-web/.yarn/releases/yarn-4.10.3.cjs install --immutable
node ../connector-web/.yarn/releases/yarn-4.10.3.cjs build

# 2. 当 apps/connector-web 已完成 build:pages（输出至 apps/connector-web/dist-pages/）后，合入 /pair/：
node ../connector-web/.yarn/releases/yarn-4.10.3.cjs merge:pair --source ../connector-web/dist-pages

1.3 Forgejo Actions 自动发布工作流

仓库中的 .forgejo/workflows/publish-docs.yaml 负责在 main 分支更新时构建静态产物并发布到 Forgejo Pages（完整的 CI Rust/WASM 编译与 merge:pair 步骤以工作流及 package.json 最终定稿为准）：

- name: Install dependencies
  working-directory: apps/docs
  run: node ../connector-web/.yarn/releases/yarn-4.10.3.cjs install --immutable

- name: Build documentation
  working-directory: apps/docs
  run: node ../connector-web/.yarn/releases/yarn-4.10.3.cjs build

- name: Publish to Forgejo Pages
  uses: https://codeberg.org/git-pages/action@v2
  with:
    site: https://pages.gjz010.com/deploy/gjz010/iroh-pairing/
    token: ${{ forgejo.token }}
    source: apps/docs/dist

无需配置 PAT 或额外 Secret：工作流直接使用 Forgejo Actions 内置的 ${{ forgejo.token }} 向 https://pages.gjz010.com/deploy/gjz010/iroh-pairing/ 认证并推送 apps/docs/dist 目录，无需在仓库或组织中配置个人访问令牌（PAT）或外部部署密钥。

2. PWA 行为边界与独立部署指南（`apps/connector-web/`）

2.1 PWA 主屏安装与静态缓存说明

connector-web 支持作为 PWA 安装到手机或桌面主屏幕，其行为边界固定如下：

仅缓存静态壳与 WASM：Service Worker 只缓存应用静态界面文件与 .wasm 产物，使应用在离线时仍能打开主界面。
浏览器配对仍需可达 Relay：由于浏览器环境运行于 browser_relay 模式，离线打开界面并不解除网络依赖，执行实际配对仍必须连接可达的 iroh relay（默认支持官方 N0 relay，或使用设置弹窗中配置的自定义 HTTPS relay）。
不缓存敏感状态、无后台动作：PWA 不缓存任何邀请、SAS 或配对会话状态，不支持后台配对或 Web Push 推送，也不会在活跃配对进行期间自动刷新页面。

2.2 独立部署到自有 HTTPS 站点

除使用官方发布的 https://iroh-pairing.gjz010.page/pair/ 外，如果你希望将 connector-web 独立部署到自己的域名（例如配合 pair-demo invite --connector-url https://pair.example.com/pair），可在 apps/connector-web/ 下执行常规构建：

cd apps/connector-web
node .yarn/releases/yarn-4.10.3.cjs install --immutable
node .yarn/releases/yarn-4.10.3.cjs build

构建输出的 apps/connector-web/dist/ 为纯静态产物，部署到自有服务器时需满足以下要求：

必须启用 HTTPS：移动端浏览器要求在 HTTPS 安全上下文下才允许调用 navigator.mediaDevices.getUserMedia 开启摄像头（仅本机开发环回 http://localhost / 127.0.0.1 / [::1] 例外）。
配置 /pair 路由 Fallback（或子目录托管）：当浏览器访问 https://pair.example.com/pair#<base64url-envelope> 时，服务器需将 /pair 路由回退到 index.html（或指向 /pair/index.html）。页面加载时，首个同步内联脚本会在任何模块或网络请求执行前读取 #<envelope> 并立即通过 history.replaceState 清除地址栏中的 hash。
MIME 类型与压缩：确保服务器对 .wasm 返回 Content-Type: application/wasm，并开启 Brotli 或 Gzip 压缩。

Nginx 独立站点配置示例：

server {
    listen 443 ssl http2;
    server_name pair.example.com;

    root /var/www/connector-web/dist;
    index index.html;

    include mime.types;
    types {
        application/wasm wasm;
    }

    gzip on;
    gzip_types text/css application/javascript application/wasm image/svg+xml;

    location = /pair {
        try_files /index.html =404;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Caddy 独立站点配置示例：

pair.example.com {
    root * /var/www/connector-web/dist
    encode zstd gzip
    try_files {path} /index.html
    file_server
}