企业官网建设流程全解析

Argilla 云端与 Kubernetes 部署实战：Kubernetes、AWS、Azure、GCP 四平台部署指南

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla

本指南围绕 Argilla 官方部署文档展开，系统讲解如何将 Argilla Server 部署到 Kubernetes、AWS、Azure 与 Google Cloud Platform（GCP）四类主流云端环境。读者学完后将掌握基于 Kubernetes Helm Chart 的容器化编排方案、基于 docker-machine 的 AWS 单机部署流程、基于 Azure Container Instances 的无服务器部署，以及基于 Cloud Run 与 GCE 虚拟机的两种 GCP 部署路径，并理解ARGILLA_*环境变量在后端启动时如何生效。

Argilla 是一个面向 AI 工程师与领域专家的协作标注平台，其服务端由 argilla-server 提供 REST API 与标注 Web UI。无论选择哪种云平台，部署的本质都是拉起 Argilla Server 容器（默认监听 6900 端口），并为其配置 PostgreSQL（元数据存储）、Elasticsearch（搜索与记录存储）与 Redis（队列与缓存）三类依赖。

Kubernetes：从最小化配置到 Helm Chart

官方推荐的部署文件集

官方文档指出，仓库中的k8s目录维护了一套最小化的 Kubernetes 部署配置，包含以下清单文件（说明以文档为准，当前仓库以 Helm Chart 形式提供等效实现）：

这些文件同时包含了资源占用的建议值（例如 HPA 将副本数限制在 1～3 之间），适合快速验证；官方建议在生产级场景使用下文介绍的 Helm Chart。

使用 Helm Chart 部署（推荐）

当前仓库在 examples/deployments/k8s/argilla-chart 中提供了完整的 Helm Chart，包含Chart.yaml、values.yaml以及templates/下的全部清单模板（Deployment、HPA、Ingress、Service、PVC、ConfigMap、Worker Deployment、Elasticsearch Operator 等）。Chart 的前置要求是 Kubernetes 1.12+、Helm 3.0+，且底层基础设施支持 PV 供应（当开启持久化时）。

说明：官方文档写作时 Argilla 官方仓库自身不直接维护独立 Helm 仓库，但可以与 Helm 部署的 Elasticsearch 组合使用——只需将ARGILLA_ELASTICSEARCH环境变量指向 Elasticsearch 所在端点即可。当前仓库的 Chart 已将这一能力模板化。

安装步骤

# 1. 添加依赖仓库（stable 与 elastic） helm repo add stable https://charts.helm.sh/stable helm repo add elastic https://helm.elastic.co helm repo update # 2.（可选）本地 Minikube 环境：分配 3G 内存、2 核并启用 ingress 插件 minikube stop minikube delete minikube config set memory 3g minikube config set cpus 2 minikube start minikube addons enable ingress kubectl get pods -n ingress-nginx # 确认 ingress controller 处于 Running # 3. 安装 ECK Operator 以托管 Elasticsearch 集群 helm install elastic-operator elastic/eck-operator -n elastic-system --create-namespace kubectl get pods -n elastic-system # 确认 elastic-operator 处于 Running # 4. 安装 Argilla Chart helm install my-argilla-server examples/deployments/k8s/argilla-chart # 5. 观察 Pod 状态，全部应为 Running kubectl get pods -w # 6. 端口转发访问 Argilla（浏览器打开 http://localhost:6900） kubectl port-forward svc/my-argilla-server 6900

卸载时执行helm delete my-argilla-server即可移除全部关联的 Kubernetes 组件。

关键 values.yaml 配置项解读

Chart 的核心配置集中在 values.yaml，主要参数如下：

模板层面可以看到环境变量是如何注入的（deployment.yaml）：

• ARGILLA_ELASTICSEARCH：使用 Operator 时指向http://{release}-es-http:9200，否则指向externalElasticsearch.host:port；
• ARGILLA_ELASTICSEARCH_SSL_VERIFY、ARGILLA_AUTH_SECRET_KEY、ARGILLA_REDIS_URL、ARGILLA_REDIS_USE_CLUSTER由对应 values 渲染；
• USERNAME、PASSWORD、API_KEY用于创建初始工作区账号；
• 开启持久化时注入ARGILLA_HOME_PATH（默认挂载/data），并通过 pvc.yaml 申请2Gi存储。

Ingress 模板（ingress.yaml）将/前缀路径（pathType: Prefix）路由到 Service 的 6900 端口，而 service.yaml 暴露的端口同样是 6900。

用集成测试验证部署

Chart 文档提供了验证方式：将ARGILLA_API_URL=http://localhost:6900与ARGILLA_API_KEY=argilla.apikey写入环境变量后，执行pytest tests/integration，即可通过 Python SDK 对刚部署的服务做一轮端到端冒烟测试。Chart 自身还内置了基于 helm-unittest 的单元测试（tests/目录下的simple_test.yaml、suite_test.yaml、test-connection.yaml），安装插件后可在 Chart 根目录运行helm unittest examples/deployments/k8s/argilla-chart验证模板渲染结果。

后端环境变量的底层实现

Kubernetes 清单中频繁出现的ARGILLA_*前缀环境变量，最终由服务端配置类解析。argilla-server/src/argilla_server/settings.py 中Settings(BaseSettings)通过 pydantic 将环境变量映射为字段，例如：

• elasticsearch（默认http://localhost:9200）对应连接 Elasticsearch 的端点，控制数据集记录的索引持久化；
• elasticsearch_ssl_verify（默认True）与elasticsearch_ca_path控制 TLS 校验与 CA 路径；
• redis_url（默认redis://localhost:6379/0）与redis_use_cluster控制 Redis 连接；
• database_url指定元数据库连接串（如postgresql+asyncpg://...），并可通过database_postgresql_pool_size、database_postgresql_max_overflow调节连接池；
• home_path决定应用数据（含上传文件）的落盘目录，对应 Docker 环境中的ARGILLA_HOME_PATH。

这意味着在 Kubernetes 中调整上述环境变量即可在不改镜像的情况下切换外部 ES/Redis/PostgreSQL，这也是 Helm Chart 将externalElasticsearch、externalRedis设计为可选项的原因。Elasticsearch 作为默认搜索引擎在 search_engine/elasticsearch.py 中注册实现。

Amazon Web Services（AWS）：docker-machine 单机部署

该方案通过docker-machine在 AWS EC2 上创建一台预装 Docker 的虚拟机，再以docker-compose拉起 Argilla 及其依赖。文档提供的 AMI 为 ubuntu-16.04-server 镜像，仅适用于 eu-west 区域；其他区域请到 AWS AMI Marketplace 筛选ubuntu获取可用镜像。

1. 配置 AWS 凭证 Profile

确保已安装awsCLI，然后创建专用 profile：

aws configure --profile argilla

按提示输入 Access Key、Secret Key、区域等；创建成功后~/.aws/config中会出现新条目。激活 profile：

export AWS_PROFILE=argilla

2. 创建 Docker Machine

docker-machine create --driver amazonec2 \ --amazonec2-root-size 60 \ --amazonec2-instance-type t2.large \ --amazonec2-open-port 80 \ --amazonec2-ami ami-0b541372 \ --amazonec2-region eu-west-1 \ argilla-aws

参数含义：--amazonec2-root-size指定 60GB 根磁盘，--amazonec2-instance-type t2.large指定机型，--amazonec2-open-port 80开放 80 端口供 HTTP 访问，--amazonec2-ami与--amazonec2-region指定镜像与区域。

若目标区域已有多个实例或 VPC，建议先创建新 VPC 再创建 Argilla 实例，并通过参数指定：

--amazonec2-vpc-id vpc-1234abcd # 替换为实际 VPC id

3. 验证机器创建并保存 IP

docker-machine ls

输出示例（IP 因实际分配而异）：

NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS argilla-aws - amazonec2 Running tcp://52.213.178.33:2376 v20.10.7

记下示例中的公网 IP52.213.178.33（以实际输出为准），后续访问 Argilla 与配置本地 Docker 客户端都要用到。

4. 连接远程 Docker Daemon

eval $(docker-machine env argilla-aws)

执行后本地docker客户端即指向远程 daemon，后续docker-compose命令会作用于 AWS 上的机器。

5. 定义 docker-compose.yaml 并启动

文档在该处引用了一份 docker-compose 模板（{{ dockercomposeyaml }}），其完整实现可在仓库 examples/deployments/docker/docker-compose.yaml 中找到。该文件定义了完整的服务拓扑：

• argilla：argilla/argilla-server:latest，映射6900:6900，通过ARGILLA_ELASTICSEARCH=http://elasticsearch:9200、ARGILLA_DATABASE_URL=postgresql+asyncpg://...、ARGILLA_REDIS_URL=redis://redis:6379/0连接依赖，并设置USERNAME、PASSWORD、API_KEY、WORKSPACE初始化账号，数据卷挂载到argilladata；
• worker：同镜像，以python -m argilla_server worker --num-workers 2启动后台任务进程；
• postgres：postgres:14，承载元数据；
• elasticsearch：docker.elastic.co/elasticsearch/elasticsearch:8.17.0单节点，禁用xpack.security以便内网直连；
• redis：提供队列服务。

在 AWS 机器上拉取并启动：

docker-compose pull docker-compose up -d

6. 访问 Argilla

启动完成后，在浏览器访问http://52.213.178.33（替换为实际分配的 IP）即可进入 Argilla 界面。

Azure：基于 Azure Container Instances（ACI）的无服务器部署

Azure 上最快捷的路径是使用 ACI——无需管理底层基础设施即可运行容器。部署全程基于azCLI。注意文档特别提醒：使用docker run配合docker context集成 Azure 的方式虽仍可行，但官方计划在 docker CLI 中废弃该方法，建议直接使用 ACI。

1. 认证

az login

2. 创建资源组

az group create --name <resource-group> --location <location>

3. 创建容器实例

az container create --resource-group <resource-group> --name <deployment-name> --image argilla/argilla-quickstart:latest --dns-name-label <dns-name> --ports 6900

argilla/argilla-quickstart:latest是预打包了存储层的快速启动镜像，因此该方式不支持水平扩展（与下文 GCP Cloud Run 的注意事项一致）。检查部署状态：

az container show --resource-group <resource-group> --name argilla --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" --out table

输出中的FQDN字段即为访问地址，浏览器打开http://<FQDN>:6900即可使用 Argilla。

Google Cloud Platform（GCP）：Cloud Run 托管部署

Cloud Run 是 GCP 的托管无状态容器平台。与 Azure 类似，本方案部署argilla/argilla-quickstart:latest快速启动镜像，因此同样无法利用 Cloud Run 的水平扩展能力——如需弹性伸缩，应改用带独立存储层的完整镜像与上文的 Kubernetes 方案。

1. 认证

gcloud auth login

2. 部署容器

使用gcloud run deploy直接从 Docker Hub 拉取镜像，将端口指向容器默认端口 6900，并指定计算资源：

gcloud run deploy <deployment-name> \ --region <region> \ --image argilla/argilla-quickstart:latest \ --allow-unauthenticated \ --port 6900 \ --cpu 2 \ --memory 4Gi \ --max-instances 1 \ --min-instances 1

关键参数：--allow-unauthenticated允许匿名访问，--cpu 2 --memory 4Gi分配 2 vCPU 与 4GiB 内存，--min-instances 1保持实例常驻以避免冷启动，--max-instances 1与快速启动镜像的"单实例"约束保持一致。

3. 获取访问地址

部署完成后可直接使用输出中的 URL，或执行：

gcloud run services describe <deployment-name> \ --region <region> \ --format 'value(status.url)'

Google Cloud Platform（GCP）：专用虚拟机（Compute Engine）部署

如果 Cloud Run 不适合你的场景（例如需要持久化存储与完整后端依赖），可以改用 GCE 虚拟机 + Docker Compose 的方式。这种方式与 AWS 方案同构，均使用完整版argilla-server镜像并自带 PostgreSQL/Elasticsearch/Redis，支持数据持久化。

1. 创建实例

gcloud compute instances create "argilla-instance" \ --machine-type "n1-standard-2" \ --image-family "debian-10" \ --image-project "debian-cloud" \ --boot-disk-size "50GB" \ --zone "asia-south2-a"

2. SSH 登录实例

gcloud compute ssh argilla-instance --zone asia-south2-a

3. 安装系统依赖

sudo apt-get update sudo apt-get install apt-transport-https ca-certificates curl software-properties-common gnupg2 lsb-release

4. 安装 Docker Engine 与 Compose 插件

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

5. 获取 docker-compose.yaml 并启动 Argilla

从仓库获取docker-compose.yaml（即 examples/deployments/docker/docker-compose.yaml 中的完整服务编排），随后启动：

mkdir argilla && cd argilla wget -O docker-compose.yaml https://raw.githubusercontent.com/argilla-io/argilla/main/docker/docker-compose.yaml sudo docker compose up -d

6. 开放外部流量

为实例打标签并创建防火墙规则，放行 6900 端口：

gcloud compute instances add-tags argilla-instance --zone asia-south2-a --tags=argilla-instance gcloud compute firewall-rules create allow-6900 --allow tcp:6900 --target-tags argilla-instance --description "Allow incoming traffic on port 6900"

7. 绑定静态 IP

为服务器预留静态 IP，保证后续始终可通过同一地址访问：

gcloud compute addresses create my-static-ip --region asia-south2

将静态 IP 绑定到实例（先删除默认的外部 NAT 配置，再添加静态地址）：

STATIC_IP=$(gcloud compute addresses list --format="value(address)" --filter="name=my-static-ip") gcloud compute instances delete-access-config argilla-instance --zone asia-south2-a --access-config-name "external-nat" gcloud compute instances add-access-config argilla-instance --zone asia-south2-a --address $STATIC_IP

8. 验证连接

curl -vI $STATIC_IP:6900

返回 HTTP 响应头即表示服务可用。之后在浏览器打开http://[STATIC_IP]:6900即可访问 Argilla。

方案选型与注意事项

无论选择哪条路径，部署完成后都应修改默认账号（argilla/12345678/argilla.apikey）与ARGILLA_AUTH_SECRET_KEY，并通过curl -vI <地址>:6900或 Python SDK 集成测试验证服务可用性。各方案最终都将 Argilla 及其 PostgreSQL、Elasticsearch、Redis 依赖正确编排在同一网络中，这也是保证标注平台元数据、检索索引与后台任务三者一致工作的前提。

【免费下载链接】argillaArgilla is a collaboration tool for AI engineers and domain experts to build high-quality datasets项目地址: https://gitcode.com/GitHub_Trending/ar/argilla