blockstack/gaia-admin

Gaia Admin Service

镜像概述和主要用途

Gaia Admin Service是一个可与Gaia hub共存的小型服务，支持通过API密钥远程管理Gaia hub。它提供了便捷的配置管理能力，使管理员无需直接操作Gaia hub服务器即可完成关键配置的调整和维护。

核心功能和特性

• 添加、修改和删除白名单写入者
• 设置和更改后端存储驱动
• 配置Gaia hub的连接设置
• 重启Gaia hub使配置更改生效

使用场景和适用范围

适用于需要远程管理Gaia hub的场景，特别是在分布式部署或需要集中管理多个Gaia hub实例的环境中。管理员可通过API接口安全地调整配置，无需直接访问服务器。

使用方法和配置说明

构建和运行

构建服务

从当前目录构建服务：

bash
$ npm run build

本地运行

直接运行服务（可指定配置文件路径）：

bash
$ node lib/index.js [/path/to/config.json]

全局安装

将服务安装为系统命令：

bash
$ sudo npm install -g
$ which blockstack-gaia-admin
/usr/bin/blockstack-gaia-admin

配置

管理服务需要独立于Gaia hub的配置文件，关键配置项包括：

• Gaia hub配置文件的位置
• 用于验证管理请求的API密钥
• 配置更改后重启Gaia hub的命令

示例配置文件

以下是一个示例配置，Gaia hub配置位于/tmp/gaia-config.json，API密钥为"hello"，重启命令通过sh执行：

json
{
  "argsTransport": {
    "level": "debug",
    "handleExceptions": true,
    "timestamp": true,
    "stringify": true,
    "colorize": true,
    "json": true
  },
  "port": 8009,
  "apiKeys": ["hello"],
  "gaiaSettings": {
    "configPath": "/tmp/gaia-config.json"
  },
  "reloadSettings": {
    "command": "/bin/sh",
    "argv": ["-c", "pkill -9 blockstack-gaia-hub; nohup /usr/bin/blockstack-gaia-hub /tmp/gaia-config.json &"],
    "env": {},
    "setuid": 1000,
    "setgid": 1000
  }
}

注意：以下示例假设Gaia admin服务运行在http://localhost:8009。

重启Gaia Hub

POST /v1/admin/reload

管理服务修改Gaia hub配置后，需重启Gaia hub使更改生效。通过以下命令触发重启：

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -X POST http://localhost:8009/v1/admin/reload
{"result":"OK"}

重启命令配置项

• reloadSettings.env：重启命令所需的环境变量键值对
• reloadSettings.setuid：运行命令的用户UID
• reloadSettings.setgid：运行命令的用户组GID

错误处理

• 未提供有效API密钥：返回HTTP 403
• 重启命令执行失败：返回HTTP 500，包含命令退出码和可能的终止信号

获取/设置Gaia Hub设置

GET /v1/admin/config

读取Gaia hub的非驱动相关设置，包括监听端口、验证配置等：

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config
{"config":{"port":4000,"proofsConfig":{"proofsRequired":0}}}

POST /v1/admin/config

更新Gaia hub设置，通过JSON格式提交更改的字段。成功后需重启Gaia hub：

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '{"port": 3001}' http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}

消息格式

POST请求数据需符合以下JSON schema：

javascript
const GAIA_CONFIG_SCHEMA = {
  type: "object",
  properties: {
    validHubUrls: {
      type: "array",
      items: { type: "string", pattern: "^http://.+|https://.+$" },
    },
    requireCorrectHubUrl: { type: "boolean" },
    serverName: { type: "string", pattern: ".+" },
    port: { type: "integer", minimum: 1024, maximum: 65534 },
    proofsConfig: { type: "integer", minimum: 0 },
    whitelist: {
      type: "array",
      items: {
        type: "string",
        pattern: "^[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]+$"
      }
    },
    driver: { type: "string", pattern: ".+" },
    readURL: { type: "string", pattern: "^http://.+$|https://.+$" },
    pageSize: { type: "integer", minimum: 1 },
    bucket: { type: "string", pattern: ".+" },
    cacheControl: { type: "string", pattern: ".+" },
    azCredentials: {
      accountName: { type: "string", pattern: ".+" },
      accountKey: { type: "string", pattern: ".+" },
    },
    diskSettings: {
      storageRootDirectory: { type: "string" }
    },
    gcCredentials: {
      email: { type: "string" },
      projectId: { type: "string" },
      keyFilename: { type: "string" },
      credentials: {
        type: "object",
        properties: {
          client_email: { type: "string" },
          private_key: { type: "string" }
        }
      },
    },
    awsCredentials: {
      assessKeyId: { type: "string" },
      secretAccessKey: { type: "string" },
      sessionToken: { type: "string" }
    }
  }
}

GET请求返回的数据结构与上述schema一致，包含在config对象中。

错误处理

• 未提供有效API密钥：GET和POST均返回HTTP 403
• 提交无效配置值：返回HTTP 400

示例

读写驱动设置

管理存储驱动配置，包括驱动类型、读取URL、分页大小及驱动特定设置。

读取当前驱动设置

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config
{"config":{"driver":"disk","readURL":"http://localhost:4001/","pageSize":20,"diskSettings":{"storageRootDirectory":"/tmp/gaia-disk"}}}

更新驱动设置（以AWS为例）

bash
$ export API_KEY="hello"
$ export AWS_ACCESS_KEY="<hidden>"
$ export AWS_SECRET_KEY="<hidden>"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw "{\"driver\": \"aws\", \"awsCredentials\": {\"accessKeyId\": \"$AWS_ACCESS_KEY\", \"secretAccessKey\": \"$AWS_SECRET_KEY\"}}" http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}

读写白名单

管理Gaia hub的白名单，控制允许写入和列出文件的用户。

读取当前白名单

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" http://localhost:8009/v1/admin/config
{"config":{"whitelist":["15hUKXg1URbQsmaEHKFV2vP9kCeCsT8gUu"]}}

设置白名单（需提供完整列表）

bash
$ export API_KEY="hello"
$ curl -H "Authorization: bearer $API_KEY" -H 'Content-Type: application/json' -X POST --data-raw '["***", "***"]' http://localhost:8009/v1/admin/config
{"message":"Config updated -- you should reload your Gaia hub now."}