配置ClearML服务器

本页描述了ClearML Server的部署和功能配置。具体来说，它包含了如何为以下内容配置ClearML Server的说明：

• 子域名和负载均衡器 - 一个AWS负载均衡示例
• 开放Elasticsearch、MongoDB和Redis的外部访问
• Web登录认证 - 创建和管理用户及密码
• 使用哈希密码 - 选择使用哈希密码而不是明文密码
• 非响应任务看门狗 - 用于非活跃的实验
• 自定义UI上下文菜单操作

有关所有配置选项，请参阅ClearML 配置参考页面。

ClearML 服务器部署配置​

ClearML 服务器支持两种部署配置：单一IP（域名）和子域名。

单IP（域名）配置​

单个IP（域名）开放了以下端口：

• 端口 8080 上的 Web 应用程序
• API 服务在端口 8008
• 文件存储服务在端口 8081

子域名配置​

使用默认HTTP/S端口（80 或 443）的子域名配置：

• 子域名上的Web应用程序：app.*.*
• API services on subdomains: api.*.*
• 子域名上的文件存储服务：files.*.*

当为ClearML Server配置子域时，它们将映射到ClearML Server内部为Dockers配置的端口。因此，例如，如果实施了某种类型的端口转发，ClearML Server Dockers仍然可以访问。

例如，一个域名被称为mydomain.com，并且创建了一个名为clearml.mydomain.com的子域名，使用以下内容：

• app.clearml.mydomain.com (网络服务器)
• api.clearml.mydomain.com (API server)
• files.clearml.mydomain.com (文件服务器)

访问ClearML Web UI时，使用app.clearml.mydomain.com会自动将API请求发送到api.clearml.mydomain.com。

services:
    webserver:
        environment:
	        WEBSERVER__fileBaseUrl: "https://files.<my_domain>/"
	        WEBSERVER__useFilesProxy: true

ClearML 服务器功能配置​

ClearML 服务器的功能可以通过配置文件或环境变量进行配置。

配置文件​

ClearML 服务器使用以下配置文件：

• apiserver.conf
• hosts.conf
• logging.conf
• secure.conf
• services.conf

启动时，ClearML 服务器将在 /opt/clearml/config 目录中查找这些配置文件 （此路径可以使用 CLEARML_CONFIG_DIR 环境变量进行修改）。默认配置文件位于 clearml-server 仓库中。

如果你想修改服务器配置，而相关的配置文件不存在，你可以创建该文件，并输入相关的修改配置。

tasks {
   "multi_task_histogram_limit": <new-value>
}

环境变量​

ClearML 服务器支持多个固定的环境变量，这些变量会影响其行为，以及可以用于覆盖任何配置文件设置的动态环境变量。

固定环境变量​

通用

• CLEARML_CONFIG_DIR 允许覆盖服务器查找配置文件的默认目录。可以指定多个目录（使用与指定系统的 PATH 环境变量相同的格式）

数据库服务覆盖：

• CLEARML_MONGODB_SERVICE_HOST 允许覆盖MongoDB服务的主机名
• CLEARML_MONGODB_SERVICE_PORT 允许覆盖MongoDB服务的端口
• CLEARML_ELASTIC_SERVICE_HOST 允许覆盖ElasticSearch服务的主机名
• CLEARML_ELASTIC_SERVICE_PORT 允许覆盖ElasticSearch服务的端口
• CLEARML_REDIS_SERVICE_HOST 允许覆盖 Redis 服务的主机名
• CLEARML_REDIS_SERVICE_PORT 允许覆盖 Redis 服务的端口

动态环境变量​

动态环境变量可以用来覆盖配置文件中出现的任何配置设置。

环境变量的名称应为CLEARML__，其中表示要设置的配置字段的完整路径，包括配置文件名。配置路径的元素应使用__（双下划线）分隔。

例如，给定默认的 secure.conf 文件内容：

    ...
    
    credentials {
        apiserver {
            role: "system"
            user_key: "default-key"
            user_secret: "default-secret"
        }
        
        ...
        
    }

您可以通过设置以下环境变量来覆盖系统apiserver组件的默认密钥： CLEARML__SECURE__CREDENTIALS__APISERVER__USER_SECRET="my-new-secret"

配置程序​

子域名和负载均衡器​

以下示例基于AWS负载均衡，展示了配置过程：

1. 在ClearML服务器的/opt/clearml/config/apiserver.conf文件中，添加以下auth.cookies部分：

   auth {
       cookies {
       httponly: true
       secure: true
       domain: ".clearml.mydomain.com"
       max_age: 99999999999
     }
   }
   
   tip

   如果apiserver.conf文件不存在，请在ClearML Server的/opt/clearml/config目录（或您配置的替代文件夹）中创建您自己的文件，并输入修改后的配置

2. 使用以下负载均衡器配置：

   • 监听器：

     • 可选：HTTP监听器，将所有流量重定向到HTTPS。
     • 用于app.的HTTPS监听器，转发到AppTargetGroup
     • 用于api.的HTTPS监听器，转发到ApiTargetGroup
     • 用于files.的HTTPS监听器，转发到FilesTargetGroup

   • 目标群体：

     • AppTargetGroup: 基于HTTP的目标群体，端口 8080
     • ApiTargetGroup: 基于HTTP的目标群体，端口 8008
     • FilesTargetGroup: 基于HTTP的目标群体，端口 8081

   • 安全性和路由：

     • 负载均衡器：确保负载均衡器能够接收来自相关IP地址的流量（安全组和子网定义）。
     • 实例：确保负载均衡器能够使用相关端口访问实例（安全组定义）。

3. 重启ClearML服务器。

开放Elasticsearch、MongoDB和Redis以供外部访问​

为了提高安全性，ClearML Server的Elasticsearch、MongoDB和Redis服务器的端口默认不暴露；它们仅在docker网络内部开放。如果需要外部访问，请打开这些端口（但请确保了解这样做所涉及的安全风险）。

要开放对Elasticsearch、MongoDB和Redis端口的外部访问：

1. 关闭ClearML服务器。执行以下命令（假设配置文件在环境路径中）。

   docker-compose down
   

2. 编辑 docker-compose.yml 文件如下：

   • 在elasticsearch部分，添加以下两行：

     ports:
     - "9200:9200"
     

   • 在mongo部分，添加以下两行：

     ports:
     - "27017:27017"
     

   • 在redis部分，添加以下两行：

     ports:
     - "6379:6379"
     

3. 启动 ClearML 服务器。

   docker-compose -f docker-compose.yml pull
   docker-compose -f docker-compose.yml up -d
   

Web登录认证​

可以在ClearML服务器中配置Web登录认证，以便仅允许提供凭据的用户访问ClearML系统。这些凭据包括用户名和密码。

没有网络登录认证，ClearML Server 默认不限制访问。

为ClearML服务器添加网页登录认证：

1. 在ClearML Server的/opt/clearml/config/apiserver.conf中，添加auth.fixed_users部分并指定用户。

   例如：

   auth {
       # Fixed users login credentials
       # No other user will be able to login
       fixed_users {
           enabled: true
           pass_hashed: false
           users: [
               {
                   username: "jane"
                   password: "12345678"
                   name: "Jane Doe"
               },
               {
                   username: "john"
                   password: "12345678"
                   name: "John Doe"
               },
           ]
       }
   }
   
   tip

   如果apiserver.conf文件不存在，请在ClearML Server的/opt/clearml/config目录（或您配置的替代文件夹）中创建您自己的文件，并输入修改后的配置

2. 重启ClearML服务器。

使用哈希密码​

你也可以使用哈希密码而不是明文密码。要做到这一点：

• 设置 pass_hashed: true

• 在password字段中使用base64编码的哈希密码，而不是明文密码。假设Jane的明文密码是123456，使用以下bash命令生成base64编码的哈希密码：

  > python3 -c 'import bcrypt,base64; print(base64.b64encode(bcrypt.hashpw("123456".encode(), bcrypt.gensalt())))'
  b'JDJiJDEyJDk3OHBFcHFlNEsxTkFoZDlPcGZsbC5sU1pmM3huZ1RpeHc0ay5WUjlzTzN5WE1WRXJrUmhp'
  

• 使用命令的输出作为用户的密码。生成的apiserver.conf文件应如下所示：

  auth {
       # Fixed users login credentials
       # No other user will be able to login
       fixed_users {
           enabled: true
           pass_hashed: true
           users: [
               {
                   username: "jane"
                   password: "JDJiJDEyJDk3OHBFcHFlNEsxTkFoZDlPcGZsbC5sU1pmM3huZ1RpeHc0ay5WUjlzTzN5WE1WRXJrUmhp"
                   name: "Jane Doe"
               }
           ]
       }
   }
  
  tip

  如果apiserver.conf文件不存在，请在ClearML Server的/opt/clearml/config目录（或您配置的替代文件夹）中创建您自己的文件，并输入修改后的配置

非响应任务监视器​

非响应实验看门狗监控那些在指定时间间隔内未更新的实验，然后看门狗将它们标记为aborted。非响应实验看门狗始终处于活动状态。

修改以下看门狗设置：

• 看门狗状态 - 启用 / 禁用
• 实验不活动的时间阈值（以秒为单位）（默认值为7200秒（2小时））。
• The time interval between watchdog cycles in seconds.

配置ClearML Server的非响应看门狗：

1. 在ClearML服务器的/opt/clearml/config/services.conf文件中，添加或编辑tasks.non_responsive_tasks_watchdog部分，并指定看门狗设置。

   例如：

   tasks {
       non_responsive_tasks_watchdog {
           enabled: true
   
           # In-progress tasks that haven't been updated for at least 'value' seconds will be stopped by the watchdog
           threshold_sec: 7200
       
           # Watchdog will sleep for this number of seconds after each cycle
           watch_interval_sec: 900
       }
   }
   
   tip

   如果apiserver.conf文件不存在，请在ClearML Server的/opt/clearml/config目录（或您配置的替代文件夹）中创建您自己的文件，并输入修改后的配置

2. 重启ClearML服务器。

CORS 配置​

要在您的ClearML文件服务器上启用CORS，请编辑ClearML服务器的/opt/clearml/config/apiserver.conf文件的cors部分。例如：

cors {
   origins: "*"

   # Not supported when origins is "*"
   supports_credentials: true
}

查看Flask-Cors文档以获取详细的初始化选项。

自定义UI上下文菜单操作​

创建自定义UI上下文菜单操作，以便在ClearML对象（项目、任务、模型、数据视图或队列）上执行 通过定义在从对象的上下文菜单中点击操作时发出的HTTP请求。

要创建自定义操作，请将操作定义添加到ClearML Server的/opt/clearml/config/services.conf文件中，使用以下格式：

organization.ui_actions: {
  # key is the object type: project / task / model / dataview / queue
  project: [ 
    {
        # name of action which will appear in the context menu
        name: "Action Item Name"
        tooltip: "Custom action 1"
        # action specifies the HTTP request performed by the browser when clicking the action
        action {  
           # request method, options are GET / POST / DELETE
           method: GET  
           # request URL, may contain ${id} which will be replaced by the object's ID
           url: "http://example.com/${id}"
           # Request payload (any string)  
           payload: "{'foo': 'bar'}"
           # Request headers, custom key/value header values  
           headers {  
              # example: specify to the request target that the payload is in JSON format  
              "Content-Type": "application/json"  
           }
        }
     }
  ]
}

该操作将出现在指定对象类型的上下文菜单中：

• 任务、模型、数据视图 - 分别在实验、模型和数据视图表中右键点击一个对象。或者，点击对象以打开其信息标签，然后点击菜单按钮以访问上下文菜单。
• 项目 - 在项目页面 > 点击特定项目卡片上的菜单按钮 以访问其上下文菜单
• 队列 - 在编排页面 > QUEUES 标签中，右键点击队列以访问其上下文菜单

自定义操作总是从特定选定项目打开的上下文菜单中执行。

当点击自定义操作时，UI 会向目标端点 (url) 发送适当的请求，并将模板注入对象的 ID。

用户界面将显示一个提示消息，传达操作成功或失败。