MBTiles 和 PMTiles 文件源

Martin 可以从 PMTile 和 MBTile 文件提供任何类型的瓦片。要从 CLI 提供文件，只需将文件路径或包含 *.mbtiles 或 *.pmtiles 文件的目录放置即可。PMTiles 文件的路径可以是 URL。例如：

martin  /path/to/mbtiles/file.mbtiles  /path/to/directory   https://example.org/path/tiles.pmtiles

您可能还想使用 --save-config my-config.yaml 生成配置文件，然后编辑它并使用 --config my-config.yaml 选项使用它。

tip

有关可用数据源之间差异的更详细说明，请参阅我们的瓦片源说明。

自动发现

对于 mbtiles 或本地 pmtiles 文件，我们支持启动时自动发现。这意味着以下命令将发现目录中的所有 mbtiles 和 pmtiles 文件：

martin  /path/to/directory

warning

对于远程 PMTiles，我们目前不支持自动发现。如果您想实现此功能，请参阅 https://github.com/maplibre/martin/issues/2180

我们目前也不支持在运行时刷新目录。如果您想实现此功能，请参阅 https://github.com/maplibre/martin/issues/288。

从本地文件系统、http 或对象存储提供 PMTiles

PMTiles 源的可用设置取决于后端：

对于本地源，您需要提供路径或 URL。例如：

martin  path/to/tiles.pmtiles

可用的方案是：

file:///path/to/my/file.pmtiles
path/to/my/file.pmtiles

您也可以通过配置文件进行配置：

pmtiles:
  sources:
    tiles: file:///path/to/my/file.pmtiles

对于 HTTP(s)，您需要提供 url。例如：

martin  https://example.com/tiles.pmtiles

可用的 url 方案是：

http://example.com/path.pmtiles
https://example.com/path.pmtiles

如果您想对请求有更多控制，可以在此处配置其他选项：

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

可用的 http 客户端设置

安全选项

配置	描述	示例
`allow_http`	允许非 TLS，即非 HTTPS 连接安全警告：如果启用此选项，攻击者可能能够读取您请求的数据	`true`
`allow_invalid_certificates`	在 https 连接上跳过证书验证安全警告：在使用此方法之前，您应该非常仔细地考虑。如果信任无效证书，则任何站点的任何证书都将被信任使用。这包括过期的证书。这会引入重大漏洞，应该仅作为最后手段或用于测试	`true`

连接选项

配置	描述	示例
`user_agent`	此客户端使用的 User-Agent 头	`martin 1.0.0`
`randomize_addresses`	随机化 DNS 解析产生的地址顺序。这将在更多服务器之间分散连接。	`true`
`connect_timeout`	仅客户端连接阶段的超时	`5s`
`timeout`	从请求开始连接到响应正文完成的超时	`10s`
`pool_idle_timeout`	池最大空闲超时	`5m`
`pool_max_idle_per_host`	每个主机的最大空闲连接数	`10`
`http1_only`	仅使用 http1 连接	`false`
`http2_only`	仅使用 http2 连接	`false`
`http2_keep_alive_interval`	发送 HTTP2 Ping 帧以保持连接活动的间隔。	`15s`
`http2_keep_alive_timeout`	接收保持活动 ping 确认的超时	`15s`
`http2_keep_alive_while_idle`	为空闲连接启用 HTTP2 保持活动 ping	`true`
`http2_max_frame_size`	设置用于 HTTP2 的最大帧大小。

代理设置

配置	描述	示例
`proxy_url`	用于请求的 HTTP 代理	`http://proxy.example.com:8080`
`proxy_ca_certificate`	代理连接的 PEM 格式 CA 证书	`-----BEGIN CERTIFICATE-----` … `-----END CERTIFICATE-----`
`proxy_excludes`	绕过代理的主机列表	`example.com`, `maplibre.org`

important

即使我们将此部分命名为 Amazon S3，它也适用于支持 S3 API 的其他提供商，例如 MinIO、Ceph、Cloudflare R2、hetzner 对象存储等等。

对于 AWS，您需要提供存储桶名称和对象键的前缀。例如：

martin  s3://my-bucket/tiles.pmtiles

可用的 url 方案是：

s3://bucket/path
s3a://bucket/path

如果您想对请求有更多控制，可以在此处配置其他选项：

pmtiles:
  allow_http: true
  sources:
    tiles: s3://bucket/path/to/tiles.pmtiles

tip

所有设置也可在 aws_ 前缀下使用。如果您想拥有不同的云提供商，这会很有用。

可用的 AWS S3 设置

AWS specific Authentication & Credentials

configuration	description	example
`access_key_id`	AWS Access Key	`AKIAIOSFODNN7EXAMPLE`
`secret_access_key`	Secret Access Key	`wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
`session_token` `token`	AWS session token used for temporary credentials	`IQoJb3JpZ2luX2VjEOr...`
`web_identity_token_file`	Web identity token file path for AssumeRoleWithWebIdentity	`/var/run/secrets/eks.amazonaws.com/serviceaccount/token`
`role_arn`	Role ARN to assume with web identity token	`arn:aws:iam::123456789012:role/MyWebIdentityRole`
`role_session_name`	Session name for web identity assumption	`my-session`
`endpoint_url_sts`	Custom STS endpoint for web identity token exchange	`https://sts.amazonaws.com`

AWS specific Connection & Endpoint Configuration

configuration	description	example
`region`	AWS region Defaults to `us-east-1`	`us-west-2`
`bucket` `bucket_name`	Bucket name	`my-app-bucket`
`endpoint` `endpoint_url`	Custom S3 endpoint Defaults to regional endpoint Ensure consistency with `virtual_hosted_style_request` By default, only HTTPS schemes are enabled; enabling HTTP can expose sensitive data Local testing example: `"http://localhost:4566"`	`https://s3.us-west-2.amazonaws.com`
`metadata_endpoint`	Instance metadata endpoint (IPv4 default `http://169.254.169.254`) IPv6 alternative: `http://fd00:ec2::254`	`http://169.254.169.254`
`container_credentials_relative_uri`	ECS container credentials relative URI	`/v2/credentials/12345678-1234-1234-1234-123456789012`
`container_credentials_full_uri`	EKS container credentials full URI	`http://169.254.170.2/v2/credentials/abc123`
`container_authorization_token_file`	Authorization token file for EKS container creds	`/var/run/secrets/eks.amazonaws.com/serviceaccount/token`

AWS specific Request Behavior & Fallbacks

configuration	description	example
`imdsv1_fallback`	Fall back to IMDSv1 if IMDSv2 is not supported (useful for older kube2iam deployments) Security note: AWS recommends IMDSv2 only; IMDSv1 is vulnerable to SSRF attacks Has no effect if not using instance credentials	`true`
`virtual_hosted_style_request`	Use virtual-hosted-style requests instead of path-style Endpoint must match the style Ensures correct bucket addressing for security and routing	`true`
`skip_signature`	Skip signing request Security warning: Unsigned requests may expose credentials or allow tampering if endpoint is public	`true`
`unsigned_payload`	Use unsigned payload option (`UNSIGNED-PAYLOAD`) instead of signed Impact: Checksums for request body are not computed in canonical requests, which can reduce integrity guarantees Default is signed payload with checksum	`true`
`disable_tagging`	Disable tagging objects (useful if unsupported by backend)	`true`
`s3_express`	Enable S3 Express One Zone	`true`
`request_payer`	Enable S3 Requester Pays	`true`

AWS Specific Object Integrity & Encryption

configuration	description	example
`checksum`	Checksum algorithm for uploads	`SHA256`
`server_side_encryption`	Type of server-side encryption: `AES256` (SSE-S3) `aws:kms` (SSE-KMS) `aws:kms:dsse` (DSSE-KMS) `sse-c`	`AES256`
`kms_key_id`	KMS Key ID for SSE-KMS or DSSE-KMS	`arn:aws:kms:us-east-1:123456789012:key/abcd-1234-efgh-5678`
`bucket_key_enabled`	Use bucket’s default KMS key (`true`/`false`)	`true`
`customer_encryption_key`	Base64-encoded 256-bit key for SSE-C	`MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=`

安全选项

配置	描述	示例
`allow_http`	允许非 TLS，即非 HTTPS 连接安全警告：如果启用此选项，攻击者可能能够读取您请求的数据	`true`
`allow_invalid_certificates`	在 https 连接上跳过证书验证安全警告：在使用此方法之前，您应该非常仔细地考虑。如果信任无效证书，则任何站点的任何证书都将被信任使用。这包括过期的证书。这会引入重大漏洞，应该仅作为最后手段或用于测试	`true`

连接选项

配置	描述	示例
`user_agent`	此客户端使用的 User-Agent 头	`martin 1.0.0`
`randomize_addresses`	随机化 DNS 解析产生的地址顺序。这将在更多服务器之间分散连接。	`true`
`connect_timeout`	仅客户端连接阶段的超时	`5s`
`timeout`	从请求开始连接到响应正文完成的超时	`10s`
`pool_idle_timeout`	池最大空闲超时	`5m`
`pool_max_idle_per_host`	每个主机的最大空闲连接数	`10`
`http1_only`	仅使用 http1 连接	`false`
`http2_only`	仅使用 http2 连接	`false`
`http2_keep_alive_interval`	发送 HTTP2 Ping 帧以保持连接活动的间隔。	`15s`
`http2_keep_alive_timeout`	接收保持活动 ping 确认的超时	`15s`
`http2_keep_alive_while_idle`	为空闲连接启用 HTTP2 保持活动 ping	`true`
`http2_max_frame_size`	设置用于 HTTP2 的最大帧大小。

代理设置

配置	描述	示例
`proxy_url`	用于请求的 HTTP 代理	`http://proxy.example.com:8080`
`proxy_ca_certificate`	代理连接的 PEM 格式 CA 证书	`-----BEGIN CERTIFICATE-----` … `-----END CERTIFICATE-----`
`proxy_excludes`	绕过代理的主机列表	`example.com`, `maplibre.org`

对于 Google Cloud，您需要提供存储桶名称和对象键的前缀。例如：

martin  gs://my-bucket/tiles.pmtiles

可用的 url 方案是：

gs://bucket/path

如果您想对请求有更多控制，可以在此处配置其他选项：

pmtiles:
  allow_http: true
  sources:
    tiles: gs://bucket/path/to/tiles.pmtiles

tip

所有设置也可在 google_ 前缀下使用。如果您想拥有不同的云提供商，这会很有用。

可用的 google 设置

Google 特定配置

配置	描述	示例
`service_account` `service_account_path`	服务帐户文件的路径	`some/path/to/file`
`service_account_key`	序列化的服务帐户密钥	`{"private_key": "private_key", "private_key_id": "private_key_id", "client_email":"client_email", "disable_oauth":true}`
`bucket` `bucket_name`	存储桶名称	`foobar-abc`
`application_credentials`	设置应用程序凭据文件的路径	`some/path/to/file`
`skip_signature`	跳过签名请求	`true`

安全选项

配置	描述	示例
`allow_http`	允许非 TLS，即非 HTTPS 连接安全警告：如果启用此选项，攻击者可能能够读取您请求的数据	`true`
`allow_invalid_certificates`	在 https 连接上跳过证书验证安全警告：在使用此方法之前，您应该非常仔细地考虑。如果信任无效证书，则任何站点的任何证书都将被信任使用。这包括过期的证书。这会引入重大漏洞，应该仅作为最后手段或用于测试	`true`

连接选项

配置	描述	示例
`user_agent`	此客户端使用的 User-Agent 头	`martin 1.0.0`
`randomize_addresses`	随机化 DNS 解析产生的地址顺序。这将在更多服务器之间分散连接。	`true`
`connect_timeout`	仅客户端连接阶段的超时	`5s`
`timeout`	从请求开始连接到响应正文完成的超时	`10s`
`pool_idle_timeout`	池最大空闲超时	`5m`
`pool_max_idle_per_host`	每个主机的最大空闲连接数	`10`
`http1_only`	仅使用 http1 连接	`false`
`http2_only`	仅使用 http2 连接	`false`
`http2_keep_alive_interval`	发送 HTTP2 Ping 帧以保持连接活动的间隔。	`15s`
`http2_keep_alive_timeout`	接收保持活动 ping 确认的超时	`15s`
`http2_keep_alive_while_idle`	为空闲连接启用 HTTP2 保持活动 ping	`true`
`http2_max_frame_size`	设置用于 HTTP2 的最大帧大小。

代理设置

配置	描述	示例
`proxy_url`	用于请求的 HTTP 代理	`http://proxy.example.com:8080`
`proxy_ca_certificate`	代理连接的 PEM 格式 CA 证书	`-----BEGIN CERTIFICATE-----` … `-----END CERTIFICATE-----`
`proxy_excludes`	绕过代理的主机列表	`example.com`, `maplibre.org`

对于 Azure，您需要提供帐户名称、容器和路径。例如：

martin  az://account/container.pmtiles

可用的 url 方案是：

az://account/container/path.pmtiles
adl://account/container/path.pmtiles
azure://account/container/path.pmtiles
abfs://account/container/path.pmtiles
abfss://account/container/path.pmtiles

如果您想对请求有更多控制，可以在此处配置其他选项：

pmtiles:
  allow_http: true
  sources:
    tiles: az://account/container/path.pmtiles

tip

所有设置也可在 azure_ 前缀下使用。如果您想拥有不同的云提供商，这会很有用。

可用的 azure 设置

Azure specific Authentication & Credentials

configuration	description	example
`account_name`	Name of the Azure Storage account	`myaccount`
`access_key` `account_key` `master_key`	Master key for accessing the storage account Security note: Keep this key secret; anyone with access can read/write all data in the account	`abcd1234efgh5678ijkl9012mnop3456qrst7890uvwx1234yzab5678cdef9012`
`client_id`	Service principal client ID for OAuth authorization	`12345678-90ab-cdef-1234-567890abcdef`
`client_secret`	Service principal client secret for OAuth authorization Security note: Must be kept confidential	`s3cr3tV@lu3!`
`tenant_id` `authority_id`	Tenant ID used in OAuth flows	`abcdef12-3456-7890-abcd-ef1234567890`
`authority_host`	Authority host used in OAuth flows	`https://login.microsoftonline.com/`
`sas_key` `sas_token`	Shared Access Signature (percent-encoded) Security note: Grants scoped access; treat as sensitive credentials	`sv=2021-06-08&ss=b&srt=sco&sp=rwdl` `&se=2025-12-31T23:59:00Z&sig=ABCDEF1234567890`
`bearer_token` `token`	Bearer token for requests Security note: Token must be protected; use HTTPS	`eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`identity_endpoint` `msi_endpoint`	Endpoint to request a managed identity token	`http://169.254.169.254/metadata/identity/oauth2/token`
`object_id`	Object ID for use with managed identity authentication	`12345678-90ab-cdef-1234-567890abcdef`
`msi_resource_id`	Resource ID for managed identity authentication	`/subscriptions/12345678-90ab-cdef-1234-567890abcdef/` `resourcegroups/myrg/providers/Microsoft.ManagedIdentity/` `userAssignedIdentities/myidentity`
`federated_token_file`	File containing token for Azure AD workload identity federation	`/var/run/secrets/azure/federated-token`
`use_azure_cli`	Use Azure CLI for acquiring access token	`true`

Azure specific Connection & Endpoint Configuration

configuration	description	example
`endpoint`	Override endpoint used to communicate with blob storage	`https://myaccount.blob.core.windows.net`
`object_store_use_emulator` `use_emulator`	Use Azurite storage emulator	`true`
`use_fabric_endpoint`	Use Azure Fabric endpoint (account.dfs.fabric.microsoft.com)	`true`
`container_name`	Container name in the storage account	`mycontainer`

Azure specific Request Behavior & Security Options

configuration	description	example
`skip_signature`	Skip signing requests Security warning: Unsigned requests may expose sensitive data or allow tampering; use only in secure or local environments	`true`
`disable_tagging`	Disable object tagging (useful if backend does not support it)	`true`
`fabric_token_service_url`	URL of Fabric token service	`https://fabric-token.mycompany.com`
`fabric_workload_host`	Host for Fabric workload	`https://workload.fabric.mycompany.com`
`fabric_session_token`	Session token for Fabric Security note: Must be protected; use HTTPS	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`fabric_cluster_identifier`	Identifier for Fabric cluster	`fabric-cluster-01`

安全选项

配置	描述	示例
`allow_http`	允许非 TLS，即非 HTTPS 连接安全警告：如果启用此选项，攻击者可能能够读取您请求的数据	`true`
`allow_invalid_certificates`	在 https 连接上跳过证书验证安全警告：在使用此方法之前，您应该非常仔细地考虑。如果信任无效证书，则任何站点的任何证书都将被信任使用。这包括过期的证书。这会引入重大漏洞，应该仅作为最后手段或用于测试	`true`

连接选项

配置	描述	示例
`user_agent`	此客户端使用的 User-Agent 头	`martin 1.0.0`
`randomize_addresses`	随机化 DNS 解析产生的地址顺序。这将在更多服务器之间分散连接。	`true`
`connect_timeout`	仅客户端连接阶段的超时	`5s`
`timeout`	从请求开始连接到响应正文完成的超时	`10s`
`pool_idle_timeout`	池最大空闲超时	`5m`
`pool_max_idle_per_host`	每个主机的最大空闲连接数	`10`
`http1_only`	仅使用 http1 连接	`false`
`http2_only`	仅使用 http2 连接	`false`
`http2_keep_alive_interval`	发送 HTTP2 Ping 帧以保持连接活动的间隔。	`15s`
`http2_keep_alive_timeout`	接收保持活动 ping 确认的超时	`15s`
`http2_keep_alive_while_idle`	为空闲连接启用 HTTP2 保持活动 ping	`true`
`http2_max_frame_size`	设置用于 HTTP2 的最大帧大小。

代理设置

配置	描述	示例
`proxy_url`	用于请求的 HTTP 代理	`http://proxy.example.com:8080`
`proxy_ca_certificate`	代理连接的 PEM 格式 CA 证书	`-----BEGIN CERTIFICATE-----` … `-----END CERTIFICATE-----`
`proxy_excludes`	绕过代理的主机列表	`example.com`, `maplibre.org`

Keyboard shortcuts

Martin Tile Server Documentation