W WPMMCC ATS / 文档中心
English

WPTSALL 客户端安装与运维全指南

WPTSALL Client 是 WPMMCC ATS WordPress 插件的配套本地优先翻译客户端。本文档系统介绍客户端在 Linux、macOS 与 Windows 上的安装配置、OTA 安全更新、卸载策略、环境变量参数表，以及与 WordPress 插件协同的端到端自动化翻译流程。

本地优先隐私承诺： WPTSALL Client 严格运行在你自己的硬件设备上（服务器、VPS 或个人电脑），绝不上云。站点授权凭据、翻译记忆库、AI 翻译厂商 API 密钥等敏感数据均仅保存在本地 SQLite 数据库（wptsall.db，位于系统数据目录）中，绝无第三方 SaaS 中继。

1. 双形态产品与核心架构

WPTSALL Client 提供两种产品形态，两者共享完全一致的 Rust 原生核心引擎（基于 tokio 异步运行时、rustls 安全 TLS、内置嵌入式 SQLite 以及严格的密码学验签能力）：

  • 本地 WebUI（后台常驻守护进程）： 启动一个常驻后台的服务，监听 127.0.0.1:8977，通过任意现代浏览器直接访问操作。极度轻量，适合部署在 Linux 服务器、VPS、本地工作站或 NAS 设备上。
  • Desktop 桌面应用： 同一套引擎的本机窗口。默认监听 127.0.0.1:8978，界面留在这台电脑上，因此可以和 8977 上的 WebUI 同时开着。它不会把界面开到网络上。

2. 跨平台安装指南

所有官方发布的安装包与安装脚本均托管于 wptsall-client-releases 仓库。每个分发套件（kit）均使用 minisign 进行了非对称加密签名，并附带 SHA-256 校验和。

Linux 安装（WebUI 守护进程）

下载官方安装脚本、审阅后再执行——切勿将远端脚本直接管道进 shell：

curl -fsSL -o install.sh https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.sh
less install.sh    # 先审阅脚本再运行
sh install.sh

该脚本将自动执行以下标准化部署流程：

  1. 自动检测 CPU 架构（x86_64 或 aarch64），下载对应 kit 并严格验证 minisign 签名与 SHA-256 校验和。
  2. 解压安装到 ~/.local/opt/wptsall-client/ 目录。
  3. 在 ~/.local/bin/wptsall-client 和 wptsall-webui 创建命令行软链接。
  4. 自动注册并启动 systemd 用户级服务（~/.config/systemd/user/wptsall-client.service），配置进程崩溃或系统重启后自动拉起。
  5. 在本地打开并准备就绪：http://127.0.0.1:8977。

macOS 安装（WebUI 服务或 Desktop 应用）

部署后台 WebUI 守护进程服务，同样只需执行：

curl -fsSL -o install.sh https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.sh
less install.sh    # 先审阅脚本再运行
sh install.sh

脚本将配置 macOS 原生 LaunchAgent（~/Library/LaunchAgents/cc.wpmm.wptsall-client.plist），用户登录时自动在后台静默运行 WebUI。若更偏好独立窗口桌面版，可直接从 Releases 页面下载 .dmg 镜像并拖拽安装——它经过 minisign 完整性验证，但未做 Apple Developer ID 签名，首次启动时 Gatekeeper 会要求授权（见下节）。

Windows 安装（PowerShell 一键脚本）

以普通用户身份打开 Windows PowerShell，下载并审阅脚本后再运行：

irm https://raw.githubusercontent.com/wpmmcc/wptsall-client-releases/main/install.ps1 -OutFile install.ps1
Get-Content install.ps1    # 先审阅脚本再运行
powershell -ExecutionPolicy Bypass -File .\install.ps1

脚本自动化步骤包括：

  1. 下载并严格核验签名套件。
  2. 解压至当前用户目录 $env:LOCALAPPDATA\wptsall-client。
  3. 将安装路径自动加入用户 PATH 环境变量。
  4. 在开机启动文件夹中创建快捷方式，确保开机后服务自启动。
  5. 启动客户端并自动打开浏览器访问 http://127.0.0.1:8977。

从源码自行编译

如果你希望自主掌控完整编译流程，可使用标准 Rust 工具链直接构建：

# 编译 WebUI 二进制程序
cd client-wpplugin/source
cargo build --release
# 生成的二进制文件位于：target/release/wptsall-client

# 编译 Desktop 桌面应用（需要 Node.js 与 Tauri CLI）
cd client-desktop
npm install
npm run tauri build

首次启动授权（无 OS 证书构建）

发布物由 minisign 签名与 SHA-256 校验清单保护——保证你下载的文件与官方发布逐字节一致。但桌面应用目前没有操作系统级代码签名证书（无 Apple Developer ID、无 Microsoft Authenticode），因此首次启动时操作系统本身会给出警告。这是无证书构建的预期行为，不代表文件被篡改：

  • macOS（Gatekeeper）： 无法打开"WPTSALL Client"，因为无法验证开发者。——打开 系统设置 → 隐私与安全性，滚动到"安全性"区域，点 仍要打开。macOS 14 及更早版本也可以右键点按应用 → 打开 → 打开。命令行用户可在核对校验和后执行 xattr -dr com.apple.quarantine "/Applications/WPTSALL Client.app" 清除隔离属性。
  • Windows（SmartScreen）： Windows 已保护你的电脑。——点 更多信息，再点 仍要运行。或在核对校验和后执行 Unblock-File .\wptsall-client.exe。

推荐顺序：先验证（minisign + SHA-256，命令见发布物的 README-AUTHORIZATION.md），再授权。完整分步说明随每个发布物内置为 FIRST-LAUNCH-AUTHORIZATION.md，并在下载页面旁提供 README-AUTHORIZATION.md。

3. 签名更新机制与安全性保障

WPTSALL Client 具备高度可靠的原地 OTA 增量更新能力，内置企业级安全验签防线：

  • 应用内一键检查更新： 在 WebUI 界面中进入 设置 → 关于，点击 检查更新 即可探测新版本；配置了发布源（见下表 WPTSALL_SERVER_BASE）后，新版本将以签名 kit 就地应用更新。
  • 密码学验签双重验证： 每一个更新套件都必须通过官方 minisign 公钥（RWR7lrdabZEEywfWEfrRJXIyP5h+LHEabOA8JFiNJ3vGLpNtppyabHfP）的数字签名验证，以及已签名的 SHA-256 校验和。损坏、被劫持或未授权的更新包会被底层直接拒绝。
  • 防降级（Anti-Rollback）保护： 版本号按语义化规范递增，杜绝被恶意降级到已知存在隐患的历史版本。
  • Windows 运行中文件无死锁替换： 针对 Windows 系统对运行中 .exe 文件的排他锁特性，更新器设计了原子重命名与替换机制，并在更新遭遇异常时自动回滚，保障服务不中断。
  • 手动覆盖升级： 你也可以在任意时刻直接重新运行安装脚本，脚本会就地更新程序文件，完全不触动既有配置与数据库。

4. 卸载策略与数据安全保留

Releases 仓库中为每个平台配备了独立的卸载脚本，操作透明直观：

Linux / macOS 卸载命令

# 标准卸载（默认保留 SQLite 本地数据库、配置与日志）
sh uninstall-webui.sh

# 彻底清理（同时删除所有本地数据库与日志文件）
sh uninstall-webui.sh --purge-data --yes

# 若同时安装了 Desktop 且希望移除所有共享二进制
sh uninstall-webui.sh --purge-shared --purge-data --yes

Windows 卸载命令

# 标准卸载（保留数据）
.\uninstall-webui.ps1

# 彻底清理（包含 SQLite 数据库与全部日志；-PurgeData 必须搭配 -Yes 确认）
.\uninstall-webui.ps1 -PurgeData -Yes
数据安全优先准则： 与 WordPress 插件保持一致，WPTSALL 客户端在默认卸载时只移除后台服务注册、PATH 软链接与二进制目录，你的任务历史、站点配置与翻译数据（wptsall.db）默认予以妥善保留。若未来重新安装，所有配置和进度将立即恢复。

5. 核心环境变量与配置参数全表

客户端既支持在 WebUI 的设置界面中图形化配置，也支持通过环境变量或 .env 文件进行无头化运维：

环境变量 / 参数项 默认值 说明与应用场景
WPTSALL_WEB_UI false 是否启动本地 WebUI HTTP 服务守护进程。服务安装脚本会自动将其置为 1；裸终端运行时仅启动 Worker 而不带界面。
WPTSALL_WEB_UI_BIND 127.0.0.1:8977 WebUI 监听绑定的网络接口 IP 与端口。
WPTSALL_WEB_UI_PORT 8977 WebUI 独立监听端口号。
WPTSALL_DATA_DIR ~/.local/share/wptsall-client（Linux 与 macOS，由服务安装脚本设置）
%LOCALAPPDATA%\wptsall-client（Windows）		 持久化数据根目录：SQLite 数据库（wptsall.db）位于 <数据目录>/runtime/，日志位于 <数据目录>/logs/，配置位于 <数据目录>/config/。Desktop 桌面应用使用操作系统应用数据目录下独立的 wptsall-desktop 目录。未设置该变量时，终端运行使用工作目录下的 ./runtime、./logs、./config。
WPTSALL_LOG_FILE <数据目录>/logs/wptsall-client.log 客户端运行输出日志文件的具体保存路径。
WPTSALL_LOG_ENABLED false 调试日志开关。除环境变量外，也可在 WebUI 设置页动态切换。
WPTSALL_ONESHOT false 设为 true 时，Worker 仅领取一个待处理批次，翻译写回完成后立即安全退出（适用于 Linux crontab 调度）。
WPTSALL_POLL_SECONDS 20 持续模式下，后台 Worker 轮询 WordPress 任务队列的间隔时间（秒，最小 1 秒）。
WPTSALL_SERVER_BASE 未设置 发布更新清单的基准服务地址。出于本地优先设计原则，默认刻意不设任何内置回退地址：仅当显式配置后应用内更新检查才可用（旧别名 WPTSALL_SERVER_URL）。未配置时，请通过重新运行安装脚本完成升级。

8977 端口与冲突处理

WebUI 默认监听 127.0.0.1:8977 —— 仅本机回环，界面绝不会暴露到网络。8977 未被 IANA 注册，且远离常见服务与开发端口段（3306、5432、6379、8080、9000、9200 等），实际冲突概率很低。若本机已有程序占用该端口，客户端会以 bind web ui failed: 127.0.0.1:8977 启动失败；此时可将 WPTSALL_WEB_UI_PORT（或用 WPTSALL_WEB_UI_BIND 指定完整地址）改为空闲端口并重启服务。systemd 用户服务推荐用 systemctl --user edit wptsall-client 添加覆盖配置；Desktop 应用的内嵌 WebUI 同样通过环境变量支持这两个配置。

6. 端到端自动化翻译对接全流程

清晰梳理 WordPress 插件与本地客户端在全自动化翻译中的交互闭环：

  1. 内容模型扫描（WordPress 端）： 进入 WordPress 后台 WPMMCC ATS → 内容模型。插件自动探测文章、分类法、菜单以及第三方插件（WooCommerce、ACF、Elementor 等）的可翻译字段，构建统一规则集。
  2. 站点关系配置（WordPress 端）： 在 站点关系 中建立源语言与目标语言的映射（例如：源语言为简体中文，目标语言为英语虚拟站点，前缀为 /en/）。
  3. 客户端 API 授权（WordPress 端）： 在 任务管理 → 客户端授权 页面，点击 生成连接包。连接包内含站点地址、路由密钥与一次性配对码，在所选有效期（默认 5 分钟）内可被认领。WP-CLI 等价命令：wp wptsall security issue-pairing-pack --device-id=<客户端设备ID>。
  4. 添加站点连接（客户端）： 打开客户端 WebUI（http://127.0.0.1:8977）或桌面端，在 站点 页面把连接包 JSON 与配对码一并粘贴导入，客户端会自动认领设备级令牌并测试连接。
  5. 配置翻译厂商（客户端）： 在 翻译组件 页面从目录安装厂商组件（DeepSeek、OpenAI、Claude、DeepL 或本地 OpenAI 兼容端点，如运行在 http://127.0.0.1:11434 的 Ollama），并在 API 密钥 页面填入对应密钥。
  6. 执行翻译 Worker： 在 Worker 标签页下，点击 执行一次（或开启持续轮询模式）。客户端安全领取 WordPress 队列中的任务，调用厂商 API 翻译，并通过 Protocol v2 幂等接口将翻译内容精准写回。
  7. 多语言前台实时生效： 写回完成后，目标语言虚拟站点上的文章、分类、自定义字段即刻呈现，无需人工二次干预。