企业官网建设流程全解析

StarRocks CREATE FILE 语句详解：安全管理证书、密钥等配置文件的完整指南

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

StarRocks 的CREATE FILE语句用于将证书（如 PEM 格式的 CA 证书、私钥）、密钥、配置文件等小型文件上传并持久化到 StarRocks 集群内部，使其成为数据库命名空间下统一管理的"安全文件"资源。本文基于官方 SQL 参考文档，并结合 StarRocks 前端（FE）源码中FileAnalyzer与SmallFileMgr的实现，完整讲解CREATE FILE的语法、参数、权限要求、底层下载与校验机制，以及配合DROP FILE、SHOW FILE的完整文件生命周期管理实战。

功能概述与适用场景

CREATE FILE是 StarRocks 集群管理中用于创建文件的语句。执行成功后，文件会被上传并持久化存储在 StarRocks 中，之后不再依赖原始下载地址。在同一个数据库中，只有 admin 用户能够创建和删除文件，而所有具备该数据库访问权限的用户都可以使用属于该数据库的文件。

该能力最常见的落地场景是 Kafka 等数据源的加密认证：当您通过 Kafka 加载数据时，StarRocks 会从 Kafka 数据源指定的 catalog（类别）中查找对应的证书文件（如test.pem、client.key），用于 TLS/SSL 连接认证。文件由 StarRocks 统一托管后，加载任务只需引用文件名即可，无需在集群各节点分散存放敏感文件。

权限要求：执行CREATE FILE需要 SYSTEM 级别的FILE权限，可参考 GRANT 文档 进行授权。

基本概念

File（文件）：指在 StarRocks 中创建并保存的文件。文件创建并存储后，StarRocks 会为它分配一个全局唯一 ID（可在SHOW FILE结果的Id列查看）。您可以基于以下三个维度定位一个文件：

• 数据库名（database）：文件所属的数据库命名空间；
• catalog（类别）：文件的业务分类标识，创建时必须指定；
• 文件名（file_name）：文件在数据库内的唯一名称。

文件在 FE 侧的底层管理由SmallFileMgr（小文件管理器）负责，源码位于 SmallFileMgr.java，其职责是下载、校验、序列化与按 ID/数据库/名称索引文件。

语法

CREATE FILE "file_name" [IN database] [properties]

参数说明

properties 配置项

从源码看，properties支持的关键字在 CreateFileStmt.java 中被定义为常量：

• catalog（默认值DEFAULT）：类别；
• url：下载地址；
• md5：可选校验值；
• save_content：该属性当前在 StarRocks 中尚未支持。

FileAnalyzer的analyzeCreateFileProperties方法（见 FileAnalyzer.java）会在解析阶段做如下校验：

• properties中只能出现上述白名单关键字，出现其他关键字会抛出xxx is invalid property语义异常；
• url缺失或为空会抛出download url is missing异常；
• 显式声明save_content会抛出'save_content' property is not supported yet异常。

另外需要特别留意的是文件大小限制：SmallFileMgr.downloadAndCheck会先通过 HTTPHEAD请求探测Content-Length，若长度不可用或超过 FE 配置项max_small_file_size_bytes（默认 100 MB），创建操作将直接失败，防止超大文件占用 FE 内存与 BDBJE 存储。

使用示例

示例一：在类别 kafka 下创建名为 test.pem 的文件

CREATE FILE "test.pem" PROPERTIES ( "url" = "https://starrocks-public.oss-cn-xxxx.aliyuncs.com/key/test.pem", "catalog" = "kafka" );

示例二：在 my_database 数据库的 my_catalog 类别下创建 client.key，并携带 MD5 校验

CREATE FILE "client.key" IN my_database PROPERTIES ( "url" = "http://test.bj.bcebos.com/kafka-key/client.key", "catalog" = "my_catalog", "md5" = "b5bb901bf10f99205b39a46ac3557dd9" );

第二个示例中的md5值应在上传前通过md5sum client.key等命令预先计算得出，确保下载内容完整且未被篡改。

底层执行流程：下载、校验与持久化

了解CREATE FILE在 FE 内部的执行链路，有助于定位问题、评估风险。整体流程如下：

1. 解析与分析：AstBuilder将 SQL 解析为CreateFileStmt抽象语法树节点，FileAnalyzer负责补全默认数据库名并校验文件名与properties（见 FileAnalyzer.java）。
2. 权限检查：AuthorizerStmtVisitor校验当前用户是否拥有 SYSTEM 级FILE权限。
3. 执行下载与落库：SmallFileMgr.createFile调用downloadAndAddFile，再进入downloadAndCheck（见 SmallFileMgr.java）完成以下关键步骤：
   • 以 10 秒超时建立 HTTP 连接，发起HEAD请求获取内容长度；
   • 校验内容长度有效且不超过Config.max_small_file_size_bytes；
   • 流式读取文件内容，同时用MessageDigest（MD5）边读边计算摘要；
   • 若指定了md5参数，比对计算结果与期望值，不一致则抛出Invalid md5sum of file in url异常并中止创建；
   • 读取完成后通过GlobalStateMgr.getCurrentState().getNextId()为文件分配全局唯一 ID；
   • 构造SmallFile对象：文件内容以 Base64 编码保存在 FE 内存，并随元数据写入 BDBJE 持久化，同时记录大小、MD5 与isContent=true标记。

需要说明的是，源码中save_content路径在分析阶段即被禁止，因此当前版本的文件内容会被完整保存在 FE 内存中，这也正是文件大小受max_small_file_size_bytes限制、且不适合存放大型二进制制品的原因。

文件生命周期管理：查看与删除

查看文件：SHOW FILE

创建完成后，可通过SHOW FILE查看数据库下的文件信息（无需 SYSTEM 级权限，只需具备文件所属数据库的任意权限）。详见 SHOW_FILE.md。

mysql> SHOW FILE FROM test_db; +-------+---------+----------------+---------------+----------+-----------+----------------------------------+ | Id | DbName | GlobalStateMgr | FileName | FileSize | IsContent | MD5 | +-------+---------+----------------+---------------+----------+-----------+----------------------------------+ | 24016 | test_db | kafka | my_secret.txt | 43 | true | a7c71293869ec817515e61a9f0cfb48e | | 24072 | test_db | configs | db_config.txt | 18 | true | b1a32aaac8a739eac7b55a4364df8876 | +-------+---------+----------------+---------------+----------+-----------+----------------------------------+ 2 rows in set (0.01 sec)

返回列含义：

• Id：文件的全局唯一 ID；
• DbName：文件所属数据库；
• GlobalStateMgr：文件所属类别（对应创建时指定的catalog）；
• FileName：文件名；
• FileSize：文件大小，单位为字节；
• IsContent：文件内容是否已完整上传存储（true 或 false）；
• MD5：文件校验所用消息摘要。

删除文件：DROP FILE

删除文件需 SYSTEM 级FILE权限。删除时文件会同时从 FE 内存与 BDBJE 中移除。详见 DROP_FILE.md。

DROP FILE "ca.pem" properties("catalog" = "kafka");

DROP FILE的properties中catalog 为必填项——FileAnalyzer会校验 properties 中只允许出现catalog关键字，且其值不能为空，否则抛出globalStateMgr name is missing异常。

实践建议与注意事项

• URL 仅支持无需认证的 HTTP(S) 地址：下载完成后 URL 即可废弃；请勿在创建后依赖原 URL 的可用性。
• 务必指定catalog：对于 Kafka 等数据源加载场景，catalog是文件检索的命名空间，需与数据源配置保持一致。
• 善用md5校验：对证书、密钥等关键文件，建议预先计算 MD5 并随properties传入，防止下载被劫持或文件损坏。
• 控制文件大小：文件内容保存在 FE 内存中并持久化到 BDBJE，受max_small_file_size_bytes（默认 100 MB）限制，仅适合存放小型配置文件。
• 严格管控权限：仅 admin 或获得 SYSTEM 级FILE权限的用户可创建、删除文件；文件一旦创建即对整个数据库可见，请确保文件名与内容不泄露敏感信息。
• 相关语句配套使用：完整的文件管理由CREATE FILE、SHOW FILE、DROP FILE三个语句构成，相关文档均位于 cluster-management/file 目录，可按需组合使用。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks