Tiled服务配置参考

这是一份综合参考文档。另请参阅《使用配置文件提供数据服务》以获取包含示例的实践指南。

配置合并规则

若存在多个配置文件：

认证配置：至多只能有一个配置文件包含 authentication: 部分。
树结构配置：多个配置文件可以包含 tree: 部分，但如果相同path出现在多个文件中，或指定了冲突的路径（例如 /a 和 /a/b），将引发异常。
允许来源配置：如果存在多个 allow_origins 部分，其内容将被合并。
其他顶层配置：当前未定义其他顶层配置冲突的处理方式，未来可能会制定严格规则。

以下内容基于用于读取配置文件时验证这些配置文件的 schema 自动生成。

环境变量表达式

所有使用环境变量的值（格式为 $VAR 或$ {VAR}）将被展开（即用其对应值填充）。

trees

该部分包含一个或多个条目，每个条目描述一个要提供的 Tree。

trees[item].tree

要提供的树的类型. 这可以是:

字符串catalog, tiled.catalog:from_uri的简写
Tree实例的导入路径。
指向一个可返回Tree的可调用对象（函数或类型）的导入路径。对于这种情况，也必须同时提供下面所述的 args: 参数。

在导入路径中，包/模块之间用点号分隔，而对象名称则用冒号与前面的模块路径分隔。

bash 复制代码

# Tree实例
tiled.examples.generated_minimal:tree
tiled.examples.generated:tree
my_python_module:my_tree_instance

# 返回Tree实例的可调用对象
tiled.catalog:from_uri
my_python_module:CustomTree

trees[item].path

将此Tree挂载的URL子路径。如果只提供一个Tree，"/"是很好的默认选择。

trees[item].args

若 tree: 设置为 files 或某个返回 Tree 的可调用对象，则必须包含此参数。它可以包含要传递给该可调用对象的命名参数。如果该可调用对象不需要参数，它可以为空或为 null。

示例:

bash 复制代码

- path: "/"
  tree: catalog
  args:
    uri: "catalog.db"

streaming_cache

流式缓存数据库

streaming_cache.uri

连接字符串, 例如: redis://:password@host:port

streaming_cache.data_ttl

流式数据的最大保留时间(秒)

streaming_cache.seq_ttl

流式序列计数器的最大保留时间(秒)

streaming_cache.socket_timeout

配置Redis客户端. 默认值为1天，以便支持持久存活的流式客户端能够在长时间休眠期间维持连接。

streaming_cache.socket_connect_timeout

配置Redis客户端. 默认是10(秒).

media_types.array

为数组结构添加额外的导出器（亦称序列化器）。

其格式为：将媒体类型（亦称 MIME 类型）被映射到可导入的函数，例如：

bash 复制代码

application/x-my-custom-format: package.module:exporter_function

media_types.dataframe

为数据帧结构添加额外的导出器（亦称序列化器）。

其格式为：将媒体类型（亦称 MIME 类型）被映射到可导入的函数，例如：

bash 复制代码

application/x-my-custom-format: package.module:exporter_function

media_types.dataset

为xarray数据集结构添加额外的导出器（亦称序列化器）。

其格式为：将媒体类型（亦称 MIME 类型）被映射到可导入的函数，例如：

bash 复制代码

application/x-my-custom-format: package.module:exporter_function

file_extensions

此功能支持便捷别名 ?format=ext，用于请求与某个文件扩展名 ext 相对应的格式。

内容应将文件扩展名映射到媒体类型（亦称 MIME 类型），例如：

bash 复制代码

ext: application/x-my-custom-format

验证

此部分描述是否以及如何验证用户.

authentication.providers

authentication.providers[item].provider

用于在Tiled的URL及内部记录中唯一标识此身份提供者的、符合URL规范的字符串。

authentication.providers[item].authenticator

要使用验证器的类型.

这些通常来自 tiled.authenticators 模块，但用户自定义的认证器也可使用。

这以导入路径的形式给出。在导入路径中，包/模块之间用点号分隔，对象本身则用冒号与前面的路径分隔。

示例:

bash 复制代码

authenticator: tiled.examples.DummyAuthenticator

authentication.providers[item].args

传递给验证器的指定名称参数. 如果没有, args可以省略或者空.

示例:

bash 复制代码

authenticator: tiled.examples.PAMAuthenticator
args:
  service: "custom_service"

authentication.tiled_admins

为具有这些身份的用户授予'管理员'角色。

authentication.tiled_admins[item].provider

authentication.tiled_admins[item].id

authentication.secret_keys

用于签署安全令牌的密钥。

生成密钥时，必须创建难以猜测的随机数，并确保每次启动服务器时都使用不同的密钥。以下是两种同样可靠的生成安全密钥的方法......

用opnssl:

bash 复制代码

openssl rand -hex 32

用python

bash 复制代码

python -c "import secrets; print(secrets.token_hex(32))"

authentication.allow_anonymous_access

如果为 true，则允许对未通过访问策略特别控制的所有条目进行未经身份验证的公开访问。默认为false.

authentication.single_user_api_key

单用户部署中使用的 API 密钥。

生成密钥时，必须创建难以猜测的随机数，并确保每次启动服务器时都使用不同的密钥。以下是两种同样可靠的生成安全密钥的方法......

用opnssl:

bash 复制代码

openssl rand -hex 32

用python

bash 复制代码

python -c "import secrets; print(secrets.token_hex(32))"

此设置控制访问令牌的刷新频率。该过程对用户透明，仅影响系统性能。由于访问令牌无法撤销，因此其有效期应设置较短。默认时长为900秒（15分钟）。单位是秒.

authentication.refresh_token_max_age

非活跃会话（未刷新令牌的会话）的超时时间。单位是秒.

authentication.session_max_age

活跃会话在达到此限制后也会超时，用户需重新提交凭证。默认情况下，该限制未启用，活跃会话不会被关闭。

数据库

database.uri

当Tiled配置了认证提供者时，它会使用SQL数据库来持久化存储与身份、会话和密钥相关的信息。（若未使用认证提供者，则无需数据库。）

如果Tiled配置了上述认证提供者但未指定数据库URI，则将默认使用 sqlite:///file:authdb?mode=memory&cache=shared&uri=true（即进程内存中的SQLite数据库）。

Tiled官方支持PostgreSQL和SQLite，但任何SQLAlchemy支持的数据库引擎理论上均可使用。

database.init_if_not_exists

如果数据库为空, 初始化验证数据库表.

database.pool_pre_ping

若为 true（默认值），则启用悲观连接测试。推荐使用此设置。

database.pool_size

连接池大小. 默认是5. 最小2.

database.max_overflow

连接池最大溢出. 默认5.

访问控制

这部分描述哪些用户可以见到哪些条目.

access_control.access_policy

AccessPolicy对象编码规则，用于定义哪些用户可以查看哪些条目。若设置此策略（即不为null），则必须同时设置认证器。

示例:

bash 复制代码

access_policy: "tiled.access_control.access_policies:TagBasedAccessPolicy"
args:
  provider: "pam"
  tags_db:
    uri: "file:compiled_tags.sqlite"
  access_tags_parser: "tiled.access_control.access_tags:AccessTagsParser"

access_control.args

Object_cache

弃用. 这种对象缓存已经被移除. 此配置不再有效果.

object_cache.available_bytes

弃用. 这种对象缓存已经被移除. 此配置不再有效果.

object_cache.log_level

弃用. 这种对象缓存已经被移除. 此配置不再有效果.

response_bytesize_limit

响应的最大字节大小，以字节为单位。考虑到数据会读入服务器内存，通常应分块获取，因此默认值设置较低（300 MB）。

exact_count_limit

容器的最大项目数量阈值：当容器内项目数超过此值时，/metadata和/search端点将返回确切数；若无法获得估算值，此数值将作为估算值的下限。默认值为100。

catalog_pool_size

目录数据库的连接池大小. 默认是5.

catalog_max_overflow

如果数据库驱动支持，目录数据库连接池的最大溢出连接数，即允许在基础连接池容量之外创建的额外连接数量。默认值为10。

storage_pool_size

存储数据库的连接池的大小. 默认是5.

storage_max_overflow

存储数据库的连接池的最大溢出大小. 默认是10.

allow_origins

该域名列表允许托管于其他域名的Web应用向Tiled服务器发起请求。

示例:

bash 复制代码

allow_origins:
  - https://chart-studio.plotly.com

uvicorn

uvicorn.host

将套接字绑定到此主机。使用 --host 0.0.0.0 可使应用在本地网络中访问。支持 IPv6 地址，例如 --host '::'。默认值为 '127.0.0.1'。

uvicorn.port

用此端口绑定套接字. 默认8000.

uvicorn.workers

使用多工作进程。默认情况下，若已设置 $WEB_CONCURRENCY 环境变量则以其值为准，若未设置该变量，则默认为 1。

uvicorn.root_path

当应用程序部署在代理服务器之后，且通过特定路径前缀提供访问时，请为其配置 root_path。

uvicorn.proxy_headers

启用/禁用 X-Forwarded-Proto、X-Forwarded-For、X-Forwarded-Port 头部以获取远程地址信息。默认启用，但其信任范围受限于 forwarded-allow-ips 配置中指定的连接 IP。

uvicorn.forwarded_allow_ips

代理头部可信 IP 列表，以逗号分隔。若设置了 $FORWARDED_ALLOW_IPS 环境变量，则以其值为准；否则默认值为 '127.0.0.1'。通配符 '*' 表示始终信任。

uvicorn.ssl_keyfile

SSL 键文件

uvicorn.ssl_certfile

SSL证书文件

uvicorn.ssl_keyfile_password

SSL keyfile密码

uvicorn.ssl_version

要用的SSL版本. 默认2.

uvicorn.ssl_cert_reqs

是否需要客户端证书. 默认0

uvicorn.ssl_ca_cert

CA证书文件.

uvicorn.ssl_ciphers

使用的加密套件. 默认TLSv1.

metrics

metrics.prometheus

Prometheus 指标收集功能的启用/禁用设置。默认值为 true。

specs

用于上传数据接受的规格列表，并可选择性地进行验证。

以规格名称映射到可导入函数的形式给出，例如：

bash 复制代码

- spec: my-spec
  validator: package.module:validator_function

验证函数的签名应为

bash 复制代码

f(spec: tiled.structures.core.Spec,
  metadata: dict[str, Any],
  entry: Optional[tiled.adapters.protocols.AnyAdapter],
  structure_family: Optional[tiled.structures.core.StructureFamily],
  structure: dict[str, Any]) -> Optional[dict[str, Any]]

成功时返回 None 或一个可能经过修改的元数据对象，失败时则抛出 tiled.validation_registration.ValidationError 异常。如果返回了元数据对象，它将被包含在 POST 请求的响应中返回给客户端。structure_family 和 structure 是可选参数，默认值为 None；当指定时，它们被假定为用于描述新节点的结构。同样，entry 参数也是可选的，默认值为 None；当指定时，它关联到其规格和元数据正在被修改的节点。

specs[item].spec

specs[item].validator

reject_undeclared_specs

若为 true，则任何使用未在此配置文件中声明的"规格"上传的数据将被拒绝。默认情况下，此设置为 false------即宽松模式。

expose_raw_asserts

若为 true（默认值），则允许客户端下载支持其被授权读取的节点的原始资产数据。

routers

包含到应用程序中的APIRouter实例的导入路径列表。在导入路径中，包/模块之间用点号分隔，对象名称则用冒号与前面的模块路径分隔。

示例:

bash 复制代码

routers:
  - bluesky_tiled_plugins.routers:my_router

使用配置文件提供数据

我需要一个配置文件吗?

简易Tiled服务器可以在无需配置文件的情况下运行。示例：

一个已有数据的只读公共服务器

bash 复制代码

(EPICS) blctrl@blctrl-s3:~$ tiled serve  directory --public tiled-file/
Creating catalog database at /tmp/tmpvg7hglxf/catalog.db

    Navigate a web browser or connect a Tiled client to:

    http://127.0.0.1:8000?api_key=2a5413b5313d056182180a1f2169f55718630598c78b6815903c0d90492769e4

一个临时的可写目录

bash 复制代码

(EPICS) blctrl@blctrl-s3:~$ tiled serve catalog --temp
Initializing temporary storage in /tmp/tmpgsziotkc
  catalog database:          /tmp/tmpgsziotkc/catalog.db
  writable file storage:     /tmp/tmpgsziotkc/data
  writable tabular storage:  /tmp/tmpgsziotkc/data.duckdb

一个持久可写目录:

bash 复制代码

EPICS) blctrl@blctrl-s3:~/tiled-file$ tiled catalog init catalog.db 
Database sqlite+aiosqlite:///catalog.db is new. Creating tables.
Database initialized.
(EPICS) blctrl@blctrl-s3:~/tiled-file$ tiled serve catalog catalog.db --write data/

当需要进行高级部署时，配置文件是必需的，例如：

启用多用户身份认证
在诸如 /raw_data 和 /processed_data 等不同路径前缀下，提供多个不同配置的数据源

配置文件应放置于何处？

配置文件（或包含多个配置文件的目录）的路径应在启动服务器时明确指定，例如：

bash 复制代码

tiled serve config my_config_file.yml

或

bash 复制代码

tiled serve config my_config_directory/

另外, 如果未在命令行中指定, 配置路径可以通过环境变量传递.

bash 复制代码

TILED_CONFIG=my_config_file.yml tiled serve config
TILED_CONFIG=my_config_directory/ tiled serve config

最后, 如果环境变量还没有, 设置默认位置./config.yml.

bash 复制代码

tiled serve config  # 如果未设置环境变量TILED_CONFIG, 使用./config.yml

但出于明确, 推荐显式地指定配置位置.

请参阅《安全与访问控制》章节中关于身份验证与授权的示例。

示例

请参阅 Tiled 代码仓库根目录下的 example_configs/ 文件夹。