# 更新说明 UPDATE.md

## 一、最终用户：客户端自更新

1. 打开打印组件
2. **模块与更新** Tab → **检查更新** / **一键更新**  
   或菜单 **帮助 → 检查更新**
3. 更新源默认：`https://py99999.com/print-update`  
   配置文件：`%LocalAppData%\PrintComponent\update-config.json`

从 **v1.2.0** 起，更新清单同时包含 `host` 主程序包：

- 模块更新：安装到 `%LocalAppData%\PrintComponent\modules\`
- 主程序更新：下载并校验完整包 → 退出程序 → 覆盖安装目录 → 自动重启
- 若安装目录需要管理员权限，更新器会弹出 Windows UAC
- 失败日志：`%LocalAppData%\PrintComponent\update-staging\host-update.log`

> v1.1.0 及更早版本本身没有宿主自更新代码，因此需最后手工安装一次 v1.2.0；以后主界面改动即可在线更新。

多机：同一更新中心可看「多机在线状态」（心跳）。

## 二、开发者：如何发一个新版本

### 1. 打包

在开发机：

```powershell
cd "D:\源码\LABEL MATRIX 条形码标签软件"
.\tools\pack-release.ps1 -Version 1.0.2
```

产物大致在 `publish\release\`：

- `PrintComponent-Setup-{ver}.zip` — 完整安装包
- `packages\*.zip` — 各模块包
- `manifest.json` — 更新清单

### 2. 部署到服务器

```powershell
$env:PY_DEPLOY_PASS = "<勿写入仓库>"
.\tools\deploy-release.ps1 -Version 1.0.2
```

脚本会：

1. 上传下载页 `web/print-component/` → `/www/wwwroot/py99999/print-component/`
2. 上传安装包 → `/www/wwwroot/py99999/download/print-component/`
3. 同步 `manifest.json` + packages → `/opt/print-component-update/data/`
4. 必要时重启 `print-update` 服务

### 3. 同步 AI 文档与源码快照

```powershell
.\tools\deploy-dev-docs.ps1
```

目标：`/www/wwwroot/py99999/print-component/dev/`  
公开：https://py99999.com/print-component/dev/

## 三、只更新某一个模块

1. 修改对应 Module 项目版本号与功能
2. `pack-release.ps1`（会带上全部模块；客户端按 manifest 差分）
3. `deploy-release.ps1`
4. 用户端检查更新即可，无需重装整包（视模块热替换实现）

当前模块：

| id | 说明 |
|----|------|
| host | 宿主壳（完整主程序包，可自更新） |
| printing | 打印引擎 |
| labelmatrix | LABEL MATRIX 适配 |
| customarea | 独立自定义区 |

## 四、更新中心运维

机群读取接口 `/api/machines*` 需要管理 Token。服务端通过环境变量配置：

```bash
PRINT_COMPONENT_FLEET_ADMIN_TOKEN="<至少 32 位随机值>"
```

需要查看机群的受控客户端可在本机 `update-config.json` 配置 `FleetAdminToken`；普通打印客户端无需配置，心跳和检查更新不受影响。

```bash
# SSH 到 42.193.144.48
systemctl status print-update
systemctl restart print-update
journalctl -u print-update -n 80 --no-pager

# 本机探测
curl -s http://127.0.0.1:17890/health

# 外网（经 Nginx）
curl -sI https://py99999.com/print-update/health
```

部署目录：`/opt/print-component-update`  
数据：`/opt/print-component-update/data/manifest.json`、`data/packages/`

> `deploy-release.ps1` 与 `deploy-dev-docs.ps1` 不再包含密码回退；运行前必须设置 `PY_DEPLOY_PASS`。已暴露过的服务器密码必须轮换，不能继续使用。

## 五、Nginx 要点

外网不要依赖裸端口 17890（安全组可能未放行）。  
客户端应使用：`https://py99999.com/print-update`

反代目标：`http://127.0.0.1:17890`

## 六、回滚思路

1. 保留旧 `PrintComponent-Setup-{ver}.zip` 在 download 目录
2. 恢复旧 `manifest.json` 到 update data
3. `systemctl restart print-update`
4. 客户端再检查更新或重装旧包