xelos/xelos-worker

XELOS Worker容器

关于此容器

XELOS Worker是一个无状态Docker容器，用于处理XELOS系统发出的任务。基础容器基于PHP CLI镜像构建，集成OpenSwoole服务器和API控制器，通过HTTP调用进行任务处理。

• 镜像基于php:*-cli基础镜像，并安装OpenSwoole
• OpenSwoole文档：[***]

核心功能与特性

• 多类型任务处理：支持文档转换、视频处理、图像处理等多种任务
• 无状态设计：可水平扩展，适应不同负载需求
• 基于OpenSwoole：提供高性能的HTTP服务能力
• 健康检查支持：内置健康检查配置，确保服务可用性
• 可配置性：通过环境变量调整线程数、包大小限制等参数
• 安全增强：支持安全选项配置（如no-new-privileges、权限丢弃等）

使用场景与适用范围

适用于需要处理以下任务的Web环境，特别是作为XELOS系统的组成部分：

• 办公文档预览（转换为PDF格式）
• 视频格式转换（转为MP4）及缩略图、字幕提取
• 图像转换与大小调整
• 需要高性能、可扩展的后台任务处理场景

安装指南

XELOS当前使用LibreOffice Worker、Video Worker和Image Worker作为系统工作器库的一部分。以下是在docker-compose.yml中配置这些工作器服务的说明：

LibreOffice Worker

LibreOffice Worker用于将办公文档转换为PDF格式，便于文档预览。

yaml
  libreoffice:
    image: docker.xuanyuan.run/xelos/xelos-worker:libreoffice
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

Video Worker

Video Worker使用ffmpeg将视频转换为MP4格式，并可提取缩略图、字幕，适用于Web环境。

yaml
  video:
    image: docker.xuanyuan.run/xelos/xelos-worker:video
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

Image Worker

Image Worker使用libvips进行图像转换和大小调整。

yaml
  image:
    image: docker.xuanyuan.run/xelos/xelos-worker:image
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "curl","-fk", "https://localhost:9501" ]
      timeout: 20s
      retries: 10
    networks:
      - internal-network

高级设置、安全选项与安全上下文

可在docker-compose.yml中添加以下高级选项以提升安全性和性能。使用视频工作器时，若使用tmpfs请确保有足够内存；也可使用卷或设置read_only: false。

yaml
  image:
    ...
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    read_only: true
    tmpfs:
      - /tmp
      - /server/certs

建议在内部网络中运行工作器容器。LibreOffice在处理特制文档时可能尝试加载外部资源。

yaml
networks:
  internal:
    driver: bridge
    internal: true

如何在项目中设置基础容器

• 调整docker-compose.yml、Docker Swarm或K8S部署配置，包含所需的工作器容器
• 服务容器默认使用9501端口

yaml
services:
  info:
    image: docker.xuanyuan.run/xelos/xelos-worker:base-alpine
    restart: unless-stopped
    networks:
      - backend

从XELOS Web容器内测试Echo服务：

bash
curl -X 'POST' 'http://worker:9501/info/echo' -H 'accept: application/json' -H 'Content-Type: application/json'   -d '{"Hello World"}'

配置与环境变量

每个工作器通常包含从环境读取的预定义设置，默认适用于其设计任务。如有需要，可修改以下环境变量：

客户端/Composer依赖

使用工作器服务容器的最佳方式是通过相应的Composer客户端。该依赖目前仅在私有Composer镜像中可用。更新composer.json以引用镜像：

json
{
    "repositories": [
        {
            "type": "composer",
            "url": "https://repo.xelos.net/composer/",
            "canonical": false
        }
    ],
    "require": {
        "xelos-worker/php-clients": "*"
    }
}

LibreOffice Worker示例

php
<?php
$sourceFile = '/tmp/myWord.docx';
$targetFile = '/tmp/myWordAsPDF.pdf';
(new \XELOSWorker\Client\Libreoffice('https://libreoffice:9501'))->convert($sourceFile, $targetFile);

Video Worker示例

php
<?php
$pathToVideoFile = '/tmp/myVideo.mov';
$pathToConvertedVideoFile = '/tmp/myVideo.mp4';
try {
    $videoWorker = (new \XELOSWorker\Client\Video('https://video:9501'));
    // 可选：检查支持的格式 
    // $videoWorker->getSupportedFileExtensions();
    
    // 步骤1：上传视频到工作器
    $fileInfo = $videoWorker->uploadVideoFile($pathToVideoFile);
    
    // 步骤2：生成预览缩略图
    $previewImages = $videoWorker->generatePreviewImages();
    foreach ($previewImages as $previewImage) {
        $thumbCount = \basename(\substr($previewImage['downloadFileId'], \strpos($previewImage['downloadFileId'], ':')+1));
        $saveTargetFile = $destinationFolder.$thumbCount;
        $videoWorker->downloadFile($saveTargetFile, $previewImage['downloadFileId']);
    }
    
    // 步骤3：将视频编码为特定质量
    $videoWorker->encodeVideo($quality = 'sd');
    
    // 步骤4：从工作器下载编码后的视频
    $videoWorker->downloadFile($pathToConvertedVideoFile, $fileInfo['fileId'].':sd');
    
} catch(Exception $exception){
    // 错误处理
}

Image Worker示例

php
<?php
$pathToPDF = '/tmp/myWordAsPDF.pdf';
$imgFile = '/tmp/preview.png';
$resizedImgFile = '/tmp/preview-resized.png';
try {
    $imageWorker = (new \XELOSWorker\Client\Image('https://image:9501'));
    $imageWorker->pdfToImage($pathToPDF, $imgFile, $page = 0, $dpi = 300);
    $imageWorker->thumbnail($imgFile, $resizedImgFile, $width = 800, $height = 600, $crop = true);
} catch (Exception $exception) {
    // 错误处理
}

使用TLS/HTTPS

容器在首次启动时会创建自签名证书，如未通过环境变量指定，将在以下位置检查公钥/私钥证书：

• /server/certs/ssl.crt
• /server/certs/ssl.key

有关TLS实现的更多信息，请参阅OpenSwoole文档：[***]

如何设置开发环境以贡献代码

本地挂载此仓库代码：

yaml
services:
  worker:
    image: docker.xuanyuan.run/xelos/xelos-worker:base-alpine
    restart: unless-stopped
    ports:
      - 9501:9501
    volumes:
      - ../xelos-worker:/server/xelos-worker
    networks:
      - backend

内部信息

如计划重建或合并工作器容器，以下信息可能有用：

• 当前默认入口点为 php /server/xelos-worker/startup.php
• 默认命令运行单个服务，例如：CMD ["--service=libreoffice"]
• 可在单个容器中合并多个服务，例如：CMD ["--service=libreoffice,video"]，或省略--service参数运行所有可用服务
• 可启动服务的调试模式以防止提前退出，例如：CMD ["--service=libreoffice","--dev-mode=true"]
• 默认用户ID为*（worker），组ID为***（worker）**

也可使用提供的docker/docker-compose.yml快速启动服务进行测试。

联系方式

• BLUEEND / Stefan