tauri-client/README.md

# TauriClient 打包与目录说明

## 1. 打包命令流程

推荐使用双容器模式（默认）同时产出 `amd64` 和 `arm64`：

```bash
cd /path/to/TauriClient
chmod +x ./scripts/docker/run-build.sh
./scripts/docker/run-build.sh
```

> 默认会在打包结束后自动执行：
> 1) `scripts/inject-deb-bootstrap.sh`（向 deb 注入 `postinst`，安装时自动写源与公钥）  
> 2) `scripts/build-apt-repo.sh`（生成可直接部署的 `dist/repo/`）  
> 3) `scripts/verify-apt-repo.sh`（发布前完整性自检）

只打指定项目：

```bash
./scripts/docker/run-build.sh call-client
./scripts/docker/run-build.sh broadcast-client
```

可选模式：

- 默认（双容器）：`./scripts/docker/run-build.sh`
  - 容器 #1 构建 `amd64`
  - 容器 #2 构建 `arm64`
- 混合模式：`./scripts/docker/run-build.sh --hybrid`
  - 宿主机构建 `amd64`
  - 容器构建 `arm64`
- 若仅需 `.deb` 不生成仓库目录：`GENERATE_APT_REPO=0 ./scripts/docker/run-build.sh`
- 默认使用签名 Key：`com.jgzy.product`（密钥缺失时会自动创建）
- 如需禁用自动创建密钥：`APT_GPG_AUTO_CREATE=0 ./scripts/docker/run-build.sh`
- 如需跳过 deb 自动初始化注入：`INJECT_DEB_BOOTSTRAP=0 ./scripts/docker/run-build.sh`
- 默认会在生成仓库后自动自检（`verify-apt-repo.sh`）；如需跳过：`VERIFY_APT_REPO=0 ./scripts/docker/run-build.sh`

## 2. 打包产物位置

统一产物目录：

- `dist/linux-deb/call-client/amd64/*.deb`
- `dist/linux-deb/call-client/arm64/*.deb`
- `dist/linux-deb/broadcast-client/amd64/*.deb`
- `dist/linux-deb/broadcast-client/arm64/*.deb`

自动生成的 APT 仓库目录（可直接打包上传仓库机）：

- `dist/repo/dists/v10/...`
- `dist/repo/pool/main/...`

Tauri 原始输出目录：

- `call-client/src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/deb/`
- `call-client/src-tauri/target/aarch64-unknown-linux-gnu/release/bundle/deb/`
- `broadcast-client/src-tauri/target/x86_64-unknown-linux-gnu/release/bundle/deb/`
- `broadcast-client/src-tauri/target/aarch64-unknown-linux-gnu/release/bundle/deb/`

## 3. 配置文件目录与日志目录

以下与各自 `src-tauri/tauri.conf.json` 里的 **`bundle.identifier`** 一致（当前为 `com.ziyun.callclient`、`com.ziyun.broadcastclient`）。若改过 identifier，中间目录名会随之变化。

**路径中的用户名**：下文以 Linux 用户 `alice`、Windows 用户 `Alice` 为例；请把 `alice` / `Alice` 换成本机实际登录名（Linux 一般为 `/home/<登录名>` 中的 `<登录名>`；Windows 一般为 `C:\Users\<登录名>` 中的 `<登录名>`）。

### 3.1 call-client

Bundle ID：`com.ziyun.callclient`。

**默认环境（未设置 `XDG_CONFIG_HOME`、`XDG_DATA_HOME`）**

| 用途 | Linux 完整路径示例 | Windows 完整路径示例 |
|------|----------------------|----------------------|
| 应用配置 | `/home/alice/.config/com.ziyun.callclient/config.json` | `C:\Users\Alice\AppData\Roaming\com.ziyun.callclient\config.json` |
| 主程序日志 | `/home/alice/.config/com.ziyun.callclient/app.log`（轮转文件形如 `/home/alice/.config/com.ziyun.callclient/app-20260513120000.log`） | `C:\Users\Alice\AppData\Roaming\com.ziyun.callclient\app.log`（同级目录下 `app-*.log`） |
| 运行时会话（多窗口共享） | `/home/alice/.local/share/com.ziyun.callclient/runtime_session.json` | `C:\Users\Alice\AppData\Local\com.ziyun.callclient\runtime_session.json` |
| 单实例锁 | `/home/alice/.local/share/com.ziyun.callclient/single-instance.lock` | `C:\Users\Alice\AppData\Local\com.ziyun.callclient\single-instance.lock` |

**若设置了 XDG 环境变量（Linux）**

- 当 `XDG_CONFIG_HOME` 为 `/data/my-config` 时，配置文件与 `app.log` 在：  
  `/data/my-config/com.ziyun.callclient/config.json`  
  `/data/my-config/com.ziyun.callclient/app.log`
- 当 `XDG_DATA_HOME` 为 `/data/my-data` 时，`runtime_session.json` 与 `single-instance.lock` 在：  
  `/data/my-data/com.ziyun.callclient/runtime_session.json`  
  `/data/my-data/com.ziyun.callclient/single-instance.lock`

实现依据：`call-client/src-tauri/src/commands/config.rs`、`logger.rs`、`session.rs`。

> 旧版本若使用独立目录名 `call-client` 或日志放在 `local/state` 等路径，已废弃；当前统一为上述 `com.ziyun.callclient` 目录。

### 3.2 broadcast-client

Bundle ID：`com.ziyun.broadcastclient`。

**默认环境（未设置 `XDG_CONFIG_HOME`）**

| 用途 | Linux 完整路径示例 | Windows 完整路径示例 |
|------|----------------------|----------------------|
| 持久化配置 | `/home/alice/.config/com.ziyun.broadcastclient/broadcast-config.json` | `C:\Users\Alice\AppData\Roaming\com.ziyun.broadcastclient\broadcast-config.json` |
| Socket 服务日志（文件名含时间戳） | `/home/alice/.config/com.ziyun.broadcastclient/socket-service-20260513-120000-000.log` | `C:\Users\Alice\AppData\Roaming\com.ziyun.broadcastclient\socket-service-20260513-120000-000.log` |

**若 `XDG_CONFIG_HOME` 为 `/data/my-config`（Linux）**

- `/data/my-config/com.ziyun.broadcastclient/broadcast-config.json`
- `/data/my-config/com.ziyun.broadcastclient/socket-service-<时间戳>.log`

**浏览器侧回退**（`localStorage` 键名，非磁盘路径）：`runtime_broadcast_config`、`broadcast_config_local_fallback`。

实现依据：`broadcast-client/src/services/configStore.ts`、`broadcast-client/src-tauri/src/lib.rs`。

> 旧版本若使用 `broadcast-client` 作为配置目录名，已废弃；当前为 `com.ziyun.broadcastclient`。

### 3.3 两个项目仓库内 Tauri 打包配置（源码路径）

- `call-client/src-tauri/tauri.conf.json`
- `broadcast-client/src-tauri/tauri.conf.json`

## 4. 应用图标（bundle）

### 推荐：`tauri icon`（`@tauri-apps/cli` 内置，社区常用）

Tauri 官方 CLI 提供 **`tauri icon`**：用**一张**高质量源图生成各平台所需尺寸（`32x32.png`、`128x128.png`、`icon.ico` 等）。部分环境下 **`tauri.conf.json` 的 `bundle.icon` 不会自动改写**，若发现未更新，请确认其中包含上述生成文件（本仓库已按生成结果维护默认列表）。

**源图要求：** 正方形 **PNG**，建议 **1024×1024**，**RGBA**（带透明）。可先用 Photoshop / Figma 导出一张再执行下面命令。

在各子项目根目录执行：

```bash
# call-client（默认源图：src-tauri/icons/call_icon.png）
cd call-client
npm run icons:generate
```

```bash
# broadcast-client（默认源图：src-tauri/icons/bc_icon.png）
cd broadcast-client
npm run icons:generate
```

等价命令：

```bash
npm run tauri -- icon ./src-tauri/icons/call_icon.png
# 或 broadcast-client 下对 bc_icon.png
```

生成结果会写入各项目 `src-tauri/icons/`。若 **`bundle.icon` 未自动更新**，请对照目录里新生成的 `32x32.png`、`128x128.png`、`128x128@2x.png`、`icon.icns`、`icon.ico`、`icon.png` 检查配置。换源图路径可改对应 `package.json` 里的 **`icons:generate`** 脚本。

### 说明

- 这里使用的是 **`@tauri-apps/cli` 自带的 `icon` 子命令**，无需再装名为 `tauri-icon` 的独立包；若文档里写作「tauri-icon 工具」，一般即指该命令。
- 源图若不是 RGBA，构建阶段仍可能报 `icon ... is not RGBA`，请在上游导出时勾选透明度。

## 5. Windows Nginx + 内网 APT 仓库（麒麟 V10）模板

以下模板用于“客户端检查更新 + 引导 apt 升级”，适用于 `call-client` 与 `broadcast-client`。

### 5.1 仓库目录模板

```text
repo/
├─ dists/
│  └─ v10/
│     ├─ InRelease
│     ├─ Release
│     ├─ Release.gpg
│     └─ main/
│        ├─ binary-amd64/
│        │  ├─ Packages
│        │  └─ Packages.gz
│        └─ binary-arm64/
│           ├─ Packages
│           └─ Packages.gz
└─ pool/
   └─ main/
      ├─ c/call-client/call-client_<version>_amd64.deb
      ├─ c/call-client/call-client_<version>_arm64.deb
      ├─ b/broadcast-client/broadcast-client_<version>_amd64.deb
      └─ b/broadcast-client/broadcast-client_<version>_arm64.deb
```

### 5.2 发布步骤（每次发版）

由于仓库机是内网且不安装构建环境，统一在**发布机器**执行：

```bash
cd /path/to/TauriClient
chmod +x ./scripts/docker/run-build.sh ./scripts/build-apt-repo.sh ./scripts/inject-deb-bootstrap.sh ./scripts/verify-apt-repo.sh
./scripts/docker/run-build.sh
```

执行完成后会得到：

- `dist/linux-deb/...`：原始构建产物 `.deb`
- `dist/repo/...`：可直接部署到仓库机的 APT 仓库目录（含索引与签名）
- `dist/repo/zyyun-archive-keyring.asc`：客户端导入用 ASCII 公钥
- `dist/repo/zyyun-archive-keyring.gpg`：客户端可直接使用的 keyring 二进制公钥

最后只需把 `dist/repo` 整体打包上传到仓库机并对外提供 `http://80.12.140.29:80/apt`。

> 脚本内置的签名密钥生成命令如下（密钥不存在且 `APT_GPG_AUTO_CREATE=1` 时自动执行）：  
> `gpg --batch --pinentry-mode loopback --passphrase "" --quick-gen-key "com.jgzy.product" rsa4096 sign 5y`

手工初始化（仅在未使用 deb 自动初始化时作为兜底）：

```bash
curl -fsSL http://80.12.140.29:80/apt/zyyun-archive-keyring.asc | sudo gpg --dearmor -o /usr/share/keyrings/zyyun-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/zyyun-archive-keyring.gpg] http://80.12.140.29:80/apt v10 main" | sudo tee /etc/apt/sources.list.d/zyyun.list
sudo apt update
```

发布后可手工复核（脚本已在 `run-build.sh` 里自动执行一次）：

```bash
bash ./scripts/verify-apt-repo.sh
```

该脚本会校验以下关键项：

- `InRelease`、`Release`、`Release.gpg`
- 公钥文件 `zyyun-archive-keyring.asc`、`zyyun-archive-keyring.gpg`
- 各架构 `Packages.gz` 是否存在且可正常解压
- `pool/main` 下是否存在 `.deb` 包

#### 5.2.1 deb 自动初始化（已默认启用）

`run-build.sh` 默认会调用 `scripts/inject-deb-bootstrap.sh`，对构建出的 deb 注入 `postinst` 与内置公钥。  
用户只需执行 deb 安装（图形安装器或 `dpkg -i`），安装阶段会自动：

1. 安装公钥到 `/usr/share/keyrings/zyyun-archive-keyring.gpg`
2. 写入源文件 `/etc/apt/sources.list.d/zyyun.list`
3. 执行 `apt-get update`（失败不阻断安装）

内置源固定为：

```bash
deb [signed-by=/usr/share/keyrings/zyyun-archive-keyring.gpg] http://80.12.140.29:80/apt v10 main
```

发版前可快速确认某个包已注入 bootstrap：

```bash
bash ./scripts/verify-deb-bootstrap.sh dist/linux-deb/call-client/amd64/*.deb
```

或校验全部 deb：

```bash
bash ./scripts/verify-deb-bootstrap.sh --all
```

### 5.3 Windows Nginx 本地目录直读模板

```nginx
server {
  listen 80;
  server_name 80.12.140.29;

  location /apt/ {
    alias F:/workspace/zyclient_linux/TauriClient/dist/repo/;
    autoindex on;
  }
}
```

路径映射关系：

- `http://80.12.140.29:80/apt/dists/v10/Release`
- 对应本地文件 `F:/workspace/zyclient_linux/TauriClient/dist/repo/dists/v10/Release`

客户端源配置示例：

```bash
deb [arch=amd64 signed-by=/usr/share/keyrings/zyyun-archive-keyring.gpg] http://80.12.140.29:80/apt v10 main
```

### 5.3.1 方案二：80 端口被其他服务占用时

如果 `80.12.140.29:80` 已由 IIS / Apache / 其他网关占用，推荐做法是：

1. 保持现有 80 入口不变（外部地址仍为 `http://80.12.140.29:80/apt`）。
2. 让 Nginx 改为监听本机其他端口（例如 `127.0.0.1:8080`）。
3. 由现有 80 入口服务将 `/apt/` 路径反向代理到 `http://127.0.0.1:8080/apt/`。

Nginx（仓库中转）示例：

```nginx
server {
  listen 127.0.0.1:8080;
  server_name localhost;

  location /apt/ {
    alias F:/workspace/zyclient_linux/TauriClient/dist/repo/;
    autoindex on;
  }
}
```

80 入口服务需要保证：

- 对外保留路径 `/apt/`。
- 不对 `dists/`、`pool/`、`Packages.gz`、`InRelease` 做重写或鉴权跳转。
- 转发后客户端源配置保持不变：
  - `deb [arch=amd64 signed-by=/usr/share/keyrings/zyyun-archive-keyring.gpg] http://80.12.140.29:80/apt v10 main`

### 5.4 客户端交互建议

- “检查更新”按钮只做检测与引导，不在应用内直接执行 `sudo`。
- 检测成功有新版本时，提示并复制命令：
  - `sudo apt update && sudo apt install --only-upgrade call-client`
  - `sudo apt update && sudo apt install --only-upgrade broadcast-client`