加密 API 开发文档：ionCube、SourceGuardian 与 LAOKPHP VM 接入指南

本文档面向 API 接入方，介绍加密任务提交、任务状态查询、日志读取、加密结果下载及许可证生成等核心功能。接口支持 ionCube 15、SourceGuardian 17、SourceGuardian 17 PRO 和 LAOKPHP VM，并提供完整的中文接入说明与请求示例。

加密 API 接入概览

• 鉴权请求头：X-Client-Code、X-Access-Key-Id、X-Product-Code、时间戳、Nonce、内容摘要和 HMAC 签名。
• 支持的加密引擎：ionCube 15、SourceGuardian 17、SourceGuardian 17 PRO、LAOKPHP VM。
• 文件来源方式：仅支持上传文件，请在服务端完成项目文件提交。
• 主要能力：创建加密任务、查询执行状态、增量读取日志、下载加密结果、生成及下载许可证。

标准接入流程

1. 准备客户端编码、访问密钥 ID、产品编码及 HMAC 签名所需凭据。
2. 上传项目文件并调用加密任务接口，获得任务 ID。
3. 根据任务 ID 查询执行状态，并通过日志接口获取处理进度。
4. 任务完成后调用下载接口，获取加密后的项目文件。
5. 如项目需要授权控制，可创建许可证并下载对应许可证文件。

加密任务与许可证核心接口

• POST /encryption-api/tasks：提交加密任务。
• GET /encryption-api/tasks/{taskId}：查询加密任务状态。
• GET /encryption-api/tasks/{taskId}/logs：读取任务执行日志。
• GET /encryption-api/tasks/{taskId}/download：下载加密结果。
• POST /encryption-api/laokphpvm/runtime-reports：上报 LAOKPHP VM 运行诊断信息。
• POST /encryption-api/licenses：生成加密许可证。
• GET /encryption-api/licenses/{licenseId}/download：下载许可证文件。

创建加密任务请求示例

以下示例使用 SourceGuardian 加密引擎，并配置 PHP 版本、域名绑定、项目凭据、远程验证地址及压缩级别。

{
  "engine": "sourceguardian",
  "file": "project.zip",
  "options": {
    "phpVersion": "8.5",
    "copyright": "Copyright 2026 Example Corp",
    "domains": [
      "example.com",
      "*.example.com"
    ],
    "projectId": "demo-project",
    "projectKey": "demo-secret",
    "dockerSocket": "/var/run/docker.sock",
    "remoteVerificationUrl": "https://example.com/verification_id.php",
    "compression": 5
  }
}

创建 ionCube 许可证请求示例

以下示例创建一个 ionCube 许可证，限制允许使用的服务器域名，并设置许可证到期时间和自定义属性。

{
  "engine": "ioncube",
  "options": {
    "licenseFileName": "license.txt",
    "allowedServers": [
      "example.com"
    ],
    "expireOn": "2026-12-31",
    "properties": {
      "plan": "pro"
    },
    "text": "Copyright 2026"
  }
}

加密 API 接入最佳实践

• 生产环境应由服务端上传项目文件，避免将未加密的源代码或访问凭据暴露给浏览器。
• 首次联调建议使用最小参数集完成任务提交、状态查询和结果下载，再逐步增加域名绑定、许可证及到期时间等高级配置。
• 批量处理任务时，可结合日志接口返回的 nextOffset 进行轮询，实现执行日志的增量拉取。
• 需要严格审计时，应为不同客户、产品线和部署环境创建独立客户端，避免多个业务共用同一组访问凭据。
• 客户端应妥善保管访问密钥，并确保时间戳、Nonce、内容摘要和 HMAC 签名参数准确一致。
• 升级至 SourceGuardian 17 PRO 前，应验证 entangle、动态许可证和目标 PHP 运行环境的兼容性。
• LAOKPHP VM 默认使用内置加载器执行。受保护的 stub 可独立完成验签、解段和运行，rulewl_vm_loader 原生扩展仅作为可选的性能加速路径。

安全与错误排查建议

• 签名校验失败时，优先检查请求时间戳、Nonce、内容摘要、请求头字段及 HMAC 计算结果。
• 任务长时间未完成时，可先查询任务状态，再通过日志接口定位文件、参数或运行环境问题。
• 下载加密结果或许可证前，请确认任务或许可证已成功生成，并使用接口返回的有效 ID 发起请求。
• 请勿在应用日志、前端代码、公开仓库或错误响应中输出访问密钥和项目密钥。