企业官网建设流程全解析

使用 Docker 部署 Argilla：启动 Elasticsearch 后端与 Argilla Server 完整指南

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

本指南面向希望用 Docker 在本地或服务器上快速部署 Argilla 数据标注平台的开发者。它以官方文档 deployments/docker.md 为骨架，结合仓库内服务器配置源码与部署示例，完整讲解如何创建容器网络、启动 Elasticsearch 后端、运行 Argilla Server 与 UI，并深入说明ARGILLA_*环境变量的底层作用与生产级 Compose 部署方案。读完本文，你将能够独立完成一次基于 Docker 的 Argilla 全栈搭建，并具备容器化运维与数据持久化的实战能力。

一、部署前须知：Docker 部署在整个安装体系中的位置

Argilla 提供多种安装方式：除了本文讲解的 Docker 部署之外，还包括 Docker Compose 一键部署（见 docker_compose.md）、快速体验（docker-quickstart.md）、本地 Python 安装（python.md）以及 Hugging Face Spaces、云厂商等托管方案。

Docker 部署的优势在于：无需在宿主机安装 Python 与 Java 运行环境，所有依赖都被封装在镜像内；同时可以精确控制 Elasticsearch（ES）与 Argilla Server 的版本组合。本文演示的是最灵活的"双容器 + 自定义网络"模式——先启动一个 ES 容器作为搜索引擎，再启动 Argilla Server 容器连接它。这也是理解 Argilla 容器化架构的入门路径，后续阅读 Docker Compose 方案时会更容易理解。

从仓库的 Dockerfile 可以看到，官方argilla/argilla-server镜像基于python:3.13-slim，通过多阶段构建安装uvicorn[standard]与 Argilla 服务端及 PostgreSQL 依赖，并对外暴露6900端口（EXPOSE 6900，对应环境变量UVICORN_PORT=6900）。也就是说，镜像内部已经内置了 uvicorn 服务器与 Argilla 应用（UVICORN_APP=argilla_server:app），你无需在容器内再做任何启动配置。

二、第一步：创建 Docker 网络

Argilla Server 与 Elasticsearch 是相互独立的容器，要让两者"看得见对方"，必须先创建一个自定义 Docker 网络，让它们处于同一网络中并通过容器名而非localhost互相通信。

docker network create argilla-net

执行后可以用以下命令确认网络已创建：

docker network ls

需要说明的是，之所以必须用--network argilla-net把两个容器放入同一网络，是因为容器之间默认是隔离的：docker run默认创建的 bridge 网络不允许容器通过容器名互访。创建专用网络后，Argilla Server 容器便可通过http://elasticsearch-for-argilla:9200这样的容器主机名访问 ES。

三、第二步：通过 Docker 启动 Elasticsearch

Elasticsearch（以下简称 ES）是 Argilla 的搜索引擎与数据集存储后端，负责承载标注数据集的索引与检索。官方推荐的 ES 版本是8.5.x，本文命令使用8.5.3镜像。

在刚创建的argilla-net网络上运行 ES 容器：

docker run -d --name elasticsearch-for-argilla --network argilla-net \ -p 9200:9200 -p 9300:9300 \ -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \ -e "discovery.type=single-node" \ -e "xpack.security.enabled=false" \ docker.elastic.co/elasticsearch/elasticsearch:8.5.3

各参数含义如下：

注意：单节点 + 关闭安全认证的组合适用于本地开发与测试。若用于生产环境，请务必参考 ES 官方文档开启安全配置，并妥善管理xpack相关设置。

容器启动后即为后台运行状态。你可以随时查看其日志：

docker logs elasticsearch-for-argilla

也可以停止或重新启动容器：

docker stop elasticsearch-for-argilla docker start elasticsearch-for-argilla

数据持久化警告（务必阅读）

:::{warning}如果你执行docker rm elasticsearch-for-argilla删除容器，Argilla 中所有的数据集将随之丢失！:::

这是 Docker 部署最容易踩的坑：默认情况下，ES 数据写入的是容器可写层，而docker rm会连同容器可写层一并删除。仓库提供的生产级 docker-compose.yaml 中为 ES 挂载了命名卷elasticdata:/usr/share/elasticsearch/data/，即官方推荐的做法——在单容器部署时也建议自行挂载数据卷，例如追加参数：

-v elasticsearch-data:/usr/share/elasticsearch/data

这样即使容器被删除，数据仍然保留在宿主机卷中。同理，Argilla 服务端镜像 内部也声明了VOLUME $ARGILLA_HOME_PATH（默认/var/lib/argilla），用于持久化 Argilla 自身的应用数据。

四、第三步：拉取并运行 Argilla Server 与 UI

完成 ES 部署后，接下来启动 Argilla Server。该镜像同时包含服务端 API 与 Web UI，容器内通过 uvicorn 统一对外提供服务（见 start_argilla_server.sh 的启动逻辑）。

首先从 Docker Hub 拉取官方镜像：

docker pull argilla/argilla-server

然后运行容器。前提是必须先有一个运行中的 Elasticsearch 实例——Argilla Server 在启动时会尝试连接 ES 并初始化数据集索引。

docker run --network argilla-net \ -p 6900:6900 \ -e "ARGILLA_ELASTICSEARCH=http://elasticsearch-for-argilla:9200" \ --name argilla \ argilla/argilla-server

命令要点解读：

• --network argilla-net：与 ES 容器同处一个网络，保证容器间互通；
• -p 6900:6900：将容器内 uvicorn 监听端口 6900 映射到宿主机，浏览器通过http://localhost:6900即可访问 Argilla 的 UI 与 API。该端口对应镜像内默认的UVICORN_PORT=6900；
• -e "ARGILLA_ELASTICSEARCH=http://elasticsearch-for-argilla:9200"：指定 ES 端点。这里的关键点在于必须使用容器名elasticsearch-for-argilla而非localhost——容器内的localhost指向容器自身，访问不到 ES 容器。

关于默认 ES 地址的说明

如果不设置ARGILLA_ELASTICSEARCH，Argilla Server 默认会尝试连接http://localhost:9200。从服务端源码 settings.py 可以看到该默认值定义：

elasticsearch: str = "http://localhost:9200"

这正是官方文档强调"默认情况下 Argilla Server 会查找http://localhost:9200端点，可通过ARGILLA_ELASTICSEARCH环境变量自定义"的源码依据。当你把 Argilla 部署在宿主机（而非容器）上、且 ES 直接监听宿主机的 9200 端口时，保持默认值即可；而本文的容器化方案中，必须显式指定容器网络内的地址。

环境变量的命名规范

值得留意的是，ARGILLA_ELASTICSEARCH采用了ARGILLA_前缀。在 settings.py 末尾可以看到：

class Config: env_prefix = "ARGILLA_"

这意味着服务端所有配置项都通过ARGILLA_前缀的环境变量注入，例如ARGILLA_ELASTICSEARCH、ARGILLA_HOME_PATH、ARGILLA_DATABASE_URL、ARGILLA_REDIS_URL等。下表汇总了与 Docker 部署密切相关的核心配置：

五、日常运维：查看、停止与重启

容器启动后，可以用 Docker 原生命令完成日常运维。

查看所有运行中的容器，确认 Argilla Server 与 ES 都在运行：

docker ps

停止 Argilla Server：

docker stop argilla

停止后可通过docker start argilla再次启动。如果希望移除 Argilla 容器，可执行：

docker rm argilla

结合上文的持久化配置：只要 ES 数据卷与ARGILLA_HOME_PATH数据卷均做了持久化，删除并重建 Argilla 容器不会造成数据丢失；反之，若未挂载卷，docker rm将造成数据丢失。

容器启动时发生了什么

了解容器启动流程有助于理解环境变量的实际效果。官方镜像的入口脚本 start_argilla_server.sh 依次执行三步：

1. 执行数据库迁移：python -m argilla_server database migrate，保证数据库 schema 与当前版本一致；
2. 按需创建 owner 用户：若同时设置了USERNAME与PASSWORD环境变量，则调用python -m argilla_server database users create创建 owner 角色用户，并可选传入API_KEY与WORKSPACE；若未设置则跳过并打印提示；
3. 启动 uvicorn：python -m uvicorn $UVICORN_APP --host "0.0.0.0"，其中UVICORN_APP默认为argilla_server:app，监听所有网卡地址，端口由UVICORN_PORT（默认 6900）决定。

因此在单容器运行docker run时，如果你想在首次启动时自动创建管理员账号，可以追加这些环境变量，例如：

docker run --network argilla-net -p 6900:6900 \ -e "ARGILLA_ELASTICSEARCH=http://elasticsearch-for-argilla:9200" \ -e "USERNAME=argilla" -e "PASSWORD=12345678" \ -e "API_KEY=argilla.apikey" -e "WORKSPACE=default" \ --name argilla argilla/argilla-server

六、关于遥测（Telemetry）

:::{note} 默认情况下 Argilla 启用了遥测（telemetry），用于帮助团队改进产品。关于收集的具体指标以及如何关闭，请参阅 reference/telemetry.md。 :::

遥测收集的是匿名的用量与错误信息，例如错误码与实体类型、user-agent与accept-language请求头、批量操作的任务名与记录数、匿名生成的用户 UUID、Argilla 版本、Python 版本、操作系统类型与发行版本、机器类型、部署类型（quickstart 或 server）以及是否容器化部署等。不会收集任何数据集记录、数据集名称或元数据。

如需在 Docker 部署中关闭遥测，可在docker run时追加环境变量：

-e "ARGILLA_ENABLE_TELEMETRY=0"

从源码角度看，settings.py 中的enable_telemetry校验逻辑显示，除了ARGILLA_ENABLE_TELEMETRY=0（旧机制，会同时产生弃用警告）之外，新版还支持通过HF_HUB_DISABLE_TELEMETRY=1或HF_HUB_OFFLINE=1关闭遥测。官方 compose 示例 docker-compose.yaml 中也以注释形式给出了这两个选项。

七、进阶：从单容器到生产级 Docker Compose 部署

单容器模式适合快速验证与入门。若需要更完整的生产化部署（包含 PostgreSQL、Redis 与独立 worker），仓库在 examples/deployments/docker/docker-compose.yaml 提供了开箱即用的 Compose 编排，其架构如下：

• argilla：argilla/argilla-server服务容器，映射6900:6900，挂载argilladata卷到/var/lib/argilla，并注入USERNAME、PASSWORD、API_KEY、WORKSPACE用于自动创建管理员；
• worker：同一镜像启动的后台任务工作进程（python -m argilla_server worker --num-workers 2），用于异步处理数据索引等任务；
• postgres：PostgreSQL 14 元数据库，通过ARGILLA_DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/argilla接入；
• elasticsearch：单节点 ES（示例使用8.17.0镜像，同样关闭安全认证并挂载elasticdata数据卷）；
• redis：为任务队列提供支持，通过ARGILLA_REDIS_URL接入。

与本文双容器方案相比，Compose 方案额外引入了 PostgreSQL 与 Redis。原因同样可以在 settings.py 中找到：database_url默认会回退到基于ARGILLA_HOME_PATH的 SQLite（sqlite+aiosqlite:///...，仅适合单机轻量场景），而redis_url默认指向redis://localhost:6379/0——单容器模式下如果没有 Redis，相关后台任务能力会受限。生产部署时，应按照 Compose 示例配置 PostgreSQL 与 Redis，并通过ARGILLA_DATABASE_URL、ARGILLA_REDIS_URL显式指定。

无论采用哪种方式，容器化部署后请记住三个访问入口与对应地址：

八、常见问题与排查

1. Argilla Server 启动即报错，提示无法连接 ES

检查 ES 容器是否在运行（docker ps），并确认ARGILLA_ELASTICSEARCH使用的是容器名地址而非localhost。可用docker exec -it argilla curl http://elasticsearch-for-argilla:9200（容器内若含 curl）或docker logs elasticsearch-for-argilla验证 ES 就绪状态。

2. 重启机器后数据还在吗？

ES 容器与 Argilla 容器默认不配置重启策略，且数据写在容器可写层。建议为 ES 挂载命名卷（-v elasticsearch-data:/usr/share/elasticsearch/data），并为容器追加--restart unless-stopped；Compose 方案已内置数据卷与restart: unless-stopped，可直接参考。

3. 如何确认容器内实际生效的配置？

可通过docker exec argilla env查看容器内注入的环境变量，或docker logs argilla观察启动脚本输出的迁移、用户创建与 uvicorn 启动日志。

4. 想换用其他 ES 版本或部署自己的 ES 集群？

Argilla 官方推荐 ES 8.5.x，若需部署独立 ES 集群，可参考 ES 官方 Docker 文档进行集群化配置；同时注意 Argilla 也支持通过search_engine配置切换 OpenSearch 等搜索引擎（见 settings.py）。

九、总结

本文完整复现了官方文档的 Docker 部署路径：创建网络 → 启动 Elasticsearch → 运行 Argilla Server，并在此基础上结合仓库源码深入剖析了ARGILLA_前缀环境变量体系、容器启动脚本的执行链路、数据持久化风险以及生产级 Compose 架构。掌握了这套流程，你既能在几分钟内于本地拉起一套可用的 Argilla，也能以此为起点演进到 PostgreSQL + Redis + worker 的完整生产部署形态。下一步建议阅读 docker_compose.md 体验一键编排方案，或参考 configurations/server_configuration.md 深入调优服务端参数。

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