Label Studio 接入 Google Cloud StorageGCS完整指南源/目标存储配置、WIF 与 GKE 服务账号模拟【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio本文基于 Label Studio 开源仓库的官方指南 storage_gcp.md 与 GCS 存储模块源码io_storages/gcs系统讲解如何将 Google Cloud StorageGCS桶接入 Label Studio既作为源存储动态导入标注任务也作为目标存储回传标注结果同时覆盖预签名 URL 与平台代理两种数据加载模式、Workload Identity FederationWIF临时凭据方案、GKE 服务账号模拟方案以及 IP 过滤加固。读完本文你可以独立完成从 GCS 桶权限配置、CORS 设置到 Label Studio 内源/目标存储连接创建与同步的完整落地并理解每一步背后的源码实现。GCS 在 Label Studio 中的角色与整体工作流Label Studio 支持将外部存储动态接入项目源存储Source Storage用于扫描桶中的对象并生成标注任务目标存储Target Storage用于在标注完成后把注解写回桶中。官方文档 Cloud storage for projects 指出每个源/目标存储连接都是项目级的同一个项目可以挂接多个桶作为源或目标。从源码看GCS 支持在 GCSImportStorage导入与 GCSExportStorage导出两个模型上实现它们共享 GCSStorageMixin 提供的公共字段模型字段对应 UI 表单说明bucketBucket NameGCS 桶名称prefixBucket Prefix桶内目录前缀如data-set-1或data-set-1/subfolder-2regex_filterFile Filter Regex用于过滤桶内对象的正则表达式use_blob_urlsImport Methodtrue表示每个对象创建一个任务Files 模式false表示把 JSON/JSONL 当作任务定义Tasks 模式google_application_credentialsGoogle Application Credentials服务账号凭据 JSON 的文本内容安全字段序列化时会被剔除google_project_idGoogle Project ID桶所在的 Google 项目 ID导入存储还有三个特有字段GCSImportStorageBasepresign默认True控制是否生成预签名 URL、presign_ttl预签名 URL 有效期分钟、recursive_scan是否递归扫描子目录。第一步配置 GCS 桶的访问权限在 Label Studio 中创建任何 GCS 连接之前需要先完成三项前置工作详见 storage_gcp.md。1. 启用对桶的程序化访问按照 Google Cloud Storage 的 Client Libraries 文档为你的 GCS 桶配置程序化访问。Label Studio 后端实际通过google-cloud-storagePython 客户端与 GCS API 交互见 io_storages/gcs/utils.py因此对桶的 API 访问能力是硬性前提。2. 设置认证与 IAM 角色你的账号必须具备以下权限项目级Service Account Token Creatorroles/iam.serviceAccountTokenCreator角色项目级Storage Object Viewerroles/storage.viewer角色桶级storage.buckets.get访问权限如果使用 WIFWorkload Identity Federation方案则按后文 WIF 服务账号权限 配置。3. 配置 CORS仅当使用预签名 URL时才需要配置 CORS——因为标注者的浏览器会直接向 GCS 发起跨域 GET 请求。如果使用平台代理模式则无需 CORS详见 storage.md 中 Pre-signed URLs vs Storage proxies。官方推荐的 CORS 配置示例如下。先用echo生成cors-config.jsonecho [ { origin: [*], method: [GET], responseHeader: [Content-Type,Access-Control-Allow-Origin], maxAgeSeconds: 3600 } ] cors-config.json再将YOUR_BUCKET_NAME替换为真实桶名并应用gsutil cors set cors-config.json gs://YOUR_BUCKET_NAME在生产环境中建议把origin收敛为 Label Studio 部署的实际域名而不是*。第二步使用 Google Application Credentials 建立标准 GCS 连接这是社区版即可用的基础方案认证基于服务账号的长期 JSON 密钥。获取凭据 JSON 文件在 Google Cloud Console 中依次操作进入IAM Admin Service Accounts选择需要凭据的服务账号没有则新建在账号详情页进入Keys标签点击Add Key Create new key选择JSON密钥类型并点击Create浏览器会自动下载生成好的 JSON 文件。如果使用服务账号授权访问 GCP请确保已通过gcloud auth activate-service-account激活该账号。创建源存储连接在 Label Studio 中打开项目进入Settings Cloud Storage Add Source Storage选择Google Cloud Storage并点击Next。Configure Connection连接配置填写以下字段后点击Test connection验证字段说明Storage Title用于标识该存储连接的名称Bucket NameGCS 桶名称Google Application Credentials你创建的服务账号凭据 JSON 内容。On-prem 用户可留空改用GOOGLE_APPLICATION_CREDENTIALS环境变量或 Application Default CredentialsADC让用户无需手动配置凭据见下文 ADC 章节Google Project ID桶所在 Google 项目的 ID如my-label-studio-project可在 Console 的IAM Admin Settings中查看Use pre-signed URLs (On) / Proxy through the platform (Off)决定数据加载方式详见下文预签名 URL 与平台代理章节Expire pre-signed URLs (minutes)控制预签名 URL 的有效时长表单默认 15 分钟对应form_layout.yml中presign_ttl的value: 15这些字段与源码模型一一对应Test connection会调用 GCS.validate_connection该函数用当前凭据创建客户端、get_bucket校验桶存在若填写了 prefix 还会用list_blobs(prefix..., max_results1)检查该前缀下是否有对象没有则抛出No blobs found错误。Import Settings Preview导入设置与预览点击Load preview可以确认将要同步的数据是否正确字段说明Bucket Prefix可选。桶内目录名如data-set-1或data-set-1/subfolder-2Import Method选择每个文件创建一个任务或用 JSON/JSONL/Parquet 文件定义每个任务的数据File Name Filter用正则表达式过滤桶对象.*表示收集所有对象Scan all sub-folders开启后递归扫描容器内所有子目录其中 Import Method 对应源码中的use_blob_urls字段Files模式下get_data()直接构造{settings.DATA_UNDEFINED_NAME: gs://bucket/key}形式的任务models.pyTasks模式下则读取 JSON/JSONL 内容并调用load_tasks_json解析models.py。File Name Filter 对应regex_filter在 GCS.iter_blobs 中通过re.compile(str(regex_filter))编译后逐对象匹配不匹配的对象直接跳过Scan all sub-folders对应recursive_scan为True时list_blobs不带delimiter递归列举全部对象否则以delimiter/仅列出当前层级。Review Confirm确认与同步确认无误后点击Save Sync立即同步或点击Save保存设置稍后再同步。也可以调用 import storage sync API 触发同步。创建目标存储连接进入Settings Cloud Storage Add Target Storage选择Google Cloud Storage并点击Next填写字段说明Storage Title存储连接名称Bucket NameGCS 桶名称Bucket Prefix可选。导出注解时写入的桶内目录Google Application Credentials同源存储说明Google Project ID桶所在项目 IDCan delete objects from storage开启后在 Label Studio 中删除标注时同步删除桶中的注解对象要求凭据具备删除对象的权限保存后点击Sync完成导出连接配置。目标存储的写入逻辑在源码中非常清晰标注被保存post_save信号后export_annotation_to_gcs_storages 会通过 Redis 异步任务把注解写入所有关联的 GCS 导出存储GCSExportStorage.save_annotation 把注解序列化为 JSON按prefix / key作为对象名blob.upload_from_string(json.dumps(ser_annotation))上传。删除时delete_annotation_from_gcs_storages 会检查storage.can_delete_objects只有开启该选项才真正调用blob.delete()——这正是 UI 上Can delete objects选项的源码级验证对应测试见 test_cloud_export_race_and_delete.py。预签名 URL 与平台代理两种数据加载模式源存储创建时有一个关键开关Use pre-signed URLs (On) / Proxy through the platform (Off)它决定标注媒体数据如何从桶加载到标注者的浏览器详见 storage.md。对比项预签名 URL默认开启平台代理关闭预签名数据流Label Studio 生成带时效的 HTTPS 链接浏览器收到 HTTP 303 重定向后直接从云存储下载媒体后端从云存储下载文件后流式转发给浏览器流量全部经过 Label Studio 服务器性能通常更快、可扩展性更好占用更多 Label Studio worker 资源可能稍慢配置要求需要桶上配置正确的 CORS 和签名权限无需 CORS、无需签名权限安全边界媒体文件尽量与 Label Studio 网络隔离数据始终处于 Label Studio/网络边界内每次请求都执行任务级访问检查缓存文件也会受访问控制约束大文件—以 8 MB 分块流式传输见下文环境变量从源码看预签名由 GCS.generate_http_url 实现presignTrue时调用blob.generate_signed_url(versionv4, expirationtimedelta(minutespresign_ttl), methodGET)生成 v4 签名 URLpresignFalse时则把对象下载下来编码为data:...;base64,...的 data URL。presign开关保存在GCSImportStorage.presign字段默认True见 models.py。如果开启平台代理模式需要保证凭据具备以下 GCS 权限storage.objects.get读取对象数据与元数据以及storage.objects.list使用前缀时列举对象。对于 on-prem 部署大文件流式传输按顺序以 8 MB 分块拆分为多个 GET 请求可通过以下环境变量调优定义于 core/settings/base.pyRESOLVER_PROXY_BUFFER_SIZE缓冲大小默认 512 KBRESOLVER_PROXY_TIMEOUT单请求最大耗时默认 20 秒RESOLVER_PROXY_MAX_RANGE_SIZE单次请求返回的最大分块大小默认 8 MBRESOLVER_PROXY_GCS_DOWNLOAD_URLGCS 下载端点模板默认https://storage.googleapis.com/download/storage/v1/b/{bucket_name}/o/{blob_name}?altmediaRESOLVER_PROXY_GCS_HTTP_TIMEOUTGCS HTTP 请求超时默认 5 秒RESOLVER_PROXY_ENABLE_ETAG_CACHE/RESOLVER_PROXY_CACHE_TIMEOUTETag 缓存开关默认开启与缓存时长默认 3600 秒使用 Application Default Credentials 增强安全对于 on-prem 部署可以不为每个存储连接手动粘贴凭据 JSON而是通过Application Default CredentialsADC在平台层面全局提供云存储认证。推荐方式是通过GOOGLE_APPLICATION_CREDENTIALS环境变量指向凭据 JSON 文件export GOOGLE_APPLICATION_CREDENTIALSjson-file-with-GCP-creds-23441-8f8sd99vsd115a.json源码层面的支持见 GCS.get_client当google_application_credentials为空时直接以gcs.Client(projectgoogle_project_id)构造客户端底层自动回落到 ADC只有显式提供了凭据 JSON 时才通过service_account.Credentials.from_service_account_info()解析为服务账号凭据。此外设置项GCS_CLOUD_STORAGE_FORCE_DEFAULT_CREDENTIALS默认False见 base.py用于控制签名 URL 时是否强制使用默认凭据开启后仅当未提供google_application_credentials时才尝试从环境加载 ADC 凭据。Google Cloud Storage 与 Workload Identity FederationWIFWIF 方案对应 UI 中的Google Cloud Storage (WIF Auth)与长期应用凭据不同它使用临时凭据——每次向 GCS 发起请求时Label Studio 都会连接你的身份池identity pool换取临时凭据避免长期密钥的保管与轮换风险。该功能属于企业版能力。WIF 服务账号权限你需要一个具备以下权限的服务账号桶级Storage Adminroles/storage.admin项目级Service Account Token Creatorroles/iam.serviceAccountTokenCreator项目级Storage Object Viewerroles/storage.viewer创建 Workload Identity Pool官方文档提供了三种创建方式Terraform、gcloud 命令行、Google Cloud Console。方式一Terraform官方示例脚本原文完整版见 storage_gcp.md基于 AWS 托管的 HumanSignal Label Studio 身份进行信任配置需要预先设置以下变量GCP 项目变量var.gcp_project_name、var.gcp_regionHumanSignal 托管的 SaaS 标识var.aws_account_id 490065312183、var.aws_role_name label-studio-app-production然后依次执行terraform init terraform plan terraform apply脚本核心逻辑是创建google_iam_workload_identity_pool如label-studio-pool-${random_id}与google_iam_workload_identity_pool_providerAWS 类型通过attribute_condition校验attribute.aws_role可选叠加external_id条件并通过google_service_account_iam_binding将roles/iam.workloadIdentityUser授予principalSet://...attribute.aws_role/arn:aws:sts::490065312183:assumed-role/label-studio-app-production。应用成功后即获得一个信任 Label Studio AWS IAM Role 的可用 WIF 池并输出GCP_WORKLOAD_ID与GCP_WORKLOAD_PROVIDER。方式二gcloud 命令行将方括号变量[PROJECT_ID]、[POOL_ID]、[PROVIDER_ID]等替换为实际值注意引号转义。创建身份池gcloud iam workload-identity-pools create [POOL_ID] \--project[PROJECT_ID]--locationglobal--display-name[POOL_DISPLAY_NAME]- [POOL_ID]池 ID如 label-studio-pool-abc123之后需要复用 - [PROJECT_ID]Google Cloud 项目 ID - [POOL_DISPLAY_NAME]池的人类可读名称可选但推荐。 2. 创建 AWS 提供方provider。由于发起请求的 Label Studio 资源托管在 AWS必须允许具有正确 external ID 与 AWS role 的 AWS 主体模拟 Google 服务账号 shell gcloud iam workload-identity-pools providers create-aws [PROVIDER_ID] \ --workload-identity-pool[POOL_ID] \ --account-id490065312183 \ --attribute-conditionattribute.aws_role\arn:aws:sts::490065312183:assumed-role/label-studio-app-production\ \ --attribute-mappinggoogle.subjectassertion.arn,attribute.aws_accountassertion.account,attribute.aws_roleassertion.arn,attribute.external_idassertion.external_id[PROVIDER_ID]提供方 ID如label-studio-app-production。为前面创建的服务账号授予iam.workloadIdentityUser角色gcloud iam service-accounts add-iam-policy-binding [SERVICE_ACCOUNT_EMAIL] \ --roleroles/iam.workloadIdentityUser \ --memberprincipalSet://iam.googleapis.com/projects/[PROJECT_NUMBER]/locations/global/workloadIdentityPools/[POOL_ID]/attribute.aws_role/arn:aws:sts::490065312183:assumed-role/label-studio-app-production[SERVICE_ACCOUNT_EMAIL]GCS 服务账号邮箱如my-service-account[PROJECT_ID].iam.gserviceaccount.com[PROJECT_NUMBER]Google 项目编号与项目 ID 不同可通过gcloud projects describe $PROJECT_ID --formatvalue(projectNumber)查询。配置完成后在 Label Studio 建连前请记下这些值[POOL_ID]、[PROVIDER_ID]、[SERVICE_ACCOUNT_EMAIL]、[PROJECT_NUMBER]、[PROJECT_ID]。方式三Google Cloud Console进入IAM Admin Workload Identity Pools点击Get Started启用相关 API在Create an identity pool中填写Name即池 ID如label-studio-pool-abc123需记住与Description在Add a provider pool中选择AWS作为提供方Label Studio 发起请求的组件所在位置Provider name 可自定义显示名但Provider ID 必须为label-studio-app-productionAWS Account ID 填入490065312183在Configure provider attributes中添加条件attribute.aws_rolearn:aws:sts::490065312183:assumed-role/label-studio-app-production添加映射google.subject assertion.arn、attribute.aws_role ...含assumed-role的提取表达式可能已默认填好、attribute.aws_account assertion.account、attribute.external_id assertion.external_id点击Save到IAM Admin Service Accounts找到允许 AWSLabel Studio模拟的服务账号在其Principals with access标签页点击Grant Access在New principals中填入principalSet://iam.googleapis.com/projects/[PROJECT_NUMBER]/locations/global/workloadIdentityPools/[POOL_ID]/attribute.aws_role/arn:aws:sts::490065312183:assumed-role/label-studio-app-production[PROJECT_NUMBER]在IAM Admin Settings查看[POOL_ID]为第 2 步填写的 Name在Assign Roles中搜索并选择Workload Identity User角色点击Save。同样需要记下池 ID、提供方 ID应为label-studio-app-production、服务账号邮箱、Google 项目编号、Google 项目 ID。创建 WIF 源存储连接在项目中进入Settings Cloud Storage Add Source Storage选择Google Cloud Storage (WIF Auth)并点击Next填写字段说明Storage Title连接名称Bucket NameGCS 桶名称Workload Identity Pool ID创建身份池时指定的 ID可在 Console 的IAM Admin Workload Identity Pools查看Workload Identity Provider ID设置提供方时的 ID同样在IAM Admin Workload Identity Pools查看Service Account Email前置步骤中服务账号的邮箱如labelstudiorandom-string-382222.iam.gserviceaccount.com在IAM Admin Service Accounts的 Details 页查看Google Project ID项目 IDIAM Admin Settings查看Google Project Number项目编号IAM Admin Settings查看Use pre-signed URLs (On) / Proxy through the platform (Off)数据加载方式同标准 GCS 说明Expire pre-signed URLs (minutes)预签名 URL 有效期随后完成Import Settings PreviewBucket Prefix / Import Method / File Name Filter / Scan all sub-folders含义与标准 GCS 一致确认后点击Save Sync或Save。WIF 导入存储也有对应的 sync API。创建 WIF 目标存储连接选择Google Cloud Storage (WIF Auth)除上述字段外还包含Can delete objects from storage开启后删除标注时同步删除桶内注解要求凭据具备删除权限。保存后点击Sync。GCS 与 GKE 场景下的服务账号模拟SA Impersonation当 Label Studio 部署在 Google Kubernetes EngineGKE上时工作负载通常通过 GKE Workload Identity 将 Kubernetes 服务账号映射到 Google Cloud 服务账号但该直接绑定的服务账号未必对你的 GCS 桶有足够权限。服务账号模拟允许工作负载的 GCP 服务账号临时扮演另一个权限更充足的账号全程无需创建、分发和轮换长期密钥降低了凭据泄露风险。该功能需企业版并在 GKE 中部署。该方案涉及两个 Google Cloud 项目基础 GKE 项目Label Studio 部署所在由平台管理员一次性配置与目标项目GCS 桶所在由数据团队配置。配置 GKE 项目平台管理员一次性操作启用 feature flag必须在 Label Studio 部署中启用fflag_feat_bros_763_gcs_sa_impersonationfeature flag。可通过 Helm chart 的 extraEnvironmentVars 注入global: extraEnvironmentVars: fflag_feat_bros_763_gcs_sa_impersonation: true注意环境变量名必须小写Label Studio 的 feature flag 解析器以区分大小写的方式匹配fflag_前缀。创建基础服务账号在 GKE 项目中创建将作为 Label Studio Pod 身份的服务账号如lse-base创建时无需授予额外角色记下其邮箱如lse-baseyour-gke-project.iam.gserviceaccount.com——这就是后续与数据团队共享的基础服务账号邮箱。将基础服务账号绑定到 Kubernetes 服务账号为 Label Studio 使用的 Kubernetes 服务账号添加 Workload Identity 注解kubectl annotate serviceaccount label-studio-sa \ --namespacelabel-studio \ iam.gke.io/gcp-service-accountBASE_SA_EMAIL授予 Workload Identity User 角色使 K8s 服务账号能以 GCP 服务账号身份工作gcloud iam service-accounts add-iam-policy-binding BASE_SA_EMAIL \ --roleroles/iam.workloadIdentityUser \ --memberserviceAccount:GKE_PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]BASE_SA_EMAIL基础服务账号邮箱GKE_PROJECT_IDGKE 项目 IDNAMESPACELabel Studio 所在命名空间如label-studioKSA_NAMELabel Studio 使用的 Kubernetes 服务账号名如label-studio-sa。验证绑定运行测试 Pod输出中应显示基础服务账号邮箱为当前活跃账号kubectl run workload-identity-test \ --imagegoogle/cloud-sdk:slim \ --serviceaccountlabel-studio-sa \ --namespacelabel-studio \ -it --rm -- gcloud auth listTerraform 等价配置原文完整版见 storage_gcp.mdresource google_service_account lse_base { project your-gke-project account_id lse-base display_name Label Studio Base SA } resource google_service_account_iam_member workload_identity_binding { service_account_id google_service_account.lse_base.name role roles/iam.workloadIdentityUser member serviceAccount:your-gke-project.svc.id.goog[label-studio/label-studio-sa] }配置目标 Google Cloud 项目Step 1在目标项目创建服务账号在桶所在项目中创建 Label Studio 将模拟访问数据的服务账号如sa-label-studio-data记下邮箱如sa-label-studio-datayour-data-project.iam.gserviceaccount.com。Step 2授予目标服务账号桶访问权限按用途选择角色源存储导入数据roles/storage.objectViewer目标存储导出注解roles/storage.objectAdminroles/storage.objectAdmin是目标存储必需的因为 Label Studio 需要在桶中创建、覆盖并按需删除对象。若只需写入无需删除roles/storage.objectCreator即可但此时Can delete objects from storage选项将无法工作。在 Console 中进入Cloud Storage Buckets选择桶 →Permissions Grant Access→ 填入目标服务账号邮箱 → 按用途选择Storage Object Viewer或Storage Object Admin可 Add another role 同时添加→Save。gcloud 等价命令# 源存储读 gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \ --memberserviceAccount:TARGET_SA_EMAIL \ --roleroles/storage.objectViewer # 目标存储写与删 gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \ --memberserviceAccount:TARGET_SA_EMAIL \ --roleroles/storage.objectAdminStep 3允许基础服务账号模拟目标服务账号在目标服务账号上把roles/iam.serviceAccountTokenCreator授予基础服务账号。该角色包含signBlob权限——Label Studio 生成预签名 URL 供浏览器直连读取对象时正好需要它。Console 操作IAM Admin Service Accounts选择目标服务账号 →Permissions Grant Access→ New principals 填基础服务账号邮箱 → 角色选Service Account Token Creator→Save。gcloud 等价命令gcloud iam service-accounts add-iam-policy-binding TARGET_SA_EMAIL \ --memberserviceAccount:BASE_SA_EMAIL \ --roleroles/iam.serviceAccountTokenCreatorStep 4在桶上配置 CORS预签名 URL 必需创建cors.json将https://your-label-studio-domain.com替换为 Label Studio 实际域名[ { origin: [https://your-label-studio-domain.com], method: [GET, HEAD], responseHeader: [Content-Type, Content-Range, Content-Disposition], maxAgeSeconds: 3600 } ]应用并验证gcloud storage buckets update gs://YOUR_BUCKET_NAME --cors-filecors.json gcloud storage buckets describe gs://YOUR_BUCKET_NAME --formatdefault(cors_config)如果使用Proxy through the platform模式而非预签名 URL则无需配置 CORS流量全部经过 Label Studio 服务器。创建 SA Impersonation 源存储连接选择Google Cloud Storage (SA Impersonation)字段包括Storage Title、Bucket Name、Target Service Account EmailStep 1 创建的目标服务账号邮箱、Google Project ID、Use pre-signed URLs / Proxy、Expire pre-signed URLs。预签名所需的signBlob权限已包含在 Step 3 授予的roles/iam.serviceAccountTokenCreator中。Import Settings 与确认流程同前。创建 SA Impersonation 目标存储连接字段包含Storage Title、Bucket Name、Bucket Prefix、Target Service Account Email、Google Project ID、Can delete objects from storage需要目标服务账号具备roles/storage.objectAdmin见 Step 2。保存后点击Sync。SA Impersonation 排障错误原因解决方案Label Studio 中没有Google Cloud Storage (SA Impersonation)选项未启用所需 feature flag在 GKE 部署中设置小写环境变量fflag_feat_bros_763_gcs_sa_impersonationPermission iam.serviceAccounts.getAccessToken denied on resource基础服务账号无权模拟目标服务账号确认基础服务账号在目标服务账号上拥有roles/iam.serviceAccountTokenCreator见 Step 3404 Service account not found目标服务账号邮箱错误或账号不存在确认邮箱以.iam.gserviceaccount.com结尾且账号存在于 GCP 项目中Permission storage.buckets.get denied或403 Access denied to bucket目标服务账号缺少桶权限在桶上为目标服务账号授予roles/storage.objectViewer源或roles/storage.objectAdmin目标见 Step 2图片/媒体加载失败浏览器控制台报 CORS 错误桶未针对 Label Studio 域名配置 CORS仅预签名 URL 场景为桶添加允许从 Label Studio URL 发起GET/HEAD的 CORS 策略见 Step 4用 Label Studio API 编程式添加存储除 UI 外所有 GCS 连接均可通过 REST API 创建与管理。源码中为 GCS 定义了完整的视图集io_storages/gcs/api.py导入存储GCSImportStorageListAPIGET 列表 / POST 创建、GCSImportStorageDetailAPIGET / PATCH / DELETE、GCSImportStorageSyncAPIPOST 触发同步、GCSImportStorageValidateAPIPOST 校验连接、GCSImportStorageFormLayoutAPI表单布局导出存储GCSExportStorageListAPI、GCSExportStorageDetailAPI、GCSExportStorageSyncAPI、GCSExportStorageValidateAPI、GCSExportStorageFormLayoutAPI创建/更新请求体由 GCSImportStorageSerializer 与 GCSExportStorageSerializer 约束导入序列化器强制presign默认True并将google_application_credentials列为安全字段——序列化输出时会被剔除to_representation中result.pop(attr)避免凭据泄露校验阶段则会调用validate_connection()实际连接 GCS 验证桶与前缀。API 的具体端点语义可通过仓库内 OpenAPI/SDK 生成配置 查看。用 IP 过滤进一步加固 GCS 桶GCS 的bucket IP filtering允许基于源 IP 地址限制桶访问防止未授权访问并实现细粒度的访问控制详见 storage_gcp.md 与 security.md 中 Source storage behind your VPC。常见用例仅允许组织 IP 段访问桶仅允许基础设施中特定 VPC 网络访问将敏感数据限制在已知 IP 地址范围内通过白名单 IP 控制第三方集成的访问配置步骤通过 Console 或 CLI 创建 GCS 桶创建 JSON 配置文件定义过滤规则。公网 IP 范围规则{ mode: Enabled, publicNetworkSource: { allowedIpCidrRanges: [ xxx.xxx.xxx.xxx, // Your first IP address xxx.xxx.xxx.xxx, // Your second IP address xxx.xxx.xxx.xxx/xx // Your IP range in CIDR notation ] } }VPC 网络来源规则{ mode: Enabled, vpcNetworkSources: [ { network: projects/PROJECT_ID/global/networks/NETWORK_NAME, allowedIpCidrRanges: [ RANGE_CIDR ] } ] }应用规则gcloud alpha storage buckets update gs://BUCKET_NAME --ip-filter-fileIP_FILTER_CONFIG_FILE移除规则gcloud alpha storage buckets update gs://BUCKET_NAME --clear-ip-filter已知限制所有规则合计最多 200 个 IP CIDR 块IP 过滤规则中最多 25 个 VPC 网络不支持双区域dual-regional桶可能影响部分 Google Cloud 服务的访问运维建议与常见注意事项综合官方指南与源码实现落地 GCS 集成时需注意以下几点同步是单向的源存储是从桶对象创建任务目标存储是把注解推回桶。在桶侧直接改动内容并不保证与 Label Studio 结果一致只有向桶上传新文件或删除关联任务后重新同步才能让 Tasks 模式下已导入的文件变更生效storage.md 排障章节。源存储不存数据从云存储同步的任务数据不落库而是通过预签名 URL 访问storage.md。Files 模式下 Label Studio 只创建对象的引用而非导入内容因此数据访问控制完全掌握在你手中。权限最小化Files 导入模式只需 LIST 权限Tasks 模式还需 GET 权限读取 JSON 转任务浏览器加载媒体时还需对桶具备 HEAD 与 GET 权限。每个项目独立目录官方建议为每个 Label Studio 项目使用独立的桶目录Bucket Prefix便于隔离与管理。区域就近把桶放在离标注团队更近的区域而不是贴近 Label Studio 服务器可降低延迟、提升效率。凭据保护google_application_credentials属于安全字段不会出现在任何 API 响应中serializers.py建议 on-prem 环境优先采用 ADC 或 WIF 避免在 UI 中粘贴长期密钥。通过本文的配置路径与源码对照你已经可以从零开始将 GCS 桶接入 Label Studio并在预签名直连、平台代理、WIF 临时凭据与 GKE 服务账号模拟之间做出符合自身安全与性能要求的选型。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考