配置

GetWebP CLI 将许可证令牌和状态缓存存储在由 conf 库管理的加密 JSON 文件中。本指南涵盖文件位置、环境变量、加密行为和多设备工作流。

目录#

• 配置文件位置
• 配置文件内容
• 环境变量
• 加密和机器绑定
• 多设备使用
• 设备迁移
• CI/CD 环境
• 故障排除

配置文件位置#

GetWebP 使用 conf npm 包，projectName: 'getwebp'，该包通过 env-paths 委托给平台特定的配置目录。配置文件名为 config.json。

在 Linux 上，路径遵守 XDG_CONFIG_HOME 环境变量。如果设置，文件存储在 $XDG_CONFIG_HOME/getwebp-nodejs/config.json 而不是默认的 ~/.config/ 前缀。

覆盖配置目录#

设置 GETWEBP_CONFIG_DIR 环境变量以将配置文件存储在自定义目录中：

# Linux / macOS
export GETWEBP_CONFIG_DIR=/opt/getwebp
getwebp status
# 配置文件：/opt/getwebp-nodejs/config.json
 
# Windows (PowerShell)
$env:GETWEBP_CONFIG_DIR = "C:\getwebp"
getwebp status
# 配置文件：C:\getwebp\config.json

设置 GETWEBP_CONFIG_DIR 时，它会完全覆盖平台默认值。如果目录不存在，将自动创建。

找到您的配置文件#

要确认系统上的实际路径：

# macOS / Linux
ls ~/Library/Preferences/getwebp/config.json  2>/dev/null  # macOS
ls ~/.config/getwebp/config.json               2>/dev/null  # Linux
 
# Windows (PowerShell)
Test-Path "$env:APPDATA\getwebp\Config\config.json"

配置文件内容#

配置文件包含两个字段，都由 CLI 命令自动管理。您不应手动编辑此文件 -- 它是加密的，直接修改将损坏它。

statusCache 对象#

每次 getwebp status 成功联系 API 服务器时，状态缓存都会更新。当网络无法连接时，CLI 回退到缓存数据并将其标记为 cached: true。

环境变量#

用户可配置的#

这是唯一用于最终用户配置的环境变量。

构建时（内部）#

这些变量在构建过程中嵌入，不适用于最终用户。为完整性起见，此处进行了文档记录。

警告： 在运行时覆盖 API_BASE_URL 或 JWT_PUBLIC_KEY 将导致许可证验证失败，除非您运行自己的 API 服务器。这些变量仅用于内部开发和测试。

加密和机器绑定#

配置文件使用从您机器的硬件 ID（通过 node-machine-id）派生的密钥进行加密。这提供了两个安全属性：

1. 静止加密 -- JWT 令牌不以纯文本形式存储在磁盘上。
2. 机器绑定 -- 配置文件无法在不同的机器上解密。将 config.json 复制到另一台计算机不会转移您的许可证。

加密密钥如何派生#

机器硬件 ID  -->  SHA-256 哈希  -->  加密密钥

硬件 ID 源自：

• macOS: IOKit 注册表中的 IOPlatformUUID
• Linux: /var/lib/dbus/machine-id 或 /etc/machine-id
• Windows: Windows 注册表中的 MachineGuid

如果无法读取机器 ID（例如在受限容器中），CLI 回退到 hostname:username 的哈希。在此回退模式下，重命名主机或切换用户将使加密配置失效。

多设备使用#

Pro 许可证支持多个设备。每个 Pro 许可证允许最多 3 个 CLI 设备和 3 个 WordPress 站点。

每个设备由其硬件 ID 的 SHA-256 哈希标识。要检查有多少设备插槽在使用中：

getwebp status

Devices    : 2 / 3 used

您也可以从网络仪表板 getwebp.com/dashboard 管理设备。

添加新设备#

在新机器上使用相同的许可证密钥激活：

getwebp auth XXXX-XXXX-XXXX-XXXX

如果所有设备插槽都已占用，激活将失败。首先从现有设备注销以释放插槽（见下文）。

移除设备#

在您要移除的设备上运行 getwebp logout：

getwebp logout

这将联系 API 服务器以解绑设备并清除本地配置。释放的插槽随后可在另一台机器上使用。如果您不再有权访问该设备，请使用 网络仪表板 远程解绑它。

设备迁移#

要将您的许可证从一台机器移到另一台：

1. 在旧机器上，释放设备插槽：

   getwebp logout

2. 在新机器上，使用相同的许可证密钥激活：

   getwebp auth XXXX-XXXX-XXXX-XXXX

不要在机器之间复制 config.json。 该文件使用机器特定的密钥加密，无法在不同的设备上解密。始终使用 getwebp logout + getwebp auth 进行迁移。

无法访问旧机器#

如果您无法在旧机器上运行 getwebp logout（例如硬件故障）：

1. 前往 getwebp.com/dashboard。
2. 在设备列表中找到旧设备并解绑它。
3. 使用 getwebp auth 在新机器上激活。

CI/CD 环境#

在 CI/CD 管道中，每个运行器通常有一个唯一的机器 ID，这意味着每次运行都会消耗一个设备插槽。对于 CI/CD 用例：

• 如果您的 CI 运行器有持久存储，请使用 GETWEBP_CONFIG_DIR 指向持久目录。
• 在管道末尾运行 getwebp logout --force 以释放设备插槽。
• 使用 --json 输出获得机器可解析的结果（见 JSON 输出）。

# 示例：GitHub Actions 步骤
- run: |
    getwebp auth ${{ secrets.GETWEBP_LICENSE_KEY }}
    getwebp convert ./images -r --json
    getwebp logout --force

注意： 临时 CI 运行器（GitHub Actions、GitLab CI）在每次运行时生成新的机器 ID。如果设备插槽已用尽，请从 仪表板 解绑过时的设备。

故障排除#

"Token may become invalid if hostname changes"#

当 CLI 无法读取硬件机器 ID 并回退到 hostname:username 时，会出现此警告。常见原因：

• 在没有访问 /var/lib/dbus/machine-id 的容器中运行
• 对机器 ID 文件的权限受限

解决方案： 确保 /var/lib/dbus/machine-id 或 /etc/machine-id 存在且可读，或设置稳定的主机名。

配置文件似乎已损坏#

如果在操作系统重新安装或硬件更改后 CLI 无法读取配置，则加密密钥已更改，旧配置无法解密。

解决方案： 删除配置文件并重新激活：

# macOS
rm ~/Library/Preferences/getwebp-nodejs/config.json
# Linux
rm ~/.config/getwebp-nodejs/config.json
# Windows (PowerShell)
Remove-Item "$env:APPDATA\getwebp-nodejs\Config\config.json"

然后重新激活：

getwebp auth XXXX-XXXX-XXXX-XXXX

"JWT_PUBLIC_KEY was not injected at build time"#

此错误表示您正在运行开发或构建不正确的二进制文件。从 getwebp.com/download 下载官方二进制文件。

相关文档#