設定檔

本章節描述 Sylvia-IoT 的設定格式和用途。

Sylvia-IoT 的設定支援四種來源，優先權依序為（高到低）：

• JSON5 設定檔
• 命令列參數
• 環境變數
• 內部預設值（不一定存在，如為必填且不提供則會有錯誤訊息）

JSON5 可以參考範例檔案，該檔案提供了完整的設定項目。 本章節將會提供對應的說明。以下為設定的慣例：

• JSON5 的巢狀形式會以 . 來表示。
• 命令列參數遇到 JSON5 的巢狀會以 . 來表示。
• 命令列參數遇到 JSON5 為駝峰的情形，會以全小寫或是 - 尾隨小寫來表示。以下為例子：
  • JSON5 的 server.httpPort 對應 --server.httpport。
  • JSON5 的 broker.mqChannels 對應 --broker.mq-channels。
• 環境變數全大寫。
• 環境變數遇到 JSON5 的巢狀會以 _ 來表示。
• 環境變數遇到 JSON5 為駝峰的情形，會以全大寫或是 _ 分開來表示。以下為例子：
  • JSON5 的 server.httpPort 對應 SERVER_HTTP_PORT
  • JSON5 的 broker.mqChannels 對應 BROKER_MQCHANNELS

接下來是完整的表格說明。

如有標示 參照範例 表示範例的 JSON5 有提供，或是可以使用 CLI help 指令查看支援的選項。

共同設定

詳細說明

• 目前還未使用根憑證。
• 必須同時使用憑證和私鑰才能啟用 HTTPS 服務。

API Scopes

所有的 API 都需要透過在系統註冊的客戶端（client）以及訪問令牌（access token）才能存取。每一個令牌會記錄所屬的客戶端，只有經過授權的客戶端才能存取 API。

當某個 API 對應的 apiScopes 的設定被開啟時，除非客戶端在註冊的時候有啟用這些 scope 並被使用者授權，取得的令牌才能存取該 API。

命令列參數和環境變數都要是 JSON string，舉例：

--auth.api-scopes='{"auth.tokeninfo.get":[]}'

您可以自行定義 scope 名稱，並套用到各個 API scope 中。可以參考下面認證服務的範例。

認證服務（auth）

詳細說明

• templates（樣板）
  • 使用 OAuth2 authorization code 授權流程需要使用的網頁。sylvia-iot-auth 有提供預設的頁面，而 Sylvia-IoT 允許您自訂符合自己風格的網頁。
  • 樣板使用 Jinja2 格式（相依 tera 套件）。
  • 命令列參數和環境變數都要用 JSON string，比如

    --auth.templates='{"login":"xxx"}'
    

  • 詳細說明請參考 OAuth2 認證。
• API scopes
  • auth 模組提供了以下幾個 scope 可供設定給對應的 API，限制 client 可以存取的範圍：
    • auth.tokeninfo.get: 授權 client 讀取令牌的資料。
      • GET /api/v1/auth/tokeninfo
    • auth.logout.post: 授權 client 將令牌登出。
      • POST /auth/api/v1/auth/logout
    • user.get: 授權 client 存取目前使用者的個人資料。
      • GET /api/v1/user
    • user.path: 授權 client 修改目前使用者的個人資料。
      • PATCH /api/v1/user
    • user.get.admin: 授權 client 取得系統所有使用者的資料。
      • GET /api/v1/user/count
      • GET /api/v1/user/list
      • GET /api/v1/user/{userId}
    • user.post.admin: 授權 client 在系統建立新的使用者。
      • POST /api/v1/user
    • user.patch.admin: 授權 client 修改系統任意使用者的資料。
      • PATCH /api/v1/user/{userId}
    • user.delete.admin: 授權 client 刪除系統任意使用者的資料。
      • DELETE /api/v1/user/{userId}
    • client.get: 授權 client 存取得系統所有客戶端資料。
      • GET /api/v1/client/count
      • GET /api/v1/client/list
      • GET /api/v1/client/{clientId}
    • client.post: 授權 client 在系統建立新的客戶端。
      • POST /api/v1/client
    • client.patch: 授權 client 修改系統任意客戶端的資料。
      • PATCH /api/v1/client/{clientId}
    • client.delete: 授權 client 刪除系統任意客戶端的資料。
      • DELETE /api/v1/client/{clientId}
    • client.delete.user: 授權 client 刪除系統任意使用者的所有客戶端。
      • DELETE /api/v1/client/user/{userId}
  • 舉例，在您的服務定義如下的 scope：
    • api.admin: 僅能授權移除使用者的所有客戶端。
    • api.rw: 可以讀寫除了 DELETE /api/v1/client/user/{userId} 的所有 API。
    • api.readonly： 只能存取 GET API。
    • 取得令牌資料和登出，這兩個動作開放所有客戶端可以使用。

    "auth": {
        ...
        "apiScopes": {
            "auth.tokeninfo.get": [],
            "auth.logout.post": [],
            "user.get": ["api.rw", "api.readonly"],
            "user.patch": ["api.rw"],
            "user.post.admin": ["api.rw"],
            "user.get.admin": ["api.rw", "api.readonly"],
            "user.patch.admin": ["api.rw"],
            "user.delete.admin": ["api.rw"],
            "client.post": ["api.rw"],
            "client.get": ["api.rw", "api.readonly"],
            "client.patch": ["api.rw"],
            "client.delete": ["api.rw"],
            "client.delete.user": ["api.admin"],
        },
        ...
    }
    

    • 以這個例子，註冊的客戶端可以任意勾選這三種 scope。之後使用者會在授權頁面得知這些訊息，並且決定是否授權客戶端。

消息代理服務（broker）

詳細說明

• 指定認證服務位址（broker.auth）的用意在檢查呼叫 API 的令牌的合法性，包含使用者帳號與客戶端。

• MQ channels:

  • 由於 Sylvia-IoT 訊息代理服務是決定效能的關鍵模組，會將許多設定放在記憶體中。這些設定需要透過 控制訊息（control channel message） 將 API 變更的內容透過訊息佇列傳遞到叢集的各個執行個體中。
    • 相關訊息請見 快取 章節。
  • data 是 資料訊息（data channel message），將所有資料記錄到 sylvia-iot-data 模組中。
    • 不指定參數（或是 JSON5 設定 null）就會不儲存任何資料。
    • 相關訊息請見 資料流 章節。

• API scopes: 請參考認證服務的說明。

核心管理服務（coremgr）

詳細說明

• MQ channels:
  • data 是 資料訊息（data channel message）
    • 目前 coremgr 支援紀錄 GET API 以外的 HTTP 請求內容，開啟資料通道即可紀錄 API 使用歷程。
    • 不指定參數（或是 JSON5 設定 null）就會不儲存任何資料。

核心管理服務管理介面（coremgr-cli）

資料服務（data）