6.4 · 服务端配置（Server Configuration）

人工复核与反馈数据 · 本章是 Argilla DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Argilla 章节6.4 状态全文译文模块安装与启动、认证、权限与安全、存储与持久化、测试、发布与运维

项目要点页2.5 参考项目项目章节目录Argilla DeepWiki 原始章节Server Configuration 上一章6.3 下一章7

源码线索

docs/_source/_common/tabs/argilla_install_python.md
docs/_source/community/contributing.md
docs/_source/community/developer_docs.md
docs/_source/community/migration-rubrix.md
docs/_source/getting_started/installation/deployments/docker.md
docs/_source/getting_started/installation/deployments/docker_compose.md
docs/_source/getting_started/installation/deployments/python.md
docs/_source/reference/cli.md
docs/_source/reference/notebooks.rst
docs/migration-rubrix.md

模块标签

安装与启动
认证、权限与安全
存储与持久化
测试、发布与运维
检索、召回与索引

中文译文

服务端配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/argilla-io/argilla/6.4-server-configuration

翻译时间：2026-05-27T08:44:23.854Z

翻译模型：deepseek-chat

原文字符数：12433

项目：Argilla (argilla)

---

服务器配置

概述

Argilla 服务器是核心组件，负责管理数据、协调标注工作流，并提供 Python SDK 和前端 UI 所使用的 API 端点。它连接到三个主要的数据存储：

关系型数据库（SQLite 或 PostgreSQL），用于存储用户信息、工作区数据和数据集元数据
向量数据库（Elasticsearch 或 OpenSearch），用于存储记录并执行向量搜索
Redis，用于管理后台作业

配置主要通过带有 ARGILLA_ 前缀的环境变量来应用，但某些设置也可以通过命令行参数指定。

服务器架构与配置

下图展示了配置如何应用到 Argilla 服务器及其数据存储：

graph TB
    ENVvars["环境变量<br>ARGILLA_*"] --> ArgillaServer["Argilla 服务器<br>(FastAPI)"]
    CLI["命令行参数<br>--host, --port 等"] --> ArgillaServer

    ArgillaServer --> RelationalDB
    ArgillaServer --> VectorDB
    ArgillaServer --> RedisQueue

    subgraph "数据存储"
        RelationalDB[(关系型数据库<br>SQLite/PostgreSQL)]
        VectorDB[(向量数据库<br>Elasticsearch/OpenSearch)]
        RedisQueue[(Redis 队列)]
    end

    Client["Python SDK 客户端"] <--> ArgillaServer
    FrontendUI["前端 UI"] <--> ArgillaServer

来源：docs/_source/community/developer_docs.md:14-27，docs/_source/getting_started/installation/deployments/docker.md:19-42

基本服务器配置

服务器主机与端口

以下环境变量控制服务器绑定的主机和端口：

环境变量	描述	默认值
`ARGILLA_HOST`	绑定的主机	`0.0.0.0`
`ARGILLA_PORT`	绑定的端口	`6900`

这些设置也可以在启动服务器时通过命令行参数指定：

argilla server start --host 127.0.0.1 --port 8000

访问日志

可以使用 --access-log 或 --no-access-log 命令行参数启用或禁用服务器访问日志：

argilla server start --no-access-log  # 禁用访问日志

来源：docs/_source/reference/cli.md:181-186

数据库配置

Argilla 使用关系型数据库来存储元数据、用户信息和标注数据。它支持 SQLite（默认）和 PostgreSQL。

主目录

以下环境变量控制 Argilla 主目录的位置，该目录用于存储配置文件和默认的 SQLite 数据库：

环境变量	描述	默认值
`ARGILLA_HOME_PATH`	Argilla 主目录的路径	`~/.argilla`

SQLite 配置（默认）

SQLite 是默认数据库，只需极少的配置。以下环境变量控制 SQLite 的配置：

环境变量	描述	默认值
`ARGILLA_DATABASE_URL`	SQLite 数据库的 URL	`sqlite:///$ARGILLA_HOME_PATH/argilla.db`

PostgreSQL 配置

要使用 PostgreSQL 替代 SQLite，请将 ARGILLA_DATABASE_URL 环境变量设置为 PostgreSQL 连接字符串：

export ARGILLA_DATABASE_URL=postgresql://用户名:密码@主机:端口/数据库

请注意，你需要安装 PostgreSQL 的额外依赖才能使用：

pip install argilla[postgresql]

来源：docs/_source/community/developer_docs.md:295-301，docs/_source/getting_started/installation/deployments/python.md:16

向量数据库配置

Argilla 支持 Elasticsearch（版本 >=8.5）和 OpenSearch（版本 >=2.4）作为向量数据库，用于存储记录并执行向量搜索。

graph LR
    ArgillaServer["Argilla 服务器<br>(FastAPI)"]
    VectorDB[(向量数据库)]
    subgraph "向量数据库选项"
        ES["Elasticsearch ≥8.5"]
        OS["OpenSearch ≥2.4"]
    end

    ArgillaServer --> VectorDB
    VectorDB --- ES
    VectorDB --- OS

    subgraph "向量操作"
        VS["向量搜索"]
        KNN["KNN 查询"]
        DS["文档搜索"]
    end

    VectorDB --> VS
    VectorDB --> KNN
    VectorDB --> DS

来源：docs/_source/community/developer_docs.md:284-290

向量数据库连接

以下环境变量控制向量数据库的连接：

环境变量	描述	默认值
`ARGILLA_ELASTICSEARCH`	Elasticsearch/OpenSearch 服务器的 URL	`http://localhost:9200`

向量数据库认证

以下环境变量控制向量数据库的认证：

环境变量	描述	默认值
`ARGILLA_ELASTICSEARCH_USER`	认证用户名
`ARGILLA_ELASTICSEARCH_PASSWORD`	认证密码
`ARGILLA_ELASTICSEARCH_API_KEY`	认证的 API 密钥（替代用户名/密码）

向量数据库 SSL/TLS

以下环境变量控制向量数据库连接的 SSL/TLS 配置：

环境变量	描述	默认值
`ARGILLA_ELASTICSEARCH_SSL_VERIFY`	是否验证 SSL 证书	`True`
`ARGILLA_ELASTICSEARCH_CA_PATH`	SSL 验证的 CA 证书路径

来源：docs/_source/getting_started/installation/deployments/docker.md:62-66

Redis 配置

Argilla 使用 Redis 来管理后台作业和任务队列。以下环境变量控制 Redis 的配置：

环境变量	描述	默认值
`ARGILLA_REDIS_URL`	Redis 服务器的 URL	`redis://localhost:6379/0`

来源：docs/_source/community/developer_docs.md:23

认证与安全

Argilla 使用 JWT（JSON Web 令牌）进行认证。以下环境变量控制用于令牌生成和验证的密钥：

环境变量	描述	默认值
`ARGILLA_AUTH_SECRET_KEY`	JWT 令牌生成的密钥

你可以使用以下命令生成一个安全的密钥：

openssl rand -hex 32

来源：docs/_source/getting_started/installation/deployments/docker_compose.md:17

日志配置

Argilla 使用标准的 Python 日志系统。以下环境变量控制日志级别：

环境变量	描述	默认值
`ARGILLA_LOG_LEVEL`	日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）	`INFO`

访问日志可以在启动服务器时通过 --access-log 或 --no-access-log 命令行参数启用或禁用。

其他配置选项

遥测

Argilla 会收集匿名的遥测数据以帮助改进产品。可以禁用此功能：

环境变量	描述	默认值
`ARGILLA_TELEMETRY_ENABLED`	是否启用遥测	`true`

来源：docs/_source/getting_started/installation/deployments/docker.md:70，docs/_source/getting_started/installation/deployments/docker_compose.md:48

从 Rubrix 迁移

如果你正在从 Rubrix（Argilla 的旧版本）迁移，可以启用迁移功能：

环境变量	描述	默认值
`ARGILLA_ENABLE_MIGRATION`	启用从 Rubrix 的迁移（设置为 1 以启用）	`0`

来源：docs/_source/community/migration-rubrix.md:48-55

配置关系图

下图展示了 Argilla 服务器中的数据流和配置依赖关系：

flowchart TB
    subgraph "配置"
        ENV["环境变量"]
        CLI["命令行参数"]
    end

    subgraph "Argilla 服务器"
        CONFIG["配置管理器"]
        FASTAPI["FastAPI 应用"]
        AUTH["认证服务"]
        JOBS["后台作业"]
    end

    subgraph "存储系统"
        REL_DB["SQLite/PostgreSQL"]
        VEC_DB["Elasticsearch/OpenSearch"]
        REDIS["Redis"]
    end

    ENV --> CONFIG
    CLI --> CONFIG
    CONFIG --> FASTAPI
    CONFIG --> AUTH
    CONFIG --> JOBS

    FASTAPI --> REL_DB
    FASTAPI --> VEC_DB
    JOBS --> REDIS

    subgraph "外部接口"
        SDK["Python SDK"]
        UI["Web UI"]
        REST["REST API"]
    end

    SDK --> FASTAPI
    UI --> FASTAPI
    REST --> FASTAPI

来源：docs/_source/community/developer_docs.md:30-40

配置示例

基本开发配置

# 基本服务器配置
export ARGILLA_HOST=127.0.0.1
export ARGILLA_PORT=6900

# 使用默认的 SQLite 数据库
export ARGILLA_HOME_PATH=~/.argilla
export ARGILLA_DATABASE_URL=sqlite:///$ARGILLA_HOME_PATH/argilla.db

# 连接到本地 Elasticsearch 实例
export ARGILLA_ELASTICSEARCH=http://localhost:9200

# 设置认证密钥
export ARGILLA_AUTH_SECRET_KEY=$(openssl rand -hex 32)

# 开发环境设置日志级别为 DEBUG
export ARGILLA_LOG_LEVEL=DEBUG

# 启动服务器
argilla server start

使用 PostgreSQL 和 OpenSearch 的生产配置

# 基本服务器配置
export ARGILLA_HOST=0.0.0.0
export ARGILLA_PORT=6900

# 使用 PostgreSQL 作为数据库
export ARGILLA_DATABASE_URL=postgresql://用户名:密码@postgres:5432/argilla

# 连接带认证的 OpenSearch
export ARGILLA_ELASTICSEARCH=https://opensearch:9200
export ARGILLA_ELASTICSEARCH_USER=admin
export ARGILLA_ELASTICSEARCH_PASSWORD=admin
export ARGILLA_ELASTICSEARCH_SSL_VERIFY=true

# 连接 Redis 用于后台作业
export ARGILLA_REDIS_URL=redis://redis:6379/0

# 设置安全的认证密钥
export ARGILLA_AUTH_SECRET_KEY=你的安全密钥

# 设置日志级别为 WARNING 以减少日志量
export ARGILLA_LOG_LEVEL=WARNING

# 禁用遥测以保护隐私
export ARGILLA_TELEMETRY_ENABLED=false

# 启动服务器，不记录访问日志
argilla server start --no-access-log

来源：docs/_source/getting_started/installation/deployments/docker.md:52-68，docs/_source/getting_started/installation/deployments/docker_compose.md:55-101